Brings the RFD form of subagent reporting in line with the ACP [Subagent Sessions RFD](https://agentclientprotocol.com/rfds/subagents), which is moving to Preview in agentclientprotocol/agent-client-protocol#2800. The related RFD clarifications merged in agentclientprotocol/agent-client-protocol#2801. AIR output is unchanged, and no scenario snapshots changed. ## Changes - **`unknown` at a conversation reset.** A child that is still working at `conversation_reset` now reports `unknown` and `capabilities: null`, not `idle`. The adapter forgets its children at reset, so it can no longer observe or stop them. v1 reports it on the parent's `subagent_update`. v2 also sends `state_update` `unknown` on the child. - Stream end, stream error, `queryEnded`/`retire`, and `worker_restart` keep `idle`, because the work is known to have stopped. - In v2, the forgotten child's unfinished tool calls keep their last status. They are no longer forced to `failed`. - **`session` tool call content.** Added live and in replay, for the v1 RFD form and v2, only when the child is already announced: - `TaskStop` whose `task_id` is a child's agent id. - `SendMessage` that stays visible and targets a child's agent id. - v1 only: an Agent/Task launch that a permission request keeps visible. - The reference is repeated on every update that carries content, because `content` replaces the whole array. - **Docs.** The README's subagent section matches the code: SendMessage is hidden and reported as linked messages, `unknown` at reset, `session` content, and no `session_message_chunk`. Three stale comments are fixed. ## Workarounds and limits - **Post-response ordering still uses `setTimeout(0)`.** SDK 2.6.0 gives `onRequest` handlers no responder or after-response hook. The comments in `src/v2/agent.ts` and `src/v1/acp-agent.ts` now state what the ordering relies on: the response is queued in the microtask after the handler returns, and `Connection.sendMessage` is first-in, first-out. The SDK does not promise this. - **The `unknown` change assumes Claude Code keeps subagents running across `/clear`.** That comes from the existing v2 comment and test double. It was not checked against the real CLI. - No reference is added when a tool names a child by agent name, or for v2 launch calls that a permission request shows. - A child that is idle at reset keeps its `cancel` capability. Unchanged here. - A stream error with a client-supplied `spawnClaudeCodeProcess` still reports `idle`, although closing may not stop a remote CLI. ## Testing - `npm run build`: clean. - `npm run check`: clean. - `npm run test:run`: 73 files passed, 5 skipped. 4117 tests passed, 33 skipped. - Integration tests against the real CLI were not run.
7.5 KiB
Subagent sessions
A client that declares clientCapabilities.subagents, other than JetBrains AIR, gets each Agent or
Task subagent as its own child session, following the subagents RFD:
subagent_updateon the parent announces the child before any of its traffic, with the parent'stitleanddescriptionfor it, and reports its work state:running,requires_actionwhile one of its requests is open (andrunningagain when the last one ends, unless a cancel withdrew it: the child is stopping then), andidlewhen its work ends, withend_turnorcancelledwhen the SDK gives the reason. A failure isidlewith theerrorstop reason and the SDK's error text as itserror. The child keeps its session for every delegation to it.- A child that still works when Claude Code starts a fresh conversation, such as for
/clear, isunknown, and loses itscancelcapability. Claude Code can keep such a child running, but the adapter forgets the children of the old conversation, so it reports nothing more for it and cannot stop it. Its unfinished tool calls keep their status. An idle child keeps its state. - A child that runs outside its parent's working directory, such as an Agent call with
isolation: "worktree", gets itscwdonsubagent_updatebefore its first tool call. The adapter takes it from thecwdof the child's own hooks: its SubagentStart hook runs before its first model request. It sendscwd: nullwhen the child is back in its parent's directory. A child in its parent's directory gets nocwd, and no child getsadditionalDirectories: Claude Code gives a subagent the session's additional directories, so it inherits them. A replay announces a child with thecwdthat its transcript recorded, and clears it after the response when that directory no longer exists. - Session messages replace the Agent or Task call that launches the child, which its parent is
not shown:
- The launch's prompt is a
session_messagein both transcripts: the parent's outgoing view and the child's incoming one. Both use the launch's tool use id, and each names the other with the RFD'srecipientMessageIdandsenderMessageId. - A foreground child's answer, from the launch's result, is the child's
session_messageto the parent. In Claude Code's hand-back mode, the child'sSubagentHandbackcall is its message to the parent instead, in both transcripts and linked the same way. - A launch whose child is never exposed is shown as a tool call after all, with its final status.
- The launch's prompt is a
- A SendMessage call that resumes the child is not shown either. Its message is a
session_messagein both transcripts, the sender's outgoing view and the child's incoming one, linked like a launch's prompt. A SendMessage call whose message resumes no announced child, such as one to the parent, is shown as a tool call, with its final status. - Every message is one whole
session_message. The adapter sends nosession_message_chunk: it has each message's full text before it reports it, from the input or the result of the tool call that sent it. - A tool call that the client is shown and that operates on an announced child of another session
carries the RFD's
sessioncontent,{ "type": "session", "sessionId": "<child>" }, after its other content: a TaskStop call whosetask_id, or a SendMessage call whoseto, is the child's agent id; a SendMessage call that resumed the child and stays shown because a permission request showed it first; and, on v1, an Agent or Task call that stays shown for the same reason. Atool_call_updatewithout content carries none, since it would replace the content the client holds. A call that names the child by its name gets no reference: Claude Code resolves the name, and the adapter cannot tell which agent it picked. session/cancelon the parent interrupts Claude Code, which stops the foreground children that the turn waits on. Background children keep running, as the RFD prefers; a client stops one with its owncancel. Each stopped child reportsidlewithcancelledfrom Claude Code's own events, and its open requests are withdrawn. The adapter ends no child at a cancel itself, so a child that keeps running keeps its open requests and its open tool calls. To spare background children, the adapter declares the SDK optionperTaskStopAffordance, which a client can turn off in_meta.claudeCode.options. That option spares background workflows too, which a client cannot stop, so the adapter stops them after the interrupt, as Claude Code did without it. Background commands keep running after a cancel either way. A tool call of a stopped child that Claude Code reports no result for, such as the command it was running, ends in the child's session before the cancelled prompt resolves. When Claude Code stops a background child after that, or while no prompt runs, the tool call ends right after the child reportsidle. A child that still runs when Claude Code exits isidle, since its work ended with the process: with no stop reason on v1, and on v2 with theerrorstop reason and the error that ends the root's work.- A child whose parent is not yet known when it ends is not exposed, since the RFD forbids guessing its parent.
- A replay restores each child under its live session id, from its own transcript, with the same
session messages and
sessionreferences as live, and its end is anidlebefore the response. Each replayed child's current state follows the response. A launch without Claude Code's metadata file for the child stays an ordinary tool call of the parent, and a notice, for a client that takes notices, says that subagent history is missing. - After a load or resume, with or without replay, a SendMessage that resumes an agent from before it runs that agent in its session from before. Before the agent's traffic, each of its ancestors that the client was not told about in this connection is announced, parent before child and with no work state, as the RFD requires. An agent whose launch the session's history does not record stays unexposed.
- Each running child is announced with the
cancelcapability.session/cancelwith the child's session id stops that child's current work, through the SDK'sQuery.stopTask, and not its parent's: Claude Code also stops the foreground children it waits on, and the parent's turn goes on. Each stopped child reportsidlewithcancelledfrom Claude Code's own events, and its requests that the stop withdraws report norunningfirst. A replayed child, which no longer runs, gets no capabilities. A client cannot prompt or otherwise change a child.
An ACP v2 client gets the same without declaring anything, since subagents
are part of v2's baseline. Each child also reports its work state as its own state_update, right
after the parent's copy.
JetBrains AIR keeps the earlier draft of the RFD (subagent_spawned, subagent_state_update),
which it enables with nativeSubagentSessions in _meta.jetbrains.air.capabilities. See
AIR extensions.
Without either signal, Agent and Task stay ordinary tool calls and child interactions stay on the
root session. Clients that use the historical _meta["subagent-transcript"] capability or the
forwardSubagentText session option retain the flattened child transcript.