A heartbeat of a running Agent call reports under a synthetic id, so the
adapter falls back to parent_tool_use_id, which is the Agent call itself, and
also stamped that id as the beat's parentToolUseId. For a client on the
subagents RFD, which sees the Agent call, the beat and every later update of
the call then went to the child session. Found in a live run with a 40-second
subagent.
The same run showed that Claude Code's interrupt currently stops background
subagents too, so the README and comments no longer say they keep running.
The previous commit stopped a cancel from clearing each tool call's state, so
that a raced tool call of an RFD client's background child stays on the root.
For AIR that let a later update of an ended child's permission tool call reach
the child's session after subagent_state_update cancelled. Only the RFD form
keeps the state now.
Two MUSTs of the subagents RFD that rare event orders broke:
- A child is announced before any traffic that names it, and never under a
guessed parent. An Agent call made inside a child that was known but not
yet announced registered that child as the parent, so the nested child
was announced under it before the child itself was; and one made inside a
child not known yet fell back to the root. In the RFD form, such a call
now establishes no parent: its update is buffered under the child's tool
use, as before, and routed again once the child is announced, which
registers the parent and announces the nested child after it.
- An interaction already issued never moves to another session. A cancel
cleared the session of every eagerly emitted tool call, a relic of when a
cancel ended every subagent. A background child keeps running after a
cancel (agent-client-protocol#2308), so a tool call of its that a
permission request emitted on the root before the child was announced
then moved into the child, for example with its next progress beat. A
cancel now keeps the per-tool-call state (the session, the fields the
client holds, the hook callbacks); each tool call drops it when it ends,
and the cancelled turn's own tool calls end through their results or
closeUnfinished.
The subagents RFD reports a failure that ends a child's foreground work as
`idle` with `stopReason: "error"` and, when available, the failure as a
JSON-RPC `error` (agent-client-protocol#2281). SDK 1.8.0's v1
`IdleStateUpdate` has that variant, so the stand-in
`_meta.claudeCode.error` goes: a failed child is now idle with the `error`
stop reason, and with the SDK's error text as an internal error, the code a
failed turn uses on the v2 surface.
## Problem
A v1 report's `_meta` belongs to that report, and the agent gives each
report its own `_meta.claudeCode` keys. A v2 client stores a tool call's
`_meta`, and any report that carries `_meta` replaces it
(`tool-calls.mdx`; the migration guide since
agentclientprotocol/agent-client-protocol#2355). So a v2 client kept
only the last report's keys. For example, a result's `{ toolName }`
replaced the denial reason that came before it. On top of that, a
PostToolUse hook stored the whole `tool_response` in `_meta`, which for
a Write is the whole file text.
## Change
All of this is v2 only. No v1 or AIR output changes, and no v1 golden
changes.
- **Stored `_meta` (`src/v2/tool-call-meta.ts`).** The v2 bridge keeps
each tool call's `_meta` the way the client stores it. `claudeCode` keys
merge one by one, and every other key replaces whole, the same model
`ToolCallFieldTracker` uses.
- A report that changes the stored `_meta` carries all of it.
- A report that changes nothing carries no `_meta`, which leaves the
stored value unchanged.
- A permission request's subject always carries the stored `_meta`,
since a client can show the request on its own.
- The tool call's first report starts from nothing.
- **`toolName` becomes `name`.** `claudeCode.toolName` repeats the
tool's name, which v2 has a field for. It becomes the `name` of a tool
call that has none yet, and is left out otherwise. A memory recall gets
a `name` this way. Subagent routing still reads `toolName` on the
agent's v1 reports, before the bridge.
- **The `toolResponse` AIR gets.** A v2 client also keeps `_meta`, so it
gets AIR's trimmed `toolResponse`:
- a hook carries only the `status` and `isAsync` markers, not output the
content already shows;
- a denial carries the SDK message only when it differs from the reason.
## Evidence
- **v2 goldens:** 28 change. Most only lose `toolName`. Hook reports
lose the repeated stdout or file text. Memory recall gains `name`. The
denial keeps its reason type and message. Subagent tool calls and their
permission subjects keep `parentToolUseId`.
- **Live, CLI 2.1.293 on Haiku, v2:** a Write and a Bash command arrived
with `name` on their first report and no `_meta` at all.
- **Tests:** 7 unit tests for the stored `_meta`.
- **Mutation checks:** removing any of these 9 rules fails at least one
test:
- naming once;
- leaving `toolName` out;
- merging with earlier `claudeCode` keys, which also fails the
`subagent-late-child-update` golden;
- keeping other keys;
- omitting unchanged `_meta`;
- starting fresh;
- the subject's stored `_meta`;
- the bridge wiring;
- the trimmed `toolResponse`.
Forgetting a closed session's tool calls is memory cleanup that no test
observes, like `V2Terminals.forget`. A limit of 2048 tool calls also
bounds the memory.
- `npm run check`, build and all 2820 tests pass.
## Problem
The v1 schema says a forked session is active once the agent responds,
and can be prompted without `session/load` or `session/resume`
(agentclientprotocol/agent-client-protocol#2359). `session/fork` only
copied the transcript, so prompting the new id failed with "Session not
found" until the client loaded or resumed it.
## Change
- **The fork starts the new session the way a resume does.** It starts
from the copied transcript, with the model and the permission mode that
transcript records, and with the request's `cwd`, MCP servers,
additional directories and `_meta`. The response carries the session's
`modes` and `configOptions`, and the available commands follow it, as
for `session/new`.
- **A client that loads or resumes after a fork keeps working.** A later
`session/load` replays the history into the running session, and a later
`session/resume` returns it. Neither starts a second Claude Code
process. A load or resume with other settings restarts the session, as
for any loaded session. The fingerprint that decides this ignores the
AIR fork point in `_meta`.
- **Cost:** each fork now starts a Claude Code process. That added about
0.65 s to the fork response in the live run.
- **v2:** the v2 fork used to resume the forked session itself. It now
uses the session that the v1 fork starts, so the v2 bridge drops its own
resume.
- **AIR docs:** `docs/air-extensions.md` now says, under the session
fork point, what a load or resume after a fork does.
## Evidence
**Live, CLI 2.1.293 on Haiku, over v1:**
1. A new session answered "Remember the codeword PELICAN" with `OK`.
2. `session/fork` returned the fork with mode `auto` and the `mode`,
`model` and `effort` config options.
3. Prompting the fork right away returned `PELICAN`, with no load or
resume in between.
4. A `session/load` of the fork then replayed its history and was ready
in 4 ms. The timing log shows one session start for the fork and none
for the load, and a further prompt still answered.
**Tests:**
- New: the fork can be prompted at once, and its response carries modes
and config options; a later resume and load reuse the session; and the
fork fails when its session can't start.
- The existing fork tests now also check that the session starts from
the fork, with the request's additional directories.
- The v2 fork tests pass unchanged.
- **Mutation checks:** removing the start, the response's `modes`, or
the additional directories each fails a test.
- `npm run check`, build and all 2813 tests pass, with no golden
changes.
## Summary
When the user approves a plan through ExitPlanMode, a v2 client now gets
it as the session's markdown plan. The update uses the draft's unstable
plan operations:
```json
{ "sessionUpdate": "plan_update", "plan": { "type": "markdown", "planId": "plan-mode", "content": "# Plan…" } }
```
Until now a v2 client saw the plan only in the "Approve Plan" tool call
and its permission request.
## Behavior
- **Its own plan id.** The approved plan has the id `plan-mode`, and the
TodoWrite checklist keeps `plan`, so the client shows both. Claude Code
keeps one plan file per session and rewrites it on a later plan mode, so
each approval replaces the plan before it. Nothing removes it.
- **A normal approval** is a successful ExitPlanMode result. The plan
follows the tool call's result, live and on replay.
- **Live:** the plan comes from the tool's structured output, which
includes edits the user made to the plan.
- **Replay:** the SDK's `getSessionMessages` drops the structured
output, but the transcript keeps the `plan` that Claude Code adds to the
tool's input.
- **An approval that clears the context** ends the tool with an error
result. The restart into the fresh context publishes that plan, after
the new mode and config options and before the fresh context runs. It
does so only once that context exists, so a cancel or a failed restart
leaves no plan behind that was never carried out.
- **Not published:** a rejected plan, a subagent's plan
(`parent_tool_use_id` or `isAgent`), a plan still waiting for its team
lead, and an empty plan. Plans are trimmed.
- **Who gets it.** The agent sends plan operations only to a client that
advertises v1's draft `plan` capability, as the v1 draft requires. The
v2 bridge advertises it for every v2 client and passes `plan_update` and
`plan_removed` through unchanged, since the shapes match. No v1 client
advertises `plan` today, so v1 behavior doesn't change.
## Replay limits
- **After a "clear context" approval, replay doesn't show that plan.**
It reads the transcript from before the clear, where the approval is the
deny, so it shows the plan approved before that, or none. Replay never
reaches the conversation after a clear, so this is part of an existing
gap.
- **A plan approved before a compaction boundary isn't replayed**, like
the rest of the history before it.
- **Replay can't apply the subagent and team-lead checks**, since they
come from the structured output that `getSessionMessages` drops. A
subagent's transcript still carries its `parent_tool_use_id`, so it's
skipped.
## Evidence
**Live, CLI 2.1.293 on Haiku, through the adapter on v2 in plan mode:**
- **Normal approval:** the plan arrived right after "Exited Plan Mode",
and resuming with replay republished it.
- **"Clear context":** the plan arrived after the switch to auto mode,
before the fresh context's first tool call.
- **Raw SDK probe:** the structured result carries `plan`, `isAgent` and
`filePath`, and the transcript's tool use keeps `plan` and
`planFilePath`.
**Tests and checks**
- **Result path:** unit tests for each rule and for the order. They
include structured output versus input, input-only as on replay, and
structured output with no plan.
- **Restart path:** coordinator tests check that the plan comes after
the session state and before the continuation, that a client without the
capability gets none, and that a failed restart publishes none.
- **Agent:** a client that advertises `plan` gets the restart's plan,
and one that doesn't gets nothing.
- **v2:** a replay test and translation tests. The v2
`exit-plan-approve` golden gains the plan update. `exit-plan-reject` and
every v1 golden are unchanged.
- **Mutation checks:** removing any rule on either path fails at least
one test. That covers both capability checks, the agent's capability
wiring, success only, structured output first, the order, trimming, and
the `plan_removed` pass-through.
- `npm run check`, build and all 2810 tests pass.
## Problem
After a cancel, the consumer drops the main conversation's consolidated
`assistant`/`user` messages until Claude Code starts a model request
that serves none of the cancelled prompts (#1309). `stream_event` frames
skipped that check. Claude Code always streams, so when it had already
taken an abandoned prompt off its queue, the prompt's answer still
streamed to the client as deltas. Only the consolidated copy was
dropped.
That output arrives after the cancel has been reported: on v1 after the
turn's `cancelled` response, and on v2 after `idle cancelled`, outside
any cycle. Both protocol versions require an agent's updates to come
before that report. Streamed tool calls leaked the same way.
#1309's tests missed this because they scripted only consolidated
messages.
## Change
- **After the client has been told the stopped work ended**, while the
window is still open, streamed text, thinking and tool calls are dropped
like the consolidated messages they belong to. On v1 that report is the
turn's prompt response (no active turn). On v2 it's the idle state (no
open foreground work). The v2 signal also covers cycles that Claude Code
starts on its own and turns that v1 holds for their subagents.
- **Before that report**, what the interrupt flushes still streams, as
it does today. Both drafts allow updates between the cancel and the
cancelled report, and the text is in Claude Code's transcript, so a
reload shows it anyway. Existing tests pin this: v2's queued-prompt
cancel, a held turn cancelled mid-follow-up, and a cancel that arrives
during a buffered backlog.
- **A prompt that is merely queued no longer keeps the window open.**
#1309 held the window while any queued prompt was unsettled. So a
follow-up that Claude Code ran ahead of a prompt sent after the cancel
lost its consolidated copy, and with this change it would have lost its
streamed copy too. Now a request holds the window only when:
- the stopped turn is still unsettled;
- an abandoned prompt's result is still expected;
- the request names a cancelled prompt; or
- the request names an unsettled prompt. That covers one that arrived
while the cancel was still awaiting, before the cancel records it.
- **Per-block drop latch.** Where the consolidated message delivers the
text, a stream that loses a delta keeps dropping until its streamed-text
record resets: at the next message, or when a consolidated message
consumes the record. If a window closes mid-block (an older CLI's late
prompt echo), the record holds nothing, so the consolidated message
delivers the whole block once. Without the latch the record would hold
only the tail, which isn't a prefix of the text, and the client would
get the tail and then the whole text again. A client that gets subagent
text only streamed has no consolidated copy to fall back on, so its
subagent streams don't latch.
- Bookkeeping for dropped events (message id, usage, compaction
heartbeat) is unchanged.
## Evidence
**Tests**
- The "output after a cancel" suite now streams every answer the way
Claude Code does, with Claude Code's follow-up in two chunks. Without
the fix, 9 of its tests leak the streamed copy.
- New v1 tests:
- a follow-up that runs ahead of a prompt sent after the cancel;
- a prompt sent during the cancel whose request arrives before the
cancel abandons it;
- an echo in the middle of a two-block answer;
- a subagent stream for a client that gets subagent text only streamed.
- New v2 tests:
- an abandoned prompt's streamed answer;
- what the interrupt flushes of a cycle that Claude Code started;
- a held turn's follow-up that the cancel stopped before it showed
anything.
- **Mutation checks:** each of these fails at least one test:
- removing any of the window's four rules, or restoring #1309's hold for
any queued prompt;
- removing the drop;
- dropping the flushed tail before the report too;
- using the v1 signal on v2;
- removing the latch, either of its record resets, or the subagent
condition.
The exception is clearing the latch when a subagent finishes. That's
memory cleanup that no test can observe, like the
`streamedBlocksByParent.delete` beside it.
- `npm run check`, build and all 2796 tests pass, with no golden
changes.
**Live, CLI 2.1.293 on Haiku, v1 and v2**
- A plain cancel mid-answer, and cancels with a background command
finishing during or after the cancelled turn.
- Nothing of the cancelled turn arrived after its report.
- Claude Code's follow-up after the cancel streamed in full. On v2 it
came in its own `running` … `idle end_turn` cycle.
- An abandoned prompt that Claude Code had already dequeued is a narrow
race through the adapter, so I didn't reproduce it live. The tests
follow the order a direct CLI probe recorded for #1309.
## Not changed
- A dropped prompt that runs a tool can still surface it after the
cancel, through `canUseTool` (tool call plus permission request) and the
PreToolUse preview hook. Neither checks the cancel. A check there would
read the consumer's state, which lags the CLI's control channel, so this
needs its own design.
- On CLIs without `request_marker_lists_v1`, the window still lasts
until the next prompt's echo. Claude Code's own follow-ups in that
window now lose their streamed copy as well as the consolidated one. The
bundled CLI has the marker.
A Bash call that sends its command to the background returns as soon as
the command detaches, and its tool result carried `terminal_exit`. So a
client that renders terminals, whether Zed's terminal extension or a v2
display terminal, showed the command's terminal as exited, with no code,
at launch, while the command ran on.
## What changes
For a client that renders terminals and isn't AIR:
- **At launch:** the tool result of a command in the background leaves
the exit out (`withRunningTerminal`). The tool call still completes; the
v2 draft keeps "Terminal exit and tool call status are independent".
- **When the command's task ends:** the consumer sends `terminal_exit`.
It does so at the task's `task_notification`, or at its terminal
`task_updated` if that comes first. The update is routed like the tool
call, so a subagent's command ends in the subagent's session.
- **No exit code.** Claude Code names the code only in the
notification's summary text ("…failed with exit code 3"), which the
adapter doesn't parse. `completed` doesn't mean 0 either: Claude Code
accepts some non-zero codes as a success, such as grep's 1.
The terminal still exits at the tool result, as before, in four cases:
- **A fast command** whose task ended before its tool result.
- **A task that started after the tool result.** Claude Code sends
`task_started` first, but the existing `bash-background` scenario
scripts the reverse, so its goldens don't change.
- **AIR,** which shows the command through its async tasks.
- **Replay,** where the command from before the reload no longer runs,
and the structured tool result isn't available anyway.
## Evidence
- **Live, CLI 2.1.293, through the built adapter over ACP:**
- **v2:** the terminal stays running when the Bash call completes and
the turn goes idle. `terminal_update` with `exitStatus: {}` arrives when
`sleep 5` finishes, before Claude Code's follow-up.
- **v1 with `terminal_output`:** no exit at the Bash result;
`terminal_exit` with code `null` arrives when the command finishes.
- **Recorded, CLI 2.1.293:**
- the order is `task_started` (`local_bash`, `is_backgrounded: true`),
then the Bash result with `tool_use_result.backgroundTaskId`, then
`task_updated` and `task_notification` when the command ends;
- neither event carries a structured exit code.
- **Tests:**
- v2: the terminal runs until the task ends, with one exit after the
turn's `idle`; and a task that ended before the result exits at the
result.
- v1 with Zed's terminal extension: the exit comes after the prompt's
answer. AIR keeps its exit at the result.
- Unit tests for `withRunningTerminal`, including dropping a `_meta`
that would be left empty, since an empty `_meta` would clear what a v2
client stores.
- **Mutations:** removing the strip, the end-of-task exit, the liveness
guard, or the AIR guard each fails a test.
- `npm run check`, build and the full suite pass, with no golden file
changes.
A follow-up to #1310, from its review, which found no regressions but
two wrong answers. Both come from one choice in #1310: a request from an
agent without a `liveBackgroundTasks` record put v2's foreground work in
`requires_action`.
**When an agent has no record:**
- **A teammate:** it never gets one.
- **A settled subagent:** settling deletes its record, and settling
didn't re-check open requests.
- **A foreground subagent nested in a background one:** Claude Code
leaves it out of `background_tasks_changed`, so the level reconciliation
prunes it after two activations.
The main conversation waits on none of them. A background subagent's
request that the consumer read before its `task_started` also flickered
from `requires_action` to `running`.
## What changes
- **An agent without a record no longer blocks the foreground work.** A
subagent the main conversation waits on has a record by the time it
asks: its `task_started` comes first on the wire, and nothing prunes it
while the main turn waits. When the consumer reads the request first,
the `task_started` checks again, so `requires_action` comes slightly
later instead of a flicker for background subagents.
- **Settling a task re-checks** the open requests.
- **The comment on `nativeSubagentParentByToolUseId`** no longer claims
`parent_task_id` is unread.
## Tests
- **Replaced:** "stops waiting for a request once its subagent turns out
to run in the background". The new test checks that a request read
before its `task_started` doesn't block, then blocks once the
`task_started` says foreground.
- **New:** a foreground subagent's open request stops blocking once
Claude Code stops that subagent.
- **Mutations:** restoring "no record blocks" fails both tests; dropping
the re-check at settle fails the second.
- `npm run check` and the full suite pass, with no golden file changes.
v2's foreground work reported `requires_action` whenever any permission
request or question in the session was open, including a background
subagent's. The draft keeps `requires_action` for foreground work that
is blocked on user action, and a background subagent asks without
blocking the main conversation. So a v2 client saw a running turn as
waiting on the user while it kept working.
## What changes
A request blocks the foreground work when it is:
- the main conversation's own request, or
- the request of a subagent that runs in the foreground of the main
conversation, so the tool call that spawned it waits on it. This applies
up a chain of such subagents.
A request from a subagent in the background, or from one nested inside
it, no longer counts.
- **Where each task runs.** The adapter records this per task:
- from `task_started.is_backgrounded` and `parent_task_id`;
- from a later `task_updated` patch that moves the task to the
background;
- Claude Code always resumes a subagent in the background.
- **Unknown subagents.** A subagent without a record still counts,
because its request can arrive before its `task_started`. Registering a
task, or moving one to the background, checks the open requests again.
- **Requests that name no agent** still count: MCP elicitations and
dialogs.
- **Steering is unchanged.** It still treats any open request as
blocking. `Session.pendingUserInputCount` becomes
`Session.openUserInputs`: the open requests, each with the subagent that
asked.
- **v1 is unchanged.**
## Evidence
- **Live, CLI 2.1.293 via the SDK with a logging `canUseTool`:**
- `task_started` carries `is_backgrounded: true` for a background
subagent and `false` for a foreground one.
- A subagent's `canUseTool` call carries `agentID` equal to its
`task_started.task_id`.
- `task_started` arrived before the subagent's request in both cases.
- `parent_task_id` for nested subagents was not checked live; it's
documented in the SDK types and covered by a test.
- **6 new v2 tests:**
- a background subagent's permission request leaves the turn `running`,
and so does its question;
- a foreground subagent's request reports `requires_action`;
- a foreground subagent launched by a background one doesn't block;
- a request that arrives before its subagent's `task_started` stops
blocking once the subagent turns out to run in the background;
- a request stops blocking once Claude Code moves its subagent to the
background.
- **Mutation checks.** Removing each rule in turn fails at least one
test. That includes passing the subagent through for permission requests
and for questions, the recheck at registration and at `task_updated`,
and the walk up the chain.
- `npm run check`, build and the full suite pass, with no golden file
changes. Two resume tests now expect the resumed task to be recorded as
backgrounded.
After a cancel, Claude Code ends the interrupted turn with an aborted
result, then keeps working through its queue, and reports `idle` once at
the end. The queue can hold a prompt it had already taken off it, then
its own follow-ups, such as the summary of a background command that
finished. The adapter settled a cancelled turn only at that final
`idle`, and dropped everything in between until the next prompt
activated. As a result:
- **v1:** a cancelled `session/prompt` waited for any follow-up queued
behind it to finish.
- **v2:** a follow-up after a cancel streamed as text with no `running`
or `idle`.
This PR ends the cancel where Claude Code's own messages say the stopped
work ends.
## What changes
- **Where a cancelled turn settles.** It now settles at the result of
the work the interrupt stopped: its own result, or, for a turn held open
for its subagents, its follow-up's aborted result.
- The `idle`, the next echo's hand-off and the force-cancel backstop
still settle a turn whose result never comes.
- That result owes its trailing `idle` like any settling result, a
steered turn's included.
- **When the cancel ends.** The cancel records the prompts it stopped:
the unsettled turns and their steers when it arrives, and whatever it
abandons when it sweeps the queue.
- With `request_marker_lists_v1`, every `status: requesting` frame lists
the prompts its model request serves. A cycle Claude Code starts on its
own lists none.
- The cancel ends at the first request that serves none of the recorded
prompts, once no turn is unsettled and no orphan result is outstanding.
Compaction updates resume there too.
- A prompt Claude Code had already dequeued names itself, so its answer
stays dropped even when the interrupt receipt leaves it out.
- Without the capability, the cancel ends at the next activation, as
before.
- **Abandoned prompts' results.** A result that names a cancelled prompt
never promotes the next queued prompt, so a prompt sent after the cancel
can't take an abandoned prompt's result.
- **Held turns.** Since CLI 2.1.270, Claude Code reports `running` for
as long as background agents live. So with request markers, a held
turn's follow-up counts as live only when a model request has started
since the turn's result. A cancel while only the subagent runs settles
the held turn at once.
- **v2: aborted cycles.** A cycle whose result is aborted
(`terminal_reason` `aborted_streaming` or `aborted_tools`) ends
`cancelled`.
## Evidence
**What CLI 2.1.293 sends.** I recorded the stream live with a probe that
drives the SDK the way the adapter does. After an interrupt:
1. The interrupted turn's aborted result comes first.
2. Next, any prompt Claude Code had already taken off its queue runs.
Its request names it.
3. Then its own follow-ups run. Their requests name no prompt.
4. Finally, one `idle`.
The interrupt stops background agents, but not background commands.
**An audit of the bundled CLI** found exactly one source of `status:
requesting` frames: one per main query-loop iteration. Subagents,
compaction, side queries, hooks and retries emit none, or only a named
one.
**The adapter, end to end over ACP against the live CLI**, this branch
against `main`:
| Scenario | `main` | This PR |
| --- | --- | --- |
| v1: a background command finishes while the turn the user cancels
streams | `session/prompt` answered 14.1 s after the cancel | answered 4
ms after the cancel; the follow-up's text arrives after |
| v2: same | follow-up text with no `running`; `idle cancelled` 14.8 s
after the cancel | `idle cancelled` 10 ms after the cancel, then
`running`, the follow-up, `idle end_turn` |
| v2: a background command finishes after the cancelled turn | `idle
cancelled`, then text with no `running` or `idle` | `idle cancelled`,
then `running`, the follow-up, `idle end_turn` |
| v2: cancel while idle, then a background command finishes | text with
no `running` or `idle` | `running`, the follow-up, `idle end_turn` |
| v1: cancel while a background subagent holds the prompt open | (not
compared) | answered 2 ms after the cancel |
## Tests
- **20 new tests, scripted on the recorded orders.**
- v1 suite "output after a cancel" (12): a cancelled turn and a cancel
while idle; a dequeued prompt the receipt leaves out; a steer; a prompt
that Claude Code folds into its own follow-up; a prompt sent while the
cancel is still in progress; a repeated cancel; trailing idles after a
cancelled turn and after a steered one; older CLIs without request
markers.
- Held turns (3): a cancelled held turn settles at its follow-up's
aborted result, not at a placeholder result, and at once when only its
subagent runs.
- v2 (5): the follow-up after a cancelled turn as its own cycle; a
cancel while idle; a later cycle after a cancelled one; a cycle Claude
Code started before the cancel arrived; a follow-up's compaction.
- **Mutation checks.** Removing each rule in turn fails at least one
test. Two exceptions:
- Clearing the record at activation can't be observed.
- Holding for any unsettled turn, not only a recorded one, can't be told
apart from activation.
- `npm run check`, build and the full suite pass, with no golden file
changes.
## Review
The design went through two rounds of independent review.
- **The first attempt, rejected.** It judged "the stopped work is over"
from the adapter's own bookkeeping. Review found that the interrupt
stops what Claude Code is running, which the adapter may not have seen
yet. That attempt is not in this PR.
- **This design.** A second round audited the CLI's signals and the
state machine. This PR fixes what it found:
- a prompt sent after a cancel could take an abandoned prompt's result;
- a held turn could settle at a placeholder result;
- the window could close while an abandoned prompt that Claude Code
folds into its own follow-up was still due;
- a prompt sent during the cancel's awaits wasn't recorded;
- a held turn's follow-up was misread as live on CLI 2.1.270+.
## Known limitations
- **The cancelled turn's last streamed text still arrives after the
cancel**, as on `main`: the cancel never held streamed text back.
- **If the cancel lands just after Claude Code started its own
follow-up**, the interrupt stops that follow-up, and its partial output
gets through. On v2 it ends `cancelled`.
- **Trailing-idle debt can be over-counted by one in a drain run.** The
next `running` transition sweeps it, as before.
Stacked on #1304, which this targets; it retargets to `main` once #1304
merges. Together they replace #1303.
## What a v2 client gets now
**`idle` at a turn's result,** also when v1 holds the turn's answer for
the background subagents it spawned (`Turn.deferredSettle`).
- The subagents' output and permission requests arrive while the session
is idle. The draft allows that: background activity may send updates
while idle, and they don't change the state.
- A background request while idle no longer shows `requires_action`,
which the draft reserves for foreground work.
- The hold itself is unchanged. It now only delays v1's answer, with no
v2 branch in the hold logic.
**Model cycles that Claude Code starts on its own** are foreground work:
the follow-up after a background subagent or command finished, or its
answer to a message from another session.
- A cycle reports `running` before its first output, `requires_action`
while it waits, then `idle` with its own stop reason, usage and
`_meta.quota`.
- An error result gives `idle` with the `error` stop reason, and a
cancel gives `idle cancelled`.
- Before this, such a cycle streamed while v2 said `idle`.
**Take-overs:** a prompt that Claude Code takes in during a cycle takes
it over, with no new `running` and no `idle` in between. So do a steer
that resumes a held turn, and the continuation of an accepted
clear-context plan. In both, the final `idle` carries the turn's usage,
not just the last cycle's.
v1 and AIR clients are unchanged.
## How
All of this builds on #1304's `ForegroundEvents`:
- **A turn's work ends at its result:** `endForeground` in the defer
branch of `settleOrDefer`, and where the steer idle lane re-applies a
hold.
- **A cycle starts** (`startAutonomousCycle`) at model output of the
main conversation while no work runs.
- Subagent output doesn't count.
- Without command lifecycles, output while a prompt is queued stays that
prompt's, since its output can come before its echo. With lifecycles
(`msg_lifecycle_v1`), a prompt Claude Code hasn't started has no output
yet, so a cycle starts. This narrows the gap that #1303 left.
- **A cycle ends:**
- at a result no turn took, except a placeholder result (`num_turns:
0`);
- with `cancelled` at the diagnostic of an ExitPlanMode answer, as a
turn does, unless a held turn continues the accepted plan;
- at an SDK `idle` that no earlier result owes;
- when the stream ends or fails;
- before `session/close` answers.
- **Starting work while a request is open** reports `requires_action` at
once.
- **The cycle's stop reason** comes from its result, as for a turn
(`autonomousCycleEnd`). Its `_meta.quota` uses the same builder as a
turn's (`quotaMeta`, extracted from `turnQuotaMeta`).
## Checks
- `npm run check`, `npm run build` and all 2756 tests pass. No golden
file changes against #1304: no recorded scenario has a held turn or
output while no turn is active.
- New tests:
- **14 v2 tests:** #1303's eleven, plus a held turn reporting `idle` at
its result with its follow-up as a cycle and a background request while
idle, output before a queued prompt that Claude Code reports it hasn't
started, and `session/close` during a cycle;
- **agent:** a steer resuming a held turn's work; the follow-up that
ExitPlanMode's "keep planning" interrupts ending `cancelled`; the
clear-context continuation taking the cycle over, with the turn's usage;
- **turn events:** work that starts while a request is open waits at
once.
- I made 20 mutations, one per rule above, and each failed a test. The
take-overs for a steer and for the clear-context restart first survived,
since a cycle stood in for the turn with the same states. The tests now
check the usage of the final `idle` too.
## Not covered
- No recorded scenario has such a cycle. The start signal (the first
main-thread output) is chosen from the agent's side, not confirmed
against a live CLI.
- After a cancel, the agent drops main-thread output until the next
prompt (`session.cancelled` stays set). So a follow-up that Claude Code
runs after a cancel is still lost, for v1 and v2. That predates this PR,
and I'll fix it separately.
The first of two PRs that replace #1303, after a design review. This one
restructures how the agent reports v2's state, with two small changes in
behavior (below). The next PR makes v2 report `idle` at a turn's result
and adds model cycles that Claude Code starts on its own.
## Why
The agent reported each turn's v2 states (`running`, `requires_action`,
`idle`) through the prompt's `TurnEvents`, the same events that answer
the prompt. That ties v2's state to when **v1** gets its answer. The
clearest case is the hold (`Turn.deferredSettle`): v1 holds a turn open
while the background subagents it spawned run, because a v1 client stops
listening at the prompt response. So v2 stays `running` too.
Making v2 report `idle` at the turn's result in that design would need a
v2 branch inside the hold logic. That's the most intricate code in the
adapter: steering, cancel, the echo hand-off, ExitPlanMode, idle debts.
And a cycle that Claude Code starts on its own would need a second
source of v2 state beside the turn's (#1303).
## What changes
- **`TurnEvents` only answer the prompt:** `inserted`, `ended`,
`failed`. v1 answers at `ended` or `failed`. v2 answers at `inserted`,
and uses `ended`/`failed` only to reject a prompt before insertion.
- **New `ForegroundEvents`** (`src/turn-events.ts`): the session's
foreground work, meaning what a client would wait for before sending the
next prompt. Events: `running`, `awaitingUser`, `ended`, `failed`.
- Only the v2 surface supplies them, through the new `foreground`
option. They map to `state_update` in `v2Foreground`.
- A prompt's turn is the foreground work from its insertion until it
ends, exactly as before. So `idle` still waits for a held turn's
subagents; the next PR changes that.
- **The work is keyed by the session id the client knows,** not stored
on a `Session`. A clear-context restart (an accepted ExitPlanMode with a
fresh context) replaces the Claude Code session behind that id and moves
the running turn to it. Work stored on the old `Session` would stay
behind.
- **Requests report through the work** (`syncAwaitingUser`), not through
the active turn.
## Observable changes on v2
1. **The `session/prompt` response now comes before `running`, not after
it.**
- The 38 v2 golden files change by exactly that, and nothing else; I
checked every file with a script.
- The old order was not guaranteed: the SDK's `notify` writes after
`waitUntilInitialized(...).then(...)`, and the response is written once
the handler's promise resolves. The old code won that race by sending
`running` before resolving.
- The draft lets clients receive the updates before or after the
response.
2. **A request that Claude Code opens for a prompt it started, before
the prompt's echo, now reports `requires_action` when it opens,** rather
than at the echo. The prompt's work is already running then.
v1 and AIR clients are unchanged.
## Checks
- `npm run check`, `npm run build` and all 2739 tests pass.
- Every v2 state test in `acp-v2.test.ts` passes unchanged.
- `turn-events.test.ts` now reads the waiting events from the
foreground.
- New tests:
- a request opened before the echo;
- the work staying with the session id across a clear-context restart,
with a permission request in the continuation.
- I made six mutations and each failed a test: no `running` at
insertion, no end on `resolve`, no end on `reject`, waiting never
reported, waiting only for the active turn, and the work tied to the
`Session` object.
IDEs can pass their own Claude hooks through
`_meta.claudeCode.options.settings.hooks` on `session/new` and
`session/load`. Before this change, any session settings replaced
`CLAUDE_MODEL_CONFIG` entirely, so adding a single hook dropped the
deployment's `modelOverrides` / `availableModels`. The two are now
merged, and the session settings win per key.
The wrapper does not merge hooks itself: Claude Code already runs the
hooks of every settings tier, so user and project hooks keep running
next to the session ones. Hooks stay scoped to their session, and a
`session/load` with different settings recreates the query, which
replaces or removes them.
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
#1289 made a v2 client get `cancelled` for a run that Claude Code
aborted, when Claude Code reports it as an error result with
`non_execution_kind`. Claude Code has a second way to report an aborted
command: a **successful** Bash result whose structured output says
`interrupted: true`. A v2 client got `completed` for that. With this PR
it gets `cancelled` too, so the rule is the same however Claude Code
reports the abort.
## When Claude Code sends that result
I read the CLI that SDK 0.3.293 bundles. I didn't reproduce these cases
live.
| What stops the command | What the adapter receives | v2 before | v2
after |
| --- | --- | --- | --- |
| The client cancels (`session/cancel`) | an error result,
`non_execution_kind: "interrupted"` | `cancelled` (#1289) | same |
| A timeout | an error, "Command timed out after …", **not**
`interrupted` (or the command is backgrounded) | `failed` | same |
| The output limit or a replaced output file | an error with `Exit code
137`, not `interrupted` | `failed` | same |
| A `now`-priority message such as `_session/steering`, landing just
before the command starts, or while the output limit kills it | a
successful result, `interrupted: true` | `completed` | **`cancelled`** |
A successful `interrupted` result needs the abort reason `interrupt`,
which a `now`-priority message causes. That abort doesn't kill a running
command, so this result only comes from the races in the last row.
Clients will rarely see it. The point of the change is that v2's status
follows what Claude Code reports, however it reports it.
v1 and AIR clients are unchanged: `completed` with no exit code, and AIR
still gets exit code 1.
## How
- `AcpToolCallRenderer.resultStatus` takes the command's `interrupted`
fact alongside `nonExecution`.
- `result()` used to call `resultFields`, which drops the command facts.
It now computes the facts once (`resultFacts`) and builds the fields
from them (`fieldsOfResult`). That lets it pass `interrupted` without
adding a field to `RenderedResult`, which the public
`toolUpdateFromToolResult` returns.
- The agent's checks for a finished tool call already count `cancelled`
(`isFinalToolCallStatus`, #1289).
## Checks
- `npm run check`, `npm run build` and all 2730 tests pass. No golden
file changes: no recorded scenario has an interrupted command.
- New tests:
- **renderer:** an interrupted command on v2, v1 and AIR, and one that
isn't interrupted on v2;
- **v2 surface:** a v2 client receives `cancelled`, and the turn still
ends `end_turn`.
- I made four mutations and each failed a test: the rule ignores
`interrupted`, every client gets `cancelled`, `result()` doesn't pass
the fact, and `result()` inverts it.
v2 has a `cancelled` tool call status ("the tool call was cancelled
before it completed"), which v1 doesn't. #1289 started using it for a
run that Claude Code aborted. This PR uses it for the other tool call
that never ran: one that Claude dropped before running it.
## What changes
When a turn ends with `end_turn` and a streamed `tool_use` never reached
a complete assistant message, Claude dropped that tool call before it
ran, for example when it switched to a steering message. The agent
closes it at the end of the turn with "Claude stopped this tool call
before it ran." The turn itself still succeeds.
| Case | v2 client | v1 and AIR clients |
| --- | --- | --- |
| Dropped before it ran | `cancelled` (was `failed`) | `failed`, as
before |
| Ran, but Claude Code returned no result | `failed`, as before, and the
turn fails with `incomplete_tool_call` | same |
The content text is unchanged in both cases.
## How
- **The renderer builds both closing reports**
(`AcpToolCallRenderer.unfinished`), and picks the status from
`ClientCapabilities.v2`, as `resultStatus` does since #1289. Before, the
agent built the report inline with a hardcoded `failed`.
- **The agent** passes whether the tool ran. Its closing step
(`failToolCall`, now `closeUnfinished`) already removes the call from
all of its tracking itself, so no "is this status final" check needed
changing.
## Checks
- `npm run check`, `npm run build` and all 2728 tests pass. No golden
file changes: no recorded scenario drops a tool call.
- New tests:
- **renderer:** dropped and ran-without-result, on v2, v1 and AIR;
- **v2 surface:** a v2 client receives `pending` then `cancelled` for a
dropped tool call, and the turn ends `end_turn`.
- The existing v1 tests in `incomplete-tools.test.ts` are unchanged and
still pass.
- I made five mutations and each failed a test: the renderer never
cancels, the renderer cancels a tool that ran, the agent marks a dropped
call as having run, the agent marks a no-result call as dropped, and the
agent's renderer ignores the client's capabilities.
A v2 diff can't hold the snippet of an Edit's input (it needs line
numbers and the operation), so on v2 an auto-approved Edit or Write
showed its change only once the PostToolUse hook reported it, after the
tool had already run. Only an asked one showed its approval patch first.
## What changes, v2 only
The tool call shows the exact patch before the tool runs, auto-approved
or not.
## How
- **A PreToolUse hook for Edit and Write** (`fileChangePreviewHook`),
registered only on v2 connections. Claude Code runs the tool only after
the hook returns, so the file is still unchanged when the hook reads it.
That's the same guarantee the approval patch in `canUseTool` relies on.
The hook sends the same patch (`previewPatchContent`):
- **Stream already showed the tool call:** a `tool_call_update` through
the session's stream router, pinned like an approval patch.
- **Hook came first:** the SDK dispatches hook callbacks as soon as it
reads them, ahead of the message queue the agent consumes. The hook then
emits the tool call with the patch via `ensureToolCallEmitted`, the
permission flow's fix for the same race (#851).
- **Subagent tools** are attributed exactly as in `canUseTool`. That
rule moves into `toolUseOwner`, which both use, with no behavior change.
- **Safe failure:** the hook makes no permission decision, and any
failure only leaves the preview out.
- **v1 and AIR** register no PreToolUse hook, so Claude Code waits on
nothing new there and their output is unchanged.
I first tried hanging the preview on the per-tool-use hook registry that
PostToolUse uses. That fails when the hook comes before the stream, so
the hook lives on the agent instead.
## Golden files
The scenario harness now runs PreToolUse before each tool, as Claude
Code does, and applies each hook's `matcher`. The v2 golden files of the
four file-change scenarios change:
- **`write-existing`** (auto-approved): the patch now arrives before the
tool completes, and the final hook report no longer repeats it, because
the tracker sees no change.
- **`write-new`, `edit-with-permission`, `edit-rejected`:** the tool
call gets the patch just before the permission request, which carries
the same patch.
No v1, AIR or plain golden file changes.
## Checks
- `npm run check`, `npm run build` and all 2497 tests pass.
- A new v2 test runs an auto-approved Edit with the hook both after and
before the streamed tool use. It checks that the patch is computed from
the file before the edit, arrives before the result, and isn't replaced.
- A new test checks that only a v2 session registers the hook, with the
`Edit|Write` matcher.
- Mutations that fail tests: no hook on v2, the hook on v1 too, the
hook-first path doing nothing, the already-shown path sending nothing,
and Edit only.
- Not pinned by any test: the pin itself. On v2 nothing later in the
stream carries content for an Edit or Write, so it's only there for
consistency with the approval patch.
## Follow-up
AIR has the same gap for an auto-approved Write: it shows no diff until
the hook. That's out of scope here, since it changes AIR's output.
Two findings of the 2026-10-10 night perf run on a 5,000-session home
(findings 8 and 9).
## Rename push (finding 9)
The run measured "no push within 10 s" after `_session/rename`. The
cause was the harness, not the adapter. The bench renames the newest
session to `"Night renamed"`, and an earlier bench run on the same home
had already given it that title. The transcript shows that pair of title
records twice. A rename to the current title appends nothing, so there
was nothing to push. On a fresh home, the same bench gets the push. The
hypotheses checked:
- The metadata cache is not updated by a rename. The appended records
change the transcript's size, and the watcher re-reads it.
- The sidecar lies outside the non-recursive watch, but so does every
rename. Each one also appends to the transcript, which is watched.
Still, the push depended on `fs.watch` plus its 150 ms quiet period. Now
a rename, archive, unarchive or delete through this connection publishes
at once. `ListSubscriptions.sessionWritten` stats the session's
transcripts and reads its row, the way a transcript event would, without
waiting. The event that follows finds the row unchanged and sends
nothing. Renames by other processes still arrive through the watcher.
The 1 s per-session interval of a subscription still applies.
## Listing every page (finding 8)
Profiling `SessionIndex.list` showed where a page's time goes. The full
enumeration and stat of 5,000 transcripts takes about 20 ms per page.
Most of the remaining ~380 ms was the SDK `getSessionInfo`, called once
per row read: its lookup runs a `readdir` of the whole project directory
(5,000 entries) on every call.
- A metadata read no longer calls the SDK. Titles come from the head and
tail the index already reads, by the same rule (`sdkTitles`). The tail
is searched as the SDK searches it, cut first line included.
- The pages after a cursor reuse the list's enumeration. It is keyed by
the cursor and kept for at most 30 s, at most 8 lists. It is dropped as
soon as a directory of the scope adds or removes an entry, through the
`DirListings` identity check. Such a page stats only the transcripts it
reads (each with its session's other copies) right before reading them.
A transcript that changed since either keeps its order key (no new
prompt) or moves up before the cursor, so the page is as fresh as one
from a new enumeration. The first page always enumerates.
## Measurements
Real adapter (`dist/index.js`), driven as AIR drives it by
`acp-perf-harness/air-ui/night/acp-adapter-bench.mjs`. Fixture: 5,000
sessions from `gen-night-data.mjs`.
| | before | after |
|---|---|---|
| Listing every page (25 × 200) | 10.1–16.3 s | 0.92–1.16 s |
| First page (51) | 156–472 ms | 46–62 ms |
| Show more (50) | 117–283 ms | 13–23 ms |
| Push after archive | ~170 ms | 3–4 ms |
| Push after a rename | ~170 ms | 3–5 ms |
## Tests
- A rename, archive, unarchive and delete each push within 500 ms while
the watcher's quiet period is 60 s (fails without the fix). A rename by
another process is pushed through the watcher.
- Paging:
- one enumeration for all pages;
- between pages, a transcript emptied, one with a new prompt, and one
with only a new answer give the same pages as a new enumeration;
- an older copy of a session that got a prompt hides it on later pages;
- adding or removing a transcript enumerates again.
- A custom title whose record starts before the tail window matches the
SDK.
- Read-count assertions use the new `SessionIndex.transcriptsRead`
counter instead of SDK call counts.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
## Summary
Adds the opt-in AIR `sessionIndex` extension. With it, an AIR client can
show the latest sessions of a project quickly, with their state, and can
rename, archive and unarchive them over ACP. The full contract is in
`docs/air-extensions.md` ("Session index").
The extension follows ACP RFDs. The transport differs: it uses
`_meta.jetbrains.air` request options and row fields, `_session/*`
methods, and AIR capabilities that are not advertised under ACP v2. The
`archived` list filter also differs (see below).
- **Session list extensions**
(agentclientprotocol/agent-client-protocol#2323):
- `limit`, ordered by last user activity (`lastPromptAt ?? updatedAt`),
and `includeWorktrees`.
- Row fields `lastPromptAt`, `model` and `forkedFrom`.
- `state`: `running`, `idle`, `requires_action`, and `error`, which the
RFD lacks.
- `lastTurnEndedAt`.
- `cost`: the SDK's `total_cost_usd` for a session that runs on this
connection only. No cost is read from transcripts.
- Live updates come from an AIR list subscription (below).
- **Session archive** (agentclientprotocol/agent-client-protocol#2161):
- `archived` is on every row, `session_info_update` is sent on a change,
and an unknown session is `-32002`.
- The `archived` list filter has three values: `"unarchived"` (the
default), `"archived"` (archived sessions only) and `"all"` (both, in
one order). #2161 has a boolean here. Its `false` is `"unarchived"`, its
`true` is `"all"`, and `"archived"` has no counterpart.
- **Capabilities**: an AIR client that declares `sessionIndex` gets
these in `_meta.jetbrains.air.capabilities`. The client declares only
`sessionIndex`.
- `sessionIndex`.
- `sessionArchive`: `_session/archive` and `_session/unarchive`. The RFD
capability is `archive` (#2161).
- `sessionRename`: `_session/rename`. The RFD has capability `setTitle`
and method `session/set_title`
(agentclientprotocol/agent-client-protocol#1987).
- `sessionListSubscribe`: `_session/list/subscribe`,
`_session/list/unsubscribe` and `_session/list/changes`. No RFD
counterpart.
### Clients without `sessionIndex`
Clients that don't declare `sessionIndex`, which means non-AIR clients
and released AIR builds, keep the current behaviour. They get the same
SDK `listSessions` path, page size, cursor and initialize capabilities,
with no watchers and no notifications. There are two deliberate
deviations, both strictly safer:
1. **`session/delete` from an AIR client without `sessionIndex`.**
Released AIR builds use delete as "Done". Instead of deleting the
transcript (data loss), the adapter archives the session in AIR's own
Claude format (below). Archived sessions are hidden from that client's
list, so "Done" looks the same and nothing is lost. An unknown session
keeps the SDK's error. Other clients get the SDK delete, as before.
2. **`session/close`** of a session that is not loaded here returns `{}`
instead of throwing.
### Sessions open in another process
`session/load`, `session/resume` and `session/prompt` work on a session
that another live Claude Code process has open, for every client, as the
Claude CLI does. Rename, archive, unarchive and delete also go ahead,
writing records or deleting transcripts as the CLI's `/rename` and
delete do. The other process keeps running.
### Archive format and rule
The archive state uses AIR's native Claude archive format
(`ClaudeStoreThreadBackend.appendTitleRecords`, ADR 0140), so AIR's
native path and the adapter read and write the same state.
- **Archive** appends `{"type":"custom-title","customTitle":"[archived]
<title>",…}` and `{"type":"agent-name","agentName":"[archived]
<title>",…}` to every transcript copy. **Unarchive** appends the same
pair without the prefix. Titles are cut to the CLI's 200 characters.
- **Archived is decided by the agent name first**, as in AIR's native
Claude provider. A session's name is its last top-level `agentName`,
else the custom title the SDK reports. The session is archived exactly
when that name starts with `[archived] `. The listed title comes from
the same source, shown without the prefix.
- Title records are metadata: `updatedAt` and the list order do not
move.
### Rename, archive and delete
- **Rename** writes the same title pair. An archived session keeps its
prefix. A session running here is renamed through its CLI's
`rename_session` control request, serialised with auto-titling. Other
sessions get the records plus the `custom-title.json` sidecar the CLI
writes. No generated title replaces a client title, but a title stored
later by someone else (a `/rename`) is still adopted.
- **Archiving stops the running session.** `_session/archive` of a
session loaded on this connection does four things:
1. It interrupts the running turn.
2. It retitles the session through its CLI. The adapter also appends the
matching `agent-name` record to the CLI's transcript, because the CLI
writes that record only later.
3. It closes the session as `session/close` does.
4. It archives the transcripts once more if the closed CLI left them
unarchived.
The client then gets `session_info_update` with `archived: true`.
Unarchive does not reopen the session. A session that is not loaded here
is archived by writing the title records.
- **Delete** for a `sessionIndex` client deletes every copy of the
session and its `<sessionId>/` directories. A session running here is
closed first.
### Implementation (`src/session-index/`)
- **Index**:
- Reads the project dirs with `readdir` + `stat`, and keeps a 2000-entry
metadata LRU keyed by (path, mtime, size).
- Cache misses are read in parallel through `getSessionInfo`, plus a
growing tail read (64 KB → 4 MB) for the last prompt, last message, turn
end and agent name.
- SDK semantics are kept: sidecar titles, `continued-in`, long-path
hashes, darwin case, and first-prompt extraction (ported, and
fuzz-compared with the SDK).
- The `cwd` scope follows the SDK `listSessions`. Worktrees expand to
the same relative subdirectory, and a session copied to several project
directories is listed from its newest copy.
- The keyset cursor is bound to `cwd`, `archived` and
`includeWorktrees`. Session ids match exactly.
- **State**:
- For sessions of this process, the SDK state.
- For other sessions, the Claude Code live registry
(`~/.claude/sessions/<pid>.json`, with pid + procStart liveness and
Claude Desktop's rules) or the transcript tail. The registry is read
only for the row state.
- `error` means the session is not running and its last turn ended with
an error, not a cancel.
Documented in `docs/air-extensions.md`, with an extension → RFD mapping
table and the remaining differences.
### Measured on a real `~/.claude` (233 transcripts, read-only)
| Case | New path | Old SDK path |
|---|---|---|
| cwd, limit 50, cold process | ~80 ms | 78–156 ms (all rows) |
| cwd, limit 50, warm | 1.3–4 ms | — |
## Session list subscription
Replaces polling the first page. It is only for a client that declared
`sessionIndex`; the agent advertises `sessionListSubscribe` with it,
never under ACP v2.
- **Subscribe**: `_session/list/subscribe { cwd }` returns `{
subscriptionId }`. `cwd` must be absolute, else `-32602`; other params
are ignored.
- The scope is `cwd` and the same subdirectory in every linked worktree,
in any archive state, without sidechains.
- **Changes**: `_session/list/changes { subscriptionId, sessions,
removed }`.
- `sessions` holds the full `session/list` row of each session that
appeared, or whose title, `lastPromptAt`, `state`, `lastTurnEndedAt`,
`cost`, `model`, `forkedFrom` or `archived` changed since the last row
sent.
- The first change of a session after subscribe is sent in full. After
that, a change of `updatedAt` alone sends nothing.
- `removed` lists sessions that were deleted or moved out of scope.
- Archive and unarchive are row changes.
- A session is sent at most once a second, with one notification per
subscription per pass.
- **Unsubscribe**: `_session/list/unsubscribe { subscriptionId }`
returns `{}` and is idempotent.
- A subscription lives until unsubscribe or until the connection closes.
- A connection has at most 128 subscriptions. The 129th is `-32602` with
`data.reason: "too_many_subscriptions"`.
- Subscriptions of the same `cwd` share one watch and are notified
independently.
- **Delivery** is best effort, with no resync and no sequence numbers. A
rescan every 10 s (and 1 s after a project directory watch opens) sends
whatever differs.
- **Implementation** (`list-subscriptions.ts`, `session-info.ts`):
- A non-recursive `fs.watch` on the scope's project dirs, the registry
and the projects root.
- A transcript event re-reads only that transcript, and a registry event
reads only that `<pid>.json`. Sessions running here push their SDK state
at once.
- Subscribe reads no session row. The rescan reads only transcripts
whose stat changed or whose read failed.
### Measured: one subscription on the 5,200-session project (Docker
`node:22`, 2 CPU, 2 GB, shared host)
300 s of churn: 20 sessions appending 10/s each (updatedAt-only),
registry status flips every 200 ms, and a session created every 2 s and
deleted 10 s later.
| | Old `list_changed` watcher | Subscription |
|---|---|---|
| Agent CPU p50 / max | 19% / — | 12.9% / 49% |
| Event loop p99 (p50 / max of 1 s windows) | — | 16 / 31 ms; worst
single delay 87 ms |
| Change latency p50 / p95 | 950 ms (hint) | create 291 / 570 ms, delete
279 / 506 ms; registry state 902 / 990 ms* |
| Notifications / min | — | 90 (896 rows, 0 rows for updatedAt-only
appends) |
| RSS | flat ~160 MB | 159 → 198 MB (heap flat ~50 MB) |
\* The registry flips the same 5 sessions every 200 ms, so each is held
to the once-a-second limit. Latency is measured from the first unsent
change.
These numbers were measured with an earlier subscribe that read every
row up front. Subscribe now reads no rows, so that one-off cost no
longer occurs. The lazy subscription has not been re-measured yet.
## Load test: 10,000 sessions (Docker, 2 CPU, 2 GB)
Calibrated data: 10k transcripts, 15 GB, 36k subagent files, and one
5,200-session project. Sizes match a real profile (p50 311K / p90 2.67M
/ p99 20.5M).
| Scenario (limit 50) | Before | After |
|---|---|---|
| Big project, first page cold / warm p50 | out of memory | 225 / 19 ms
|
| No cwd, cold / warm p50 | 1,722 / 178 ms | 209 / 45 ms |
| Page through 4,637 rows | 457 s | 11.4 s cold, 2.9 s warm |
| Delete p50 / 100 concurrent | 23.8 ms / 4.4 s | 7.8 ms / 0.8 s |
| 300 s of churn (60k changes) | out of memory after 3 s | list p50 54
ms, 0 stalls >50 ms, RSS flat ~160 MB |
## Streaming: keep the event loop responsive under a backlog
Under a backlog of buffered SDK messages, the adapter could freeze its
event loop for seconds. Every `query.next()` on a non-empty SDK queue
resolves in a microtask, so `runConsumer` forwarded the whole backlog
without reaching a macrotask boundary. Incoming JSON-RPC, including
`session/cancel`, waited until the backlog drained.
1. **Consumer yields to the event loop.** A shared `EventLoopYielder`
(`src/utils.ts`) gives the event loop a turn via `setImmediate` once the
current iteration has run for 8 ms. Order, content and cancel semantics
are unchanged.
2. **No per-message copy in `nodeToWebWritable`** for byte streams.
Object-mode streams keep the copy.
3. **Diff memo.** The approval preview and the PostToolUse patch no
longer diff the same texts twice. Timed-out diffs are not remembered.
4. **Prefix guards** in `parseMcpCommand` and `sanitizeTitle`. Both give
identical output.
5. **Replay yields between history messages**, with the same budget.
With 10 sessions × 1 MB, the max event-loop delay went from 4205 ms to
1626 ms, and ping p95 from 2793 ms to 262 ms (interleaved A/B, Docker
`node:22`, 2 CPU). Single-stream throughput is unchanged. Remaining
stalls are inside the Claude SDK and GC.
## Test plan
- [x] Rebased on `origin/main`. `npm run check`, `npm run build` and
`npm run test:run` pass.
- [x] Regression tests for the unchanged non-`sessionIndex` paths.
- [x] Regression tests for every review finding.
- [x] Reviews: Codex (gpt-6-astra) and a Claude review subagent, run as
independent passes against `origin/main` until a round found nothing of
normal or higher severity.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
The v2 draft lets the `session/new`, `session/resume`, and
`session/fork` responses carry `availableCommands`
([agent-client-protocol#2259](https://github.com/agentclientprotocol/agent-client-protocol/pull/2259)),
so a client can show a session's commands without waiting for an update.
The v2 surface now fills it.
## Before and after, for a v2 client
- **Before:** the setup response, then an `available_commands_update`
with the list, from a `setTimeout` after the response.
- **Now:** the list is in the response itself, for `session/new`,
`session/resume` with and without replay, and `session/fork`. The field
is left out when the list is empty, as the draft asks.
- **No duplicate:** on a v2 connection the agent no longer sends that
post-setup update (`afterSetupResponse`). Later changes still arrive as
`available_commands_update`, for example the terminal-bound filtering
after Claude Code's first init frame, or `commands_changed`.
- v1 and AIR are unchanged.
## Cost
None. The commands come from `Query.supportedCommands()`, which in the
SDK is `this.latestCommands ?? (await this.initialization).commands`:
the cached initialization result that setup already awaited. So the
response doesn't wait any longer.
## Code
- `ClaudeAcpAgent.availableCommands(sessionId)` returns the session's
command list, factored out of `sendAvailableCommandsUpdate`.
- The three post-setup `setTimeout` blocks become one
`afterSetupResponse`, which skips the command update on v2.
- `setupCommands` in `src/v2/agent.ts` adds the list in v2 form. A
failure to read the commands is logged and leaves them out, since
they're optional and the session already exists.
## Title
`refactor:`, like the earlier v2 surface additions (#1253, #1255,
#1256), so no release note announces v2 yet. Retitle it if you'd rather.
## Checks
- `npm run check`, `npm run build` and all 2494 tests pass.
- The 40 v2 golden files each move the list from the post-setup
notification into the setup response, and nothing else changes; I
checked every diff with a script. No v1 or AIR golden file changes.
- New v2 tests cover each setup response (new, resume, resume with
replay, fork) and check that no post-setup update follows.
- I removed each part in turn, and each removal fails tests: the agent
still sending the update on v2, and the commands missing from new, from
resume, or from fork.
- Not covered: the empty-list case, because the adapter always adds its
`/mcp` command.
v2 has a `cancelled` tool call status ("the tool call was cancelled
before it completed"), which v1 doesn't. Until now a v2 client got
`failed` for a tool call the user interrupted, the same as a real
failure.
## What changes
Claude Code stamps a tool result that carries no tool output with
`tool_result_meta.non_execution_kind`. For a **v2 client**:
| Kind | Meaning (set in the bundled CLI) | Status |
| --- | --- | --- |
| `interrupted` | the turn was interrupted while the tool ran |
`cancelled` |
| `cancelled` | the call's own run was stopped (aborted, or moved to the
background) | `cancelled` |
| `user-rejected`, `permission-rule`, `automode-*` | the tool was
refused | `failed`, as before |
v1 and AIR clients are unchanged: `failed`, with the kind in
`_meta.claudeCode.nonExecutionKind`. v2 clients still get that `_meta`
too.
## How
- **The renderer decides the status**
(`AcpToolCallRenderer.resultStatus`), from `ClientCapabilities.v2`.
That's the same pattern the agent uses for v2 diffs: the value travels
as a v1 status (`V2_CANCELLED`, with a cast, since v1's `ToolCallStatus`
is closed), and the v2 surface passes it through. The v2 translation
still doesn't read `_meta`. The rule covers the regular result and the
two fallback reports in `toAcpNotifications`: an untracked tool call,
and a TodoWrite/Task tool call that only a permission request surfaced.
- **The agent's own "finished" checks** now use `isFinalToolCallStatus`,
which counts `cancelled`. Two places compared against
`completed`/`failed`: one removes a finished call from the turn's
foreground work, the other drops its eager-session and dispatched-call
entries. Without this, a cancelled call would have leaked those entries.
## Not covered
Replay doesn't have `tool_result_meta`, so a replayed interrupted call
stays `failed`, just as v1 replay has no `nonExecutionKind`.
## Checks
- `npm run check`, `npm run build` and all 2493 tests pass. No golden
file changes: no recorded scenario has an interrupted tool.
- New tests:
- **renderer:** each kind, for v2, v1 and AIR clients, plus the
permission-surfaced fallback;
- **agent:** a cancelled call is released from the dispatched-call
bookkeeping;
- **v2 surface:** a v2 client receives `cancelled`.
- I removed each part of the change in turn, and each removal fails a
test: never cancelled, cancelled for v1 too, refusals cancelled too, the
bookkeeping ignoring `cancelled`, and the fallback branches keeping
`failed`.
Follow-up to #1287 (SDK 1.8.0). A v2 turn that fails after its prompt
was taken in now ends with the standard `error` stop reason from
[agent-client-protocol#2281](https://github.com/agentclientprotocol/agent-client-protocol/pull/2281),
in place of the stand-ins we used while the SDK didn't have it.
## Before and after
Before, on the v2 surface only:
1. an error `notice`, titled with the failure;
2. `idle` with the custom stop reason `_error`, and the JSON-RPC error
in `_meta.claudeCode.error`.
Now, one update:
```json
{ "sessionUpdate": "state_update", "state": "idle", "stopReason": "error",
"error": { "code": -32603, "message": "Internal error: API Error: 529 Overloaded" } }
```
- `error` is the JSON-RPC error that v1 rejects the prompt with: same
code, message and data. A client can show `message` and handle `code` as
for an error response, so `-32000` (auth required) can start its sign-in
again, which `_error` couldn't.
- The notice is gone. The v2 draft's
[Failures](https://agentclientprotocol.com/protocol/v2/draft/prompt-lifecycle)
section reports a failure that ends the work through the stop reason,
and keeps notices for failures the agent recovers from.
- v1 and AIR are unchanged.
## Also
- `TurnEvents.failed` loses its `title` parameter. Only the v2 notice
read it, and v1's prompt already ignored it. Its pass-through in
`Turn.reject` and `failActive` goes too. AIR's session failures still
get the title, through their own path.
- The v2 scenario harness treats an `error` stop reason as a failed
turn, and reports its message.
## One visible difference
The old notice showed the failure title, for example `API Error: 529
Overloaded`. The error's message is v1's, `Internal error: API Error:
529 Overloaded`, which v1 clients already show. If we'd rather v2
clients see the shorter text, the alternative is to use the title as the
error's `message` and keep v1's code and data. That would make v2's
message differ from v1's.
## Checks
- `npm run check`, `npm run build` and all 2489 tests pass. No golden
file changes: no recorded scenario fails a turn after insertion.
- The two v2 failure tests pin the new update and the auth code. Putting
`_error` back fails both.
Bumps `@agentclientprotocol/sdk` from 1.7.0 to 1.8.0. The release is one
change: the protocol schema moves to v1.25.0 and v2.0.0-alpha.8.
## What changed in the SDK
Comparing the generated types of 1.7.0 and 1.8.0, the only type change
in v1 and v2 is the `error` stop reason from
[agent-client-protocol#2281](https://github.com/agentclientprotocol/agent-client-protocol/pull/2281):
`IdleStateUpdate` gains `ErrorStopReason & { stopReason: "error" }`, and
`ErrorStopReason` (an optional JSON-RPC `error`) is new. The v2 index no
longer exports `StopReason`; the adapter doesn't import it.
## The one code change
`idle()` in `src/v2/prompt.ts` built the v2 `state_update` for an ended
turn by spreading the turn's stop reason into a `SessionUpdate`. With
the larger `IdleStateUpdate` union, TypeScript can no longer match a
union of stop reasons against it (it falls through to the custom and
unknown members). The state is now typed as the members for the agent's
own stop reasons (`Extract<IdleStateUpdate, { stopReason: StopReason
}>`). A stop reason that v2 doesn't know is still a compile error, which
I checked with a throwaway probe. The output is unchanged.
## Not in this PR
The adapter doesn't use the new `error` stop reason yet. Two stand-ins
stay until a follow-up switches them, which changes behavior and golden
files:
- a failed v2 turn's `_error` stop reason with `_meta.claudeCode.error`,
and its error `notice` (`src/v2/prompt.ts`);
- a failed subagent's `_meta.claudeCode.error` in the RFD form (#1257,
not merged yet).
## Checks
- `npm run check`, `npm run build`, and all 2489 tests pass.
- The scenario suites validate every message against the schemas that
1.8.0 ships (`schema/schema.json`, `schema/v2/schema.unstable.json`),
loaded from the installed SDK. No golden file changes.
## What
ACP `logout` cleared `providerConfig` and the gateway credentials but
left live queries running. Provider and gateway routing is baked into
each query's env, so open sessions kept using the old route after
logout.
`logout` now recreates every live session through the same path as
`providers/disable` (`enqueueProviderUpdate`), but only when a provider
or gateway override was active. It waits for active turns, then resumes
each session under its id with native routing. This also runs when
`claude auth logout` fails, because the override is already cleared by
then.
A plain CLI-login logout does not touch live sessions: the running CLI
picks up the logout by itself.
## Behavior change
With an override active, `logout` now waits for running turns before it
returns, like `providers/disable`. Under `--hide-claude-auth`, a session
that cannot be recreated signed out is dropped, as with
`providers/disable`.
Bumps the minor group with 12 updates in the / directory:
| Package | From | To |
| --- | --- | --- |
|
[@anthropic-ai/claude-agent-sdk](https://github.com/anthropics/claude-agent-sdk-typescript)
| `0.3.287` | `0.3.289` |
| [eslint](https://github.com/eslint/eslint) | `10.11.0` | `10.12.0` |
| @anthropic-ai/claude-agent-sdk-darwin-arm64 | `0.3.287` | `0.3.289` |
| @anthropic-ai/claude-agent-sdk-darwin-x64 | `0.3.287` | `0.3.289` |
| @anthropic-ai/claude-agent-sdk-linux-arm64 | `0.3.287` | `0.3.289` |
| @anthropic-ai/claude-agent-sdk-linux-arm64-musl | `0.3.287` |
`0.3.289` |
| @anthropic-ai/claude-agent-sdk-linux-x64 | `0.3.287` | `0.3.289` |
| @anthropic-ai/claude-agent-sdk-linux-x64-musl | `0.3.287` | `0.3.289`
|
| @anthropic-ai/claude-agent-sdk-win32-arm64 | `0.3.287` | `0.3.289` |
| @anthropic-ai/claude-agent-sdk-win32-x64 | `0.3.287` | `0.3.289` |
|
[@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)
| `1.31.0` | `1.32.1` |
| [hono](https://github.com/honojs/hono) | `4.13.12` | `4.13.13` |
Updates `@anthropic-ai/claude-agent-sdk` from 0.3.287 to 0.3.289
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/anthropics/claude-agent-sdk-typescript/releases">@anthropic-ai/claude-agent-sdk's
releases</a>.</em></p>
<blockquote>
<h2>v0.3.289</h2>
<h2>What's changed</h2>
<ul>
<li>Updated to parity with Claude Code v2.1.289</li>
</ul>
<h2>Update</h2>
<pre lang="sh"><code>npm install @anthropic-ai/claude-agent-sdk@0.3.289
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.289
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.289
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.289
</code></pre>
<h2>v0.3.288</h2>
<h2>What's changed</h2>
<ul>
<li>Updated to parity with Claude Code v2.1.288</li>
</ul>
<h2>Update</h2>
<pre lang="sh"><code>npm install @anthropic-ai/claude-agent-sdk@0.3.288
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.288
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.288
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.288
</code></pre>
</blockquote>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md">@anthropic-ai/claude-agent-sdk's
changelog</a>.</em></p>
<blockquote>
<h2>0.3.289</h2>
<ul>
<li>Updated to parity with Claude Code v2.1.289</li>
</ul>
<h2>0.3.288</h2>
<ul>
<li>Updated to parity with Claude Code v2.1.288</li>
</ul>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="16cf0a7831"><code>16cf0a7</code></a>
chore: Update CHANGELOG.md</li>
<li><a
href="36836f000b"><code>36836f0</code></a>
chore: Update CHANGELOG.md</li>
<li>See full diff in <a
href="https://github.com/anthropics/claude-agent-sdk-typescript/compare/v0.3.287...v0.3.289">compare
view</a></li>
</ul>
</details>
<details>
<summary>Maintainer changes</summary>
<p>This version was pushed to npm by <a
href="https://www.npmjs.com/~GitHub%20Actions">GitHub Actions</a>, a new
releaser for <code>@anthropic-ai/claude-agent-sdk</code> since your
current version.</p>
</details>
<br />
Updates `eslint` from 10.11.0 to 10.12.0
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/eslint/eslint/releases">eslint's
releases</a>.</em></p>
<blockquote>
<h2>v10.12.0</h2>
<h2>Features</h2>
<ul>
<li><a
href="4618052eed"><code>4618052</code></a>
feat: handle astral letters in <code>new-cap</code> (<a
href="https://redirect.github.com/eslint/eslint/issues/21357">#21357</a>)
(sary)</li>
<li><a
href="4ec5168d6d"><code>4ec5168</code></a>
feat: allow <code>SourceCode#getText()</code> to accept tokens and
comments (<a
href="https://redirect.github.com/eslint/eslint/issues/21340">#21340</a>)
(electrohyun)</li>
</ul>
<h2>Bug Fixes</h2>
<ul>
<li><a
href="bc51eee6e3"><code>bc51eee</code></a>
fix: <code>prefer-arrow-callback</code> false positive in conditional
test (<a
href="https://redirect.github.com/eslint/eslint/issues/21373">#21373</a>)
(Daniel Pinto)</li>
<li><a
href="bbff86c415"><code>bbff86c</code></a>
fix: skip lines with multiple comments in
<code>max-lines-per-function</code> (<a
href="https://redirect.github.com/eslint/eslint/issues/21332">#21332</a>)
(xbinaryx)</li>
<li><a
href="efc4d6bdc4"><code>efc4d6b</code></a>
fix: astral letters in <code>consistent-return</code>,
<code>no-eval</code>, <code>no-invalid-this</code> (<a
href="https://redirect.github.com/eslint/eslint/issues/21360">#21360</a>)
(lumir)</li>
<li><a
href="93de066d41"><code>93de066</code></a>
fix: prefer-exponentiation-operator autofix for async function base (<a
href="https://redirect.github.com/eslint/eslint/issues/21322">#21322</a>)
(Vladimir Babin)</li>
<li><a
href="02e34ffba6"><code>02e34ff</code></a>
fix: add missing space after <code>else</code> in <code>curly</code>
autofix (<a
href="https://redirect.github.com/eslint/eslint/issues/21355">#21355</a>)
(Pixel)</li>
<li><a
href="b14b8bc213"><code>b14b8bc</code></a>
fix: correct <code>id-length</code> message for long private names (<a
href="https://redirect.github.com/eslint/eslint/issues/21348">#21348</a>)
(Pixel)</li>
<li><a
href="69aac01d89"><code>69aac01</code></a>
fix: support <code>TSFunctionType</code> in
<code>getFunctionHeadLoc</code> (<a
href="https://redirect.github.com/eslint/eslint/issues/21335">#21335</a>)
(xbinaryx)</li>
<li><a
href="686630eb34"><code>686630e</code></a>
fix: <code>no-loss-of-precision</code> false positive with
<code>0.e5</code> (<a
href="https://redirect.github.com/eslint/eslint/issues/21337">#21337</a>)
(sethamus)</li>
</ul>
<h2>Documentation</h2>
<ul>
<li><a
href="67eb586e2e"><code>67eb586</code></a>
docs: Update README (GitHub Actions Bot)</li>
<li><a
href="5370d7ee35"><code>5370d7e</code></a>
docs: clarify <code>one-var</code> <code>separateRequires</code> matches
any <code>require()</code> call (<a
href="https://redirect.github.com/eslint/eslint/issues/21192">#21192</a>)
(sethamus)</li>
<li><a
href="8816c1ddfc"><code>8816c1d</code></a>
docs: Update README (GitHub Actions Bot)</li>
<li><a
href="3d2e7cedb7"><code>3d2e7ce</code></a>
docs: fix typo in no-unused-expressions documentation (<a
href="https://redirect.github.com/eslint/eslint/issues/21346">#21346</a>)
(bytedoe)</li>
</ul>
<h2>Chores</h2>
<ul>
<li><a
href="152067f0f8"><code>152067f</code></a>
chore: update ecosystem plugins (<a
href="https://redirect.github.com/eslint/eslint/issues/21362">#21362</a>)
(ESLint Bot)</li>
<li><a
href="b56d58e0b1"><code>b56d58e</code></a>
chore: update github/codeql-action action to v4.38.2 (<a
href="https://redirect.github.com/eslint/eslint/issues/21376">#21376</a>)
(renovate[bot])</li>
<li><a
href="bfaea12ddc"><code>bfaea12</code></a>
perf: cache normalized config globals per languageOptions (<a
href="https://redirect.github.com/eslint/eslint/issues/21364">#21364</a>)
(James Ross)</li>
<li><a
href="322209ef16"><code>322209e</code></a>
ci: avoid Nx cache in ecosystem tests and disable failing test (<a
href="https://redirect.github.com/eslint/eslint/issues/21369">#21369</a>)
(Francesco Trotta)</li>
<li><a
href="d166567901"><code>d166567</code></a>
chore: update dependency prettier to v3.9.9 (<a
href="https://redirect.github.com/eslint/eslint/issues/21371">#21371</a>)
(renovate[bot])</li>
<li><a
href="29585ceba7"><code>29585ce</code></a>
chore: update dependency eslint-plugin-expect-type to ^0.7.0 (<a
href="https://redirect.github.com/eslint/eslint/issues/21359">#21359</a>)
(renovate[bot])</li>
<li><a
href="39d79ba965"><code>39d79ba</code></a>
chore: update github/codeql-action action to v4.38.1 (<a
href="https://redirect.github.com/eslint/eslint/issues/21354">#21354</a>)
(renovate[bot])</li>
<li><a
href="182a6e993a"><code>182a6e9</code></a>
chore: update dependency prettier to v3.9.8 (<a
href="https://redirect.github.com/eslint/eslint/issues/21352">#21352</a>)
(renovate[bot])</li>
<li><a
href="f995127230"><code>f995127</code></a>
chore: remove CLAUDE.md in favor of AGENTS.md (<a
href="https://redirect.github.com/eslint/eslint/issues/21339">#21339</a>)
(Jarren)</li>
<li><a
href="b95fb6cb33"><code>b95fb6c</code></a>
chore: update dependency prettier to v3.9.7 (<a
href="https://redirect.github.com/eslint/eslint/issues/21347">#21347</a>)
(renovate[bot])</li>
<li><a
href="3782dd458f"><code>3782dd4</code></a>
chore: update ecosystem plugins (<a
href="https://redirect.github.com/eslint/eslint/issues/21342">#21342</a>)
(ESLint Bot)</li>
</ul>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="a438ec3951"><code>a438ec3</code></a>
10.12.0</li>
<li><a
href="32a73f1441"><code>32a73f1</code></a>
Build: changelog update for 10.12.0</li>
<li><a
href="bc51eee6e3"><code>bc51eee</code></a>
fix: <code>prefer-arrow-callback</code> false positive in conditional
test (<a
href="https://redirect.github.com/eslint/eslint/issues/21373">#21373</a>)</li>
<li><a
href="bbff86c415"><code>bbff86c</code></a>
fix: skip lines with multiple comments in
<code>max-lines-per-function</code> (<a
href="https://redirect.github.com/eslint/eslint/issues/21332">#21332</a>)</li>
<li><a
href="152067f0f8"><code>152067f</code></a>
chore: update ecosystem plugins (<a
href="https://redirect.github.com/eslint/eslint/issues/21362">#21362</a>)</li>
<li><a
href="b56d58e0b1"><code>b56d58e</code></a>
chore: update github/codeql-action action to v4.38.2 (<a
href="https://redirect.github.com/eslint/eslint/issues/21376">#21376</a>)</li>
<li><a
href="67eb586e2e"><code>67eb586</code></a>
docs: Update README</li>
<li><a
href="bfaea12ddc"><code>bfaea12</code></a>
perf: cache normalized config globals per languageOptions (<a
href="https://redirect.github.com/eslint/eslint/issues/21364">#21364</a>)</li>
<li><a
href="322209ef16"><code>322209e</code></a>
ci: avoid Nx cache in ecosystem tests and disable failing test (<a
href="https://redirect.github.com/eslint/eslint/issues/21369">#21369</a>)</li>
<li><a
href="d166567901"><code>d166567</code></a>
chore: update dependency prettier to v3.9.9 (<a
href="https://redirect.github.com/eslint/eslint/issues/21371">#21371</a>)</li>
<li>Additional commits viewable in <a
href="https://github.com/eslint/eslint/compare/v10.11.0...v10.12.0">compare
view</a></li>
</ul>
</details>
<br />
Updates `@anthropic-ai/claude-agent-sdk-darwin-arm64` from 0.3.287 to
0.3.289
<details>
<summary>Maintainer changes</summary>
<p>This version was pushed to npm by <a
href="https://www.npmjs.com/~GitHub%20Actions">GitHub Actions</a>, a new
releaser for <code>@anthropic-ai/claude-agent-sdk-darwin-arm64</code>
since your current version.</p>
</details>
<br />
Updates `@anthropic-ai/claude-agent-sdk-darwin-x64` from 0.3.287 to
0.3.289
<details>
<summary>Maintainer changes</summary>
<p>This version was pushed to npm by <a
href="https://www.npmjs.com/~GitHub%20Actions">GitHub Actions</a>, a new
releaser for <code>@anthropic-ai/claude-agent-sdk-darwin-x64</code>
since your current version.</p>
</details>
<br />
Updates `@anthropic-ai/claude-agent-sdk-linux-arm64` from 0.3.287 to
0.3.289
<details>
<summary>Maintainer changes</summary>
<p>This version was pushed to npm by <a
href="https://www.npmjs.com/~GitHub%20Actions">GitHub Actions</a>, a new
releaser for <code>@anthropic-ai/claude-agent-sdk-linux-arm64</code>
since your current version.</p>
</details>
<br />
Updates `@anthropic-ai/claude-agent-sdk-linux-arm64-musl` from 0.3.287
to 0.3.289
<details>
<summary>Maintainer changes</summary>
<p>This version was pushed to npm by <a
href="https://www.npmjs.com/~GitHub%20Actions">GitHub Actions</a>, a new
releaser for
<code>@anthropic-ai/claude-agent-sdk-linux-arm64-musl</code> since your
current version.</p>
</details>
<br />
Updates `@anthropic-ai/claude-agent-sdk-linux-x64` from 0.3.287 to
0.3.289
<details>
<summary>Maintainer changes</summary>
<p>This version was pushed to npm by <a
href="https://www.npmjs.com/~GitHub%20Actions">GitHub Actions</a>, a new
releaser for <code>@anthropic-ai/claude-agent-sdk-linux-x64</code>
since your current version.</p>
</details>
<br />
Updates `@anthropic-ai/claude-agent-sdk-linux-x64-musl` from 0.3.287 to
0.3.289
<details>
<summary>Maintainer changes</summary>
<p>This version was pushed to npm by <a
href="https://www.npmjs.com/~GitHub%20Actions">GitHub Actions</a>, a new
releaser for <code>@anthropic-ai/claude-agent-sdk-linux-x64-musl</code>
since your current version.</p>
</details>
<br />
Updates `@anthropic-ai/claude-agent-sdk-win32-arm64` from 0.3.287 to
0.3.289
<details>
<summary>Maintainer changes</summary>
<p>This version was pushed to npm by <a
href="https://www.npmjs.com/~GitHub%20Actions">GitHub Actions</a>, a new
releaser for <code>@anthropic-ai/claude-agent-sdk-win32-arm64</code>
since your current version.</p>
</details>
<br />
Updates `@anthropic-ai/claude-agent-sdk-win32-x64` from 0.3.287 to
0.3.289
<details>
<summary>Maintainer changes</summary>
<p>This version was pushed to npm by <a
href="https://www.npmjs.com/~GitHub%20Actions">GitHub Actions</a>, a new
releaser for <code>@anthropic-ai/claude-agent-sdk-win32-x64</code>
since your current version.</p>
</details>
<br />
Updates `@modelcontextprotocol/sdk` from 1.31.0 to 1.32.1
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/modelcontextprotocol/typescript-sdk/releases">@modelcontextprotocol/sdk's
releases</a>.</em></p>
<blockquote>
<h2>1.32.1</h2>
<h2>What's Changed</h2>
<ul>
<li>[v1.x] docs: state the principles in CLAUDE.md by <a
href="https://github.com/claude"><code>@claude</code></a>[bot] in <a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/pull/2939">modelcontextprotocol/typescript-sdk#2939</a></li>
<li>[v1.x] docs: point the README at v2 and say what v1.x supports by <a
href="https://github.com/claude"><code>@claude</code></a>[bot] in <a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/pull/2942">modelcontextprotocol/typescript-sdk#2942</a></li>
<li>chore: bump version to 1.32.1 by <a
href="https://github.com/claude"><code>@claude</code></a>[bot] in <a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/pull/2954">modelcontextprotocol/typescript-sdk#2954</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/modelcontextprotocol/typescript-sdk/compare/1.32.0...1.32.1">https://github.com/modelcontextprotocol/typescript-sdk/compare/1.32.0...1.32.1</a></p>
<h2>1.32.0</h2>
<h2>Upgrade notes</h2>
<ul>
<li><strong>Redirects:</strong> the HTTP client transports now follow a
redirect only when it stays on the same origin (same scheme, host and
port; http to https on the same host is allowed). A deployment whose
endpoint redirects to another host or port either configures the final
URL or sets <code>redirectPolicy: 'follow'</code> on
<code>StreamableHTTPClientTransport</code> or
<code>SSEClientTransport</code>. In browsers, a redirected request fails
unless that option is set.</li>
<li><strong>New options, both off unless you set them:</strong>
<code>maxToolInputElements</code> on <code>McpServer</code> limits the
number of array elements and object members in a tool call's arguments.
<code>expectedResource</code> on <code>requireBearerAuth</code> accepts
only tokens issued for this server (the token's audience).</li>
</ul>
<h2>What's Changed</h2>
<ul>
<li>[v1.x] fix(client): follow redirects only within the endpoint's
origin by <a
href="https://github.com/claude"><code>@claude</code></a>[bot] in <a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/pull/2902">modelcontextprotocol/typescript-sdk#2902</a></li>
<li>docs: point SECURITY.md at GitHub Security Advisories (v1.x) by <a
href="https://github.com/claude"><code>@claude</code></a>[bot] in <a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/pull/2910">modelcontextprotocol/typescript-sdk#2910</a></li>
<li>[v1.x] examples: close idle sessions and cap the session map by <a
href="https://github.com/maxisbey"><code>@maxisbey</code></a> in <a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/pull/2914">modelcontextprotocol/typescript-sdk#2914</a></li>
<li>[v1.x] fix(tasks): keep tasks of the in-memory task store within the
session that created them by <a
href="https://github.com/claude"><code>@claude</code></a>[bot] in <a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/pull/2925">modelcontextprotocol/typescript-sdk#2925</a></li>
<li>[v1.x] feat(server): add maxToolInputElements option to limit the
number of elements in tool-call arguments by <a
href="https://github.com/claude"><code>@claude</code></a>[bot] in <a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/pull/2927">modelcontextprotocol/typescript-sdk#2927</a></li>
<li>[v1.x] fix(server): accept tools/call and prompts/get requests that
omit arguments by <a
href="https://github.com/raashish1601"><code>@raashish1601</code></a>
in <a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/pull/2045">modelcontextprotocol/typescript-sdk#2045</a></li>
<li>[v1.x] feat(auth): add expectedResource to requireBearerAuth by <a
href="https://github.com/claude"><code>@claude</code></a>[bot] in <a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/pull/2930">modelcontextprotocol/typescript-sdk#2930</a></li>
<li>[v1.x] test(e2e): cover tools/call and prompts/get without arguments
by <a href="https://github.com/claude"><code>@claude</code></a>[bot] in
<a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/pull/2931">modelcontextprotocol/typescript-sdk#2931</a></li>
<li>chore: bump version to 1.32.0 by <a
href="https://github.com/claude"><code>@claude</code></a>[bot] in <a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/pull/2935">modelcontextprotocol/typescript-sdk#2935</a></li>
</ul>
<h2>New Contributors</h2>
<ul>
<li><a
href="https://github.com/raashish1601"><code>@raashish1601</code></a>
made their first contribution in <a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/pull/2045">modelcontextprotocol/typescript-sdk#2045</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/modelcontextprotocol/typescript-sdk/compare/1.31.0...1.32.0">https://github.com/modelcontextprotocol/typescript-sdk/compare/1.31.0...1.32.0</a></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="ff07b00119"><code>ff07b00</code></a>
chore: bump version to 1.32.1 (<a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/issues/2954">#2954</a>)</li>
<li><a
href="8a74d504a9"><code>8a74d50</code></a>
[v1.x] docs: point the README at v2 and say what v1.x supports (<a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/issues/2942">#2942</a>)</li>
<li><a
href="a8cf50360f"><code>a8cf503</code></a>
[v1.x] docs: state the principles in CLAUDE.md (<a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/issues/2939">#2939</a>)</li>
<li><a
href="32549b00a9"><code>32549b0</code></a>
chore: bump version to 1.32.0 (<a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/issues/2935">#2935</a>)</li>
<li><a
href="588d51dbe3"><code>588d51d</code></a>
[v1.x] test(e2e): cover tools/call and prompts/get without arguments (<a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/issues/2931">#2931</a>)</li>
<li><a
href="5a0724d14c"><code>5a0724d</code></a>
[v1.x] feat(auth): add expectedResource to requireBearerAuth (<a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/issues/2930">#2930</a>)</li>
<li><a
href="0ca0b62d93"><code>0ca0b62</code></a>
[v1.x] fix(server): accept tools/call and prompts/get requests that omit
argu...</li>
<li><a
href="fd26801b3b"><code>fd26801</code></a>
[v1.x] feat(server): add maxToolInputElements option to limit the number
of e...</li>
<li><a
href="727075b5bb"><code>727075b</code></a>
[v1.x] fix(tasks): keep tasks of the in-memory task store within the
session ...</li>
<li><a
href="0ff63772da"><code>0ff6377</code></a>
[v1.x] examples: close idle sessions and cap the session map (<a
href="https://redirect.github.com/modelcontextprotocol/typescript-sdk/issues/2914">#2914</a>)</li>
<li>Additional commits viewable in <a
href="https://github.com/modelcontextprotocol/typescript-sdk/compare/1.31.0...1.32.1">compare
view</a></li>
</ul>
</details>
<br />
Updates `hono` from 4.13.12 to 4.13.13
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/honojs/hono/releases">hono's
releases</a>.</em></p>
<blockquote>
<h2>v4.13.13</h2>
<h2>Mount Middleware</h2>
<p><code>app.mount()</code> is now available as the Mount Middleware,
<code>hono/mount</code>. It is just a handler, so you register it with
<code>app.all()</code>:</p>
<pre lang="ts"><code>import { Router as IttyRouter } from 'itty-router'
import { Hono } from 'hono'
import { mount } from 'hono/mount'
<p>const ittyRouter = IttyRouter()<br />
ittyRouter.get('/hello', () => new Response('Hello from
itty-router'))</p>
<p>const app = new Hono()<br />
app.all('/itty-router/*', mount(ittyRouter.handle))<br />
</code></pre></p>
<p><code>app.mount()</code> still works in v4 but is deprecated and will
be removed in v5. Migrating is a one-line change:</p>
<pre lang="diff"><code>- app.mount('/itty-router', ittyRouter.handle)
+ app.all('/itty-router/*', mount(ittyRouter.handle))
</code></pre>
<h2>What's Changed</h2>
<ul>
<li>test(client): simulate network error for undefined route in
parseResponse test in <a
href="https://redirect.github.com/honojs/hono/pull/5439">honojs/hono#5439</a></li>
<li>docs(request): fix jsdoc comments for some getters in <a
href="https://redirect.github.com/honojs/hono/pull/5445">honojs/hono#5445</a></li>
<li>fix(jsx): allow JSXNode function component results in <a
href="https://redirect.github.com/honojs/hono/pull/5476">honojs/hono#5476</a></li>
<li>feat(mount): introduce Mount Middleware and deprecate
<code>app.mount</code> in <a
href="https://redirect.github.com/honojs/hono/pull/5221">honojs/hono#5221</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/honojs/hono/compare/v4.13.12...v4.13.13">https://github.com/honojs/hono/compare/v4.13.12...v4.13.13</a></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="08a023cbfd"><code>08a023c</code></a>
4.13.13</li>
<li><a
href="ae595de8ae"><code>ae595de</code></a>
feat(mount): introduce Mount Middleware and deprecate
<code>app.mount</code> (<a
href="https://redirect.github.com/honojs/hono/issues/5221">#5221</a>)</li>
<li><a
href="f23b146afc"><code>f23b146</code></a>
fix(jsx): allow JSXNode function component results (<a
href="https://redirect.github.com/honojs/hono/issues/5476">#5476</a>)</li>
<li><a
href="6d73a74f97"><code>6d73a74</code></a>
docs(request): fix jsdoc comments for some getters (<a
href="https://redirect.github.com/honojs/hono/issues/5445">#5445</a>)</li>
<li><a
href="deff529656"><code>deff529</code></a>
test(client): simulate network error for undefined route in
parseResponse tes...</li>
<li>See full diff in <a
href="https://github.com/honojs/hono/compare/v4.13.12...v4.13.13">compare
view</a></li>
</ul>
</details>
<br />
Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.
[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)
---
<details>
<summary>Dependabot commands and options</summary>
<br />
You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore <dependency name> major version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's major version (unless you unignore this specific
dependency's major version or upgrade to it yourself)
- `@dependabot ignore <dependency name> minor version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's minor version (unless you unignore this specific
dependency's minor version or upgrade to it yourself)
- `@dependabot ignore <dependency name>` will close this group update PR
and stop Dependabot creating any more for the specific dependency
(unless you unignore this specific dependency or upgrade to it yourself)
- `@dependabot unignore <dependency name>` will remove all of the ignore
conditions of the specified dependency
- `@dependabot unignore <dependency name> <ignore condition>` will
remove the ignore condition of the specified dependency and ignore
conditions
</details>
---------
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>
## Motivation
A prompt sent while Claude Code runs a turn it started on its own, for
example after a background task finished, is folded into that turn. The
turn's result keeps `origin: task-notification` but lists the prompt in
`user_message_uuids`. The adapter routed results by origin only, so
`session/prompt` was never answered and the client stayed in a running
state. A JetBrains AIR session stayed "running" for hours this way.
## Change
A task-notification result that names a pending prompt now answers it. A
turn held for its subagents still waits for them. Results without the
uuids behave as before.
## Tests
Unit tests in `acp-agent.test.ts` and a replay of the session in
`folded-prompt-scenario.test.ts`. Both hang without the fix.
From a third review of the RFD form, against the subagents RFD as
revised by agentclientprotocol/agent-client-protocol#2308 (a cancel stops
the descendant work the cancelled work waits on; the rest is up to the
Agent; the Client cleans up a descendant's requests once it reports a
cancelled idle):
- At the end of the stream, or a conversation reset, a child that still
runs is idle with no stop reason. After a cancel it is a background
child that outlived it, so reporting `cancelled` invented a
cancellation, which under #2308 also tells the client to clean up its
requests. Foreground children report their cancellation from the SDK's
task events, before the cancelled prompt resolves.
- A SendMessage result whose call has no message text still names the
call, so a late result does not resume a run that already ended.
- An agent-level test pins #2308's validation scenario: at a root
cancel, the foreground child's request is withdrawn and it reports a
cancelled idle before the prompt response; the background child keeps
running with its request open, and ends idle with no reason.
- README says what `session/cancel` does to children.
AIR's path and golden files are unchanged.
The RFD needs a child session id unique within the connection and never
under two parents. Agent ids are random and an agent keeps its parent, so
only a fork could repeat one under another root, which the SDK's
forkSession cannot do today because it copies no subagents/ history.
Bumps the minor group with 2 updates:
[@types/node](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/node)
and [ip-address](https://github.com/beaugunderson/ip-address).
Updates `@types/node` from 26.6.3 to 26.6.4
<details>
<summary>Commits</summary>
<ul>
<li>See full diff in <a
href="https://github.com/DefinitelyTyped/DefinitelyTyped/commits/HEAD/types/node">compare
view</a></li>
</ul>
</details>
<br />
Updates `ip-address` from 10.7.2 to 10.7.3
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/beaugunderson/ip-address/releases">ip-address's
releases</a>.</em></p>
<blockquote>
<h2>v10.7.3</h2>
<h2>What's Changed</h2>
<ul>
<li>Reject an in-addr.arpa name longer than 32 characters before
splitting it by <a
href="https://github.com/beaugunderson"><code>@beaugunderson</code></a>
in <a
href="https://redirect.github.com/beaugunderson/ip-address/pull/228">beaugunderson/ip-address#228</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/beaugunderson/ip-address/compare/v10.7.2...v10.7.3">https://github.com/beaugunderson/ip-address/compare/v10.7.2...v10.7.3</a></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="c7f838eeca"><code>c7f838e</code></a>
10.7.3</li>
<li><a
href="09b8072f5e"><code>09b8072</code></a>
Reject an in-addr.arpa name longer than 32 characters before splitting
it (<a
href="https://redirect.github.com/beaugunderson/ip-address/issues/228">#228</a>)</li>
<li>See full diff in <a
href="https://github.com/beaugunderson/ip-address/compare/v10.7.2...v10.7.3">compare
view</a></li>
</ul>
</details>
<br />
Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.
[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)
---
<details>
<summary>Dependabot commands and options</summary>
<br />
You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore <dependency name> major version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's major version (unless you unignore this specific
dependency's major version or upgrade to it yourself)
- `@dependabot ignore <dependency name> minor version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's minor version (unless you unignore this specific
dependency's minor version or upgrade to it yourself)
- `@dependabot ignore <dependency name>` will close this group update PR
and stop Dependabot creating any more for the specific dependency
(unless you unignore this specific dependency or upgrade to it yourself)
- `@dependabot unignore <dependency name>` will remove all of the ignore
conditions of the specified dependency
- `@dependabot unignore <dependency name> <ignore condition>` will
remove the ignore condition of the specified dependency and ignore
conditions
</details>
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Fixes from a second review of the RFD form, for resume and end events
that arrive out of their usual order:
- Each delegation is the call the SDK runs it under. A run's end records
its call; a SendMessage result for a call whose run already ended
resumes nothing (`isEndedDelegation`), so a late result no longer sets
an idle child running for good or re-arms the turn's hold.
- The end of an earlier delegation ends nothing (`isStaleEnd`), now also
in the agent: a stale task_notification no longer settles the resumed
run's live task, which permission attribution and the turn hold use.
- A run under an id the child used before becomes the current delegation
again: the check compares with the current call, not the map.
- A child that was never announced does not take a resume's call, so a
late frame cannot announce a withdrawn child.
- A running task_updated patch reports only that the child runs: its
prompt is a guess, and the task_started or SendMessage result carries
the delegation (`sendMessageResumed`). `taskResumed` keeps its
signature from main.
- A resume while a request of the child is open reports requires_action.
- The end-to-end stale-end test now checks that the child stays running
until the real end.
AIR's path and golden files are unchanged.
It affects AIR clients with the `asyncTasks` capability.
## Problem
- A subagent can start a background Bash or Monitor and then end its
turn. The task ends after the subagent finished. The route of the task
dropped every update of a finished child generation, so the client never
got the terminal `async_task_state_update`. The task stayed running in
the client forever. One AIR log held 440 such dropped updates.
- The `Monitor` tool streams the stdout of a background command to the
model only. The SDK reports its task as `local_bash`, so the client
showed it as a background shell. In one real session, 18 of 18 Monitor
tasks had no output file, no progress and no result. The Stop button
only broke the agent's wait.
- The adapter read a task id from the text of a Bash tool result. A
foreground `sed`, `strings` or `python3` that printed adapter source,
test fixtures or CLI strings became a background task, for example with
the id `";\n const start = text` or `${e}`. The client got a spawn and a
`backgrounded` marker on a foreground call, and the task never ended.
- Claude Code 2.1.287 reports a background command in four texts, and
only one gave an output path. A subagent tool result almost never has
`tool_use_result` (0 of 48 in one session). So a subagent command that
hit its timeout got no output path (9 of 10).
## Fix
- `NativeSubagentRuntime.routeOfToolCall` still sends
`async_task_spawned`, `async_task_progress` and
`async_task_state_update` to the child generation that owned the tool
call after that child finished. It never sends them to a later
generation. Every other late update is dropped as before. The spawn is
in the list because a held task can get its tool call id after the
subagent finished.
- `AsyncTaskRuntime` takes a `toolNameOf` lookup. A task of a `Monitor`
tool call is ignored, like a subagent task: no spawn, no progress, no
state, and no stop. A held task that gets its tool call id later goes
through the same check. A `local_monitor` task is ignored too. The
`Monitor` tool call stays in the transcript.
- A task comes only from structured data:
`tool_use_result.backgroundTaskId` or the SDK task events. The text id
parser is gone.
- The output path of a known task can come from the result of its own
tool call. The path ends with `tasks/<id>.output` and starts after the
nearest `": "` on the same line, so a path with spaces works, for
example under `C:\Users\John Doe\AppData\Local\Temp`. It must be
absolute (POSIX, a Windows drive or UNC), and it never holds the end of
another path. The parse is linear in the text length. All four texts
give the path in both event orders: the tool result before or after the
SDK names the task. The memory is bounded. A structured path still wins,
and the terminal `output_file` reaches the client also after a level
close.
- The `backgrounded` marker comes only from structured data: the
structured task, a known background task of the tool call, or a
`run_in_background` input. The "both event orders" above holds for the
path, not for this marker. The marker rides the tool result update, so a
command that the SDK names only after its tool result gets the marker
only from a `run_in_background` input. A command that the user moved to
the background by hand gets no marker in that order.
- The replay behaves the same in each case.
## Tests
- Native subagent and agent tests: a task update and a late spawn after
the child finished go to `worker-1`; a held task of a subagent gets its
spawn and state in the child session after the subagent finished; a late
message chunk is still dropped; a subagent's background Bash ends after
the subagent and the client gets the terminal state in the child
session.
- Monitor: runtime, live and replay tests, also a task that names its
tool call after the tool result. A Monitor task cannot be stopped.
- Structured ids: foreground output with each marker text creates no
task; each of the four texts gives the path in both orders, also a
Windows and a POSIX path with spaces and a UNC path; no path of another
task, another tool call, `.outputs`, a relative path, a path without a
`": "` boundary, or a path across a line; two paths on one line are not
glued; a 2 MB text without `": "` parses in milliseconds; a structured
path wins. An agent test covers a subagent without `tool_use_result`,
and a replay test takes the path from the tool result.
- The new tests fail without the change. Build, lint, format and all
tests pass.
## Abandoned streamed tool calls
This part affects every client, Zed included.
**Problem.** The adapter opens a tool call at the `content_block_start`
of a streamed `tool_use`. Claude can abandon that block before it is
complete, for example for a steering message. The tool then never runs.
At end_turn the settle check reported the session failure "Claude ended
the turn without returning results for tool calls"
(`incomplete_tool_call`). A real AIR session showed a red service error
after 27 minutes of normal work, for a call that never had input.
**Fix.**
- The session records the tool calls that Claude Code sent to the tool
runner: the `tool_use` blocks of a complete assistant message, and the
tool calls of a permission request. The record is bounded and is dropped
when the call ends.
- At end_turn, an open foreground call without that record is abandoned.
The adapter closes it as failed with "Claude stopped this tool call
before it ran." and reports no session failure. The turn ends as
`end_turn`.
- An open call with that record keeps the old behaviour: the old failure
text and the `incomplete_tool_call` session failure.
- The cleanup and the cancellation checks are the same for both groups.
- The replay does not change, because the history holds no partial
`tool_use`. No scenario golden file changes, for AIR, plain or Zed.
**Tests.** A partial `tool_use` and then text ends as `end_turn` with
the neutral close. A mixed turn still fails for the unfinished call. A
steering message during a partial `tool_use` gives no failure. The
existing incomplete-tool tests now send the complete `tool_use` and keep
their failure. The new tests fail without the change.
Fixes from a close review of the RFD form, against the subagents RFD and
the bundled Claude Code CLI:
- The CLI runs a resumed agent under the id of the call that resumed it
(`toolUseContext.toolUseId`, the SendMessage call). The child now takes
over that id, so the resumed run's output and its task_notification
reach the child instead of being buffered and dropped. A task_started
of a known child resumes it even without a subagent type.
- A prompt message's id is the id of the call that delegated, and a
prompt whose id is already in the child's transcript is not sent
again, so a repeated resume signal does not overwrite or repeat it.
- The end of an earlier delegation no longer ends the current one.
- A resume's `senderSessionId` is the session that made the SendMessage
call, and is left out when unknown, instead of always the parent.
- A failure reported first without the SDK's error text gets it when a
later event of the same failure carries it.
- A task that a worker restart orphaned is idle with no stop reason, not
cancelled: the RFD forbids inventing a cancellation.
- A child that ends before its parent is known stays unexposed, rather
than being announced under the root: the RFD forbids guessing parentage.
- A late frame that names a child keeps its role in the title.
- `announceNativeSubagent` takes its form explicitly.
- README, docs/air-extensions.md and doc comments say what the code does.
AIR's path and golden files are unchanged.
A client that declares `clientCapabilities.subagents` and is not AIR now
gets native subagent sessions in the form of the revised subagents RFD
(agentclientprotocol/agent-client-protocol#1992, docs/rfds/subagents.mdx),
which SDK 1.7.0 types. AIR keeps the earlier draft it implements
(`subagent_spawned`, `subagent_state_update`), whichever signal it
declares; its golden files do not change.
In the RFD form (`SubagentForm`, chosen by `subagentForm`):
- The child's session id is the SDK agent id, for every delegation to
it: a SendMessage resume no longer opens a new generation.
- `subagent_update` announces the child on its immediate parent before
any child traffic, with `title` (the agent's name, with its role after
it, else the role), `description` (the Agent input's short
description, never the prompt), and the `running` state.
- The prompt of each delegation is a `session_message` in the child's
transcript, from the parent, with the id of the tool use that sent it.
The Agent, Task, or SendMessage tool call stays a tool call of the
session that made it.
- The work state follows the SDK: `requires_action` while a permission
or question request of the child is open, `idle` with `end_turn`,
`cancelled` when the SDK stopped or killed the task, and a failure as
`idle` with the SDK's error in `_meta.claudeCode.error`. (The RFD's
`error` stop reason is newer than SDK 1.7.0's closed v1 StopReason.)
`session/cancel` no longer ends the children: a background subagent
outlives the interrupt, and the RFD reports a cancellation only from
evidence. At the end of the stream a running child gets `idle`,
`cancelled` after a cancel.
- An idle child is reusable, so its later updates still reach it.
- No per-child capabilities, so a client may not change a child.
- Replay does not expose children yet, until it keeps their live ids.
The agent-side `sessionCapabilities.subagents` goes to AIR alone: the RFD
has only the client capability. compare.ts allows it against the
origin/main baseline.
Tests: the end-to-end tests of the earlier draft now run with an AIR
client; new runtime and end-to-end tests cover the RFD form, and check
every update against the v1 schema.
Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>
Step 6 of opt-in ACP v2 support, option (b) as decided in review.
Stacked on #1255: both change the `initialize` line of every v2 golden
file. Once #1255 merges, I'll merge `main` into this branch so the diff
shows fork alone. Nothing changes on ACP v1.
## Why fork, then resume
The agent's v1 fork copies the transcript into a new session and returns
only its id. Until a client resumes or loads the fork, a prompt to it
fails with "Session not found", and the request's `mcpServers` go
unused. AIR, the only v1 client that forks, loads the fork right away.
The fork RFD describes the response as "the same as `session/new`", with
config options, and the request as taking `session/load`'s options. So
on v2 the client gets a session it can prompt at once:
- `v1ForkSessionRequests` (`src/v2/session.ts`) builds the v1 fork, then
a v1 resume of the fork without replay, with the request's `cwd`,
`additionalDirectories` and `mcpServers`. The request's `_meta` goes to
the fork alone.
- The response is the new `sessionId` plus the resume's `configOptions`.
The available commands follow as an update, as for `session/new` and
`session/resume`.
- `capabilities.session.fork: {}` is advertised.
Each fork starts its own Claude Code process, as `session/new` does. The
draft doesn't say whether a fork must be live, so that's recorded as
feedback for it.
## Verification
- An end-to-end test forks a session with an HTTP MCP server, checks the
forked Claude Code session resumes the copied transcript with that
server, and prompts the fork without a `session/resume`.
- Removing the resume, the MCP servers or the capability fails tests.
- Every v2 golden file changes on its `initialize` line only, which
gains `session.fork`.
- Build, lint and all 2411 tests pass.
Step 6 of opt-in ACP v2 support. Stacked on #1254: both change the
`initialize` line of every v2 golden file. GitHub retargets this PR to
`main` once #1254 merges. Nothing changes on ACP v1.
## Change
- The v2 surface serves `providers/list`, `providers/set` and
`providers/disable` through the agent's unstable v1 methods. Every
provider type is identical in v1 and v2, so requests and responses pass
through unchanged.
- The v2 `initialize` response advertises `capabilities.providers: {}`,
a constant like `capabilities.session`, since the agent serves the
methods for every client.
## Verification
- An end-to-end test lists the provider, sets a gateway and lists it,
gets `invalid_params` for an unknown provider, and disables the provider
back to the native routing.
- The handshake test checks the capability. Removing the capability or a
handler fails tests.
- Every v2 golden file changes on its `initialize` line only, which
gains `providers: {}`.
- Build, lint and all 2410 tests pass.
Found while reviewing what's left of opt-in ACP v2 support. Nothing
changes on ACP v1.
## Problem
The agent advertises `_session/steering` in the top-level `_meta` of its
v1 `initialize` response (`steering: { supported: true }`), and the v2
handshake passed that `_meta` through. The v2 surface doesn't register
`_session/steering`, so a v2 client that steered got "method not found".
## Change
The v2 `initialize` response leaves out the top-level `_meta` keys that
advertise an extension the v2 surface doesn't serve
(`UNSERVED_EXTENSION_KEYS` in `src/v2/initialize.ts`), which is
`steering` alone today. That sits next to the existing rule that keeps
the unstable `providers` capability unadvertised.
Whether v2 serves steering is left to the plan for the unstable and
extension surfaces. The protocol has no steering RFD yet, and steering
may need a different design on v2, which answers a prompt as soon as
it's accepted.
## Verification
- The handshake test checks that the v2 response has no
`_meta.steering`. The v1 handshake tests still check that v1 advertises
it.
- Every v2 golden file changes on its `initialize` line only. The line
loses its `_meta` and is otherwise identical.
- Build, lint and all 2409 tests pass.
Part of step 6 of opt-in ACP v2 support. Compaction and session notices
are both Preview features of the v2 draft that are expected to stabilize
soon, and v2 requires no client capability for either. Nothing changes
on ACP v1.
## Compaction
The agent already implements the compaction RFD for v1 clients that
declare `clientCapabilities.session.compaction`, live and on replay. A
v2 client got the legacy "Compact conversation" tool call instead,
because the v2 surface didn't declare it.
- `v1InitializeRequest` now tells the agent that every v2 client takes
compaction updates, as it already did for notices.
- `v2SessionUpdate` passes `compaction_update` and
`compaction_summary_chunk` through: their v1 and v2 shapes are
identical.
So a v2 client now gets:
- **live:** `compaction_update` `in_progress`, the summary as
`compaction_summary_chunk`, then `completed` (or `failed` with the
standard `error`);
- **on replay:** one completed `compaction_update` with the summary, at
the summary's position in the transcript. That's the materialized form
the v2 draft asks for, without the start/chunk/finish sequence.
The token counts and duration that the tool call's `rawOutput` carried
have no v2 field. Only AIR gets them, in `_meta`.
## Notices
These were already sent to every v2 client, but no test covered one on
v2. A new end-to-end test sends Claude Code's `informational` warning as
a live `notice`. The agent sends notices only live, never during replay,
which matches the draft's "SHOULD NOT be replayed".
## Not changed
**A replayed compaction's id differs from its live id.** Live, the id is
the uuid of Claude Code's `compacting` status, which the transcript
doesn't keep. Replay uses the summary message's uuid. The draft and the
RFD ask for the original, stable ids. As with replayed message ids, a
client that kept its view would see the compaction twice. Matching them
needs Claude Code to persist the live id.
## Verification
- The 3 compaction scenarios change their v2 golden files: the tool call
becomes the compaction entity. The scenario names still say `legacy`
because they're named for the v1 capability.
- Unit tests cover the pass-through and the capability. End-to-end tests
cover the live notice, and the replayed compaction between the messages
around it.
- Removing the capability or the pass-through fails tests.
- Build, lint and all 2409 tests pass.
Found while mapping commands to ACP v2 display terminals (#1240). It
affects Zed and plain ACP v1 terminal clients and the v2 surface. **AIR
is unchanged.**
## Problem
The agent reported every command's exit with a number, even when it
didn't know the code:
- **any failure as 1.** A command that exited with 2, or a denied
command that never ran, showed "Exited with code 1".
- **a backgrounded command as 0 when it launched**, though it's still
running.
- **an interrupted command as 1**, and a non-zero code that Claude Code
accepted as a success (grep with no matches) as 0.
## Change
`CommandOutput.exitCode` is now optional. `BashReporter` sets it only
when the tool result says it. I checked each source against the Claude
Code 2.1.287 binary:
- **a failure:** the `Exit code N` line that starts Claude Code's text
of a command that exited with a failing code (`rE`/`JPr` for a
`ShellError`). A failure that names none, such as a denial or a spawn
error, has no code.
- **a success:** 0, unless the structured `BashOutput` says otherwise.
Claude Code accepts a non-zero code as a success only with a
`returnCodeInterpretation`, such as grep's "No matches found" or diff's
"Files differ". An interrupted command (an Esc interrupt returns a
success with `interrupted: true`) and a backgrounded one have no code
either.
- **the code-execution block:** its `return_code`, as before.
An unknown code goes out as:
- **v1, Zed and plain clients:** `_meta.terminal_exit.exit_code: null`.
The v1 `TerminalExitStatus` allows null. Zed (`as_u64()` → `None`) and
Delta's v1 adapter (`Option<u32>`) read it as an optional code. Zed then
shows a failed command as failed, without the "Exited with code N"
tooltip, and every other exit as before. `compare.ts` allows the null
code against the origin/main baseline, a documented difference like the
`mcp` command in #1218.
- **v2:** `exitStatus` without `exitCode`, which the v2 schema treats
the same as null.
- **AIR:** the numbers it always got (1 for a failed or interrupted
command, else the code, or 0). Whether AIR accepts a null code is
unchecked, so this stays out of AIR's contract. The command fact carries
`interrupted` for that. The AIR golden files and
`docs/air-extensions.md` don't change.
## For review
- **Interrupted commands** no longer show as failed in Zed, since the
tool call completes and no code is known. Their output still ends with
"[Command was aborted before completion]".
## Not changed
- **A backgrounded command's terminal still exits at launch**, now
without a code. It could stay running until the task's
`task_notification`. That needs the task's end routed to the terminal,
also on replay, so it's a separate change.
- **Replay has no `tool_use_result`** (the same gap as replayed diffs),
so a replayed success still reports 0 when Claude Code interpreted the
code or backgrounded the command.
## Verification
A table test pins, for each kind of exit, the code Zed gets and the
number AIR gets: a success, a failure that names its code, one that
names none, an interrupted, a backgrounded, and an interpreted command.
A unit test covers the v2 `exitStatus` without a code. Removing any one
of the rules, including AIR's, fails tests. Golden files change for 3 v2
scenarios, each on its exit line only. Build, lint and all 2399 tests
pass.
## Why
#1112 removed the main-thread agent picker on the assumption that ACP
clients don't use it. That was wrong: Zed exposes the `Agent` config
option and users rely on it daily to start sessions with a custom agent
(see the feedback on #1112). It is also still the only way to pick a
main-thread agent for enterprise Claude Code setups.
Restoring it has no meaningful cost: `supportedAgents()` reads from the
already-awaited initialization response, so session creation doesn't
gain a round-trip.
## Summary
Reverts #1112:
- restore the `agent` session config option (shown only when custom
agents are configured) and custom-agent discovery
- restore live agent switching via `applyFlagSettings({ agent })`
- forward `_meta.claudeCode.options.agent` again and keep it across
context resets
- restore the exports `DEFAULT_AGENT_ID`, `AGENT_CONFIG_ID`,
`BUILTIN_AGENT_NAMES`, `discoverCustomAgents`
Conflicts with later changes on `main` (MCP command import, initial
permission mode / bypass resolution, context-window refresh after model
switch, effort settings) were resolved keeping the newer code.
## Testing
- npm run check
- npm run build
- npm run test:run (2399 passed)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Found while writing the test for #1242. It affects ACP v1 and v2.
## Problem
When Claude Code wedges after a cancel (issue #680), the force-cancel
backstop aborts the consumer's cancel signal, so the consumer settles
the turn as `cancelled`. The consumer races each next message against
that signal by adding an `abort` listener on each iteration. But a
listener added to an already-aborted signal never fires.
So if the backstop fired while the consumer was busy outside the race,
such as sending an update to a slow client, the consumer missed it. It
then waited for a message from the wedged Claude Code that never came,
and the cancelled `session/prompt` was never answered (v2: no `idle
cancelled`). Teardown aborts the same signal, which is how #1242's test
ran into it.
## Change
The race also wakes for a signal that's already aborted:
- The consumer re-arms its signal after each abort it handles, so an
aborted signal there is always an unhandled abort. It can't loop.
- A message that's already waiting still wins the race, since
`Promise.race` checks it first, so no message is dropped.
## Verification
A new turn-events test has Claude Code stream an answer and then wedge.
The client takes the chunk slowly, the user cancels, and the backstop
(10 ms in the test) fires while the consumer is still sending. The turn
ends `cancelled`; without the change it never ends. Build, lint and all
2389 tests pass.
Found while planning the permission requests of opt-in ACP v2 support
(step 5 of the v2 plan). It affects ACP v1 clients that show native
subagent sessions (`subagents` capability, or AIR's native subagent
sessions).
## Problem
For such a client, a native subagent's permission request or
AskUserQuestion goes to the subagent's child session. The agent counted
the open request on that session id, but child sessions aren't in
`sessions`, so `withPendingUserInput` counted nothing:
- **Steering:** a message steered while the subagent's request was open
didn't see it, so it went out with interrupting priority instead of
`later`, the priority used while the user has a prompt open.
- **Turn state:** the turn didn't report that it awaits the user. That's
`requires_action` in ACP v2, though the v2 surface doesn't show child
sessions today, so v2 isn't affected yet.
## Change
The request is still sent to the child session, but it now counts
against the owner session, whose turn and steering it blocks. Both paths
take the owner id: `requestPermissionFromClient` already had it
(`ownerSessionId`), and `handleAskUserQuestion` gets it next to the
session it sends the elicitation to.
## Verification
The existing "uses priority:'later' while … is pending" test gains two
cases: a subagent's permission request and a subagent's AskUserQuestion,
both sent to an announced child session. Each fails when its half of the
fix is reverted. Build, lint and all 2390 tests pass.
Found while reviewing the ACP v2 prompt lifecycle (#1226). It affects
ACP v1 and v2.
## Problem
`session/close` tears the session down: `teardownSession` cancels its
turns, wakes the consumer, and closes the query. It returned without
waiting for the cancelled turns to end, so the close could answer first:
- **v1:** the `session/prompt` response arrived after the
`session/close` response.
- **v2:** the turn's `idle cancelled` arrived after the close response.
v2's `session/close` cancels "as if `session/cancel` had been called",
then frees the session.
It happens when the consumer settles the turn late: for example, while
it's still sending an update to a slow client, or when it settles the
turn only at the end of the stream that the close ends.
## Change
`teardownSession` now returns once the turns it cancels have ended (each
turn's `completion`), for at most `TEARDOWN_TURN_END_TIMEOUT_MS` (5 s),
which it logs if a wedged consumer hits it. Its other callers get the
same order too: `session/delete`, the recreation of a session whose
parameters changed on resume or load, and `dispose()`.
## Found along the way, not changed here
The consumer's abort race adds an `abort` listener to the cancel signal
on each iteration. A listener added to an already-aborted signal never
fires, so an abort that lands while the consumer is busy, such as
sending an update, is missed. In production the close still ends the
turn, through the end of the stream, which is the path this PR waits
for. But the same gap can defeat the force-cancel backstop for a wedged
Claude Code (issue #680). That gets its own PR next.
## Verification
A new turn-events test has the client accept an answer chunk slowly,
closes the session while the consumer is still sending it, and checks
that the turn's end comes before the close returns. It fails without the
change: the close returns first. Build, lint and all 2389 tests pass.
Third part of step 4 of opt-in ACP v2 support (after #1231, #1232,
#1237): a v2 client now sees each command the agent runs in an
Agent-owned display terminal, instead of its output as a code block.
Nothing changes on ACP v1.
## Why a mapping
The agent already reports commands through the terminal extension of ACP
v1 clients, as codex-acp does:
- `_meta.terminal_info` names a terminal, which the tool call's content
references;
- `terminal_output` (a snapshot) or `terminal_output_delta` (a chunk)
carries the output;
- `terminal_exit` carries the exit.
v2 standardizes exactly this as display terminals: the same `{ type:
"terminal", terminalId }` content, plus `terminal_update` and
`terminal_output_chunk` for the terminal's state. So the v2 surface maps
the extension rather than adding new agent types. Unlike the agent's
private `_meta.claudeCode` keys, these keys are a cross-agent protocol
extension, so this maps one protocol form to another.
## Change
- `ToolCallClientCapabilities.from` reports a v2 client as taking the
extension.
- `V2Terminals` (`src/v2/terminal.ts`), one per connection, turns the
extension's keys into v2 updates, sent before the tool call report
without those keys:
- `terminal_info` → `terminal_update` naming the terminal;
- `terminal_output` → `terminal_update` with an `output` snapshot,
base64-encoded;
- `terminal_output_delta` → `terminal_output_chunk`;
- `terminal_exit` → `terminal_update` with `exitStatus`.
- **The command:** the extension names none, so the terminal gets the
command from the tool call's `rawInput` once a report carries it. The
first report of a streamed tool use has no input yet. `V2Terminals`
remembers each running command's terminal for that, and forgets it at
exit or `session/close`.
- **A report that carried only the output is dropped.** Its remaining
`_meta` (the `parentToolUseId` stamp, for a subagent's command) would
replace the tool call's stored `_meta` in v2.
- Terminal content passes through the tool call translation. A v2 client
has no client terminals, so these are the agent's only terminals.
The 8 v2 scenarios that run a command change their golden files:
`terminal_update`s in place of the code block, the terminal referenced
in the permission request, and the exit before the tool call's status.
## Not changed here
The agent reports a backgrounded command as exiting with 0 when it
launches, and a failure whose exit code it doesn't know as 1. v1
terminal clients get the same values, since the extension requires a
number. v2 can leave the exit status out, or say it's unknown, but that
needs the agent's command fact to carry it, and it affects v1 too, so
it's left for its own PR.
## Verification
- Unit tests cover output chunks and snapshots, signals, the command
arriving once, the dropped output report, a report without terminal keys
passing untouched, and forgetting a closed session.
- Each rule fails a test when removed.
- Build, lint and all 2388 tests pass.
Step 4's last session piece for opt-in ACP v2 support (after #1237,
#1238). The v2 surface now serves the whole v2 session baseline, so its
`initialize` response advertises `capabilities.session`. Until now a
conforming v2 client wouldn't call the session methods. Nothing changes
on ACP v1, and the v2 surface stays behind
`CLAUDE_AGENT_ACP_EXPERIMENTAL_V2`.
## Change
`V2_SESSION_CAPABILITIES` is a constant, since it describes what the v2
surface serves:
- **the session baseline:** `session/new`, `list`, `resume` (with replay
since #1237), `close`, `prompt`, `cancel`, and `update`;
- **`session/delete` and `additionalDirectories`.** Not `session/fork`
yet, which v1 advertises but the v2 surface doesn't serve;
- **prompt content and MCP transports,** as the agent's v1 `initialize`
lists them: images and embedded context; stdio and HTTP servers. v2 has
no SSE transport.
The top-level `_meta` (`promptQueueing`, `authStatus`) passes through as
before. `providers` stays unadvertised.
Every v2 golden file changes on its `initialize` line only.
## Release
Titled `refactor:` like the other v2 PRs, so it triggers no release on
its own. This is the point where the v2 surface becomes usable by a
conforming client, so `feat:` would also fit if you want the next
release to be a minor one.
## Verification
The handshake test pins the advertised capabilities, the schema check
validates every recorded `initialize` response, and build, lint and all
2386 tests pass.
Fixes a bug in #1237 on the opt-in ACP v2 surface. Nothing changes on
ACP v1.
## Problem
A v2 `session/resume` with `replayFrom` failed with an internal error on
any session that contains a Write:
- A replay has no approval preview and no PostToolUse hook, so the Write
reporter builds a diff from the input for every client on replay.
- That's a v1 diff. It even claims a creation, since the input doesn't
say whether the file existed.
- The v2 surface rejects v1 diffs (#1232), so the replay threw and the
resume failed.
`session-load-replay` has an Edit but no Write, so the scenario suite
didn't catch it.
## Change
A v2 client gets no diff from a Write's input, live or replayed: a v2
diff names the operation (`add` or `modify`), which the input doesn't
tell. Replayed Writes and Edits show no diff on v2 yet; building them
needs the tool's structured result, which the SDK's transcript reader
leaves out (see the follow-up discussion).
## Verification
A new test replays a transcript with a Write through a v2
`session/resume`: it failed with "Internal error" before the change and
passes after. The v1 golden files are unchanged. Build, lint and all
2386 tests pass.
Last part of step 4's session baseline for opt-in ACP v2 support (after
#1231–#1235): a v2 `session/resume` can now replay the session's
history. Nothing changes on ACP v1.
## Change
- **Routing.** v2 restores a session with `session/resume` and replays
only when `replayFrom` asks for it. v1 splits that into
`session/resume`, which never replays, and `session/load`, which replays
everything before it responds. That's exactly what v2 requires of
`replayFrom: { type: "start" }`. So `v1RestoreSessionRequest` maps the
v2 request to one of the two. A cursor that starts elsewhere is
rejected, since v1 can only replay from the start.
- **Clearing replayed messages.** The agent replays messages as chunks,
and chunks append. A v2 client may still hold a replayed message, so
before the first replayed chunk of each message, the v2 surface sends
that message with `content: []`. The draft requires that of a message
replayed as chunks. It happens only while that session replays
(`V2ClientConnection.replaying`), and the clear and the chunk go to the
connection together, so nothing comes between them.
- **Prompt ids.** The draft requires a prompt's user message to replay
under the id its `session/prompt` response returned. Since #1226 that id
is the user message's uuid, which Claude Code keeps in the transcript,
so no new code is needed. A test checks it end to end.
## Scenario suite
`session-load-replay` passes, so every scenario now passes on v2. The
status table becomes `V2_STOPS`: the scenarios that stop on v2, which is
empty today and stays as the place for a scenario v2 can't run yet. The
replay golden file shows each message cleared before its chunks, and the
`session/resume` response after the last replayed update.
A replayed Edit or Write shows no diff yet on v2: replay has no
PostToolUse hook. Building it from the transcript is the next PR.
## Verification
- **Replay test:** a live prompt, then resume with replay from a
transcript holding the uuid Claude Code saved. The replayed user message
carries the prompt response's id, each message is cleared before its
chunks, everything arrives before the response, and a live prompt
afterwards gets no clears.
- **Mutations:** each rule fails a test when removed: no clears, clears
that stay on after the replay, a replay served as a plain resume, and
one clear per id rather than per message.
- Build, lint and all 2385 tests pass.
Second part of step 5 of opt-in ACP v2 support (after #1234): the v2
surface now sends the agent's plan. Nothing changes on ACP v1.
## Change
- v1 `plan` becomes v2 `plan_update` with an items plan: `{ type:
"items", planId, entries }`. Plan entries are identical in both
versions, and a v2 items plan is replaced whole on each update, as a v1
plan is. The update's `_meta` passes through.
- **One plan id per session** (`SESSION_PLAN_ID`). v1 has one plan per
session, which every update replaces, whether it comes from TodoWrite or
from the Task tools. Several plans, such as one per subagent (a
subagent's TodoWrite replaces the session's plan today, marked by
`_meta.claudeCode.parentToolUseId`), and v2's unstable markdown plans
wait for step 6.
## Scenario suite
`todo-write` and `task-create-update` pass, with golden files. That
leaves only `session-load-replay` in the status table.
## Verification
A unit test covers the mapping; build, lint and all 2383 tests pass.
First part of step 5 of opt-in ACP v2 support (after #1231, #1232): the
v2 surface now sends the agent's permission requests. Nothing changes on
ACP v1: no v1 golden file changes.
## What differs in v2
A v1 request asks about a tool call, and clients show the tool call's
title as the prompt. A v2 request gives the prompt a required `title`
and an optional `description` of its own, apart from the tool call. It
asks about a `subject`, which can be a tool call or a command.
## Change
- **Prompt text.** The agent already computes the prompt's heading and
explanation, but only AIR gets them, in
`_meta.jetbrains.air.permission`. The agent's request type,
`AcpPermissionRequest`, now carries them as `title` and `description`
for a v2 client. It's the same rule #1232 uses for diffs: build what v1
can't express only for a v2 client. So v1 requests are byte-identical,
and the v1 scenario golden files, which record what the agent hands
`requestPermission`, don't change. The v2 surface fails on a request
without a title, so a missed site fails loudly.
- **Subject.** Always `{ type: "tool_call", toolCall }`, where
`toolCall` is the same patch a `tool_call_update` carries
(`v2ToolCallPatch`). The `command` subject would suit Bash once display
terminals exist, since its `terminalId` refers to one.
- **Approval preview.** The exact patch before an Edit or Write runs is
now built in v2 form for a v2 client, and the request shows it. This
fixed a real gap: the agent pins the preview as content the client
holds, but only AIR's request shape included it. Without the fix, a v2
client saw no diff at all, because the hook's identical patch was then
dropped as unchanged.
- **Answer.** v2's outcomes map back unchanged. An outcome v1 doesn't
know, which the draft says is no approval, becomes `cancelled`, and the
agent reads that as an aborted tool use.
- **`requires_action`** while a request is open was already in place
since #1226.
## Scenario suite
All 12 scenarios that stopped at a permission request now pass: Bash,
Edit (approved and rejected), Write, NotebookEdit, WebFetch, MCP,
network, ExitPlanMode (approved and rejected), and two subagent
scenarios. Each recording shows `requires_action`, the request, then
`running`. Now only replay and the two plan scenarios remain.
## Verification
- **End to end:** a new test drives the agent's real `canUseTool`
through a v2 client. Allow, reject, and an unknown outcome become allow,
deny, and an aborted tool use.
- **Unit tests:** the prompt's title is separate from the tool call's
(ExitPlanMode: "Ready to code?" vs "Approve Plan"), the preview shows in
the request, the v2 preview fallback works, and the title guard rejects
a missing title.
- **Mutations:** each rule fails a test when removed. Sending
`title`/`description` to every client fails 37 tests, including v1
golden files.
- Build, lint and all 2380 tests pass.
Second part of step 4 of opt-in ACP v2 support (after #1231): the v2
surface now sends file changes as v2 diffs. Nothing changes on ACP v1:
no v1 golden file changes.
## Why the agent builds them
A v2 diff names each change's operation (`add`, `modify`, …) and can
carry a `git_patch`. A v1 diff is a path with `oldText`/`newText`, and
the agent often fills those with a snippet: an Edit's
`old_string`/`new_string`, or one display hunk. So a v1 diff can't be
translated. It says neither the operation (`oldText: null` can mean a
new file, or a hunk with no old lines) nor where the lines are.
So the agent builds v2 diffs itself, at the sites that build v1 diffs
and know the change. The v2 surface creates the agent with `{ v2: true
}`, which becomes `ToolCallClientCapabilities.v2`. A v1 client can't set
it. This follows how the renderer already picks a form by capability, as
it does for AIR's `diffPatch`.
## What a v2 client gets
- **Live Edit and Write tool calls show no diff,** as a Write already
does for AIR. The input holds a snippet, or doesn't say whether the file
exists.
- **The PostToolUse hook sends the exact patch** built from the written
file. That's the existing AIR `diffPatch` path, which now produces
either form. When it can't be exact, it falls back to a patch from the
toolResponse:
- a created file: `add` with its whole text;
- an update: `modify` with the display hunks, which are fine for v2's
renderable patch;
- an update without hunks (previous content too large): the change
alone;
- an Edit with an empty `old_string`: no diff, since the response looks
the same for a created file and a filled empty one.
- **`git_patch` headers use absolute paths** without git's `a/` and `b/`
prefixes, as the draft's example does: `diff --git /p/a.ts /p/a.ts`.
## Plumbing
- The exported `toAcpNotifications` and `streamEventToAcpNotifications`
take the agent's tool call capabilities (`toolCallCapabilities`) next to
the ACP ones, which can't carry the v2 flag. External callers are
unchanged.
- The v2 diff travels through the agent as v1-typed content, with one
documented cast in `v2DiffContent`. Nothing in the agent reads inside a
diff item.
- The v2 surface passes v2 diffs through and rejects a v1 diff, so a
missed site fails loudly. That's how the scenario suite found the
notification functions on the first run.
- The approval preview stays AIR-only until v2 serves permission
requests (step 5).
## Scenario suite
`write-existing` passes, with an exact patch (golden file added).
`write-new`, `edit-with-permission` and `edit-rejected` now stop at
their permission request (step 5). No scenario stops at a diff any more.
## Verification
- Unit tests cover the absolute-path headers, the live tool calls, the
exact patch, and each fallback.
- Each new rule fails a test when removed: git-style paths in a v2
patch, the v1 snippet for a v2 Edit, the AIR path for a v2 hook result,
the notification functions ignoring the agent capabilities, and the
missing guard for an Edit that created or filled a file.
- Build, lint and all 2362 tests pass.
First part of step 4 of opt-in ACP v2 support (#1217, #1219, #1226,
#1230): the v2 surface now sends the agent's tool calls. Nothing changes
on ACP v1.
## Change
`src/v2/tool-call.ts` maps the agent's v1 tool call reports to v2:
- **One message.** v1 reports a new tool call with `tool_call` and
changes it with `tool_call_update`. v2 has one `tool_call_update` that
upserts by `toolCallId`, so both become that.
- **`null` is left out.** Both versions leave an omitted field unchanged
and replace `content` and `locations` as whole arrays. They differ on
`null`: in v1 it leaves a field unchanged (v1's `name` docs say so
explicitly), in v2 it clears it. The agent doesn't send `null` fields
today; a unit test pins the rule.
- **Content blocks pass through.** v2's content blocks are a superset of
v1's.
- **Diff and terminal content still throw**, until their own parts of
step 4.
## Scenario suite
Of the 30 scenarios that stopped at their first `tool_call`:
| Status now | Scenarios |
|---|---|
| passes | 17: `read`, `grep-and-glob`, `bash-error`, `bash-background`,
`skill`, `ask-user-question`, `memory-recall`, `permission-denied`,
`tool-progress`, `task-output-and-stop`, four subagent scenarios, the
three compaction scenarios |
| stops at a permission request (step 5) | 9 |
| stops at diff content (next part of step 4) | 4 |
The 17 new golden files are in
`src/tests/acp-scenarios/__snapshots__/v2/`.
**One new check.** In v1, a `tool_call_update` for an id the client
hasn't seen is an orphan, and clients drop it. In v2 the same message
creates a tool call. A stray update would show up as a blank tool call,
and the schema can't catch that. So every scenario recording, including
those that stop, must give each tool call a title in its first report.
It passes everywhere; making the first report lose its title fails it in
30 scenarios.
## Noted for later, not changed here
- **`_meta` becomes stored state.** In v1, a report's `_meta` belongs to
that report. In v2 it's stored on the tool call, and a concrete value
replaces it. So a v2 client keeps only the last report's
`_meta.claudeCode`: in `permission-denied`, the denial's `toolResponse`
is replaced by the result's `{ toolName }`. No v2 client reads these
keys yet.
- **v2 has a `cancelled` tool status.** v1 reports an interrupted tool
as `failed` with `_meta.claudeCode.nonExecutionKind`. Mapping it to
`cancelled` means deciding where that fact lives.
## Verification
Build, lint and all 2353 tests pass.
Last part of step 3 of opt-in ACP v2 support (#1222, #1226): the
scenario suite now also runs on the v2 surface. It's test-only.
## What
`src/tests/acp-scenarios-v2.test.ts` runs all 40 scenarios of the ACP
scenario suite the way `serveAcp` serves v2: through the protocol
router, driven by the SDK's own v2 client. Per scenario:
- `initialize`, then `session/new`, or `session/resume` with
`replayFrom` for a transcript;
- one `session/prompt` per turn, waiting for the turn's `idle`.
The agent's JSON-RPC messages are recorded off the wire, so a message
the client would reject is still recorded and checked.
Three checks:
1. **Status table.** A scenario passes when every turn ends with a stop
reason other than `_error`. Otherwise it records why it stopped: the
rejected request's error, or the failed turn's notice.
| Status today | Scenarios |
|---|---|
| passes | 7: `session-setup`, `text-and-thinking`, `goal`,
`rate-limit-and-origin`, the three async-task scenarios |
| `tool_call` not translated yet (step 4) | 30 |
| `plan` not translated yet (step 5) | 2 |
| replay not supported yet (step 4) | 1 |
Each step that translates more updates must flip its entries to
`passes`, so the table is that step's checklist.
2. **Schema.** Every recorded message, including those of scenarios that
stop, validates against the SDK's draft v2 JSON schema. The definition
is looked up from the method and side the schema itself names
(`x-method`/`x-side`). One test checks that the validator rejects a
chunk without `messageId`, so the check can't pass vacuously.
3. **Golden files** for the passing scenarios, in
`src/tests/acp-scenarios/__snapshots__/v2/`. For example,
`text-and-thinking.jsonl` shows the prompt lifecycle from #1226:
`user_message`, `running`, the `session/prompt` answer, the chunks with
their `messageId`, and `idle end_turn` with usage.
`harness.ts` gains `runScenarioV2` next to `runScenario`, sharing the
scripted Claude Code, the id normalization and the elicitation answer.
`schema.ts` gains `validateV2Message` next to `validateRecorded`.
## Testing
- Dropping `messageId` from the v2 chunk translation fails both the
schema check and the golden files of the scenarios with chunks.
- The v2 file is stable across repeated runs and takes about 1.3 s; the
full suite stays at about 4.4 s.
`npm run build`, `npm run check`, `npm run test:run` (2293 passed).
Found while reviewing #1226. It affects ACP v1 and v2.
## Problem
A turn held open for its background subagents (`Turn.deferredSettle`,
issues #864–#866) was settled `cancelled` inside `cancel()`, before the
interrupt. The followup cycle can be live at that point, writing the
subagents' summary or blocked on a permission request. The interrupt
still flushes that cycle's output, so:
- **v1:** the output arrives after `session/prompt` has answered
`cancelled`, when many clients have stopped listening.
- **v2 (#1226):** the output arrives after `idle cancelled`. The v2
draft says updates after a cancel MUST come before it.
## Change
`cancel()` now settles inline only where the consumer can't:
- **a settling turn,** blocked in its checkpoint preview, which can't
process the interrupt's trailing idle (unchanged);
- **a held turn whose session sits idle,** or has reported no state yet:
the interrupt emits nothing, so no trailing idle comes (unchanged).
**A held turn with a live followup** (`running` or `requires_action`) is
now left to the consumer, like any live turn. It ends at the interrupt's
trailing idle, or at the next prompt's echo if that idle lags, after the
output the interrupt flushed. The force-cancel backstop is armed for it
meanwhile.
Two consequences, both handled:
- **The trailing-idle debt:** the interrupted followup's result is
autonomous, so it records its trailing idle as owed. When that idle ends
the cancelled held turn, it now also pays the debt. Otherwise the debt
would absorb a later issue-#825 signal.
- **Usage:** a held turn can now be ended by the trailing idle, the echo
hand-off, stream end or the backstop, not only by `cancel()`. All of
them take the outcome from one rule, `cancelledOutcome`: a turn that
already has its result keeps that result's usage and `_meta`, as the
inline settle did (issue #844). Today the session's tally equals that
recorded outcome anyway, since followup results aren't accumulated.
Stream end already treats the stored one as authoritative.
## Testing
- **New:** `src/tests/turn-events.test.ts` cancels a held turn
mid-followup. The interrupt flushes more of the summary, then the
followup's result and idle arrive. It asserts:
- the flushed output comes before the turn ends `cancelled`;
- a wedged next turn still fails at its un-owed idle (issue #825), so no
trailer debt leaked.
- **Updated:** the two existing tests that cancel a held turn in a live
cycle (running, and blocked on a permission request) expected the prompt
to resolve at `cancel()`. Their scripts send the interrupt's trailer
only after the next prompt's echo, so the turn now ends at that echo
hand-off. They keep their issue #825 assertion, and one now also checks
the usage the turn keeps (issue #844).
- **Unchanged:** the tests for an idle hold, which settles at `cancel()`
without pre-counting a trailer, pass as before.
- **Mutations:** settling a live held turn inline again, settling an
idle one at an idle that never comes, or skipping the debt payment each
fail at least one test.
`npm run build`, `npm run check`, `npm run test:run` (2244 passed).
Found while reviewing #1226: a prompt that `session/cancel` reports as
cancelled still runs in Claude Code. It affects ACP v1 and v2.
## Problem
`cancel()` settles every queued prompt as `cancelled`, but each was
already pushed to Claude Code. Claude Code keeps queued messages through
an interrupt and runs them next. The SDK documents the interrupt
receipt's `still_queued` as "messages that WILL still run unless
cancelled first". So:
- Claude Code answers prompts the client was told were cancelled, and
they stay in the conversation, and in the model's context, for later
turns.
- The orphan accounting skips their results, and a cancelled session
drops consolidated `assistant` frames, but their streamed deltas still
reach the client after the cancel.
- In v2 (#1226), such a prompt is answered `-32800` ("not inserted"),
then its output arrives anyway.
## Change
`cancel()` now sends `cancel_async_message` for each queued message it
abandons, before the interrupt. That covers queued prompts and pending
steers. This is the pattern the SDK's own docs describe for a wrapper
that wants per-uuid control, rather than `cancel_queued` on the
interrupt, which would also sweep a prompt the client sends right after
the cancel.
- **Before the interrupt**, because once the interrupt stops the running
turn, Claude Code starts the next queued message right away.
- **Not awaited.** The SDK writes control requests to Claude Code in
call order, so the drops still arrive before the interrupt, and a wedged
CLI can't hold up the cancel, or the teardown that uses it.
- **No new accounting.** A dropped message gets a `cancelled` lifecycle
frame and is missing from the interrupt receipt's `still_queued`, and
the orphan accounting already handles both.
- **Residual window:** a message Claude Code had already dequeued, or
one the SDK hadn't written yet, still runs as an orphan, exactly as
before.
The SDK implements the request as `Query.cancelAsyncMessage` (0.3.287)
but doesn't type it, so it's looked up. A mocked query without it skips
the drop. A CLI that doesn't know the request rejects it, which is
logged.
## Testing
A new test in `src/tests/turn-events.test.ts` scripts Claude Code's
queue: a queued prompt runs after the interrupt unless it was dropped
first, as the real CLI does. It asserts:
- the drop goes out before the interrupt;
- the queued turn ends `cancelled`;
- the cancelled prompt's answer never reaches the client.
Without the drop, the test fails with the leaked answer (`chunk Answer
to a cancelled prompt` after `first ended cancelled`). Sending the drop
after the interrupt also fails it. The rest of the suite passes
unchanged. `npm run build`, `npm run check`, `npm run test:run` (2243
passed).
Part of opt-in ACP v2 support. It fixes the first issue the review of
#1226 found in the agent's turn reporting. It's independent of #1226 and
changes nothing for ACP v1.
## Problem
A turn reported `inserted` (#1222) at activation: the prompt's echo, or
for an echo-less command, its result. The echo can come after the turn's
first output; the agent already handles deltas that stream before it
(see `injectSessionEchoAt` in the tests). With #1226's v2 mapping, that
means a v2 client sees:
- a turn's output before its `user_message` and before `running`;
- `/compact`'s `session/prompt` answered only after the whole command.
## Change
On CLIs that report command lifecycles (`msg_lifecycle_v1`), the
`command_lifecycle` "started" frame now reports the turn inserted.
**Why that frame is early enough.** I read the order in the CLI bundled
with SDK 0.3.287 rather than in a live capture:
- **A command that starts a fresh turn:** the engine pushes "started"
into its lifecycle buffer at turn start (`C.push(W(w.uuid,"started"))`,
before `[engine] turn N start`). The turn's message loop then flushes
that buffer before it yields anything the turn produced
(`if(C.length>0)yield*te()`), including its echo and first
`stream_event`.
- **A prompt folded into a running turn:** its `queued_command`
attachment (the echo) is yielded before "started", so activation at the
echo already comes first and this frame changes nothing.
**One guard.** While another turn is still active, insertion still waits
for the echo. That covers a turn held for its background work, a steered
turn, and a cancelled turn awaiting its trailing idle. The echo's
hand-off ends that turn first, so a turn is never reported inserted
before the previous one ends.
**Older CLIs** without lifecycle frames keep insertion at activation.
Only the time `inserted` is reported changes. Activation, output
attribution and settlement don't, and ACP v1 ignores `inserted`.
## Testing
`src/tests/turn-events.test.ts`:
- a fresh turn whose answer streams between "started" and its echo is
reported inserted before that output;
- a prompt that starts while the turn before it is held is reported
inserted only after that turn ended.
Removing the new insertion point fails the first test, and removing the
guard fails the second. The rest of the suite passes unchanged,
including the recorded v1 scenario traffic. `npm run build`, `npm run
check`, `npm run test:run` (2231 passed).
Second part of step 3 of opt-in ACP v2 support (#1217, #1219, #1222).
The v2 surface now serves `session/prompt` and `session/cancel`. It
still doesn't advertise `capabilities.session`; that waits for tool
calls and replay (step 4).
## What
`src/v2/prompt.ts` serves a v2 prompt through the agent's turn events
(#1222), instead of translating it into a v1 prompt:
| Turn event | v2 |
|---|---|
| `inserted(messageId)` | `user_message` (the prompt as received, under
the uuid Claude Code echoed), `state_update: running`, then the answer
`{ messageId }` |
| `awaitingUser()` / `resumed()` | `requires_action` / `running` |
| `ended(outcome)` | `idle` with the stop reason, `usage`, and `_meta` |
| `ended` before insertion | `-32800`: a queued prompt that a cancel
ended |
| `failed` before insertion | the error as the JSON-RPC answer |
| `failed` after insertion | an error `notice` that shows it, then
`idle` with the custom stop reason `_error` and v1's JSON-RPC error in
`_meta.claudeCode.error` |
The last row is a gap in the draft: the idle `state_update` has no
error, its stop reasons are all non-error ones, and a notice "must not
carry … fatal-error reporting". So the failure travels on `idle` as a
`_`-prefixed custom stop reason, which the draft allows, with the error
in `_meta`; `auth_required`'s code survives there. The notice shows the
agent's own failure title ("API Error: 529 Overloaded");
`TurnEvents.failed` gains an optional `title` for it. That's going back
to the v2 draft as feedback.
- `session/cancel` maps to the v1 cancel.
- **Ordering:** the turn's state updates and the agent's own updates go
through one `ctx.notify` path in call order, so `idle` comes after the
turn's last output. The tests check the order.
- **Message chunks** (`agent_message_chunk`, `agent_thought_chunk`,
`user_message_chunk`) are translated with the `messageId` v2 requires,
and fail loudly without one.
- **Prompt content:** blocks that v1 can't express (a custom or future
type) are rejected with `-32602`. Audience roles that v1 doesn't know
are dropped from annotations, which the agent doesn't read.
- Tool call and plan updates still fail loudly until their step.
## The one change on v1
The agent built three message chunks without a `messageId`: local
command output, a result forwarded as the answer (a local-only command,
or the issue #453 fallback), and a refusal explanation. Each now carries
the uuid of the SDK message it came from, the id `messageIdForGrouping`
already uses for non-assistant messages. It's an additive field on v1.
None of the recorded v1 scenario baselines contain these chunks, so they
don't change.
## Testing
`src/tests/acp-v2.test.ts` drives the router with the SDK's v2 client,
which validates every message against the v2 schema. Its mocked Claude
Code now answers prompts: each turn echoes its prompt, then runs a
script. New tests:
- a prompt is answered with the echoed uuid while its turn still runs,
then `agent_message_chunk` and `idle end_turn` with usage;
- a queued prompt stays unanswered until the turn before it ends, then
is answered with its own echoed uuid;
- an MCP elicitation during the turn gives `requires_action`, then
`running`;
- `session/cancel` follows a real interrupt: output Claude Code sends
after it arrives before `idle cancelled`, and a queued prompt is
answered `-32800`;
- a turn whose result is an API error gives an error `notice` with the
agent's title, then `idle _error` with the error code; a missing login
keeps `auth_required`'s code;
- a queued prompt whose stream ends before insertion is answered with
the error;
- a refusal explanation carries the refusing result's uuid;
- local command output and a forwarded result each arrive with their SDK
message's uuid as `messageId`;
- a prompt with a `_acme/widget` block is rejected and never reaches
Claude Code;
- a chunk without a `messageId` fails translation, and audience roles v1
doesn't know are dropped.
Mutation check: answering at the end or at queueing instead of at
insertion, dropping `user_message`, answering a cancelled queued prompt,
dropping the failure notice or its title, ending a failure with
`end_turn` or without the error, dropping `requires_action`, removing
any of the three new `messageId`s, accepting any content block, or
swallowing a failure before insertion each fails at least one test.
`npm run build`, `npm run check`, `npm run test:run` (2240 passed).
## Not in this PR
A review of this PR found these in the agent's turn reporting and
cancellation, outside the mapping. They're tracked for their own PRs
before the v2 surface is advertised; the first three also affect v1:
- insertion is reported at the echo, which can lag the turn's first
output;
- a cancelled queued prompt's streamed output still reaches the client;
- cancelling a held turn settles it before the interrupt's remaining
output;
- `session/close` answers before the active turn's `idle cancelled`;
- whether a held turn should delay `idle` in v2 at all.
## Summary
In an ACP client, `/mcp` showed the CLI text "… Use `/mcp` in the
terminal for details." The user of an ACP client has no terminal. In SDK
mode, Claude Code also refuses `/mcp reconnect|enable|disable` with
"Reconnect, enable, and disable aren't available in this session." and
changes nothing.
- `/mcp` and `/mcp reconnect|enable|disable [<server>|all]` still run as
a normal Claude Code turn. The adapter replaces the text of the local
command, through the same hook that `/usage` uses. Prompt order, cancel,
and the provider update stay with the turn.
- For an action, the adapter runs it in that turn through the SDK
control API (`reconnectMcpServer`, `toggleMcpServer`). It shows one
result line for each server, then the status list.
- The status list comes from `query.mcpServerStatus()`. It has a summary
line and groups by status: failed, needs authentication, connecting,
connected, and disabled on one line. A failed server shows a short
cleaned error. A list is used and not a table, because a table breaks
words in narrow columns.
- Useful CLI sentences stay, for example "There's no MCP server named
…". Sentences that point to the terminal are removed.
- After an explicit reconnect, a server from the ACP session that needs
authentication starts the existing MCP OAuth flow, when the client
supports URL elicitation.
- `/mcp` is advertised with the input hint `[reconnect|enable|disable
[<server>|all]]` and is hidden on history replay.
## Other commits in this branch
This branch also carries commits of other work: skill command metadata
for AIR, a faster `session/load` replay, and the resumed permission
mode. They can move to separate PRs if preferred.
## Tests
- `src/tests/mcp-command.test.ts` (61 tests). The fake CLI answers with
the real SDK-mode texts and message shapes (synthetic assistant +
result) and does not change any status.
- A live run through the adapter with a broken and a working stdio
server: `/mcp`, `/mcp disable good`, `/mcp enable good`, `/mcp reconnect
broken`, `/mcp reconnect nosuch`.
- `compare.ts` allows one new difference against the origin/main
baseline: the `mcp` command in `available_commands_update`. The baseline
files are unchanged.
- `npm run check` and `npm run test:run` pass.
## Summary
- Bumps `@anthropic-ai/claude-agent-sdk` to 0.3.287 (Claude Code
2.1.287). No compile or test fixes were needed.
## Review notes for 0.3.287
- **WebFetch/WebSearch keep running when a steer arrives: not active for
the adapter.** In 2.1.287, a human-origin `priority: 'now'` steer no
longer cancels WebFetch or WebSearch. The call keeps running, and its
tool_result is a "[Still running…]" notice for the model with
`tool_use_result: {detachedToolCall: true}`. The steer gets its own
result, and the CLI holds back idle. When the fetch finishes, Claude
starts a follow-up turn on its own. That turn has no user message and
its result carries no uuid, and idle only arrives after it. I checked
this against the live CLI. However, the CLI only does this when no
PostToolUse, PostToolUseFailure or PostToolBatch hook applies to the
tool. The adapter's PostToolUse hook has no matcher, so it applies to
every tool, and through the adapter the steer still cancels the fetch,
as before. I also checked that end to end. Turning the new behavior on
needs three changes: limit the hook to
Write/Edit/NotebookEdit/EnterPlanMode, render the card while the call
keeps running, and close the card at the follow-up turn. That is left
for a follow-up PR.
- **No changes needed:**
- the `includePartialMessages` late or missing `message_stop` fix (the
adapter's `message_stop` handling can safely run more than once)
- the `commands_changed`-before-`init` fix
- the clearer revoked-OAuth error text (it still arrives as an
`authentication_failed` error)
- MCP `structuredContentOmitted` (the adapter doesn't read
`structuredContent`)
- the `alwaysLoad: false` semantics (unused)
- the remote-only `first_text_post_*` result fields
- `get_task_output` (in the types, but `Query` has no method for it)
- the fix for a model fallback repeating on every later message
## Test plan
- [x] `npm run build`
- [x] `npm run test:run` (2142 passed)
- [x] `npm run check`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Fixes an intermittent failure of "replays a subagent from its own
transcript file", and with it a broader leak: the unit suite was running
the real Claude CLI hundreds of times per run.
## Cause
The agent runs `claude auth status --json` in the background, without
awaiting it, on every `initialize` and prompt. The scenario suite stubs
it (`CLAUDE_CODE_EXECUTABLE=/usr/bin/false`), but other files didn't.
Logging the probe's executable over one `vitest run` showed about 670
runs of the real CLI:
| File | Real CLI runs |
|---|---|
| `acp-agent.test.ts` | 375 |
| `create-session-options.test.ts` | 14 |
| `incomplete-tools.test.ts` | 12 |
| `session-titles.test.ts` | 8 |
| `file-change-audit-integration.test.ts` | 5 |
Each run uses the machine's own Claude config, unless a test points
`CLAUDE_CONFIG_DIR` elsewhere.
That flaky test points `CLAUDE_CONFIG_DIR` at a temp dir. The CLI it
started then wrote `.claude.json`, `.claude.json.lock` and `backups/`
into that dir about a second later, after the test body had finished.
Under full-suite load, that overlapped the `rm` in the test's `finally`,
which failed with `ENOTEMPTY`. Its assertions always passed.
## Change
`vitest.config.ts` sets `CLAUDE_CODE_EXECUTABLE=/usr/bin/false` in
`test.env`:
- It's the override `claudeCliPath()` already honors, and the value the
scenario suite already uses, so production code doesn't change.
- `test.env` is the base environment, so it survives the
`vi.unstubAllEnvs()` that three files call.
- Runs that exercise the real CLI keep it: with `RUN_INTEGRATION_TESTS`
(`npm run test:integration`) or `RUN_LIVE_CAPABILITY_AUDIT=true`, the
variable is left unset.
Tests that mock `execFile` or set their own executable are unaffected.
## Evidence
- After the change, the same logging shows 0 runs of the real CLI: 688
probes run `/usr/bin/false`, and 108 hit files that already mock
`execFile`.
- The flaky test's temp dir now holds only the test's own `projects/`
after the test, with no `.claude.json`.
- Before the change, it failed in about 2 of 6 full runs on my machine.
After, 8 of 8 full runs passed.
- A full run takes about 4.8 s instead of 8.4 s.
- The variable is `/usr/bin/false` in a default run and unset with
either opt-in flag.
- `npm run build`, `npm run check`, `npm run test:run`.
First part of step 3 of opt-in ACP v2 support (step 1: #1217, step 2:
#1219). It's independent of #1219. It changes no ACP v1 behavior, apart
from one failure-only case noted below.
## Why
ACP v2 changes the prompt lifecycle. `session/prompt` is answered when
the prompt is *inserted* into the conversation, and progress and the
stop reason arrive as `state_update`s. In v1, the response comes at the
end of the turn. The agent only exposed the v1 shape: `prompt()` returns
at the end of the turn. So v2 can't be mapped from the outside.
Following the discussion on #1219, the adapter gets its own view of a
turn, and each ACP version maps to it, instead of v2 being translated
into v1.
## What
`src/turn-events.ts` defines the adapter's own turn lifecycle:
- `inserted(messageId)`: Claude Code took the prompt in as this user
message. At most once, and never after the turn ends.
- `awaitingUser()` / `resumed()`: a permission request or question is
open in the session / none is open any more.
- `ended(outcome)`: with a `TurnOutcome` (`stopReason`, `usage`,
`_meta`).
- `failed(error)`.
The agent calls these synchronously while it updates its own state, so
handlers must not throw or call back into the agent.
In the agent:
- `startTurn(params, events)` starts a turn. It resolves once the prompt
is queued for Claude Code, and rejects only if the prompt is refused
before that. Events can arrive before it resolves. `prompt()` is now the
v1 view of it: it awaits the turn's outcome.
- **inserted** is reported in `activateTurn`, the single place a queued
turn becomes active. That's when Claude Code takes the prompt in: its
echo, or for an echo-less command, its result. Two guards:
- a clear-context restart re-activates the same turn in the fresh
session, so it's reported once;
- a turn that a cancel settled during the previous turn's hand-off isn't
reported at all.
- **awaiting user / resumed** follow one session-level rule: the active
turn awaits the user exactly while any request in the session is open,
rechecked when a turn activates. A request carries no prompt id, and
Claude Code can ask for a queued prompt before the consumer reaches its
echo. So tying a request to the turn that was active when it opened
would misattribute it.
- **ended / failed** come from the existing settle points, each guarded
by `settled`, so a turn reports exactly one of them.
- `TurnOutcome` and `StopReason` are the adapter's own types. A turn's
outcome is field for field a v1 prompt response, so `PromptResponse` now
only appears at the v1 boundary.
**The one v1 difference:** a prompt that sets a goal publishes it to AIR
clients after the prompt is queued. If that notification fails,
`startTurn` now logs it rather than rejecting, because the turn is
already running. For v1 this only matters on a dead connection:
`prompt()` waits for the outcome instead of rejecting with the write
error.
## Notes for the v2 step
- A prompt sent while another turn is running is inserted only when
Claude Code takes it in, after the running turn. The open question about
queued prompts is going back to the v2 draft.
- An echo-less command (such as `/compact`) is inserted at its result,
after its output. On `msg_lifecycle_v1` CLIs, the `command_lifecycle`
"started" frame may be an earlier insertion point.
- A queued turn that a cancel ends before insertion may still be run by
Claude Code (the orphan accounting).
- Any open request counts towards `requires_action`, a background task's
included; `agentID` could refine that in the permission step.
## Testing
`src/tests/turn-events.test.ts` covers:
- a normal turn: inserted under the uuid of the message Claude Code
received, then ended;
- a permission request: awaiting user, then resumed;
- a request open from before the turn: the turn awaits the user from
insertion, through its own answered request, until the earlier one is
answered too;
- a cancel during the hand-off from the previous turn: the queued turn
ends as cancelled and is never inserted;
- cancelling while a second prompt is queued: the active turn is
inserted, then ended as cancelled, and the queued turn ends as cancelled
without being inserted;
- the stream ending with a turn queued: it fails without being inserted;
- a prompt for an unknown session: `startTurn` rejects and reports
nothing.
The existing clear-context restart test also checks that the restarted
turn is inserted once.
Each guard is checked by mutation: removing the `insertedReported`
guard, the `settled` guard, the activation recheck, or the change-only
dedupe; tying `resumed` to the request's own turn; or reporting
insertion at enqueue each fails at least one test.
The existing suite passes unchanged, including the 474 scenario tests
that compare outbound v1 traffic with recorded baselines. `npm run
build`, `npm run check`, `npm run test:run`.
Step 2 of opt-in ACP v2 support (step 1: #1217). Behind
`CLAUDE_AGENT_ACP_EXPERIMENTAL_V2=1`, the v2 surface now serves
`session/new`, `session/list`, `session/resume` (without replay),
`session/close`, `session/delete`, and `session/set_config_option`. ACP
v1 is unchanged.
`capabilities.session` is still not advertised. Under v2, advertising it
commits the agent to the whole baseline, including `session/prompt` and
`replayFrom: start` replay, and those come in later steps. Until then
these methods are served but not advertised.
## Translation
As in step 1, each v2 request becomes the v1 request that
`ClaudeAcpAgent` already serves, and each v1 response or update becomes
its v2 form (`src/v2/session.ts`, `src/v2/session-update.ts`):
- **MCP servers:** v2 requires a `type` on every transport, but the
agent recognizes a v1 stdio server by its *missing* `type`. A v2 `type:
"stdio"` config passed through as is would be silently skipped, so the
tag is dropped. The lists v1 requires (`args`, `env`, `headers`) are
defaulted. A transport v1 can't express is rejected with invalid params
instead of being left out of the session.
- **Config options:** `id` → `configId`, a select group's `group` →
`groupId`. A select value in `session/set_config_option` drops its v2
`type: "id"`, and value types v1 can't express are rejected.
- **Modes:** responses drop `modes`, and `current_mode_update` is
dropped. The agent always lists the mode as the `mode` config option,
and every mode change also reaches the client as a
`config_option_update` or in the `set_config_option` response.
- **Commands:** `available_commands_update` inputs gain `type: "text"`.
- **Notices, session info, usage:** passed through unchanged. v2 needs
no capability for notices, so a v2 client is reported to the agent as
taking them, and advisories arrive as `notice` instead of transcript
messages.
- **Elicitation:** the same in v1 and v2, so it's forwarded. MCP OAuth
at `session/new` works.
- Update kinds that aren't translated yet (messages, tool calls, plans,
extensions) throw, so a gap shows up as an error, not a missing update.
- `replayFrom` is rejected until replayed history can be translated.
Also bumps `@agentclientprotocol/sdk`:
- to 1.6.1, whose router types `closed` as always present, so `serveAcp`
drops its `closed!`;
- to 1.7.0, which type-checks the v2 extensible-union values the adapter
builds, at any depth
([typescript-sdk#268](https://github.com/agentclientprotocol/typescript-sdk/pull/268)).
The v2 translations compile unchanged. The exception is
`createElicitation`, which relays the v1 request: v1 types a property
schema's tag as any string, and an MCP server's schema passes through
unchecked, as on v1. It gets a cast with a comment saying so.
## Testing
- `src/tests/acp-v2.test.ts` drives the router with the SDK's v2 client
app, which validates every response, session update, and elicitation
against the v2 schema. New cases cover session creation with v2 MCP
servers, config options, and commands; rejected MCP transports;
list/close/resume/delete and rejected `replayFrom`; setting the mode
with no `current_mode_update` reaching the client; notice support; MCP
OAuth through URL elicitation; and unit tests for grouped options,
rejected value types, and untranslated updates. Breaking the stdio or
command-input translation makes the tests fail.
- Ran the built binary over stdio against a real Claude Code session: v2
`initialize`, `session/new`, `list`, setting the mode, and `close` all
passed the v2 client's validation, and the 52 real commands arrived with
`type: "text"` inputs. `session/new` took ~0.7 s, the same as over v1.
- `npm run build`, `npm run check`, `npm run test:run`.
First step toward optional support for the [draft ACP v2
protocol](https://agentclientprotocol.com/protocol/v2/draft/overview).
ACP v1 stays the default and is unchanged.
## What it does
Set `CLAUDE_AGENT_ACP_EXPERIMENTAL_V2=1` and the adapter routes each
connection by the protocol version the client requests in `initialize`
(via the SDK's `AgentProtocolRouter`):
- A client that requests version 2 or later gets the draft ACP v2
`initialize`, `auth/login`, and `auth/logout`, plus the
`_auth/status_update` push.
- Every other client gets ACP v1, served by the same handlers as today.
Without the variable, the adapter never builds the router and serves ACP
v1 exactly as before.
The v2 response does not advertise `capabilities.session` yet. A v2
agent that advertises it must serve the whole session baseline
(`session/new`, `list`, `resume`, `close`, `prompt`, `cancel`,
`update`), which follow-up PRs add. So for now a v2 client can
initialize and authenticate, but cannot open a session.
## How
`ClaudeAcpAgent` keeps speaking ACP v1 types. The v2 surface in
`src/v2/` is a thin translation layer around it, so v1 and v2 share one
implementation:
- `v2AgentApp` registers the v2 methods and translates each request to
the v1 request the agent already serves, and each response back. For
`initialize` that means `info`/`capabilities` instead of
`agentInfo`/`agentCapabilities`, and auth methods with `methodId` and a
required `type`, with terminal `env` as `{ name, value }` pairs. A v2
client gets no client `fs` or terminals, and boolean config options are
baseline.
- `V2ClientConnection` is the `AcpClient` of a v2 connection. It sends
the agent's v1-shaped messages in their v2 form. Only connection-level
messages can reach it so far; session-scoped methods reject until v2
sessions land.
- `v1AgentApp` is the existing v1 handler registration, pulled out of
`runAcp` so the router can reuse it. Each surface now creates the agent
of its connection in `onConnect`, because under the router the
connection opens only after `initialize` has been read. `runAcp` (a
public export) behaves as before.
Also bumps `@agentclientprotocol/sdk` to 1.6.0 (schema v2.0.0-alpha.7).
The bump changes nothing for v1: the full suite passes unchanged on it.
## Testing
- `src/tests/acp-v2.test.ts` drives the real router over in-memory
streams with the SDK's own v1 and v2 client apps (the v2 client
validates every response against the v2 schema). It covers the v1
handshake through the router, the v2 handshake, method-not-found for v2
session methods, the `_auth/status_update` push, and gateway
`auth/login` followed by `auth/logout`.
- Ran the built binary over stdio: v2 client with the flag, v1 client
with the flag, v2 client without the flag (gets the unchanged v1
response), and stdin EOF before `initialize` (exits 0).
- `npm run build`, `npm run check`, `npm run test:run`.
## Summary
- `teardownSession` sends the interrupt but does not await its reply
- `query.close()` follows at once and ends the CLI process
- `session/cancel` still awaits the interrupt reply
On a fresh session, the background `getContextUsage` request from
`refreshContextWindowInBackground` is still in flight. The SDK
serializes control requests, so the CLI answered the interrupt only
after it. With a real CLI, `session/close` took 2.5 s in an empty
directory and 3.2 s in a large repository. ACP clients with a 3 s close
timeout timed out. With this change, close answers in about 2 ms, and
the CLI process exits.
## Tests
- `npm run test:run -- src/tests/create-session-options.test.ts`
- `npx tsc --noEmit`
- `npm run check`
When a background task stops, the CLI persists a `<task-notification>`
user record. Live, the adapter hides it and handles the SDK task
lifecycle frame; replay previously showed the raw XML as a user prompt.
Replay now hides notification records and removes embedded notification
XML while preserving adjacent user text and delivered prompts with an
origin `subkind`. It restores known non-agent tasks through
`AsyncTaskRuntime`, including `killed` → `stopped` and duplicate
terminal-event suppression. Agent notifications override the launch
result's terminal state. Unknown tasks remain hidden without creating a
task card.
Task launches are recognized in `tool_use`, `server_tool_use`, and
`mcp_tool_use` blocks. Async task updates use the session that owns the
launching tool call, even when another session receives the
notification. History has no `task_started` frame, so tasks without a
persisted stop notification cannot be reconstructed.
The large Write patch test now uses a fixed clock to check patch
correctness independently of CI speed; a separate advancing-clock test
verifies the existing timeout fallback. The production 100 ms budget
remains unchanged.
Validation on current main (SDK 0.3.286):
- `npm run build`: passed.
- `npm run check`: passed.
- `env -u ANTHROPIC_BASE_URL npm run test:run`: 2119 passed, 29 skipped.
The local gateway environment otherwise changes the expected default URL
in four provider tests.
- Regression coverage includes origin/text notifications, adjacent user
text, unknown and repeated tasks, killed tasks, background Agents,
delivered subkind prompts, alternate tool block types, task session
ownership, and patch timeout fallback.
Released AIR versions, such as 262.air/release-09, read the custom
answer companion only from the root key
_meta._askUserQuestionCustomAnswer. The adapter sent only
_meta.jetbrains.air.customAnswer, so these versions showed the companion
as a separate question.
For an AIR client the companion now carries both keys with the same
value. Other clients get no key, as before. Remove the root key when the
ACP registry no longer serves AIR versions that read only that key.
IJAI-2892
## Summary
- Bumps `@anthropic-ai/claude-agent-sdk` to 0.3.286 (Claude Code
2.1.286). No compile or test fixes were needed.
- Updates the steer comments for a CLI behavior change. A `priority:
'now'` steer that lands during a foreground tool call (Bash, Agent, MCP)
now moves the tool to the background instead of stopping the turn.
Depending on timing, the CLI then either:
- adds the steer to the running cycle, which ends in **one** result
stamped with both the prompt's and the steer's uuids, or
- ends the cycle early and runs the steer as a second cycle.
During plain text output it still stops the turn, as before.
- Adds a test for the case where the steer joins the running cycle, with
and without an echo of the steer. The case where the steer runs as a
second cycle was already covered.
I checked all of this against the live CLI 2.1.286. In each case the
result that answered the steer carried the steer's uuid, so the existing
steer settlement logic handles it without code changes.
## Review notes for 0.3.285 and 0.3.286
- **Raw XML in subagent replay:** `getSubagentMessages()` now returns
delivered `<task-notification>` rows as plain user messages (`origin:
{kind: "task-notification"}`, `isQueuedCommand: true`, no `is_meta`).
They reach child replay and show up as raw XML user messages. #1205
already hides this exact shape, so it fixes the subagent case once
merged.
- **Omitted `permissionMode`:** the SDK now leaves it to the CLI. The
adapter always passes an explicit mode, so this has no effect.
- **No changes needed:** the `fallback_credit` type, Artifact pin/unpin,
`provider_not_allowed`, the SDK MCP manifest fields, the background Bash
timeout (its stop notice goes through the existing task-stopped path),
and the `setModel` output-limit fix.
## Test plan
- [x] `npm run build`
- [x] `npm run test:run` (2095 passed)
- [x] `npm run check`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Follow-ups to the SDK 0.3.284 / CLI 2.1.284 bump (#1189), which landed
with only package changes.
## Replay showed messages from other agents and sessions as user text
Since 0.3.284, `getSessionMessages()` returns `is_meta` user messages
from other agents, sessions and channels (`origin.kind` peer, channel,
observer, observer-activity, slack-ping). Their content is the full
harness framing: the `<cross-session-message>` envelope plus the "not
typed by your user" preamble. `replayMessage` sent them as
`user_message_chunk`, while the live prompt loop never shows them.
Replay now skips them. Other `is_meta` messages (compact summaries)
still replay.
Verified against a live 0.3.284 transcript: the enveloped peer turn is
gone, and the user's own prompts still replay.
Fixes#1203. Complements #1205, which hides `task-notification` records
the same way. The two cover different origin kinds and merge with only a
trivial test-file conflict.
## Effort applies turned ultracode off
CLI 2.1.284 turns ultracode off when an `applyFlagSettings` call changes
`effortLevel` without an `ultracode` key. The adapter applies effort at
session start (recommended-value clients), after a model switch and from
the effort picker, so a settings-enabled `ultracode: true` was silently
cleared. The CLI's own `/effort` control now keeps ultracode on at any
level, so all three applies send `ultracode: true` when the settings
request it (`effortFlagSettings`).
## Checked, no change needed
Elicitation-hook `decision: 'block'`, the background-agent stdin fix
(the adapter never hit it; keep
`CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1`), MCP startup waits, Sonnet
5.5 (natively 1M, already covered by the background context-window
refresh), malformed-image handling (now done by the CLI), and notice
rewording (the adapter matches none of the changed strings).
## Testing
- New tests for both helpers, replay of the probe's peer-message shape,
and a session test checking that the startup and picker applies keep
ultracode.
- `npm run build`, `npm run check` and `npm run test:run` (2093 passed)
all pass.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Bumps [diff](https://github.com/kpdecker/jsdiff) from 8.0.4 to 9.0.0.
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/kpdecker/jsdiff/blob/master/release-notes.md">diff's
changelog</a>.</em></p>
<blockquote>
<h2>9.0.0</h2>
<p>(All changes part of PR <a
href="https://redirect.github.com/kpdecker/jsdiff/pull/672">#672</a>.)</p>
<ul>
<li>
<p><strong>ES5 support is dropped</strong>. <code>parsePatch</code> now
uses <code>TextDecoder</code> and <code>Uint8Array</code>, which are not
available in ES5, and TypeScript is now compiled with the
"es6" <code>target</code>. From now on, I intend to freely use
any features that are deemed "Widely available" by <a
href="https://web.dev/baseline">Baseline</a>. Users who need ES5 support
should stick to version 8.</p>
</li>
<li>
<p><strong>C-style quoted strings in filename headers are now properly
supported</strong>.</p>
<p>When the name of either the old or new file in a patch contains
"special characters", both GNU <code>diff</code> and Git quote
the filename in the patch's headers and escape special characters using
the same escape sequences that are used in string literals in C,
including octal escapes for all non-ASCII characters. Previously, jsdiff
had very little support for this; <code>parsePatch</code> would remove
the quotes, and unescape any escaped backslashes, but would not unescape
other escape sequences. <code>formatPatch</code>, meanwhile, did not
quote or escape special characters at all.</p>
<p>Now, <code>parsePatch</code> parses all the possible escape sequences
that GNU diff (or Git) ever output, and <code>formatPatch</code> quotes
and escapes filenames containing special characters in the same way GNU
diff does.</p>
</li>
<li>
<p><strong><code>formatPatch</code> now omits file headers when
<code>oldFileName</code> or <code>newFileName</code> in the provided
patch object are <code>undefined</code></strong>, regardless of the
<code>headerOptions</code> parameter. (Previously, it would treat the
absence of <code>oldFileName</code> or <code>newFileName</code> as
indicating the filename was the word "undefined" and emit
headers <code>--- undefined</code> / <code>+++ undefined</code>.)</p>
</li>
<li>
<p><strong><code>formatPatch</code> no longer outputs trailing tab
characters at the end of <code>---</code>/<code>+++</code>
headers.</strong></p>
<p>Previously, if <code>formatPatch</code> was passed a patch object to
serialize that had empty strings for the <code>oldHeader</code> or
<code>newHeader</code> property, it would include a trailing tab
character after the filename in the <code>---</code> and/or
<code>+++</code> file header. Now, this scenario is treated the same as
when <code>oldHeader</code>/<code>newHeader</code> is
<code>undefined</code> - i.e. the trailing tab is omitted.</p>
</li>
<li>
<p><strong><code>formatPatch</code> no longer mutates its input</strong>
when serializing a patch containing a hunk where either the old or new
content contained zero lines. (Such a hunk occurs only when the hunk has
no context lines and represents a pure insertion or pure deletion, which
for instance will occur whenever one of the two files being diffed is
completely empty.) Previously <code>formatPatch</code> would provide the
correct output but also mutate the <code>oldLines</code> or
<code>newLines</code> property on the hunk, changing the meaning of the
underlying patch.</p>
</li>
<li>
<p><strong>Git-style patches are now supported by
<code>parsePatch</code>, <code>formatPatch</code>, and
<code>reversePatch</code></strong>.</p>
<p>Patches output by <code>git diff</code> can include some features
that are unlike those output by GNU <code>diff</code>, and therefore not
handled by an ordinary unified diff format parser. An ordinary diff
simply describes the differences between the <em>content</em> of two
files, but Git diffs can also indicate, via "extended
headers", the creation or deletion of (potentially empty) files,
indicate that a file was renamed, and contain information about file
mode changes. Furthermore, when these changes appear in a diff in the
absence of a content change (e.g. when an empty file is created, or a
file is renamed without content changes), the patch will contain no
associated <code>---</code>/<code>+++</code> file headers nor any
hunks.</p>
<p>jsdiff previously did not support parsing Git's extended headers, nor
hunkless patches. Now <code>parsePatch</code> parses some of the
extended headers, parses hunkless Git patches, and can determine
filenames (e.g. from the extended headers) when parsing a patch that
includes no <code>---</code> or <code>+++</code> file headers. The
additional information conveyed by the extended headers we support is
recorded on new fields on the result object returned by
<code>parsePatch</code>. See <code>isGit</code> and subsequent
properties in the docs in the README.md file.</p>
<p><code>formatPatch</code> now outputs extended headers based on these
new Git-specific properties, and <code>reversePatch</code> respects them
as far as possible (with one unavoidable caveat noted in the README.md
file).</p>
</li>
<li>
<p><strong>Unpaired file headers now cause <code>parsePatch</code> to
throw</strong>.</p>
<p>It remains acceptable to have a patch with no file headers whatsoever
(e.g. one that begins with a <code>@@</code> hunk header on the very
first line), but a patch with <em>only</em> a <code>---</code> header or
only a <code>+++</code> header is now considered an error.</p>
</li>
<li>
<p><strong><code>parsePatch</code> is now more tolerant of
"trailing garbage"</strong></p>
<p>That is: after a patch, or between files/indexes in a patch, it is
now acceptable to have arbitrary lines of "garbage" (so long
as they unambiguously have no syntactic meaning - e.g. trailing garbage
that leads with a <code>+</code>, <code>-</code>, or <code> </code> and
thus is interpretable as part of a hunk still triggers a throw).</p>
<p>This means we no longer reject patches output by tools that include
extra data in "garbage" lines not understood by generic
unified diff parsers. (For example, SVN patches can include
"Property changes on:" lines that generic unified diff parsers
should discard as garbage; jsdiff previously threw errors when
encountering them.)</p>
<p>This change brings jsdiff's behaviour more in line with GNU
<code>patch</code>, which is highly permissive of
"garbage".</p>
</li>
<li>
<p><strong>The <code>oldFileName</code> and <code>newFileName</code>
fields of <code>StructuredPatch</code> are now typed as <code>string |
undefined</code> instead of <code>string</code></strong>. This type
change reflects the (pre-existing) reality that <code>parsePatch</code>
can produce patches without filenames (e.g. when parsing a patch that
simply contains hunks with no file headers).</p>
</li>
</ul>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="ed13aca03a"><code>ed13aca</code></a>
Update version in package.json and in release notes (<a
href="https://redirect.github.com/kpdecker/jsdiff/issues/683">#683</a>)</li>
<li><a
href="7a49317b50"><code>7a49317</code></a>
Bump dependencies again (<a
href="https://redirect.github.com/kpdecker/jsdiff/issues/682">#682</a>)</li>
<li><a
href="afe5aecad1"><code>afe5aec</code></a>
Add Git support, and otherwise variously improve & fix parsePatch
(and other ...</li>
<li><a
href="2e46779d88"><code>2e46779</code></a>
Fix a typo (<a
href="https://redirect.github.com/kpdecker/jsdiff/issues/679">#679</a>)</li>
<li>See full diff in <a
href="https://github.com/kpdecker/jsdiff/compare/8.0.4...v9.0.0">compare
view</a></li>
</ul>
</details>
<br />
[](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores)
Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.
[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)
---
<details>
<summary>Dependabot commands and options</summary>
<br />
You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore this major version` will close this PR and stop
Dependabot creating any more for this major version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this minor version` will close this PR and stop
Dependabot creating any more for this minor version (unless you reopen
the PR or upgrade to it yourself)
- `@dependabot ignore this dependency` will close this PR and stop
Dependabot creating any more for this dependency (unless you reopen the
PR or upgrade to it yourself)
</details>
---------
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
## Summary
One PR with separate commits (the earlier stack #1168 and #1169 is
folded back in).
### Exact git patches
- `src/diff.ts` builds exact git patches for Edit and Write: real line
numbers, file modes, CRLF, the final-newline marker, a size limit
(including a bound for `replace_all`), binary detection, and an
asynchronous diff with a time budget. The approval preview mirrors the
input normalisation of the bundled CLI.
- No creation patch over an existing file or for an Edit of an existing
empty file, and no patch for a Write that changed nothing.
### For every client
Clients that do not declare `_meta.jetbrains.air` (Zed, plain ACP
clients) get the same information as on `main`.
- A `tool_call_update` omits top-level fields that did not change since
the last report of the same tool call (ACP merge semantics). The `_meta`
of each report stays complete.
- Bug fixes: a failed approval preview no longer blanks the approval
diff; a permission denial replaces a pinned approval patch; the
compaction summary is not repeated when the streamed text is identical;
streamed subagent text is not sent twice; async task fields are recorded
only after a successful send; late updates of a finished native subagent
are dropped; the updates of a fresh Claude context after a clear-context
restart reach the ACP session.
### For AIR only
- One fact in one field: input in `rawInput`, the file text of an edit
only in the diff (`diffPatch`), output once, no display copies of the
input (`rawInputRendering`), `_meta.claudeCode` reduced to `toolName`,
`parentToolUseId` and the `toolResponse` markers, per-key `_meta`
filtering.
- Plan file mode (`planFile`): ExitPlanMode carries only
`rawInput.planFilePath`; AIR follows the file that Claude writes.
- AIR-only keys move under `_meta.jetbrains.air.*` and are no longer
sent to other clients.
### Structure and docs
- `src/tool-calls/`: one reporter per tool, one `ClientCapabilities`,
one `AcpToolCallRenderer`, the field tracker and the changed-meta
filter.
- `docs/air-extensions.md` replaces the per-extension AIR docs.
## Tests
- `npm run build`, `npm run check`, `npm run test:run`: 1995 passed.
- Scenario tests for plain, Zed, and AIR clients: the SDK mock honours
the adapter's session id, every update must reach its ACP session, every
message is validated against the ACP JSON schema with all formats
checked, plain and Zed are compared with a recorded `main` baseline, AIR
keeps compact golden recordings.
Authentication failures now use the ACP authRequired error only. The
adapter does not send a second access failure or login text as a chat
message. Provider verification and cloud credential errors use the
service category because signing in cannot resolve them. Checks: npm run
check; npm run build; npm run test:run (1468 passed, 28 skipped).
### Summary
Fixes#1158.
When a native subagent session is resumed for subsequent turn execution
(`task_started`), `this.parentByToolUse.get(task.toolUseId)` returns
`undefined` because `finishTask` deletes the mapping at the completion
of earlier generations. Because `knownParentSessionId` evaluated to
`undefined`, `if (knownParentSessionId || !task.toolUseId)` evaluated to
`false`, postponing the subagent announcement until `finishTask`.
### Changes
- In `src/native-subagents.ts`: Added fallback `const
knownParentSessionId = this.parentByToolUse.get(task.toolUseId) ??
previous?.parentSessionId;` so resumed subagents recognize their
existing session parent at `task_started`.
- In `src/tests/native-subagents.test.ts`: Added unit test confirming
`subagent_spawned` is emitted immediately upon `taskStarted` for resumed
sessions.
### Verification
- `npm test src/tests/native-subagents.test.ts` (all 8 tests passing).
- `npx tsc --noEmit` (clean, 0 type errors).
---------
Co-authored-by: shobhitagnihotri69 <shobhitagnihotri69@users.noreply.github.com>
Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Fixes#1167.
## Problem
In plan mode the model often runs Explore agents in the background. The
user turn's result then comes back while those agents are still running,
so `session/prompt` is held open (#864/#866). When an agent finishes,
the model writes the plan and calls `ExitPlanMode` in the
**task-notification followup**. The user accepts it with a clear-context
option.
The interrupted cycle's `[ede_diagnostic] … stop_reason=tool_use` result
carries that cycle's `task-notification` origin. That sends it into the
autonomous-result branch, which:
1. sends the `usage_update` with `_claude/origin: task-notification`.
This is the "background task finished at the same time" update from the
report; it's actually the same cycle.
2. settles the held turn with `end_turn` and returns early, before the
ExitPlanMode restart check runs.
The plan is never continued, the mode stays `plan`, and nothing tells
the client.
## Fix
- The diagnostic match now lives in one shared function,
`isExitPlanInterruptionResult()` in `exit-plan.ts`. Both the user-result
path and the new check call it; the user path behaves as before.
- In the autonomous branch, when the active turn is held and the result
is the recorded ExitPlanMode interruption:
- **Clear-context option:** drop the held turn's stored outcome, then
run the usual fresh-context restart. The fresh query doesn't have the
old background tasks, so the stale hold would otherwise settle the moved
turn with `end_turn` before the plan runs. The continuation's own result
settles the turn.
- **"No, keep planning":** settle `cancelled` with the user turn's own
usage, through `settleOrDefer`, so the turn stays open while other
spawned subagents are still running.
## Tests
There are two new tests in the deferred-settlement block. Each runs a
held turn whose task-notification followup calls `ExitPlanMode`: one for
the clear-context restart, one for keep-planning. The restart test also
fails if the held outcome isn't dropped.
## Known limitations (unchanged by this PR)
- **Background agents are killed by the restart.** Upstream `/clear`
keeps background agent tasks running (`hasAgentTaskSurvivingClear`). The
adapter's restart closes the old query, so any other running subagents
are killed, just as on the existing user-turn restart path.
- **Plans approved after the turn has ended are still dropped.** If
`ExitPlanMode` runs after the turn has already settled, there's no open
turn to continue, and the plan is dropped as before. A client-visible
notice for that case would be a follow-up.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
## Summary
- include the current assistant model id on `usage_update` notifications
as `model`
- mirror the same value in `_meta["_claude/model"]` so clients that
prefer extension metadata can consume it
- preserve existing `_meta` entries such as `_claude/origin` and
rate-limit metadata
Fixes#1021
## Verification
- `npm run build`
- `npm run check`
- `npm run test:run -- src/tests/acp-agent.test.ts -t
'usage_update|effective model|origin handling'`
- `npm run test:run` *(fails only in existing root-environment
`resolve-permission-mode` expectations: `bypassPermissions` falls back
to `default` when run as root; unrelated to usage updates)*
---------
Signed-off-by: Emre Koca <110906681+kocaemre@users.noreply.github.com>
Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
A warm `session/resume` or `session/load` currently ignores changed
`maxTurns` and `maxBudgetUsd`: the session fingerprint compares only cwd
and MCP servers, so the SDK query retains its old options. A client can
request a tighter limit and receive success while the old limit remains
active.
Include these two SDK execution limits in the session fingerprint.
Adding, changing or removing a limit recreates the query with the
supplied options and the same session ID. Identical limits reuse the
existing query; object key order does not trigger recreation. Budget
accounting across recreated SDK processes remains the client's
responsibility.
Validation:
- Four regression cases failed before the fix; six new cases cover both
methods, both limits, tightening/removal, and unchanged reuse.
- `npm run check` and `npm run build` passed.
- Focused suites: 551 passed, 9 skipped.
- Full suite with `--maxWorkers=2`: 1,240 passed, 27 skipped. An initial
unrestricted run hit one existing provider-switch test's 5s timeout and
macOS `EMFILE` watcher errors; bounding workers passed without changing
tests or timeouts.
Prepared while integrating typed runtime limits in
BinaryBourbon/fountain#1732. No live SDK budget-enforcement claim is
made by these adapter tests.
---------
Signed-off-by: Jake Gaylor <jhgaylor@gmail.com>
Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Synthetic usage-limit frames from the Claude SDK carry an all-zero usage
object. When one follows a real assistant response, the ACP bridge
currently overwrites the latest context measurement and emits a final
`usage_update` with `used: 0`.
Keep the previous measurement for a synthetic usage-limit frame when one
exists. A fresh quota-limited turn remains zero.
Includes a regression test covering a 170,910-token context followed by
a synthetic spend-limit frame.
Verified with:
- `npx vitest run src/tests/acp-agent.test.ts`
- `npm run check`
- `npm run build`
---------
Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
## Summary
- keep `ANTHROPIC_VERTEX_BASE_URL` unset when `providers/set` selects
Vertex's native default endpoint
- retain explicit `ANTHROPIC_VERTEX_BASE_URL` only for custom Vertex
gateways/endpoints
- add a regression test for the default Vertex endpoint env mapping
Closes#1087
## Test Plan
- `npm run test:run -- src/tests/providers.test.ts` — passed (21 tests)
- `npm run check` — passed (`eslint src --ext .ts` + `prettier --check
.`)
- `npm run build` — passed (`tsc`)
- `git diff --check origin/main..HEAD` — passed
Note: `claude -p` delegation was attempted for candidate discovery but
this cron shell's Claude Code auth is not logged in (`Not logged in ·
Please run /login`), so the implementation/validation above was done
directly with local tests.
Signed-off-by: Emre K <110906681+kocaemre@users.noreply.github.com>
## Summary
- Fixes#1092 by treating `Please run /login` in a `success` result as
auth-required only when the result is actually error-shaped.
- Applies the same error-state guard to goal-command failure detection
so quoted login text in a normal answer does not roll back the active
goal.
- Adds a regression test for a successful model answer that mentions
`/login` without publishing a session failure.
## Test Plan
- [x] `npm run test:run -- src/tests/acp-agent.test.ts -t
'login|auth_required'`
- [x] `npm run build`
- [x] `npm run check`
- [ ] `npm run test:run` (blocked locally by pre-existing root
permission-mode assertions: `resolvePermissionMode("bypassPermissions")`
and `resolvePermissionMode("bypass")` resolve to `default` when running
as root)
Signed-off-by: Emre K <110906681+kocaemre@users.noreply.github.com>
## Summary
- allow the scheduled-wakeup live audit to wait through the full
minute-alignment window
- keep a small buffer for the autonomous model turn to complete
- raise the Vitest case timeout accordingly
`ScheduleWakeup(delaySeconds=60)` is persisted as a minute-aligned cron
entry. Depending on where scheduling lands within a minute, delivery can
take close to two minutes. The previous 75-second predicate timeout can
therefore fail even though the idle ACP stream delivers the wakeup
correctly. I reproduced both outcomes against current `main`: one run
timed out at 75 seconds, while a second run delivered `LIVE_WAKE_OK`
through the idle ACP stream.
Related: #838
## Verification
- `npm run check`
- `npm run build`
- `npm run test:run` (971 passed, 27 skipped)
- live SDK/ACP probe on Agent SDK 0.3.238 observed `SCHEDULED` followed
by autonomous `LIVE_WAKE_OK` while idle
## Summary
- reconstructs marker-only model-bound slash skill prompts during
history replay
- keeps client/local command metadata hidden when local stdout/stderr is
present
- adds regression coverage for both string and content-array transcript
shapes
Closes#998.
## Verification
- `npm run test:run -- src/tests/acp-agent.test.ts -t
'stripLocalCommandMetadata'`
- `npm run test:run -- src/tests/acp-agent.test.ts`
- `npm run build`
- `npm run check`
- `git diff --check`
I also ran `npm run test:run`. It completed with 965 passing tests, 27
skipped, and the same two root-environment `resolve-permission-mode`
failures seen when running as root: `bypassPermissions` is intentionally
downgraded to `default` in that environment. The changed replay/metadata
tests passed.
Signed-off-by: Emre Koca <1328630750+kocaemre@users.noreply.github.com>
Co-authored-by: Emre Koca <1328630750+kocaemre@users.noreply.github.com>
## Summary
- include normalized Claude SDK `skills` in the resumed-session
fingerprint
- preserve the distinct semantics of omitted, `'all'`, empty, and
explicit skill selections
- avoid unnecessary Query recreation for reordered or duplicate skill
names
- keep unrelated `_meta.claudeCode.options` fields out of the
fingerprint
- recreate the Query with the same native session ID when skills change
- merge the latest `origin/main` so the change is validated against the
current session logic and SDK 0.3.238
## Testing
- clean Linux Node 22 environment with
`@anthropic-ai/claude-agent-sdk@0.3.238`
- `npm run build`
- `npm run lint`
- `npm run check`
- targeted lifecycle tests: `425 passed, 9 skipped`
- full test suite: `978 passed, 27 skipped`
- successful lifecycle case: `newSession(['pdf']) ->
resumeSession(['docx'])`
Closes#955
Fixes#1114.
## Problem
A steered turn settles only at an SDK `idle`, and only once the steer's
echo has been replayed and an outcome recorded. Two ways that never
happens, both from #1114:
- **Missing echo.** If the CLI never replays the steered message, every
idle is swallowed and `session/prompt` parks until cancel or the next
prompt.
- **Owed-idle debt eats the settling idle.** If the steer aborts an
autonomous followup, that followup's result counts a trailing idle, but
the abort folds it into the one idle that spans both cycles. The debt
lane absorbs that idle and the steered turn never settles.
## Fix
1. **Exact lane: settle on the result that answers the steer.** A result
whose `user_message_uuids` (falling back to `user_message_uuid`) names
one of the turn's steers retires that steer's echo, even if the CLI
never replayed it. Once no steer is outstanding, the turn leaves the
steer lane and settles at that result through the ordinary lanes,
including the subagent hold and failure lanes. It owes its trailing idle
like any other settling result. No timer.
2. **Idle fallback, for producers that don't stamp results: count only a
result recorded after the last echo.** Before this, the outcome of the
cycle the steer interrupted (or a held turn's outcome that `steer()`
moved over) made the turn look ready as soon as the echo landed.
`steeredAwaitingResult` is set when an echo drains and cleared when a
result is recorded.
3. **A ready steered turn takes the idle ahead of owed-idle debt.** Its
outcome is final, so whichever idle arrives settles it correctly. The
debt is left standing: a separate trailing idle still absorbs the idle
it belongs to, and one that never comes is cleared by the existing sweep
at the next `running` transition. A steered turn that isn't ready still
goes through the debt lane first, so an earlier turn's late idle can
never settle a steered cycle that's still running.
## Live verification (CLI 2.1.280, SDK 0.3.280)
A probe with the adapter's query options (`replay-user-messages`,
partial messages) steered a running turn three ways: mid-generation at
`now`, mid-tool-call at `now`, and mid-tool-call at `later`. All three
had the same frame order:
```
RESULT stamp=ORIG stamps=[ORIG] <- interrupted (or finished) original cycle
lifecycle ORIG cancelled|completed
lifecycle STEER started
ECHO STEER
RESULT stamp=STEER stamps=[STEER] <- steered cycle
lifecycle STEER completed
STATE idle <- the only idle
```
So the interrupted cycle's result never names the steer, and the steered
cycle's result always does. `later` doesn't fold the steer into the
running turn either; it runs as its own cycle after the original
finishes, with no idle in between.
## Tests
Three new tests in `turn steering (_session/steering)`:
- **Echo missing, stamped result:** the turn settles at the result
before any idle, and the idle that follows is absorbed. Hangs on `main`.
- **Steer aborts an autonomous followup, only one idle:** the turn
settles. Hangs on `main`.
- **Owed idle arrives after the echo but before the steered result:**
the turn must not settle on it, and it ends with both cycles' usage.
Passes on `main`, but fails with the post-echo readiness check removed,
so it guards against settling early on a pre-steer outcome.
`npm run build`, `npm run test:run` and `npm run check` pass.
## Remaining gap
If the echo never replays and the result carries no stamp (older
producers), the turn still waits for cancel or the next prompt, as
documented before.
Supersedes #1115 and #1063. Thanks to @KlausUllrich for the #1114
analysis and the result-acknowledgement idea, which this builds on.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
## Problem
Claude Code refuses `bypassPermissions` when any settings tier sets
`permissions.disableBypassPermissionsMode` to `"disable"`. The adapter
ignored the setting: it still listed the Bypass mode, passed
`allowDangerouslySkipPermissions`, and accepted `defaultMode:
"bypassPermissions"` as the starting mode.
## Change
Fold the setting into `allowBypass` at session creation. That single
value already drives the mode catalog, the SDK flag and the spawn-time
mode clamp, so all three now agree with the CLI. Like the CLI, the
setting is honored from any tier. It can only take away a permission, so
project settings are trusted for it.
## Validation
- `npm run build`, `npm run check` and `npm run test:run` pass.
- New tests set the option in user settings and in project settings.
Both fail without the fix.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Supersedes #1140 by @s-cork. Their commit is kept as-is (rebased onto
`main`), plus one follow-up commit. The fork is org-owned, so
maintainers can't push to it.
## Problem
ExitPlanMode always led with Auto and dropped bypass, even when the
session advertised `bypassPermissions`. Clients that deliberately run in
full-access mode lost that choice at plan approval.
Claude Code itself offers one elevated choice and prefers bypass over
Auto. It can do that because the CLI only offers bypass to users who
launched with it. The adapter advertises bypass for every non-root
session, so copying that priority would hide Auto for almost everyone.
## Change
- Offer both Auto and bypass whenever the session advertises them
(@s-cork's commit).
- Follow-up: remember the mode the session left when it entered plan
mode (`SessionModeManager.syncConfig`, which every mode change goes
through, including plan approval since #1163). If that was
`bypassPermissions`, bypass comes first and is also what the
clear-context option uses. Otherwise Auto leads, as before. A remembered
bypass mode is ignored if the session no longer advertises it.
This also fills the gap where the clear-context choice only ever came in
the Auto flavour.
Partially addresses #1077.
## Validation
- `npm run build`, `npm run check` and `npm run test:run` pass.
- New tests cover the pre-plan mode tracking and the option order with
and without a pre-plan bypass mode, including the clear-context row.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: stu <stucork@gmail.com>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
## Summary
- tag SDK `informational` notices with `_meta.claudeCode.kind =
"informational"`
- include the notice `level` so clients can separate hook/status notices
from model text
- keep the existing rendered text unchanged for clients that ignore
`_meta`
Fixes#1042
## Test plan
- `npm test -- --run src/tests/acp-agent.test.ts -t informational`
- `npm run build`
- `npm run check`
- `IS_SANDBOX=1 npm run test:run`
- `git diff --check`
---------
Signed-off-by: Emre Koca <110906681+kocaemre@users.noreply.github.com>
Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Fixes#1124.
## The defect
`src/index.ts` awaited `resolveSettings` at module scope with nothing
around it:
```ts
const policy = await resolveSettings({ settingSources: [] });
for (const [key, value] of Object.entries(policy.effective.env ?? {})) {
process.env[key] = value;
}
```
That is a top-level `await` in an ESM entry point, so a rejection aborts
module evaluation and the process exits before serving any ACP traffic.
The client only sees a process that exited 1 with no protocol messages.
Two neighbours make this the only call that can do it, and both are
still true on \`main\`:
- `SettingsManager.loadAllSettings` (`src/settings.ts:105-113`) wraps
the same SDK call in `try`/`catch` and falls back to `{}`.
- The `process.on("unhandledRejection", ...)` handler is registered at
\`src/index.ts:62\`, after this await, so it does not cover it.
Reading the managed tier is best-effort by nature — on a host with no
MDM and no managed policy the result is empty and the agent behaves
identically — so a transient `EINTR`/`EMFILE`/`EAGAIN` while reading it
should leave the agent running with no policy env rather than stop it
from starting.
## The change
The guard lives in a new `src/managed-policy.ts` rather than inline, for
one reason: `src/index.ts` is an ESM entry point with top-level side
effects, so nothing in it can be imported by a test. Extracting the tier
read makes the failure path testable, which is what the regression test
below exercises.
`applyManagedPolicyEnv` mirrors `loadAllSettings`: it takes the SDK call
through a parameter defaulting to `resolveSettings` and a target env
defaulting to `process.env`, reports the failure on stderr, and returns
without applying anything. `src/index.ts` becomes:
```ts
await applyManagedPolicyEnv();
```
`console.error` is correct here: this runs before stdout is redirected,
so the ACP stream stays clean.
## Verification
Four tests in `src/tests/managed-policy.test.ts` cover the applied case,
an empty tier, a tier with no `env` table, and the failure path — the
last one asserts the promise **resolves** rather than rejects, with the
target env untouched, which is the property the entry point depends on.
```
before after
tests 17 failed | 1366 passed 17 failed | 1370 passed
```
The 17 failures are pre-existing in this checkout and untouched by this
change; the four added tests account for the difference. `eslint src
--ext .ts`, `tsc`, and `prettier --check` (with the repository's
`.prettierrc.json`) are clean on the three files.
## Note
I have not established whether those 17 pre-existing failures are
host-specific or real, so I am not claiming anything about them or
changing anything for them.
Supersedes #1139 by @s-cork. Their commit is kept as-is (rebased onto
`main`), plus one follow-up commit. The fork is org-owned, so
maintainers can't push to it.
## Problem
Approving a plan through ExitPlanMode changes the SDK permission mode,
but ACP clients keep showing Plan. When Auto isn't available for the
current model, clients should also see the fallback mode that actually
applies.
## Change
- After an ExitPlanMode permission is allowed, send
`current_mode_update` and `config_option_update` with the session mode
as it stands after `applyPermissionFallback`. Rejection and
clear-context handling don't change.
- Follow-up: wrap those two notifications in a try/catch. The plan is
already approved at that point, so a rejected `sessionUpdate` is logged
and no longer turns the approval into a failed permission request. This
matches `publishFallbackWarning`.
Partially addresses #1077. It doesn't fix session restoration after a
clear-context approval.
## Validation
- `npm run build`, `npm run check` and `npm run test:run` pass.
- Regression tests cover the ordinary default, bypass and Auto
approvals, plus Auto falling back to acceptEdits. They check both the
stored mode and both ACP notifications.
- A new test rejects the mode notification and checks that the approval
still returns `allow` with the `setMode` update. It fails without the
follow-up fix.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: stu <stucork@gmail.com>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude Code 2.1.280 (SDK 0.3.280, bumped in #1157) now accepts Write
calls where the model sends `path` instead of `file_path`, or
`file_text`/`file_content` instead of `content`. The CLI renames these
for its own validation, but the streamed `tool_use` block keeps the
model's original field names. So we showed the call as "Preparing file…"
with no diff or location, even though the write went through.
`toolInfoFromToolUse` now reads those fields the same way the CLI does.
When both spellings are present, the canonical fields win.
Nothing else in the 0.3.280 / 2.1.280 changelog needed an adapter
change. I checked Opus 5.5 model rows, the hand-back frame header,
`requires_action` during MCP elicitation, and headless elicitation
cancellation.
## Test plan
- New `toolInfoFromToolUse - Write input aliases` tests
- `npm run build`, `npm run check`, `npm run test:run`
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
## Summary
Close unfinished ACP compactions before interrupted prompts settle.
Previously, force cancellation could return `stopReason: cancelled`
while leaving the compaction `in_progress`; SDK stream teardown and
conversation reset had similar cleanup gaps.
- Add shared, idempotent interruption cleanup for cancellation,
force-cancel recovery, provider failures, SDK EOF/errors, and
conversation reset.
- Close compactions before resolving echo-less `/compact` commands,
which may still be queued while their compaction is running.
- Discard abandoned pending summaries and ignore late compaction
openings, completions, chunks, and hooks until an identified live turn
resumes.
- Preserve normal early-summary buffering across ordinary result
boundaries.
- Add regression coverage for terminal-before-response ordering,
echo-less cancellation, late SDK events, fresh-turn recovery,
EOF/errors, reset, and best-effort delivery failures.
After interruption, hooks without a command identity are conservatively
omitted until a new live turn is identified, rather than risking
attribution to the wrong compaction. Older echo-less commands without
dispatch identity may likewise omit the ambiguous compaction lifecycle
until turn activation.
This fixes an implementation gap found while auditing the [Session
Compaction
RFD](https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/session-compaction.mdx).
No protocol or RFD changes are included.
## Validation
- [x] `npm run test:run` — 1,397 passed, 28 skipped
- [x] `npm run build`
- [x] `npm run check` — ESLint and Prettier
- [x] `git diff --check`
Tests use mocked SDK streams; no live provider calls were made.
Bumps the minor group with 11 updates:
| Package | From | To |
| --- | --- | --- |
|
[@anthropic-ai/claude-agent-sdk](https://github.com/anthropics/claude-agent-sdk-typescript)
| `0.3.274` | `0.3.276` |
|
[@types/node](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/HEAD/types/node)
| `26.5.1` | `26.6.1` |
| [prettier](https://github.com/prettier/prettier) | `3.9.7` | `3.9.8` |
| @anthropic-ai/claude-agent-sdk-darwin-arm64 | `0.3.274` | `0.3.276` |
| @anthropic-ai/claude-agent-sdk-darwin-x64 | `0.3.274` | `0.3.276` |
| @anthropic-ai/claude-agent-sdk-linux-arm64 | `0.3.274` | `0.3.276` |
| @anthropic-ai/claude-agent-sdk-linux-arm64-musl | `0.3.274` |
`0.3.276` |
| @anthropic-ai/claude-agent-sdk-linux-x64 | `0.3.274` | `0.3.276` |
| @anthropic-ai/claude-agent-sdk-linux-x64-musl | `0.3.274` | `0.3.276`
|
| @anthropic-ai/claude-agent-sdk-win32-arm64 | `0.3.274` | `0.3.276` |
| @anthropic-ai/claude-agent-sdk-win32-x64 | `0.3.274` | `0.3.276` |
Updates `@anthropic-ai/claude-agent-sdk` from 0.3.274 to 0.3.276
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/anthropics/claude-agent-sdk-typescript/releases">@anthropic-ai/claude-agent-sdk's
releases</a>.</em></p>
<blockquote>
<h2>v0.3.276</h2>
<h2>What's changed</h2>
<ul>
<li>Updated to parity with Claude Code v2.1.276</li>
</ul>
<h2>Update</h2>
<pre lang="sh"><code>npm install @anthropic-ai/claude-agent-sdk@0.3.276
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.276
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.276
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.276
</code></pre>
<h2>v0.3.275</h2>
<h2>What's changed</h2>
<ul>
<li>Fixed a deferred tool call's result being emitted with internal keys
such as <code>toolUseResult</code> instead of
<code>tool_use_result</code> when the tool re-runs at the start of a
resumed turn</li>
<li>Fixed <code>getSessionMessages()</code> and
<code>forkSession()</code> sometimes missing a turn's assistant message
when called right after the turn's <code>result</code> message</li>
<li>Fixed <code>forkSession({ upToMessageId })</code> rejecting a
client-supplied <code>SDKUserMessage.uuid</code> that is not in UUID
format</li>
<li>Fixed <code>forkSession</code> rejecting the id that
<code>getSessionMessages</code> returns for a message sent while Claude
was working, and a fork showing a re-run prompt twice</li>
<li>Fixed <code>getSessionMessages()</code> omitting a task notification
or other queued message that Claude read while running a tool; it now
comes back where Claude read it</li>
<li>Updated to parity with Claude Code v2.1.275</li>
</ul>
<h2>Update</h2>
<pre lang="sh"><code>npm install @anthropic-ai/claude-agent-sdk@0.3.275
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.275
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.275
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.275
</code></pre>
</blockquote>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/anthropics/claude-agent-sdk-typescript/blob/main/CHANGELOG.md">@anthropic-ai/claude-agent-sdk's
changelog</a>.</em></p>
<blockquote>
<h2>0.3.276</h2>
<ul>
<li>Updated to parity with Claude Code v2.1.276</li>
</ul>
<h2>0.3.275</h2>
<ul>
<li>Fixed a deferred tool call's result being emitted with internal keys
such as <code>toolUseResult</code> instead of
<code>tool_use_result</code> when the tool re-runs at the start of a
resumed turn</li>
<li>Fixed <code>getSessionMessages()</code> and
<code>forkSession()</code> sometimes missing a turn's assistant message
when called right after the turn's <code>result</code> message</li>
<li>Fixed <code>forkSession({ upToMessageId })</code> rejecting a
client-supplied <code>SDKUserMessage.uuid</code> that is not in UUID
format</li>
<li>Fixed <code>forkSession</code> rejecting the id that
<code>getSessionMessages</code> returns for a message sent while Claude
was working, and a fork showing a re-run prompt twice</li>
<li>Fixed <code>getSessionMessages()</code> omitting a task notification
or other queued message that Claude read while running a tool; it now
comes back where Claude read it</li>
<li>Updated to parity with Claude Code v2.1.275</li>
</ul>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="4919e0693e"><code>4919e06</code></a>
chore: Update CHANGELOG.md</li>
<li><a
href="e51cd0b1ba"><code>e51cd0b</code></a>
chore: Update CHANGELOG.md</li>
<li>See full diff in <a
href="https://github.com/anthropics/claude-agent-sdk-typescript/compare/v0.3.274...v0.3.276">compare
view</a></li>
</ul>
</details>
<br />
Updates `@types/node` from 26.5.1 to 26.6.1
<details>
<summary>Commits</summary>
<ul>
<li>See full diff in <a
href="https://github.com/DefinitelyTyped/DefinitelyTyped/commits/HEAD/types/node">compare
view</a></li>
</ul>
</details>
<br />
Updates `prettier` from 3.9.7 to 3.9.8
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/prettier/prettier/releases">prettier's
releases</a>.</em></p>
<blockquote>
<h2>3.9.8</h2>
<ul>
<li>Markdown: Don't let Liquid objects interrupt paragraphs (<a
href="https://redirect.github.com/prettier/prettier/pull/20087">#20087</a>
by <a href="https://github.com/seiyab"><code>@seiyab</code></a>)</li>
</ul>
<p>🔗 <a
href="https://github.com/prettier/prettier/blob/3.9.8/CHANGELOG.md#398">Changelog</a></p>
</blockquote>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/prettier/prettier/blob/main/CHANGELOG.md">prettier's
changelog</a>.</em></p>
<blockquote>
<h1>3.9.8</h1>
<p><a
href="https://github.com/prettier/prettier/compare/3.9.7...3.9.8">diff</a></p>
<h4>Markdown: Don't let Liquid objects interrupt paragraphs (<a
href="https://redirect.github.com/prettier/prettier/pull/20087">#20087</a>
by <a href="https://github.com/seiyab"><code>@seiyab</code></a>)</h4>
<!-- raw HTML omitted -->
<pre lang="markdown"><code><!-- Input -->
If `module` is not a
[`WebAssembly.Module`](https://github.com/prettier/prettier/blob/main/en-US/docs/WebAssembly/Reference/JavaScript_interface/Module)
object instance, a
{{jsxref("TypeError")}} is thrown.
<p><!-- Prettier 3.9.7 -->
If <code>module</code> is not a <a
href="https://github.com/prettier/prettier/blob/main/en-US/docs/WebAssembly/Reference/JavaScript_interface/Module"><code>WebAssembly.Module</code></a>
object instance, a</p>
<p>{{jsxref("TypeError")}} is thrown.</p>
<p><!-- Prettier 3.9.8 -->
If <code>module</code> is not a <a
href="https://github.com/prettier/prettier/blob/main/en-US/docs/WebAssembly/Reference/JavaScript_interface/Module"><code>WebAssembly.Module</code></a>
object instance, a
{{jsxref("TypeError")}} is thrown.
</code></pre></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="4f2ab6765d"><code>4f2ab67</code></a>
Release 3.9.8</li>
<li><a
href="3d82af8b15"><code>3d82af8</code></a>
Update Regex related dependencies (<a
href="https://redirect.github.com/prettier/prettier/issues/20082">#20082</a>)</li>
<li><a
href="5ec8db1745"><code>5ec8db1</code></a>
[3.9.x] Markdown: Don't let Liquid objects interrupt paragraphs (<a
href="https://redirect.github.com/prettier/prettier/issues/20087">#20087</a>)</li>
<li><a
href="5b142ed2bc"><code>5b142ed</code></a>
Release Release <code>@prettier/plugin-hermes</code><a
href="https://github.com/0"><code>@0</code></a>.2.3,
<code>@prettier/plugin-oxc</code><a
href="https://github.com/0"><code>@0</code></a>.2.3, an...</li>
<li><a
href="0df8eb86b5"><code>0df8eb8</code></a>
Bump Prettier dependency to 3.9.7</li>
<li><a
href="3cf6c8c058"><code>3cf6c8c</code></a>
Clean changelog_unreleased</li>
<li>See full diff in <a
href="https://github.com/prettier/prettier/compare/3.9.7...3.9.8">compare
view</a></li>
</ul>
</details>
<br />
Updates `@anthropic-ai/claude-agent-sdk-darwin-arm64` from 0.3.274 to
0.3.276
Updates `@anthropic-ai/claude-agent-sdk-darwin-x64` from 0.3.274 to
0.3.276
Updates `@anthropic-ai/claude-agent-sdk-linux-arm64` from 0.3.274 to
0.3.276
Updates `@anthropic-ai/claude-agent-sdk-linux-arm64-musl` from 0.3.274
to 0.3.276
Updates `@anthropic-ai/claude-agent-sdk-linux-x64` from 0.3.274 to
0.3.276
Updates `@anthropic-ai/claude-agent-sdk-linux-x64-musl` from 0.3.274 to
0.3.276
Updates `@anthropic-ai/claude-agent-sdk-win32-arm64` from 0.3.274 to
0.3.276
Updates `@anthropic-ai/claude-agent-sdk-win32-x64` from 0.3.274 to
0.3.276
Dependabot will resolve any conflicts with this PR as long as you don't
alter it yourself. You can also trigger a rebase manually by commenting
`@dependabot rebase`.
[//]: # (dependabot-automerge-start)
[//]: # (dependabot-automerge-end)
---
<details>
<summary>Dependabot commands and options</summary>
<br />
You can trigger Dependabot actions by commenting on this PR:
- `@dependabot rebase` will rebase this PR
- `@dependabot recreate` will recreate this PR, overwriting any edits
that have been made to it
- `@dependabot show <dependency name> ignore conditions` will show all
of the ignore conditions of the specified dependency
- `@dependabot ignore <dependency name> major version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's major version (unless you unignore this specific
dependency's major version or upgrade to it yourself)
- `@dependabot ignore <dependency name> minor version` will close this
group update PR and stop Dependabot creating any more for the specific
dependency's minor version (unless you unignore this specific
dependency's minor version or upgrade to it yourself)
- `@dependabot ignore <dependency name>` will close this group update PR
and stop Dependabot creating any more for the specific dependency
(unless you unignore this specific dependency or upgrade to it yourself)
- `@dependabot unignore <dependency name>` will remove all of the ignore
conditions of the specified dependency
- `@dependabot unignore <dependency name> <ignore condition>` will
remove the ignore condition of the specified dependency and ignore
conditions
</details>
---------
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>
When a client advertises terminal_output_delta, send Bash output through
that channel. Keep the completion update free of duplicate raw output
while preserving the existing terminal_output fallback.\n\nTracks
IJAI-2376.
## Summary
- use the canonical tool-call title for permission prompts, so shell
approvals show the exact command instead of the model-authored
description
- map `PowerShell` through the same shell presentation path as `Bash`
- complete the PowerShell terminal lifecycle with matching
`terminal_info`, `terminal_output`, and `terminal_exit` metadata,
including failed commands
- add focused regression coverage without changing the existing Bash
lifecycle tests
Fixes#1068
## PowerShell input and result contract
`PowerShell` is a distinct tool name, but its documented input fields
match `Bash`: the executable command is in `command`, while
`description` is an optional human-readable summary. The Claude Code
hooks reference documents the shared `command`, `description`,
`timeout`, and `run_in_background` fields, and the tools reference
likewise states that PowerShell hooks receive the command in
`tool_input.command`.
Anthropic closed
[claude-code#83647](https://github.com/anthropics/claude-code/issues/83647#issuecomment-5310033500)
after documenting this equivalence. Reusing the SDK's exported
`BashInput` shape for the common input fields is therefore intentional;
the SDK currently does not export a separate `PowerShellInput` type.
PowerShell results do not need a PowerShell-specific output assumption
here. The result mapper first shape-checks structured stdout/stderr and
otherwise falls back to the standard raw `tool_result` string or
content-block array. Routing PowerShell through that existing mapper
preserves this fallback while completing the adapter's capability-gated
terminal sequence:
1. initial `tool_call` with `terminal_info`
2. `tool_call_update` with `terminal_output`
3. final `tool_call_update` with `terminal_exit`
All three events use the original tool-use ID, so the client can
reconcile and close the terminal. Failed PowerShell results also bypass
the generic error renderer and finish the terminal with a non-zero
display exit code.
The permission presentation introduced in #1004 already handled `Bash`
and `PowerShell` together when choosing a description-based permission
title, but the canonical tool presentation and terminal result paths
only handled `Bash`. This PR completes both paths.
References:
- [Claude Code hooks: PowerShell
input](https://code.claude.com/docs/en/hooks#powershell)
- [Claude Code tools reference: PowerShell
tool](https://code.claude.com/docs/en/tools-reference#powershell-tool)
- [Anthropic schema
confirmation](https://github.com/anthropics/claude-code/issues/83647#issuecomment-5310033500)
## Verification
- `npm run check`
- `npm run build`
- `npm run test:run -- src/tests/tools.test.ts -t "PowerShell terminal
output"` (1 passed)
- full suite with an empty temporary Claude config:
`CLAUDE_CONFIG_DIR=<empty temporary directory> npm run test:run` (1070
passed, 27 skipped)
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>
## Summary
- replace the hidden model-authored file audit turn with Claude native
file checkpointing
- preview changed paths with rewindFiles at the terminal turn boundary
while preserving the existing AIR metadata contract
- enable checkpointing only for clients that negotiate
agentFileChangeReport and fail open after two seconds
- retain legacy audit filtering so persisted sessions do not replay old
hidden audit turns
This follows Claude Code checkpoint semantics. It tracks changes made
through supported Claude file tools; Bash and most subagent changes may
not be included.
Reference: https://code.claude.com/docs/en/checkpointing
## Validation
- npm run build
- npm run check
- env -u ANTHROPIC_BASE_URL npm run test:run (1368 passed, 28 skipped)
Claude supplies structured patches for Edit and Write, but ACP diff
blocks previously carried only the reconstructed texts. AIR had to
compare those texts again to display added and removed counts.
Count patch operations in the existing conversion loop and publish
`_meta.jetbrains.air.diffStats` on each diff block. This uses the same
contract as https://github.com/agentclientprotocol/codex-acp/pull/501.
Each block has its own counts. No extra traversal, full file comparison,
or navigation calculation is needed.
Omit statistics when patches are absent or inconsistent, so clients
retain their existing fallback. Exclude EOF markers from the displayed
texts. Document the extension and cover per-block counts, Edit and Write
hooks, EOF changes, and fallback behavior.
Validation:
- `npm run build`
- `npm run check`
- `env -u ANTHROPIC_BASE_URL npm run test:run` (the local endpoint
override affects unrelated provider tests)
## Summary
For a single-select `AskUserQuestion`, a non-empty custom-answer field
(`question_<n>_custom`) replaced the selected option. A client that
renders that box as a notes step (as in #1050, seen via Devin/Windsurf)
therefore returned only the typed text and the selection never reached
the model.
- The pick now stays in `answers`, and the typed text travels beside it
as the tool's own per-question `annotations[question].notes`. That is
the slot the CLI itself uses for free text attached to a selection and
renders to the model as `"Q"="A" notes: ...`, so no new answer format is
invented.
- Custom text with no pick is still the answer on its own (the CLI's
"Other").
- Multi-select folding from #1031 is unchanged: the text still joins the
checked options with CLI-style quoting.
- `annotations` is only added to `updatedInput` when non-empty.
- The single-select field description now says the box can also add a
note to the chosen option.
Supersedes #1054, which conflicted with #1031 and glued label and text
into one string.
The "empty notes field won't submit" part of #1050 is client-side:
nothing in the requested schema is marked required.
Closes#1050
## Test plan
- `npm run check`
- `npm run build`
- `npm run test:run` (1325 passed, 27 skipped)
- New test: pick + custom text yields `answers: { Q: "A" }` and
`annotations: { Q: { notes } }`
- New test: custom text alone on a single-select stays the answer
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
## Summary
Closes#1119. Supersedes #1120 by @amansk (their commits are included on
this branch; the fork does not allow maintainer edits, so review fixes
landed here instead).
Hosts that never use `bypassPermissions` can opt a session out by
sending `_meta.claudeCode.options.allowDangerouslySkipPermissions:
false` on `session/new` (and again on `session/load`). When omitted or
`true`, behavior is unchanged: bypass is available on non-root sessions.
## Design
Bypass availability is decided once per session in `createSession`:
```ts
const allowBypass =
ALLOW_BYPASS && sessionMeta?.claudeCode?.options?.allowDangerouslySkipPermissions !== false;
```
and threaded to the three places that must agree:
- the SDK `allowDangerouslySkipPermissions` flag (the actual
enforcement; the CLI refuses bypass without it)
- the spawn-time mode clamp in `resolvePermissionMode`, so a
`permissions.defaultMode` of `bypassPermissions` (or a mode carried
across a clear-context restart) becomes `default` before `query()`
rather than failing at spawn
- the session mode catalog in `SessionModeManager.initialize`, so the
client is never offered a mode the CLI would reject
## Changes from #1120
- Fold the host opt-out into `resolvePermissionMode` via an
`allowBypass` parameter instead of a second inline clamp; drop the
separate `resolveAllowDangerouslySkipPermissions` helper
- Make `allowBypass` a required `initialize` parameter and remove the
module-global `ALLOW_BYPASS` fallback from `session-mode.ts`
- Fix `tsc` errors in the new tests (`modes` is optional on
`NewSessionResponse`), which broke the CI build job
- Move the settings-driven clamp test onto the shared
`acp-agent-settings` fixture (isolated cwd, no double module reload,
passes as root)
- Document the opt-out in `docs/permission-extension.md`
## Testing
- `npm run check`, `npm run build` — pass
- `npm run test:run` — pass (the branch is based before #1123, so the
SDK version guard in `model-presentation.test.ts` only passes with the
pinned 0.3.257; it clears on rebase)
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Amandeep Khurana <amansk@gmail.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
## Summary
`applyAskElicitationResponse` drops a multi-select question's checked
options as soon as
that question's custom-answer field is non-empty: the typed text
replaces the selection
instead of joining it, so the checked options never reach the model.
Versions: reproduced on v0.69.0, code unchanged on v0.70.0 and current
`main` (996d488);
`@agentclientprotocol/sdk` 1.3.0; Node 22. Noticed through Zed 1.16.1,
which does return
both fields, but the repro below is adapter-local and needs no client.
## Where the two fields diverge
`askUserQuestionsToCreateRequest` publishes, per question, two
**independent optional**
fields: `question_<n>` and `question_<n>_custom`. Neither is `required`,
and nothing in
the schema makes them exclusive. The
`_meta._askUserQuestionCustomAnswer` marker from #929
identifies the companion field's role (`{ questionId, isCustomAnswer }`)
— it doesn't ask a
client to clear the selection when the box is filled. So a client that
returns both is
doing nothing wrong, and the fold has no ground to keep only one of
them.
Before #774 the two coexisted: selections in `answers`, the custom text
in a separate
top-level `response` field. Scoping the custom answer per question
(fixing #770) turned
that coexistence into an overwrite:
```js
const custom = content[questionCustomFieldKey(index)];
if (typeof custom === "string" && custom.trim() !== "") {
answers[question.question] = custom.trim();
return; // <- selections discarded
}
```
For a **single-select** question replacing is right — the user typed an
answer instead of
picking one — and that stays. For a **multi-select** question the
options were never
mutually exclusive, so the typed answer should join them.
Restoring `response` isn't the alternative: it is a single form-level
field, so using it
for per-question custom answers would reintroduce exactly the collapse
#770 reported.
## Reproduction (no client, no model, no network)
```js
import { applyAskElicitationResponse } from "@agentclientprotocol/claude-agent-acp/dist/elicitation.js";
const q = [{ question: "Which features?", header: "F", multiSelect: true,
options: [{ label: "Alpha" }, { label: "Bravo" }] }];
const fold = (content) =>
applyAskElicitationResponse({ action: "accept", content }, { questions: q }, q)
.updatedInput.answers;
fold({ question_0: ["Alpha", "Bravo"] }); // { "Which features?": "Alpha, Bravo" } (control)
fold({ question_0: ["Alpha", "Bravo"], question_0_custom: "Charlie" });
// actual: { "Which features?": "Charlie" }
// expected: { "Which features?": "Alpha, Bravo, Charlie" }
```
## Change
Multi-select questions join the custom answer onto their selections;
single-select keeps
replacing. The selection normalization is deliberately untouched, so a
multi-select
question with a non-empty custom answer is the only input that folds
differently than
before. Comma-joining follows the documented shape of `answers`
("multi-select answers are
comma-separated"), which also means a label containing a comma stays
exactly as ambiguous
as it already was.
The `"Other"` box described itself as *"Type your own answer instead of
choosing an option
above"*; it now describes both roles, since for a multi-select question
it is no longer an
either/or.
---------
Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
## Summary
- Replace the ambiguous regex used to parse textual `TaskList` output
with linear string parsing.
- Preserve support for owners, multiple dependencies, and malformed
suffixes treated as subject text.
- Add a regression test covering adversarial input.
This addresses a potential ReDoS reported by CodeQL without changing the
structured JSON path.
Closes#1005.
## Testing
- `npm run test:run`
- `npm run build`
- `npm run check`
## Summary
- strip `<system-reminder>` blocks from replayed user messages, through
the marker scanner that already handles the local-command tags
- what the user actually typed is preserved; a reminder-only message
strips to nothing and is skipped
- regression coverage for the string shape, the content-array shape, and
`replaySessionHistory` end to end
## Why
`stripLocalCommandMetadata` exists for a stated reason: *"The live
prompt loop drops them; replay must strip them too or they leak into the
UI on session/load."* Injected reminders are the same class of leak and
are not covered by it.
The CLI appends `<system-reminder>` blocks to a user turn to steer the
model — a worktree that was deleted, a background task that started
elsewhere. They are persisted in the same text block as the prose the
user typed, and they are not `isMeta`, so `getSessionMessages` returns
them. Live, nothing reaches the client: the prompt loop's user-message
skip covers the whole message. On `session/load` the block is replayed
verbatim, so a client renders a paragraph of instructions the user never
wrote, followed by their one-line prompt.
Reproduced against `main` with a real transcript: a reminder about a
deleted worktree, followed by a five-word prompt, arrives as a single
`user_message_chunk` containing both. With this change the chunk is the
five words.
## Not included, deliberately
- **`<task-notification>` envelopes.** They still replay as user
messages, but #1028 is already doing that properly, keyed on the
SDK-provided `origin.kind` rather than the text — the better trust
boundary, since a user can type the tag themselves.
- **`[Request interrupted by user]`.** Also still replayed as a user
message. It is untagged prose and it is the only trace a cancelled turn
leaves, so whether it should be dropped, typed, or marked in `_meta`
reads as your product call rather than a bug fix. Happy to open a
follow-up if you want it handled.
The exported name `stripLocalCommandMetadata` is left alone — it is part
of `lib.ts` — so only the shared marker list and the doc comment grew.
## The one false positive
A user who literally types `<system-reminder>…</system-reminder>` in a
prompt loses that span on replay, while seeing it live. It is the same
trade already accepted for `<command-name>`, the surrounding prose still
survives, and text is the only signal available here — unlike task
notifications, reminders carry no `origin` to key on. Flagging it rather
than leaving it for review to find.
## Verification
- `npm run build`
- `npm run check`
- `env -u ANTHROPIC_BASE_URL npm run test:run` — 974 passed, 27 skipped
- the three new tests fail on `main` and pass with the change
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
## Why
The main-thread agent option is a rarely used, provider-specific
parameter. It is not used by ACP clients or their settings, and
maintaining a public picker for it adds config state, discovery calls,
restart propagation, and live-switch handling for functionality that
clients do not need.
Removing it keeps the session configuration contract focused on settings
that ACP clients actually use. This does not remove ACP subagent
sessions or the Agent/Task tool behavior; it only removes the unused
main-thread agent selector and parameter plumbing.
## Summary
- remove the main-thread Agent session config picker and custom-agent
discovery
- remove live agent switching and session state used only by that picker
- ignore claudeCode.options.agent and stop restoring it during context
resets
- document agent as ignored in the exported NewSessionMeta contract
- preserve ACP subagent sessions and Agent/Task tool behavior
## Breaking change
BREAKING CHANGE: claudeCode.options.agent is no longer forwarded to
Claude Code, and the agent-picker exports DEFAULT_AGENT_ID,
AGENT_CONFIG_ID, BUILTIN_AGENT_NAMES, and discoverCustomAgents are
removed. Consumers relying on main-thread agent selection must stop
passing that option.
## Testing
- npm run check
- npm run build
- npx vitest run src/tests/create-session-options.test.ts (62 passed)
Clients that negotiate the AIR `recommendedValue` capability receive
concrete model and effort choices instead of ambiguous default rows. The
SDK's default model is mapped only to an exact selectable model
(including equivalent context suffix spellings); unavailable
recommendations retain the legacy default. Recommendations remain
independent of explicit selections.
The adapter applies the displayed effort to the SDK at startup and on
model switches, preserving supported user pins and re-reading per-model
settings for automatic choices. Permission modes and clients without the
capability retain their existing configuration behavior. Model and
effort configuration logic is extracted into dedicated modules.
Terse SDK model labels are enriched with concrete versions from model
metadata: for example, `Fable` becomes `Fable 5.1`, `Sonnet` becomes
`Sonnet 5`, and `Opus (1M context)` becomes `Opus 5`. Custom names are
preserved, and collisions fall back to the original labels. An SDK
version guard requires review on upgrades, and an opt-in live
initialization test verifies the upstream model contract without sending
a prompt.
Validation:
- `npm run check`
- `npm run build`
- `env -u ANTHROPIC_BASE_URL npm run test:run` — 1253 passed, 28 skipped
- `RUN_INTEGRATION_TESTS=true npx vitest run
src/tests/model-presentation.test.ts` — 4 passed
- Regression coverage for unavailable model generations/context windows,
startup effort, per-model settings, unsupported effort pins, and
duplicate Opus labels
Today nothing reaches npm between two release-please releases, so trying
a merged
but unreleased change means building from source. This adds a
continuously
published preview channel.
Every CI-green push to `main` that is not a release merge publishes
`<package.json version, patch bumped>-preview.N` under the `preview`
dist-tag,
tags the commit `v<version>`, and dispatches the same agent registry
update a
stable release does. With `main` at 0.73.0 that gives
`0.73.1-preview.1`,
`0.73.1-preview.2`, and so on; `N` restarts at 1 whenever a release
moves the
base. `latest` is untouched.
## Approach
- **Added to `publish.yml` rather than a new workflow.** npm binds a
trusted
publisher to one repo + workflow filename, and a package gets only one.
A
separate file would fail OIDC and cost the stable path its publisher.
- **Gated on the `CI` workflow succeeding** (`workflow_run`), so a red
commit is
never published. release-please's release merge is excluded by the head
commit's author and subject — its `releases_created` output is not
reachable
from a different workflow run.
- **`N` is the max of the npm registry and local git tags.** npm
reserves
versions forever, even after `unpublish`, so a reused `N` is a hard
failure;
but the registry is CDN-served and lags, which the tags cover. A
registry read
failure aborts rather than guessing.
- **Base is patch+1, not release-please's prediction**, which moves
mid-flight
and would reset `N` under already-published previews.
- **The version is applied to the CI working tree only**, never
committed —
`package.json` and the release-please manifest stay release-please's to
own.
- **`--tag preview` is mandatory:** `npm publish` defaults to `latest`
even for a
semver prerelease.
- **Three jobs.** `publish-npm-preview` mirrors `publish-npm` and only
publishes
(no repo write access); `publish-tag-preview` only tags, so a failed tag
is
retryable with _Re-run failed jobs_ without re-publishing an immutable
version;
`trigger-registry-update` is shared with the stable path. Both
downstream jobs
gate on a `published` output the publish step sets, not on job status —
the tag
push happens after the publish, so a red job can still mean npm has the
version.
## Next step
The publish is `npm publish --dry-run` for now. The `workflow_run`
trigger and
the `release` environment's protected-branch policy mean this job cannot
run off
the default branch at all, so merging this is the only way to exercise
the
trigger, the gate and the version calculation — and with `published`
unset, the
rehearsal neither tags nor touches the registry.
Once one run looks right, a follow-up drops `--dry-run` and adds
`echo "published=true" >> "$GITHUB_OUTPUT"` to that step. Nothing else
changes.
## Summary
- resolve AIR fork points from the complete persisted transcript when
the target is outside the active parent chain
- support message fingerprints and repeated assistant content when
resolving persisted fork points
- restore resumed models from the same local assistant transcript record
Claude Code uses
- remove all automatic `getContextUsage` control requests; use
`compact_metadata.post_tokens` after compaction
- add structured timing logs for fork, load, replay, and session
creation phases
## Performance
Cold-loading the reproduced 69-message forked session dropped from 20–29
seconds to 1.9 seconds. Transcript model lookup took 5 ms and replay
took 14 ms; the remaining time was SDK initialization.
## Tests
- `env -u ANTHROPIC_BASE_URL npm run test:run` (1230 passed, 27 skipped)
- `npm run build`
- `npm run lint`
- Prettier check for all changed files
- real ACP cold-load probe against the reproduced forked session
## Summary
- recognize Claude Code local /usage output
- render subscription limits and MCP contributions as structured
Markdown with progress bars
- keep usage parsing and rendering in a dedicated module with unit
coverage
- preserve existing handling for other local commands and unknown future
usage formats
## Testing
- npm run check
- npm run build
- env -u ANTHROPIC_BASE_URL npm run test:run (1210 passed, 27 skipped)
## Summary
- surface Claude context compaction as a synthetic ACP tool lifecycle
instead of assistant text
- emit provider-neutral `_meta.contextCompaction` metadata with schema
version 1
- handle status, stream heartbeat, compact-boundary, terminal-only,
failure, and duplicate terminal event shapes
- keep the generated compaction summary internal to the agent
## Protocol
Compaction tool calls use `kind: "think"`, title `Compact conversation`,
standard ACP lifecycle statuses, and optional metadata fields `trigger`,
`preTokens`, `postTokens`, `durationMs`, and `error`.
## Testing
- `npm run test:run` (769 passed, 26 skipped)
- `npm run build`
- `npm run check`
* push renamed sessions to list subscribers and reuse one listing across pages ([#1293](https://github.com/agentclientprotocol/claude-agent-acp/issues/1293)) ([92abb8f](https://github.com/agentclientprotocol/claude-agent-acp/commit/92abb8fd4db862c465c4b3a49ea32dac0720de2c))
* add the AIR sessionIndex extension for fast session lists ([#1268](https://github.com/agentclientprotocol/claude-agent-acp/issues/1268)) ([03d84f6](https://github.com/agentclientprotocol/claude-agent-acp/commit/03d84f6663a2f561b3c59bc30e622e085b869024))
* **deps:** Bump @agentclientprotocol/sdk to 1.8.0 ([#1287](https://github.com/agentclientprotocol/claude-agent-acp/issues/1287)) ([446a721](https://github.com/agentclientprotocol/claude-agent-acp/commit/446a7217fa2654a9bcfaff9ddbfcdf2917cef024))
* Support custom instructions for agent sessions via meta ([#1177](https://github.com/agentclientprotocol/claude-agent-acp/issues/1177)) ([908c994](https://github.com/agentclientprotocol/claude-agent-acp/commit/908c994901b857918c23655670468298f6bbd33b))
### Bug Fixes
* recreate live sessions on logout when it clears a provider or gateway override ([#1278](https://github.com/agentclientprotocol/claude-agent-acp/issues/1278)) ([966be7a](https://github.com/agentclientprotocol/claude-agent-acp/commit/966be7abe60435f2f1c6379a5255ea7d533a1a20))
* report a failed turn with the error stop reason on the experimental ACP v2 surface ([#1288](https://github.com/agentclientprotocol/claude-agent-acp/issues/1288)) ([060bdb2](https://github.com/agentclientprotocol/claude-agent-acp/commit/060bdb212a9354f2dd0c88e4234a7659aeb6d27e))
* report an interrupted tool call as cancelled on the experimental ACP v2 surface ([#1289](https://github.com/agentclientprotocol/claude-agent-acp/issues/1289)) ([55c3106](https://github.com/agentclientprotocol/claude-agent-acp/commit/55c3106c60f58909af76f75df9f6c5815dcf0021))
* **deps:** Bump the minor group with 2 updates ([#1260](https://github.com/agentclientprotocol/claude-agent-acp/issues/1260)) ([0724b17](https://github.com/agentclientprotocol/claude-agent-acp/commit/0724b17c581e30b1242cfbec7bce44c21df99525))
* settle prompts folded into a task-notification cycle ([#1233](https://github.com/agentclientprotocol/claude-agent-acp/issues/1233)) ([390b0b9](https://github.com/agentclientprotocol/claude-agent-acp/commit/390b0b9f8bf0cc0aa7d9273a7b614172c916d3a6))
* answer /mcp in chat with the MCP server status and a reconnect ([#1218](https://github.com/agentclientprotocol/claude-agent-acp/issues/1218)) ([190a00f](https://github.com/agentclientprotocol/claude-agent-acp/commit/190a00f68f773315e93630464397944e645616ff))
* **deps:** Bump @anthropic-ai/claude-agent-sdk to 0.3.287 ([#1224](https://github.com/agentclientprotocol/claude-agent-acp/issues/1224)) ([ddd5f54](https://github.com/agentclientprotocol/claude-agent-acp/commit/ddd5f541879118edb18df7ff09cd6682d455c710))
### Bug Fixes
* count a subagent's permission requests as the turn waiting on the user ([#1241](https://github.com/agentclientprotocol/claude-agent-acp/issues/1241)) ([d599333](https://github.com/agentclientprotocol/claude-agent-acp/commit/d599333b722a951553c0efd40a76559b1f32e6ab))
* drop queued prompts a cancel ends from Claude Code's queue ([#1228](https://github.com/agentclientprotocol/claude-agent-acp/issues/1228)) ([d83f28a](https://github.com/agentclientprotocol/claude-agent-acp/commit/d83f28a4035c5a5e54950fd58c7b73bfc2313664))
* end a cancelled turn when the force-cancel fires during an update ([#1243](https://github.com/agentclientprotocol/claude-agent-acp/issues/1243)) ([a44c486](https://github.com/agentclientprotocol/claude-agent-acp/commit/a44c486019e98ad478c549c4902e7092f1418d0b))
* end a closed session's turns before session/close answers ([#1242](https://github.com/agentclientprotocol/claude-agent-acp/issues/1242)) ([b1d6cfc](https://github.com/agentclientprotocol/claude-agent-acp/commit/b1d6cfc6c9fc9ec397e607b68ac100f4d48745b3))
* end a held turn cancelled mid-followup at its interrupt's idle ([#1229](https://github.com/agentclientprotocol/claude-agent-acp/issues/1229)) ([d3e673b](https://github.com/agentclientprotocol/claude-agent-acp/commit/d3e673b263cf47603a35a50bb3da8b483199f690))
* excessive message/token_count API calls when probing context window ([#1258](https://github.com/agentclientprotocol/claude-agent-acp/issues/1258)) ([5598efb](https://github.com/agentclientprotocol/claude-agent-acp/commit/5598efbc8ab16720ea79f5c97db40771ad0b317b))
* replay a session with a Write on the experimental ACP v2 surface ([#1238](https://github.com/agentclientprotocol/claude-agent-acp/issues/1238)) ([22139f7](https://github.com/agentclientprotocol/claude-agent-acp/commit/22139f73c48e621752089a91fb095269493896b1))
* report a command's exit code only when the tool result says it ([#1252](https://github.com/agentclientprotocol/claude-agent-acp/issues/1252)) ([52a92be](https://github.com/agentclientprotocol/claude-agent-acp/commit/52a92be959f7f8ea90ab08d54bae6900596ab435))
* answer session/close without waiting for the interrupt reply ([#1216](https://github.com/agentclientprotocol/claude-agent-acp/issues/1216)) ([0c862e2](https://github.com/agentclientprotocol/claude-agent-acp/commit/0c862e29496bb018e7a4400697bd2315dfd5b845))
* fail turns with unfinished tools ([#1212](https://github.com/agentclientprotocol/claude-agent-acp/issues/1212)) ([7f8d547](https://github.com/agentclientprotocol/claude-agent-acp/commit/7f8d5471e24b981b129b3c9c2d6736c4ba3f8011))
* restore background task stops on replay instead of showing them as prompts ([#1205](https://github.com/agentclientprotocol/claude-agent-acp/issues/1205)) ([4ffa625](https://github.com/agentclientprotocol/claude-agent-acp/commit/4ffa625977af7e85526b9a3098f4dee5844467b4))
* **deps:** Bump @anthropic-ai/claude-agent-sdk to 0.3.286 ([#1211](https://github.com/agentclientprotocol/claude-agent-acp/issues/1211)) ([f53b0d7](https://github.com/agentclientprotocol/claude-agent-acp/commit/f53b0d7f40bcd0e9bddace85f123ff4851afcb1f))
### Bug Fixes
* Adapt to SDK 0.3.284 replay and ultracode changes ([#1208](https://github.com/agentclientprotocol/claude-agent-acp/issues/1208)) ([4af8079](https://github.com/agentclientprotocol/claude-agent-acp/commit/4af807968c7f0813bcb20fe2bcab2370320e9074))
* send the legacy custom answer key to AIR ([#1210](https://github.com/agentclientprotocol/claude-agent-acp/issues/1210)) ([af0b43d](https://github.com/agentclientprotocol/claude-agent-acp/commit/af0b43de944e36f81343f40b7aa1a96cd48c3218))
* AIR tool call contract, exact git patches, plan file, and fixes for every client ([#1153](https://github.com/agentclientprotocol/claude-agent-acp/issues/1153)) ([875d75f](https://github.com/agentclientprotocol/claude-agent-acp/commit/875d75f2a4941d9c6313ed51f89da0f42443ac2f))
### Bug Fixes
* use ACP auth errors without access updates ([#1179](https://github.com/agentclientprotocol/claude-agent-acp/issues/1179)) ([e6681d2](https://github.com/agentclientprotocol/claude-agent-acp/commit/e6681d2a5734857727352474c8c9aa848f9210ee))
* announce resumed subagent generations when they start ([#1173](https://github.com/agentclientprotocol/claude-agent-acp/issues/1173)) ([b495e55](https://github.com/agentclientprotocol/claude-agent-acp/commit/b495e55a2249f066dab76e56316080f151df99be))
* continue clear-context plans approved in a background followup ([#1170](https://github.com/agentclientprotocol/claude-agent-acp/issues/1170)) ([a2c362c](https://github.com/agentclientprotocol/claude-agent-acp/commit/a2c362c948511b203b43982f13ab068ba14741ea))
* gate login result text on error state ([#1103](https://github.com/agentclientprotocol/claude-agent-acp/issues/1103)) ([6e97e07](https://github.com/agentclientprotocol/claude-agent-acp/commit/6e97e071c581002b43d9556dbd1d1376ebf9516f))
* include model on usage updates ([#1032](https://github.com/agentclientprotocol/claude-agent-acp/issues/1032)) ([da11f1f](https://github.com/agentclientprotocol/claude-agent-acp/commit/da11f1feb269b93f13fde7470f2b5a1b070867a9))
* keep the agent starting when the managed-policy tier cannot be read ([#1146](https://github.com/agentclientprotocol/claude-agent-acp/issues/1146)) ([58c5db1](https://github.com/agentclientprotocol/claude-agent-acp/commit/58c5db1fdc1b6fbce27224523fddebd3c52a65dd))
* mark informational chunks with metadata ([#1055](https://github.com/agentclientprotocol/claude-agent-acp/issues/1055)) ([bd059c1](https://github.com/agentclientprotocol/claude-agent-acp/commit/bd059c10e042c126933f27abd33f5523f39fab72))
* offer bypass alongside auto in plan approval ([#1164](https://github.com/agentclientprotocol/claude-agent-acp/issues/1164)) ([43c27e9](https://github.com/agentclientprotocol/claude-agent-acp/commit/43c27e97aacd9b711aefcb4b84271bf872c2eea7))
* preserve context usage when quota is exhausted ([#1132](https://github.com/agentclientprotocol/claude-agent-acp/issues/1132)) ([39062b6](https://github.com/agentclientprotocol/claude-agent-acp/commit/39062b63ff3087fc7ce2655a9738450f5f61682c))
* publish effective mode after plan approval ([#1163](https://github.com/agentclientprotocol/claude-agent-acp/issues/1163)) ([a2f4239](https://github.com/agentclientprotocol/claude-agent-acp/commit/a2f4239543b22d0928fbdbef7a9c7a4854b3d61d))
* recreate resumed sessions when any session option changes ([#1097](https://github.com/agentclientprotocol/claude-agent-acp/issues/1097)) ([df38ccc](https://github.com/agentclientprotocol/claude-agent-acp/commit/df38cccae04ce4abb525447c5e8d9db78ffec61c))
* render Write tool calls that use path/file_text aliases ([#1161](https://github.com/agentclientprotocol/claude-agent-acp/issues/1161)) ([90cde4b](https://github.com/agentclientprotocol/claude-agent-acp/commit/90cde4b3974656794fbb274ac6ad8e57f701e618))
* settle steered turns on the result that answers the steer ([#1166](https://github.com/agentclientprotocol/claude-agent-acp/issues/1166)) ([9392c69](https://github.com/agentclientprotocol/claude-agent-acp/commit/9392c69cc66591ade56a08200d807577180aa682))
* **deps:** update Claude SDK ([#1157](https://github.com/agentclientprotocol/claude-agent-acp/issues/1157)) ([eb989e9](https://github.com/agentclientprotocol/claude-agent-acp/commit/eb989e93f4e20315a85405ef099f97eec899df13))
* Send experimental session notices for live advisories ([#1155](https://github.com/agentclientprotocol/claude-agent-acp/issues/1155)) ([79851b8](https://github.com/agentclientprotocol/claude-agent-acp/commit/79851b86685b8a0673dec54d85d6fa2a3b749cfb))
* Update to claude agent sdk 0.3.274 ([#1143](https://github.com/agentclientprotocol/claude-agent-acp/issues/1143)) ([d0fa8e0](https://github.com/agentclientprotocol/claude-agent-acp/commit/d0fa8e03853c4f5a9b074fc2af32931ffe6f588f))
### Bug Fixes
* show shell commands in permission prompts ([#1070](https://github.com/agentclientprotocol/claude-agent-acp/issues/1070)) ([bbae5c2](https://github.com/agentclientprotocol/claude-agent-acp/commit/bbae5c2c0936554104b07630b142fd71fe1d839e))
* Add experimental ACP compaction update support ([#1134](https://github.com/agentclientprotocol/claude-agent-acp/issues/1134)) ([543a9a2](https://github.com/agentclientprotocol/claude-agent-acp/commit/543a9a2f97429659bb28d09691a71e4c99e41ed5))
### Bug Fixes
* keep the picked option when AskUserQuestion custom text is also supplied ([#1131](https://github.com/agentclientprotocol/claude-agent-acp/issues/1131)) ([8823ea6](https://github.com/agentclientprotocol/claude-agent-acp/commit/8823ea6fcb6743d37c1aad91ccd44725164b8927))
### Performance Improvements
* report file changes from Claude checkpoints ([#1138](https://github.com/agentclientprotocol/claude-agent-acp/issues/1138)) ([91f1699](https://github.com/agentclientprotocol/claude-agent-acp/commit/91f1699366ee98f9b3e9a6b96f0662c40b6ee38e))
* supply AIR diff counts from Claude structured patches ([#1122](https://github.com/agentclientprotocol/claude-agent-acp/issues/1122)) ([735950a](https://github.com/agentclientprotocol/claude-agent-acp/commit/735950a83ee1fa25366515a3239482183a051dca))
* claudeCode.options.agent is no longer forwarded to Claude Code, and the agent-picker exports DEFAULT_AGENT_ID, AGENT_CONFIG_ID, BUILTIN_AGENT_NAMES, and discoverCustomAgents are removed. Consumers relying on main-thread agent selection must stop passing that option.
### Features
* Add tool names to tool calls ([#1128](https://github.com/agentclientprotocol/claude-agent-acp/issues/1128)) ([67c7c9b](https://github.com/agentclientprotocol/claude-agent-acp/commit/67c7c9b117af7464fd5d583f719bf6214a5508a8))
* **deps:** Bump @anthropic-ai/claude-agent-sdk to 0.3.270 ([#1123](https://github.com/agentclientprotocol/claude-agent-acp/issues/1123)) ([d3205ab](https://github.com/agentclientprotocol/claude-agent-acp/commit/d3205ab11f873f58e50dddbf13f6d7c555a9f478))
### Bug Fixes
* keep multi-select answers when a custom answer is typed ([#1031](https://github.com/agentclientprotocol/claude-agent-acp/issues/1031)) ([1a4512c](https://github.com/agentclientprotocol/claude-agent-acp/commit/1a4512c71199709f6c59bd56c2c67aba63fe243d))
* parse TaskList output without ambiguous regex ([#1006](https://github.com/agentclientprotocol/claude-agent-acp/issues/1006)) ([b274923](https://github.com/agentclientprotocol/claude-agent-acp/commit/b274923ef84a5a39b4ab3d12b3d10a8fa23f51f6))
* strip injected system reminders from replayed prompts ([#1040](https://github.com/agentclientprotocol/claude-agent-acp/issues/1040)) ([15ba608](https://github.com/agentclientprotocol/claude-agent-acp/commit/15ba608a79b2cdfdb94c04ce1ebe03cfdae2fb51))
* **deps-dev:** Bump vitest from 4.1.11 to 5.0.0 ([#1099](https://github.com/agentclientprotocol/claude-agent-acp/issues/1099)) ([194e195](https://github.com/agentclientprotocol/claude-agent-acp/commit/194e195b057497311558fea2a5fbd1b4953ea29d))
* **deps:** Bump fast-uri from 3.1.6 to 3.1.7 ([#1100](https://github.com/agentclientprotocol/claude-agent-acp/issues/1100)) ([d870ebd](https://github.com/agentclientprotocol/claude-agent-acp/commit/d870ebd2fd14bda95f81ec4b86d76ef4ae258005))
* restore session forks and speed up loading ([#1089](https://github.com/agentclientprotocol/claude-agent-acp/issues/1089)) ([f5e79f5](https://github.com/agentclientprotocol/claude-agent-acp/commit/f5e79f55f8ba8d1cd0a72cbc78bfea726bea2f00))
-Session-scoped long-running goals through the provider-neutral [goal extension](docs/goal-extension.md)
- Structured errors, recovery, and warnings through the opt-in [session failure extension](docs/session-failure-extension.md)
-Tool permission presentation, editable choices, and durable effects through the [permission extension](docs/permission-extension.md)
-`/mcp` in the chat: the MCP server status as a list. The adapter runs `/mcp reconnect`, `/mcp enable`, and `/mcp disable` through 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](docs/air-extensions.md#goal) under `_meta.jetbrains.air.goal`
-Structured errors, recovery, and warnings through the opt-in [session failure extension](docs/air-extensions.md#session-failure)
- Concrete model and effort defaults through the opt-in [recommended config value extension](docs/air-extensions.md#recommended-config-values)
- Tool permission presentation, editable choices, and durable effects through the [permission extension](docs/air-extensions.md#permission-presentation)
- One fact per field in every tool call report, as the [ACP tool call contract](docs/air-extensions.md#tool-call-contract) defines
- All AIR extensions, capabilities, and `_meta` keys: [AIR extensions](docs/air-extensions.md)
Learn more about the [Agent Client Protocol](https://agentclientprotocol.com/).
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
Subagents are exposed only after bilateral capability negotiation. Until the released ACP SDKs
preserve the draft `clientCapabilities.subagents` field, a supporting client may advertise
`nativeSubagentSessions` in `_meta.jetbrains.air.capabilities`; the adapter mirrors the capability
in its initialize response. The canonical field remains supported and takes precedence once it is
available. Without either client signal, Agent/Task lifecycle keeps its legacy ordinary ACP
tool-call representation and child interactions stay on the root session. Clients that use the
historical `_meta["subagent-transcript"]` capability or `forwardSubagentText` session option retain
the flattened child transcript behavior.
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](https://github.com/agentclientprotocol/agent-client-protocol/blob/main/docs/rfds/subagents.mdx):
-`subagent_update` on the parent announces the child before any of its traffic, with the
parent's `title` and `description` for it, and reports its work state: `running`,
`requires_action` while one of its requests is open, and `idle` when its work ends, with
`end_turn` or `cancelled` when the SDK gives the reason. A failure is `idle` with the `error`
stop reason and the SDK's error text as its `error`. The child keeps its session for every
delegation to it.
- The prompt of the Agent or Task call that launches the child, and the message of each
SendMessage call that resumes it, is a `session_message` in the child's transcript. The tool
call stays a tool call of the session that made it.
-`session/cancel` on the parent interrupts Claude Code, which stops the foreground children that
the turn waits on and, currently, background children too. Each stopped child reports `idle`
with `cancelled` from Claude Code's own events, and the open requests of the foreground ones are
withdrawn. The adapter ends no child at a cancel itself, so a child that keeps running keeps its
open requests. A child that still runs when Claude Code exits is `idle` with 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 client cannot prompt, cancel, or otherwise change a child yet, and a replay does not restore
children yet.
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
This document defines a provider-neutral experimental ACP extension implemented by `claude-agent-acp`. It is intentionally shaped like a possible future first-class ACP API: implementations publish `_meta.goal`, not provider-specific metadata such as `_meta.claudeCode.goal`.
## Capability negotiation
An agent advertises support in its `initialize` response:
```json
{
"_meta":{
"goal":{
"version":1,
"controlMethod":"_session/goal",
"actions":["clear"]
}
}
}
```
`actions` is the implementation-supported subset of `set`, `pause`, `resume`, and `clear`. Clients must not infer support for an action that is not advertised. The control request contains `sessionId` and `action`; a future version may add action-specific fields such as an objective for `set`.
## Session state
The current snapshot is published in `session_info_update._meta.goal`. Clearing a goal publishes `goal: null`.
```json
{
"objective":"Ship the change",
"status":"active",
"iterations":3,
"lastReason":"Tests still need work",
"createdAt":1710000000123,
"controlMethod":"_session/goal"
}
```
Common statuses are `active`, `paused`, `blocked`, `limited`, and `complete`. Optional fields allow implementations to report budgets, usage, iteration count, and the last continuation reason. Timestamps are Unix milliseconds.
## Lifecycle architecture
A goal belongs to the ACP session, not to an individual `session/prompt` request. Goal activity and prompt activity are independent:
-`status: active` means the persistent objective can drive more work; it does not mean an ACP prompt is currently executing.
- A prompt completes when its current backend turn reaches a quiescent boundary, even when the goal remains active.
- A later autonomous cycle may publish more session updates outside that completed prompt.
- While a turn is running, clients use steering or prompt queueing when advertised. While the session is quiescent, clients may send an ordinary `session/prompt`.
This separation prevents a persistent goal from monopolizing the session's prompt slot and lets clients model “working now” independently from “objective remains active.”
## Claude mapping
Claude's session-scoped `/goal` command installs a Stop hook. The runtime emits internal `active_goal` messages when that hook updates or clears its state; the adapter maps them into the neutral snapshot before the exhaustive SDK message switch. `condition`, `iterations`, `set_at`, and `last_reason` become `objective`, `iterations`, `createdAt`, and `lastReason`. Provider-only bookkeeping such as `tokens_at_start` is not exposed.
Some Claude runtime versions persist the goal and begin the Stop-hook workflow without emitting the initial `active_goal` message on the SDK stream. To avoid leaving clients without visible state for the whole long-running prompt, the adapter publishes a minimal active snapshot as soon as it submits `/goal <condition>`, and publishes `goal: null` for `/goal clear`. While that command is pending, late updates for the previous goal are ignored. A matching runtime `active_goal` remains authoritative and enriches the optimistic snapshot with iteration, reason, and timestamp fields; a failed command restores the previously published state.
`set` and `clear` are advertised for out-of-band control; pause and resume are not. When a goal turn is running, the adapter injects the corresponding `/goal` command at steering priority `now` so it cannot remain queued behind the Stop-hook workflow; on an idle session it uses the ordinary prompt lifecycle. Cancelling a turn does not clear the session-scoped goal: clients use the goal control method when they intend to replace or remove it.
When an ACP caller provides`settings` via `_meta.claudeCode.options.settings` in the `sessions/create` request, `CLAUDE_MODEL_CONFIG` is ignored entirely. The env var is a deployment-level fallback for cases where the caller does not configure model settings itself.
An ACP caller can provide `settings` via `_meta.claudeCode.options.settings` in `session/new` or `session/load`, as an object or a path to a settings file. The adapter merges `CLAUDE_MODEL_CONFIG` into those settings, so a caller that only adds hooks keeps the model settings. When both set the same key, the caller wins; the merge is shallow, so a caller's `modelOverrides` replaces the env var's map.
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"claudeCode":{"toolName":"AskUserQuestion"}},"content":[],"kind":"other","name":"AskUserQuestion","sessionUpdate":"tool_call","status":"pending","title":"Asking for your input","toolCallId":"toolu_ask"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"rawInput":{"questions":[{"header":"Database","multiSelect":false,"options":[{"description":"Relational","label":"Postgres","preview":"CREATE TABLE t ();"},{"description":"Key-value","label":"Redis"}],"question":"Which database?"}]},"sessionUpdate":"tool_call_update","toolCallId":"toolu_ask"}}}
{"kind":"createElicitation","payload":{"message":"Which database?","mode":"form","requestedSchema":{"properties":{"question_0":{"oneOf":[{"_meta":{"_claude/askUserQuestionOption":{"preview":"CREATE TABLE t ();"}},"const":"Postgres","description":"Relational","title":"Postgres"},{"const":"Redis","description":"Key-value","title":"Redis"}],"title":"Database","type":"string"},"question_0_custom":{"_meta":{"_askUserQuestionCustomAnswer":{"isCustomAnswer":true,"questionId":"question_0"},"jetbrains":{"air":{"customAnswer":{"isCustomAnswer":true,"questionId":"question_0"},"version":1}}},"description":"Type your own answer, or add a note to the option you chose above (optional).","title":"Other","type":"string"}},"type":"object"},"sessionId":"<session>","toolCallId":"toolu_ask"}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"content":[{"content":{"text":"User has answered your questions: \"Which database?\"=\"Postgres\".","type":"text"},"type":"content"}],"sessionUpdate":"tool_call_update","status":"completed","toolCallId":"toolu_ask"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"asyncTaskId":"workflow_3","canStop":true,"description":"Watch the logs","name":"Watch the logs","sessionUpdate":"async_task_spawned","showInTranscript":true,"taskType":"workflow","toolCallId":"toolu_workflow"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"jetbrains":{"air":{"asyncTasks":{"backgrounded":true}}},"terminal_output_delta":{"data":"Command running in background with ID: bash_1. Output is being written to: /tmp/tasks/bash_1.output. You will be notified when it completes.","terminal_id":"toolu_bg"}},"sessionUpdate":"tool_call_update","toolCallId":"toolu_bg"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"jetbrains":{"air":{"contextCompaction":{"error":"Context too small","version":1}}}},"content":[{"content":{"text":"Compaction failed: Context too small","type":"text"},"type":"content"}],"sessionUpdate":"tool_call_update","status":"failed","toolCallId":"00000000-0000-4000-8000-000000000001"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"requestPermission","payload":{"_meta":{"jetbrains":{"air":{"permission":{"title":"Edit src/app.ts","version":1},"version":1}}},"options":[{"kind":"allow_once","name":"Yes","optionId":"allow-once"},{"kind":"reject_once","name":"No","optionId":"reject"}],"sessionId":"<session>","toolCall":{"content":[{"_meta":{"jetbrains":{"air":{"diffPatch":{"format":"git_patch","text":"diff --git a<cwd>/src/app.ts b<cwd>/src/app.ts\n--- a<cwd>/src/app.ts\n+++ b<cwd>/src/app.ts\n@@ -1 +1 @@\n-const value = 1;\n+const value = 2;\n","version":1},"version":1}}},"newText":"","oldText":null,"path":"<cwd>/src/app.ts","type":"diff"}],"rawInput":{"file_path":"<cwd>/src/app.ts"},"title":"Edit src/app.ts","toolCallId":"toolu_edit"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"content":[{"content":{"text":"```\nThe user doesn't want to proceed with this tool use. The tool use was rejected.\n```","type":"text"},"type":"content"}],"sessionUpdate":"tool_call_update","status":"failed","toolCallId":"toolu_edit"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"content":[{"newText":"const value = 2;","oldText":"const value = 1;","path":"<cwd>/src/app.ts","type":"diff"}],"rawInput":{"file_path":"<cwd>/src/app.ts"},"sessionUpdate":"tool_call_update","toolCallId":"toolu_edit"}}}
{"kind":"requestPermission","payload":{"_meta":{"jetbrains":{"air":{"permission":{"title":"Edit src/app.ts","version":1},"version":1}}},"options":[{"kind":"allow_once","name":"Yes","optionId":"allow-once"},{"kind":"reject_once","name":"No","optionId":"reject"}],"sessionId":"<session>","toolCall":{"content":[{"_meta":{"jetbrains":{"air":{"diffPatch":{"format":"git_patch","text":"diff --git a<cwd>/src/app.ts b<cwd>/src/app.ts\n--- a<cwd>/src/app.ts\n+++ b<cwd>/src/app.ts\n@@ -1,3 +1,3 @@\n line 1\n-const value = 1;\n+const value = 2;\n line 3\n","version":1},"version":1}}},"newText":"","oldText":null,"path":"<cwd>/src/app.ts","type":"diff"}],"rawInput":{"file_path":"<cwd>/src/app.ts"},"title":"Edit src/app.ts","toolCallId":"toolu_edit"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"rawOutput":"The file <cwd>/src/app.ts has been updated successfully.","sessionUpdate":"tool_call_update","status":"completed","toolCallId":"toolu_edit"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"content":[{"newText":"line 1\nconst value = 2;\nline 3","oldText":"line 1\nconst value = 1;\nline 3","path":"<cwd>/src/app.ts","type":"diff"}],"locations":[{"line":1,"path":"<cwd>/src/app.ts"}],"sessionUpdate":"tool_call_update","toolCallId":"toolu_edit"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"rawInput":{"plan":"# Plan\n1. Do it"},"sessionUpdate":"tool_call_update","toolCallId":"toolu_plan"}}}
{"kind":"requestPermission","payload":{"_meta":{"jetbrains":{"air":{"permission":{"title":"Ready to code?","version":1},"version":1}}},"options":[{"kind":"allow_once","name":"Yes, manually approve edits","optionId":"exit-plan-default"},{"kind":"allow_always","name":"Yes, clear context (0% used) and use auto mode","optionId":"exit-plan-clear-auto"},{"kind":"allow_always","name":"Yes, and use auto mode","optionId":"exit-plan-auto"},{"kind":"allow_always","name":"Yes, and bypass permissions","optionId":"exit-plan-bypass"},{"kind":"reject_once","name":"No, keep planning","optionId":"reject"}],"sessionId":"<session>","toolCall":{"rawInput":{"plan":"# Plan\n1. Do it"},"title":"Approve Plan","toolCallId":"toolu_plan"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"configOptions":[{"category":"mode","currentValue":"default","description":"Session permission mode","id":"mode","name":"Mode","options":[{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Always ask before making changes","name":"Manual","value":"default"},{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"_meta":{"jetbrains":{"air":{"kind":"plan","version":1}}},"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"_meta":{"jetbrains":{"air":{"kind":"auto_review","version":1}}},"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"_meta":{"jetbrains":{"air":{"kind":"full_access","version":1}}},"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","id":"model","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionUpdate":"config_option_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"sessionUpdate":"tool_call_update","status":"completed","title":"Exited Plan Mode","toolCallId":"toolu_plan"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"rawInput":{"plan":"# Plan\n1. Do it"},"sessionUpdate":"tool_call_update","toolCallId":"toolu_plan"}}}
{"kind":"requestPermission","payload":{"_meta":{"jetbrains":{"air":{"permission":{"title":"Ready to code?","version":1},"version":1}}},"options":[{"kind":"allow_once","name":"Yes, manually approve edits","optionId":"exit-plan-default"},{"kind":"allow_always","name":"Yes, clear context (0% used) and use auto mode","optionId":"exit-plan-clear-auto"},{"kind":"allow_always","name":"Yes, and use auto mode","optionId":"exit-plan-auto"},{"kind":"allow_always","name":"Yes, and bypass permissions","optionId":"exit-plan-bypass"},{"kind":"reject_once","name":"No, keep planning","optionId":"reject"}],"sessionId":"<session>","toolCall":{"rawInput":{"plan":"# Plan\n1. Do it"},"title":"Approve Plan","toolCallId":"toolu_plan"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"rawOutput":"The user doesn't want to proceed with this tool use.","sessionUpdate":"tool_call_update","status":"failed","toolCallId":"toolu_plan"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"jetbrains":{"air":{"goal":{"controlMethod":"_session/goal","objective":"Ship the feature","status":"active"},"version":1}}},"sessionUpdate":"session_info_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"locations":[{"path":"<cwd>/n.ipynb"}],"sessionUpdate":"tool_call_update","title":"Edit cell in n.ipynb","toolCallId":"toolu_nb"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"sessionUpdate":"tool_call_update","title":"Edit cell cell-1 in n.ipynb","toolCallId":"toolu_nb"}}}
{"kind":"requestPermission","payload":{"_meta":{"jetbrains":{"air":{"permission":{"title":"Edit cell cell-1 in n.ipynb","version":1},"version":1}}},"options":[{"kind":"allow_once","name":"Yes","optionId":"allow-once"},{"kind":"reject_once","name":"No","optionId":"reject"}],"sessionId":"<session>","toolCall":{"rawInput":{"cell_id":"cell-1","edit_mode":"replace","new_source":"print('hi')","notebook_path":"<cwd>/n.ipynb"},"title":"Edit cell cell-1 in n.ipynb","toolCallId":"toolu_nb"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"claudeCode":{"toolResponse":{"decisionReasonType":"rule","message":"Permission to use Bash has been denied."}}},"content":[{"content":{"text":"Permission denied: Denied by rule Bash(rm:*)","type":"text"},"type":"content"}],"sessionUpdate":"tool_call_update","status":"failed","toolCallId":"toolu_denied"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"terminal_output_delta":{"data":"Permission to use Bash has been denied.","terminal_id":"toolu_denied"}},"sessionUpdate":"tool_call_update","toolCallId":"toolu_denied"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"content":{"text":"Fix the bug","type":"text"},"messageId":"00000000-0000-4000-8000-00000000c001","sessionUpdate":"user_message_chunk"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"content":{"text":"Check the file.","type":"text"},"messageId":"msg_r1","sessionUpdate":"agent_thought_chunk"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"content":{"text":"I will edit it.","type":"text"},"messageId":"msg_r1","sessionUpdate":"agent_message_chunk"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"rawOutput":"The file <cwd>/src/app.ts has been updated successfully.","sessionUpdate":"tool_call_update","status":"completed","toolCallId":"toolu_r_edit"}}}
{"kind":"loadSession","payload":{"configOptions":[{"category":"mode","currentValue":"default","description":"Session permission mode","id":"mode","name":"Mode","options":[{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Always ask before making changes","name":"Manual","value":"default"},{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"_meta":{"jetbrains":{"air":{"kind":"plan","version":1}}},"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"_meta":{"jetbrains":{"air":{"kind":"auto_review","version":1}}},"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"_meta":{"jetbrains":{"air":{"kind":"full_access","version":1}}},"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","id":"model","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"modes":{"availableModes":[{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Always ask before making changes","id":"default","name":"Manual"},{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Automatically accept all file edits","id":"acceptEdits","name":"Accept edits"},{"_meta":{"jetbrains":{"air":{"kind":"plan","version":1}}},"description":"Create a plan before making changes","id":"plan","name":"Plan"},{"_meta":{"jetbrains":{"air":{"kind":"auto_review","version":1}}},"description":"Claude handles permission decisions","id":"auto","name":"Auto"},{"_meta":{"jetbrains":{"air":{"kind":"full_access","version":1}}},"description":"Accepts all permissions","id":"bypassPermissions","name":"Bypass permissions"}],"currentModeId":"default"},"sessionId":"<session>"}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"newSession","payload":{"configOptions":[{"category":"mode","currentValue":"default","description":"Session permission mode","id":"mode","name":"Mode","options":[{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Always ask before making changes","name":"Manual","value":"default"},{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"_meta":{"jetbrains":{"air":{"kind":"plan","version":1}}},"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"_meta":{"jetbrains":{"air":{"kind":"auto_review","version":1}}},"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"_meta":{"jetbrains":{"air":{"kind":"full_access","version":1}}},"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","id":"model","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"modes":{"availableModes":[{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Always ask before making changes","id":"default","name":"Manual"},{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Automatically accept all file edits","id":"acceptEdits","name":"Accept edits"},{"_meta":{"jetbrains":{"air":{"kind":"plan","version":1}}},"description":"Create a plan before making changes","id":"plan","name":"Plan"},{"_meta":{"jetbrains":{"air":{"kind":"auto_review","version":1}}},"description":"Claude handles permission decisions","id":"auto","name":"Auto"},{"_meta":{"jetbrains":{"air":{"kind":"full_access","version":1}}},"description":"Accepts all permissions","id":"bypassPermissions","name":"Bypass permissions"}],"currentModeId":"default"},"sessionId":"<session>"}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"capabilities":{},"name":"Background review","prompt":"Review the diff","sessionUpdate":"subagent_spawned","subagentSessionId":"a2","task":"Review the diff"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"capabilities":{},"name":"Check the logs","prompt":"Check logs","sessionUpdate":"subagent_spawned","subagentSessionId":"agent_late","task":"Check logs"}}}
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
