The Claude Agent SDK integration

The agent host process #

Claude runs through the agent host, a small TypeScript program in desktop/agent-host that uses @anthropic-ai/claude-agent-sdk. The desktop starts it with Node and passes the path of the packaged Claude executable as its only argument. A development build runs node from the PATH with agent-host/dist/src/entry.js. A packaged app runs its bundled node with claude/host/entry.mjs from its resources. The macOS build and the Windows builds package this runtime.

The two sides exchange one JSON object per line over stdin and stdout. A request carries an id of 1 to 200 characters, and its reply carries the same id with a result or an error. A line without an id is an event. The host checks every request against a strict schema, so an unknown field fails. The desktop gives each request 35 seconds. A request without a reply by then fails with “Claude host request timed out”.

Every run gets a new host, and the host never survives its run. When the run ends, the desktop sends close and waits at most 3 seconds for the reply. Then it closes stdin and gives the host 10 seconds to exit, and after that it kills the host and every process that the host started: the process group on macOS, and the process tree with taskkill on Windows. Reads that need no open conversation, such as the model catalog or a title, run in a one-shot host of their own. Before the start, the desktop removes nine environment markers that a parent Claude Code session gives its children, among them CLAUDECODE, CLAUDE_CODE_CHILD_SESSION, CLAUDE_CODE_SESSION_ID, and CLAUDE_PID. A desktop that you start from inside Claude Code would otherwise run its sessions as child sessions, and Claude doesn’t save their transcripts.

A request that fails the schema gets an error reply with its id. A line that the host can’t read as JSON gets a reply with the id null, and the desktop ignores it. The desktop buffers at most 256 events from one host. When the host’s stdout closes or a line is not JSON, the desktop fails every waiting request and makes a failed event itself. The host’s standard error goes to the desktop debug log.

• Settings and prompt: the query loads user, project, and local settings and uses the claude_code system prompt. The host appends the instructions of open to it. For each run, agents/session_rules.rs writes this text in this order: the questions rule, the session messages rule, the directions rule, and the text of the reply style. The questions rule says that Claude asks the user with AskUserQuestion and that the call doesn’t wait: the user answers in a later message. The session messages rule says that Claude reaches another HB Code session only with the hbcode tools send_session_message and maintain_sessions, because SendMessage and ListAgents reach only Claude Code sessions outside HB Code. The directions rule tells Claude to do all of an explicit direction, to ask one question, or to object with evidence. Simplified Technical English adds its reply text last, and Default adds no text. The app-tool text is not in this text: it is the instructions of the MCP server hbcode.
• Stream: includePartialMessages gives the live deltas, and forwardSubagentText sends each subagent turn in full. persistSession saves the transcript.
• Tools: the query gets the MCP server hbcode and its allowedTools. A PreToolUse hook answers every AskUserQuestion call at once. allowDangerouslySkipPermissions is set only for bypassPermissions.
• Run end: the host turns on Claude’s session state events with an environment variable, because a turn that starts background subagents ends before they do. Only the idle state tells the host that the whole run is over.
• Input: the query reads its messages from one stream that stays open for the whole run. The host writes each send into it at once, also while a turn runs.

The title request is a separate query. It uses the model haiku with no tools, one turn, no settings, and no saved session, and its system prompt forbids Claude to act on the message. The desktop asks for a title after send, in a one-shot host on the active account.

HB Code tools over the host #

Codex and Claude get the same HB Code tools from one catalog in services/agent_tools. For Claude, the desktop builds the list for each run and sends it in open.appCapabilities: one instructions text and, for each tool, its name, description, input schema, and approval class. The host turns the list into an in-process SDK MCP server named hbcode, so Claude sees each tool as mcp__hbcode__<name>. A duplicate name or an input schema that is not an object fails the open.

The list depends on the settings. send_mobile_notification is there only while notifications are on, and synthesize_speech, create_explainer_video, and extract_video_context only with a Gemini key.

When Claude calls a tool, the SDK handler checks the arguments against the full schema, makes a new requestId, and emits toolCall. Then the handler waits. The event can’t choose its target. The desktop rejects a toolCall with any field besides requestId, toolUseId, tool, and arguments, and it routes the call by the session and the run that own this host. A rejected event or a second call with the same requestId fails the run.

Each call runs in a task of its own beside the run loop. A slow tool therefore can’t block Stop, approvals, timeline rows, or the result of another tool. The task runs the shared tool handler with Claude’s tool use id as its call id and then sends toolResult itself. A tool that fails returns a result with success false, and Claude sees a tool error. If the toolResult request fails, the run fails.

When the SDK aborts a call or the run stops, the host answers the handler with “Run stopped.” and emits toolCancel, and the desktop aborts that task. A result that crosses the cancel is ignored. At the end of the run the desktop stops every task that is left. In the timeline the desktop makes the title of an HB Code tool row from its request, for example “Create session” or “Revise explainer video”.

History and the shared timeline rows #

The desktop never reads Claude’s transcript files itself. The host reads them with getSessionMessages and returns pages of at most 100 complete messages. It joins adjacent assistant envelopes that have the same API message id and drops messages with nothing to show. A page boundary is a message uuid, and when that message is gone the reply asks the desktop to reload. A conversation without a transcript loads as empty. The SDK returns a compacted conversation from its last compaction on, so older turns of such a conversation don’t appear in HB Code. A command’s full output is read on demand through toolOutput, also for a subagent, the same way a Codex protocol output is read.

The cursor for older pages is a JSON object with session, before, anchor, and revision, at most 4096 characters long. The desktop checks it against the conversation or the subagent that it pages. A cursor for another target fails with a conflict that asks you to reload the conversation.

Reads are not cheap. Every transcript read starts a one-shot host, and getSessionMessages reads the whole transcript, because the SDK call has no range. A timeline load runs two hosts side by side: one for the page and one for the subagent list. A delivery proof is one messageSaved read. During a run the host of the run answers it. After the run a one-shot host answers it.

The Claude adapter projects each message into the same timeline rows that Codex uses. A row takes its identity from stable data only, so the saved row replaces the live one in place.

The SDK sends a final envelope for each content block. Such an envelope replaces its own text fragment, so a delta is never added twice. Saved rows sort by their position in the transcript, and live rows by arrival. A live view also sends the rows that it showed before and no longer shows, so every client removes them. A live prompt row exists only for a message that HB Code sent. Its row shows the display text and the attachments from claude_operations. The text that Claude gets is longer, because the desktop adds the skills context and the attachment paths. Every other prompt shows from the saved transcript.

Find and continue a saved conversation #

To continue an existing Claude Code conversation, the desktop lists the saved conversations of exactly that workspace folder, newest first. The host calls listSessions with includeWorktrees false and includeProgrammatic false. A conversation from another checkout or worktree can’t resume in this folder, so it isn’t listed. A page holds 25 conversations by default and 100 at most, and its cursor is an offset into Claude’s own sorted list. Each row carries linkedAppSessionId when an HB Code session already owns the conversation. A title shows only when it says more than the first prompt.

A preview reads one page of the transcript. It binds nothing, writes nothing, and has no older pages.

When you continue, inspect must find the transcript in this exact folder. The new session takes Claude’s own name for the conversation, the custom title or else the summary. The table claude_sessions then binds the two ids. It has one row per session, and native_session_id is unique. A conversation therefore belongs to at most one HB Code session, and choosing it again opens that session instead of a second one. If that session belongs to another folder, the request fails with a conflict that names the session. A copy of a session gets a new conversation id. Transcript reads need no sign-in, and they always run with the default account’s folder.

Models and effort #

The model list comes from a one-shot catalog host, one read per account and workspace folder. The desktop keeps a list for 10 minutes and clears all lists on a sign-in, a sign-out, an account switch, and an account removal. Claude lists aliases such as default and opus beside pinned model ids. The desktop keeps one row per resolved model id, and the alias default only marks the model that the account recommends.

A model’s default effort is high when the model offers it, and otherwise its first level. A model without effort levels gets the effort default, and open then carries no effort field. A new conversation starts with the recommended model. A continued conversation starts with the model that answered last, if the catalog still has it.

Live runs, delivery proof, and approvals #

agents/dispatch sends a queued message to the adapter of the session’s agent. A Claude session can’t replace the latest turn or use a speed mode. It can steer a running turn. A session has one active Claude run at a time. The registry RUNS holds one run per app session, and a second run fails with “The Claude session already has an active run.”

The run opens the host with the session’s model, effort, and permission mode, records the operation, and then sends the text. The record is one row in claude_operations with a new UUID for the message. The insert keeps an existing row, so a retry of the same operation keeps the first UUID. A retry with another text or other attachments fails as a conflict. A retry from another run reads the transcript first. When the transcript has the message, the run sends nothing and the operation counts as sent. When it does not, the operation moves to the new run and goes out with the same UUID. The host of the earlier run has stopped, so Claude can’t take the message from it any more.

A message that you send while the run is active is a steer. The run loop owns every write to the host, so the steer goes to the loop. The loop records the operation with a UUID of its own and sends it. Claude reads the message after its current step, between two tool rounds. When the turn ends first, the message starts the next turn of the same run. The outbox entry stays sending with an acceptance that names the run, the Claude session ID as the thread, and the Claude ID of the message that started the run as the turn. A steer that finds no active run, or a run other than the one it names, is deferred, and the message stays queued.

Stop and send now takes a joined message back. The loop sends cancel to the host. When Claude has not started the message, the desktop stops the run and sends the same operation as a new run. When Claude has the message already, nothing is sent again.

Claude’s live stream never echoes the prompt, and a stdin write or a delta is never proof of delivery. Claude saves the message that starts a run before it calls the model. So the first message frame after send starts one transcript read. After a read that found nothing, each frame that names the message starts another. A frame names a message in user_message_uuid or user_message_uuids, or as a command_lifecycle frame with the state started or completed. The thinking counter and the idle frame start none. Claude saves a joined message later, with its next reply. So the frame that says that Claude started the message starts a read, and each of the next 3 replies of the conversation starts one more. When a read finds a message, the saved row appears first and the outbox row goes after it. At run end, one more read for each message without proof is the final proof, also for a stopped or failed run. A message that started the run and that no read finds is never sent again automatically. A joined message that no read finds returns to the queue.

When Claude asks to use a tool, the host holds the SDK’s canUseTool promise and sends a permission event. The desktop shows the same approval card as for Codex, with Accept and Decline and no other decision. A Bash call is a command approval, and every other tool is a permissions approval. A phone answers through run.chatResolveApproval, and the dispatch lets the Claude adapter answer first when it holds that request id.

• Reason text: for ExitPlanMode the card shows “Claude wants to carry out this plan:” and the plan. For Bash it shows Claude’s own description of the command. For another tool it shows the description, or else the tool name with its file path or URL, or else the tool name with its input as JSON.
• Subagents: a subagent’s request starts with “Requested by” and the name that the agents list shows.
• Answer: the adapter checks the thread, the turn, the item, and the decision. When no run holds the request any more, the answer fails with “The Claude run has ended.”
• Decline: Claude gets “The user declined this action.”, and the tool row becomes Tool declined.
• Stop: the host denies every open request and stops every open HB Code tool call with “Run stopped.” The end of the run marks the remaining cards as cancelled.
• Questions: a question never holds the run. A PreToolUse hook in the host answers AskUserQuestion at once in every permission mode, and Claude gets the notice that the question is shown and that the answer arrives as a later message. The timeline shows the call as a “Question for you” row, its options put an answer in the composer, and phones get a notification. No card opens.
• Duplicates: the host denies a second request with a request id that is still open.

The run loop, failures, and Stop #

After send, one loop owns the run. It waits on seven inputs at the same time and handles the one that is ready first.

Two message frames get special handling. The result frame records the success or the failure of the turn, and the loop goes on. The idle state ends the loop, with one exception. Claude can report that it rests just before it reads a message that arrived at that moment, and it then starts a turn for that message. So when a joined message still waits for Claude and the run has no failure, the loop goes on and waits 10 seconds for the next frame.

The exit order is fixed, whatever ended the loop.

1. The desktop closes the event channel and stops every tool task that is left.
2. It shuts the host down: close, 3 seconds, stdin closed, 10 seconds, kill.
3. It marks every open approval card as cancelled.
4. It settles every subagent view that is still open: as aborted after a stop or a failure, and as completed otherwise.
5. It runs the final proof reads: first for each joined message without proof, then for the message that started the run.
6. It sends the terminal event of the run: aborted, failed with the reason, or completed.
7. It returns each joined message that the transcript does not have to the queue.

Then the desktop forgets the account’s usage reading, finishes the run in the run registry, and removes it from RUNS. The send boundary decides what a failure means. ProvenUnadmitted says that Claude did not get the message. AdmissionUncertain says that Claude can have it, so the saved history must decide before a retry.

The reason of a failed result comes from Claude’s errors list, or from its result text for API errors such as a missing sign-in. A failed run keeps its reason in the desktop error log under claude_run, with the session, run, and operation ids. Packaged apps discard standard error, so the log line alone would be lost.

A cancel answers only for the exact run id. It sets the stop flag and waits until the run reports that it is done, which happens after the host has exited. If the run’s task died and can no longer report, the cancel itself shuts that host down, finishes the run, and removes it from RUNS.

The shared run registry reclaims a run as stale when it shows no activity for 45 seconds. A Claude host can need longer than that to open a conversation, and the first heartbeat comes only from the loop. So the registry asks the Claude adapter first, and a run whose exact host process is alive is never reclaimed.

Subagents as child threads #

Claude subagents use the same list, timeline, and live paths as Codex child threads. During a run, Claude reports each subagent through task events and forwards its turns with the id of the spawning tool call. Only a task_started event with the task type local_agent makes a subagent. The adapter sends the forwarded turns to the subagent’s own view. The call that started the subagent and its result leave the parent’s view, so no row stands for the subagent. A subagent that the conversation started has depth 1, and each nesting adds 1. A live subagent carries no parent id, so the depth of a nested subagent is known only from its saved transcript.

A workflow is a script that the conversation starts with one call of the Workflow tool, and the script starts subagents in phases. The running turn follows a workflow as one task: a task_started event with the task type local_workflow, which gives the id of the starting tool call, the workflow name, and a summary. The later task events of that task change its status as the table above shows. Claude does not forward the turns of a workflow’s subagents, and no task event names them. They appear in the list only through their saved files.

The saved files are the source for every subagent that the running turn does not report, and after the run they are the only source. The SDK gives the list of subagent ids and each transcript. The host also reads three kinds of Claude files itself, because the SDK exposes none of them.

Claude names a project folder after the working directory by a rule of its own. So the host looks in every folder under projects in CLAUDE_CONFIG_DIR, or under ~/.claude/projects, for a folder with the session id that has a subagents folder with entries. Each reader returns nothing when a file is absent or has another shape, and the list then shows fewer facts.

One subagents request reads all of this in a one-shot host. A transcript read costs the full file, so the desktop names what it already holds, and the host reads only the rest. The desktop keeps these facts per conversation until it quits.

The host decides the outcome in this order. The run record says completed for the state done and failed for the state error. Otherwise a last message with the model <synthetic> is an API error and means failed. Otherwise a last assistant message with stop_reason end_turn, with text, and with no tool call means completed. Text that comes before a tool call in the same turn does not finish the subagent. Otherwise a subagent of a run that has a record is stopped, because the run ended before the subagent did. Every other subagent has the outcome null.

A workflow run takes its name, summary, phases, status, start, and duration from its record. A run without a record is still open. The line “Run ID:” in the result of its Workflow call then links the run to that call, and the line “Summary:” gives its summary. Its name and its phase titles come from the meta statement of its script.

A workflow gives each subagent its task inside a frame. A frame is one line that starts with “[Workflow harness — user request]” or “[Workflow harness — computed task]”, and the text follows with each line indented by two spaces. The host removes the frame line and the indent for the task field. subagentHistory returns the computed task without its frame and leaves out the framed user request, because the conversation already shows that request.

The desktop then gives each subagent a status. The first rule that applies wins.

1. The running turn of this session reports the subagent as a task: the status of that task.
2. The files give an outcome: completed is Completed, failed is Errored, and stopped is Interrupted.
3. The subagent belongs to a workflow that the running turn reports as running: Running.
4. The last transcript message is less than 10 minutes old, and it is later than the end of this session’s last run in this desktop run: Running. Another Claude app can run the same conversation, so recent activity is the only sign.
5. Otherwise: Interrupted.

The 10 minutes come from Claude’s longest normal silence, a shell command, which Claude stops after 10 minutes at most. A workflow run takes the outcome of its record, or else the status of its task in the running turn, or else rule 4 with the latest activity of its subagents. A subagent that the turn reports and that has no transcript yet is added to the list from its task event. Subagents that are still open when a run ends stop with it, so activity from before that end does not count.

The list result uses the agent thread contract that Codex child threads use. Claude fills fields that Codex leaves empty.

No timeline row stands for a subagent or a workflow. The call that starts one and its result leave the view, and the agents list shows the subagents and the workflow runs. A task event that changes the list, and the end of a run with open subagents, send the agent-threads signal. Each client then loads the list again. On the desktop, the agents list groups workflow subagents under their workflow and phase and shows model, effort, tokens, tool calls, and duration.

Accounts and usage #

The default account is this computer’s Claude sign-in and runs with Claude’s own folder. That folder is ~/.claude, or the folder in the desktop’s own CLAUDE_CONFIG_DIR. Each added account is a folder claude/accounts/<uuid> in HB Code’s local application data. It keeps its own sign-in and links every other entry to the main folder. All accounts therefore read and continue the same sessions with the same settings, and a switch changes only who pays for a turn.

The setting agent.chat.claude_account_id names the active account, and no value means the default account. The next turn runs on the active account, and a removed account leaves the default account active. The desktop makes the links before every start of a Claude process. It creates projects in the main folder first, so an added account never starts a transcript store of its own. A projects link that fails stops the start. Any other link that fails is only logged. On macOS each link is a symbolic link. On Windows a folder gets a directory junction, and a file gets a symbolic link, or a hard link when Windows refuses the symbolic link, so no Developer Mode is needed.

HB Code runs Claude’s own sign-in commands for one account folder. It never reads a token or runs its own authorization flow.

Usage comes from the SDK: the rolling five-hour window and the weekly windows. The weekly window for third-party apps is left out. An API-key account has no plan windows. The usage host loads no settings and skips the scan of local transcripts. Usage is read only for a signed-in account, and a read that fails shows as an error text on that account while the list still loads. For the weekly windows per model, the server’s own labels come first, and the fixed Opus and Sonnet fields fill in a model that it did not list. Reset times are rounded to the nearest minute, and each reading goes to the usage history. The sidebar, the settings page, and the phones share one reading per account per minute, and a finished run clears that account’s reading.