e369479f93
A foreground fork can stream a copied `tool_result` for the Agent call that launched it. That placeholder completed the call and removed its tracked state, so the real report arriving later was dropped. Ignore only results whose tool ID equals the message's parent tool ID, keeping the launching call open for its actual report. Keep other results in the same message and discard the message-level `tool_use_result` sidecar when its launch result was removed, so it cannot be attributed to a remaining tool result. Regression coverage exercises plain and Air clients, root and nested launch results, and a mixed message containing a genuine nested Agent result. Fixes #1389. Validation: - [Linux CI](https://github.com/agentclientprotocol/claude-agent-acp/actions/runs/40217593917) passes the full suite: 3,304 passed, 32 skipped (57 test files passed, 4 skipped). All PR checks are green. - `npm run check` and `npm run build` pass. - `vitest run src/tests/acp-agent.test.ts --maxWorkers=1`: 712 passed, 10 skipped. The four new regression cases fail on the original code and pass with the fix. - Eight actual-SDK runs against localhost fake gateways complete successfully without model calls: plain and Air foreground forks, native Air child sessions, nested forks with the background option omitted or false, the SDK's fork-inside-fork rejection, a background launch receipt, and history replay. Foreground reports arrive exactly once and no launch-result tracking warning remains. The local full-suite run encountered 19 failures in `session-index.test.ts` and then stopped progressing, so it was interrupted. A standalone recursive-file-watcher probe also emits `EMFILE` on this machine. The successful Linux CI run above provides the complete-suite verification. Review dependencies (updated 26 October): | Related proposal | Relationship to this PR | | --- | --- | | [#1408](https://github.com/agentclientprotocol/claude-agent-acp/pull/1408) — targeted session lookup | Independent. Both orders merge cleanly onto the checked main and produce the same tree. | | [#1422](https://github.com/agentclientprotocol/claude-agent-acp/pull/1422) — resumed subagents | Complementary, with no dependency on this PR. It now conflicts with upstream main in `src/acp-agent.ts`; its author needs to resolve that conflict, integrate the [separately shared AIR routing patch](https://github.com/agentclientprotocol/claude-agent-acp/pull/1422#issuecomment-6401008862) and complete its validation. | <details> <summary>Additional local integration validation — 25 October</summary> A local combination of the recorded main, #1408, #1431, #1422 and the already-reviewed routing patch passed 199 focused foreground/resume/native-subagent checks (647 other cases filtered or skipped), TypeScript build, and two replays of previously captured SDK frames for AIR and standard subagents. The two captured-frame replays were independently repeated. No new model calls were made. The combination is a private test tree, not a published change. It does not replace full CI for #1422 or live Air acceptance. The routing patch needed three-way application against that recorded main because its surrounding source had moved; it applied cleanly that way. The current-main conflict in #1422 means this historical result does not establish today’s combined compatibility. Checked main `739dde3`, #1408 `e3b3aa4`, #1431 `8f96f46`, #1422 `dd3bf2c`. The two orders of #1408 and #1431 produce tree `1716d7e`; the full local test tree is `61c0447`. Refresh this evidence if these inputs change. </details> Co-authored-by: Codex <codex@openai.com>
ACP adapter for the Claude Agent SDK
Use Claude Agent SDK from ACP-compatible clients!
This tool implements an ACP agent by using the official Claude Agent SDK, supporting:
- Context @-mentions
- Images
- Tool calls (with permission requests)
- Compact file changes through the negotiated AIR diff patch extension
- Following
- Edit review
- TODO lists
- Nested subagent transcripts
- Interactive (and background) terminals
- Custom Slash commands
- Client MCP servers
/mcpin the chat: the MCP server status as a list. The adapter runs/mcp reconnect,/mcp enable, and/mcp disablethrough the SDK control API, because Claude Code refuses them in SDK mode. A reconnect of an ACP server that needs authentication starts MCP OAuth through URL elicitation- Session-scoped long-running goals for AIR through the goal extension under
_meta.jetbrains.air.goal - Structured errors, recovery, and warnings through the opt-in session failure extension
- Concrete model and effort defaults through the opt-in recommended config value extension
- Tool permission presentation, editable choices, and durable effects through the permission extension
- One fact per field in every tool call report, as the ACP tool call contract defines
- All AIR extensions, capabilities, and
_metakeys: AIR extensions
Learn more about the Agent Client Protocol.
To try changes that have landed on main but are not released yet, install from the
preview channel — every push to main publishes one. See
docs/RELEASES.md.
npm install @agentclientprotocol/claude-agent-acp@preview
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.- 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 draft 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
- The message of a SendMessage call that resumes the child is a
session_messagein the child's transcript. The SendMessage call stays a tool call of the session that made it. 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 isidlewith no stop reason.- 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 as live, and its end is an
idlebefore 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.
Experimental ACP v2
The adapter also serves the draft ACP v2:
a client that asks for protocol version 2 or later in initialize gets v2, and every other client
gets v1. The draft can still change, and this surface changes with it.
CLAUDE_AGENT_ACP_PROTOCOL limits the adapter to one version. With v1, a client that asks
for v2 is negotiated down to v1. With v2, the adapter rejects the initialize of a v1 client.
auto, the default, serves both.
On v2 the adapter serves the session baseline (session/new, session/list, session/resume
with replay, session/close, session/prompt, session/cancel), session/delete,
session/fork, additional directories, config options (the mode is one), plans, notices,
compaction, display terminals for commands, permission requests, elicitation, providers, auth, and
subagents. Steering and the AIR extensions are v1 only for now.
Contribution Policy
This project does not require a Contributor License Agreement (CLA). Instead, contributions are accepted under the following terms:
By contributing to this project, you agree that your contributions will be licensed under the Apache License, Version 2.0. You affirm that you have the legal right to submit your work, that you are not including code you do not have rights to, and that you understand contributions are made without requiring a Contributor License Agreement (CLA).