Repository navigation
docs(unstable): clarify subagent message views, unknown state, and session references - #2801
Merged
Merged
Conversation
Open
benbrandt
added a commit
to agentclientprotocol/claude-agent-acp
that referenced
this pull request
Nov 12, 2026
…ence children from tool calls (#1608) 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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Clarifies points in the Subagent Sessions RFD that came up while bringing the Claude Agent and Codex adapters in line with it. None of these change the wire format. The feature stays behind
unstable_subagents.RFD
senderSessionIdwhen the Agent has no evidence of the sender. The Agent must not assume the parent.unknownstate. It also applies when the Agent itself stops tracking a child that may still be working. The child's unfinished tool calls, terminals, and v2backgroundlist stay as last reported. The Agent must not invent final statuses, and the Client must not present them as confirmed live or as failed.unknown. The Agent can revoke them in the samesubagent_update.Draft guides and schema descriptions
prompt-turnand v2prompt-lifecycledraft pages cover the sender-less incoming view and the linking rule.tool-callspages cover resending session references and resolving handles.UnknownStateUpdatedescription in v1 and v2 said "Capabilities are updated separately". It now matches the RFD and mentions unfinished tool calls and terminals. The unstable schemas and draft schema pages are regenerated.Stable pages are unchanged.
Related