Repository navigation
Conversation
benbrandt
force-pushed
the
docs/subagents-preview
branch
from
November 12, 2026 14:58
50bbcc0 to
8c32489
Compare
benbrandt
changed the base branch from
main
to
docs/subagents-clarifications
November 12, 2026 14:59
benbrandt
force-pushed
the
docs/subagents-preview
branch
from
November 12, 2026 15:34
8c32489 to
7db34e3
Compare
benbrandt
added a commit
to agentclientprotocol/codex-acp
that referenced
this pull request
Nov 12, 2026
…en from tool calls (#760) Brings the standard subagent contract 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 AIR legacy contract is unchanged, and its fixtures are untouched. ## Changes - **Delegated tasks are `session_message` views**, live and on replay, for v1 and v2. - A `userMessage` item in a child's thread becomes the incoming view on the child. It was dropped before, and counted as a history gap on replay. - A completed `spawnAgent`, `sendInput`, `sendMessage`, or `followupTask` with a prompt becomes the outgoing view on the sender. Failed or interrupted calls report nothing. - The two views are linked with `senderMessageId` and `recipientMessageId` when the same text is seen for the same recipient on both sides. - **`description` no longer holds the task prompt.** It is the thread's `agentRole`, and is omitted when Codex reports none. - **Collaboration tool calls carry `session` content** for each already-announced receiver. `spawnAgent` stays hidden, because the announcement and the task message report the delegation. - **No Agent-side capability for standard Clients.** `sessionCapabilities.subagents` is sent only to AIR, whose contract documents it. The RFD defines no Agent-side capability. - **SDK `~2.6.0`**, which types `session` content. It also adds `configOptions` to v2 `session/new` and `session/resume`. The adapter does not advertise initial config options, so it does not apply them. - **Docs.** `docs/subagent-sessions.md` now describes the standard contract, the AIR legacy contract, and the fallback separately. The README, `readme-dev.md`, and `docs/air-extensions.md` are corrected. ## Workarounds and limits - **Linking by text.** Codex exposes no ID shared by the sender's collab item and the receiver's `userMessage` item, so views are matched by recipient and equal text. If Codex rewrites the prompt on delivery, the views stay unlinked. - **Sender-less incoming views.** `userMessage` items have no sender field, so an unlinked incoming view carries only `recipientSessionId`. The adapter does not assume the parent, since another session can also send input. - `description` is the raw role token, for example `default`. - The unlinked-view lists are not pruned during a session. ## Testing - `npm run typecheck`: clean. - `npm test`: 159 files passed, 7 skipped. 2512 tests passed, 39 skipped. - New live and replay delegation snapshots for v1 and v2. Not run against real Codex.
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 branch has not been deployed
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.
Moves the Subagent Sessions RFD from Active to Preview.
Stacked on #2801, which holds the RFD and draft doc clarifications. This PR only contains the lifecycle move.
docs/docs.json: moverfds/subagentsto the Preview group.docs/rfds/updates.mdx: add the Preview lifecycle entry.docs/rfds/subagents.mdx: add the revision history entry.The feature stays behind
unstable_subagents.Implementations checked
The schema covers ACP v1 and v2, and the Rust SDK 5.2.0 and TypeScript SDK 2.6.0 carry the types. I checked the RFD against three implementations on their main branches:
subagent_updatewith state,cwd, and per-child cancel, linkedsession_messageviews, child configuration, and replay.subagent_updatewith state (includingunknown),cwd, and per-child cancel, child configuration, and replay. feat: report delegated tasks as session messages and reference children from tool calls codex-acp#760 adds session-directed messages andsessiontool call content.acp-betaflag): the Client side, including linked session-directed messages andsessiontool call content.No Agent sends
session_message_chunkoradditionalDirectoriesyet.