## Problem
When the API refuses a turn, the SDK retries on the fallback model and
makes the swap persistent for the session. We flag that with a
transcript line:
```ts
text: `**Model fallback:** ${message.original_model} declined this request${category}; retried with ${message.fallback_model}. ${outcome}${explanation}`,
```
It goes out as an `agent_message_chunk`, so the client cannot tell a
session-level advisory from something the model actually said — the bold
label is the only severity signal available, and it is just characters
inside the assistant's own text.
The comment above that code already states the stakes: *"Without a
notice the user just sees regenerated output."* The notice matters; the
channel it uses does not fit it.
## Change
Routes it through the AIR typed session-failure extension instead, as a
new `advisory` category:
- `severity?: "error" | "warning"` on the record. **Optional, and absent
means `error`**, so a client that predates this keeps treating every
record it receives as a failure.
- The advisory carries its own wording (`safeMessage`) rather than the
canned per-category message, so the client renders the explanation
verbatim in a warning banner.
- **Clients that did not negotiate the `sessionFailure` capability keep
the exact transcript line they get today.**
### Advisories are not turn failures
Two existing behaviours would have mangled them, so both are now
guarded:
- `createSessionFailure` clears every other active record when a new one
is published. An advisory no longer does that, and is no longer cleared
by one — otherwise a model-fallback notice would erase an actionable
error, or vice versa.
- `clearFailuresFromEarlierTurns` clears everything whose `turnId` is
not the active turn. Advisories carry no `turnId`, so without the guard
every turn boundary would sweep them away.
They therefore live under their own `:notice:` id namespace,
session-scoped, one slot, newest wins.
## Scoped out
`**Fast mode turned off:**` (`syncFastMode…`) is the same pattern and
deserves the same treatment, but it sits in a class method while the
failure machinery is closure-scoped inside `prompt()`. Lifting that out
is a separate change rather than something to smuggle into this one.
## Tests
`npm run build`, `npm run check`, and `npm run test:run` (**766
passed**) are clean.
The existing `model_refusal_fallback` tests still assert the `**Model
fallback:**` transcript line and still pass — they never call
`initialize`, so they exercise the no-capability path, which is exactly
the backward-compatibility guarantee.
One test added for the typed path, asserting that the advisory is
published with `severity: "warning"`, that its `safeMessage` carries the
real model ids and refusal category, that it uses the `:notice:` id
namespace, that it contains no `**` markdown lead-in, and that the
transcript line is **not** also emitted.
Client side: IJAI-993.
## Summary
- Add `skill?: string` to `ToolUpdateMeta.claudeCode`, populated from
`toolUse.input.skill` in `claudeCodeMetaFromToolUse`. Lets ACP clients
detect skill invocations from structured metadata rather than parsing
the title string.
- Add `case "Skill":` to `toolInfoFromToolUse`: sets `title` to `"Load
skill: <name>"` and returns empty content — readable fallback for
clients that don't read `_meta`.
- Add `case "Skill":` to `toolUpdateFromToolResult`: returns `{}` to
suppress the raw `"Launching skill: <name>"` result text, matching the
pattern used for `Edit`/`Write`.
## Motivation
Without this, the Skill tool falls through to the `default` case and
renders as a generic `kind: "other"` block with title `"Skill"` and an
expand control showing the raw result text. With this change, clients
that read `_meta.claudeCode.skill` can render the block with the
appropriate icon, the skill name, and no expand control.
## Test plan
- [ ] Invoke a skill (e.g. `/commits`) and confirm
`_meta.claudeCode.skill` is present in the emitted `tool_call` update
- [ ] Confirm title is `"Load skill: commits"` in the ACP event stream
- [ ] Confirm no content is emitted for the skill tool result
## Summary
- When the SDK's `"default"` model entry carries a `resolvedModel` (e.g.
`"claude-sonnet-5"`), `buildConfigOptions` now sets the option's
`description` to the human-readable `displayName` of the matching named
model (e.g. `"Claude Sonnet 5"`)
- Falls back to the raw `resolvedModel` string if no named entry shares
that resolved ID
- No behaviour change when `resolvedModel` is absent
This lets ACP clients show the actual model behind "Default" — e.g.
"Default (Claude Sonnet 5)" — instead of just "Default (recommended)".
## Test plan
- [ ] `buildConfigOptions model option resolved description > sets
description to the named model's displayName when resolvedModel matches`
- [ ] `buildConfigOptions model option resolved description > falls back
to resolvedModel itself when no named model shares it`
- [ ] `buildConfigOptions model option resolved description > leaves
description undefined when default model has no resolvedModel`
- [ ] All 753 existing tests still pass
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
## Summary
- Negotiate the JetBrains AIR `sessionFailure` extension when the client
advertises an integer version `>= 1` and the capability name.
- Return turn-terminal failures only on `PromptResponse._meta`; publish
idle and asynchronous session health failures through `session/update`.
- Preserve legacy ACP behavior for clients that do not negotiate the
extension.
- Emit bounded fixed safe messages without SDK/provider details, paths,
credentials, or stack traces.
## Recovery contract
Failures use `_meta.jetbrains.air.sessionFailure` with a stable id,
monotonic revision, phase, category, source, safe message, retryability,
and optional real turn attribution. Session-scoped ids include a
consumer epoch, so replayed tombstones from a dead consumer cannot
suppress failures after restart. Stale consumers cannot publish into a
replacement session.
AIR owns localized action presentation. Claude supplies typed category
and retryability facts. Billing maps to quota exhaustion, max-output
limits map to context exhaustion, and the irreversibly closed Claude
Query reports non-retryable `transport_lost` so AIR offers New Session.
A held-open turn keeps its already recorded successful `PromptResponse`,
while worker shutdown or transport death also emits a separate
session-scoped health failure without `turnId`; the next prompt is
proven to fail because the Query is closed. Worker-shutdown remains
armed through buffered trailing frames and is classified only when EOF
proves the live tail.
## Validation
- 750 passed, 25 skipped.
- Build passed.
- ESLint passed.
- Changed files pass Prettier; the repository-wide check is blocked only
by an unrelated untracked local proposal file.
- Tests cover negotiation, taxonomy, sanitization, terminal/asynchronous
carrier separation, stale consumers, worker replay/live-tail behavior,
held turns, process/transport failure, restart-safe ids, clear
revisions, and capability-off behavior.
## Summary
- show `Preparing file…` instead of the bare `Write` title while
streamed input has no `file_path`
- refine the same tool call to `Write <display path>` as soon as the
path is available
- cover both partial-field refinement and
complete-input/consolidated-message delivery
## Tests
- `npm run lint`
- `npx prettier --check src/tools.ts src/tests/acp-agent.test.ts`
- `npm run build`
- `npm run test:run` — 716 passed, 25 skipped
YouTrack: https://youtrack.jetbrains.com/issue/IJAI-841
## Summary
- republish unfinished Task* plan snapshots when a follow-up prompt
starts
- avoid resurfacing fully completed historical plans on unrelated
prompts
- clear stale task state when Claude starts a fresh conversation
- reconcile task state from authoritative TaskList results after resume
or history compaction
- consume structured Task* outputs during live sessions and parse Claude
Code textual output when replaying history
- reject logically failed TaskUpdate results instead of persisting the
requested mutation
- keep scanning structured tool output past unrelated JSON blocks
- use Claude activeForm for in-progress TodoWrite and Task* entries
This keeps ACP clients from losing an unfinished task list at prompt
boundaries, restores state when incremental history is unavailable, and
prevents plans from leaking across conversation resets.
## Tests
- npm run test:run (713 passed, 20 skipped)
- npm run check
- npm run build
- git diff --check
## Summary
- publish optimistic provider-neutral goal snapshots for submitted and
steered goal commands
- advertise and implement `set`, using steering for an active turn and
an ordinary prompt while idle
- suppress stale old-goal runtime updates while replacement/clear is
pending and roll back failed commands
- keep cancellation turn-scoped and orphan-account pending steers so
stale results cannot settle the next prompt
- reject unsupported pause/resume controls without host-side fallbacks
## Validation
- `npm test -- --run` (702 passed, 20 skipped)
- `npm run check`
- `npm run build`
- regression coverage for idle/active set and clear, stale runtime
updates, command failure rollback, cancellation, and stale steer
isolation
## Summary
- advertise a provider-neutral goal extension in
`InitializeResponse._meta.goal`
- map Claude SDK `active_goal` messages to
`session_info_update._meta.goal`
- expose the shared `_session/goal` control method with the truthfully
supported `clear` action
- document the extension as a candidate shape for a future first-class
ACP goal API
## Architecture
A goal is persistent **session state**, not the lifecycle of one
`session/prompt` request. `goal.status === "active"` says that the
objective may drive more work; it does not say that a prompt is
executing now.
This keeps two independent axes:
1. **Goal state** is published asynchronously as session metadata and
may survive multiple prompt turns.
2. **Prompt activity** follows the backend's actual running/quiescent
boundaries. While a turn runs, clients use advertised steering or prompt
queueing. Once the backend is quiescent, an ordinary `session/prompt` is
valid even if the goal remains active.
The metadata is deliberately provider-neutral:
```json
{
"_meta": {
"goal": {
"version": 1,
"controlMethod": "_session/goal",
"actions": ["clear"]
}
}
}
```
State is emitted as `session_info_update._meta.goal`; `null` clears it.
The common snapshot vocabulary supports `objective`, common statuses,
timestamps in Unix milliseconds, budgets/usage, iteration count, and a
continuation reason. Each implementation emits only fields it actually
knows. This shape is intentionally close to a future typed ACP
capability/update so promotion out of `_meta` would not require a
provider-specific migration.
Control actions are capability-negotiated. The shared vocabulary
reserves `set`, `pause`, `resume`, and `clear`, but an agent advertises
only the subset it can implement with correct semantics.
## Claude mapping
The Claude runtime already emits internal `active_goal` messages,
although that message is not currently included in the public
`SDKMessage` union. The adapter handles it before the exhaustive switch:
- `condition` → `objective`
- `iterations` → `iterations`
- `set_at` → `createdAt`
- `last_reason` → `lastReason`
- `value: null` → `goal: null`
Provider bookkeeping such as `tokens_at_start` is intentionally not
exposed. Goal updates do not settle, extend, or otherwise mutate ACP
prompt lifecycle. Claude's existing Stop hook remains authoritative for
whether the backend itself continues working.
Only `clear` is advertised for out-of-band control. It submits `/goal
clear` through the existing session prompt queue, preserving the
adapter's established ordering and turn ownership. Setting a goal
remains available through `/goal <condition>` but is not advertised as a
control action because it starts the long-running Stop-hook workflow.
The companion Codex implementation is agentclientprotocol/codex-acp#371.
## Verification
- `npm run test:run` — 692 passed, 20 skipped
- `npm run build`
- `npm run check`
Bumps the minor group with 1 update:
[globals](https://github.com/sindresorhus/globals).
Updates `globals` from 17.8.0 to 17.9.0
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/sindresorhus/globals/releases">globals's
releases</a>.</em></p>
<blockquote>
<h2>v17.9.0</h2>
<ul>
<li>Update globals (2026-08-01) (<a
href="https://redirect.github.com/sindresorhus/globals/issues/348">#348</a>)
5a958ed</li>
</ul>
<hr />
<p><a
href="https://github.com/sindresorhus/globals/compare/v17.8.0...v17.9.0">https://github.com/sindresorhus/globals/compare/v17.8.0...v17.9.0</a></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="8e7b9358b1"><code>8e7b935</code></a>
17.9.0</li>
<li><a
href="5a958ed060"><code>5a958ed</code></a>
Update globals (2026-08-01) (<a
href="https://redirect.github.com/sindresorhus/globals/issues/348">#348</a>)</li>
<li>See full diff in <a
href="https://github.com/sindresorhus/globals/compare/v17.8.0...v17.9.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 <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>
Steering is delivered at priority `now`, which makes the CLI **abort**
the running cycle instead of folding the message into it. The aborted
cycle ends with an ordinary human-origin `result`, so we answered
`session/prompt` with `end_turn` while the steered work was still going
— its remaining tool calls, its answer, and its file edits then streamed
with no turn in flight.
A steered turn's results now only record their outcome, and the turn
settles at the SDK's `idle` — the only signal spanning both the
interrupted and the steered cycle. The injected message's replay tells
them apart: an idle arriving before it means the steered cycle hasn't
started, so it is swallowed. `session/cancel` and the next prompt still
settle the turn early, with the recorded stop reason.
Four steering tests cover the interrupt, an early idle, the next-prompt
hand-off, and cancel.
Bumps [nanoid](https://github.com/ai/nanoid) from 3.3.16 to 3.3.17.
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/ai/nanoid/releases">nanoid's
releases</a>.</em></p>
<blockquote>
<h2>3.3.17</h2>
<ul>
<li>Fixed infinite loop on zero size.</li>
</ul>
</blockquote>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/ai/nanoid/blob/main/CHANGELOG.md">nanoid's
changelog</a>.</em></p>
<blockquote>
<h2>3.3.17</h2>
<ul>
<li>Fixed infinite loop on zero size.</li>
</ul>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="73d6716813"><code>73d6716</code></a>
Release 3.3.17 version</li>
<li><a
href="f9d13f1508"><code>f9d13f1</code></a>
Sync 0 size behaviour with PostCSS 5</li>
<li>See full diff in <a
href="https://github.com/ai/nanoid/compare/3.3.16...3.3.17">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>
## Description
Testing this agent means wiring it into an editor's ACP integration,
which is an overkill when you just want to watch the JSON and reply with
JSON. This adds a second example next to `examples/steering.ts`: a
minimal interactive ACP client that spawns the built agent, prints every
JSON-RPC message in both directions, and turns what you type into
prompts.
```
npm run build
npm run example:simple-client
```
All four ways a client can get a message to this agent are reachable
from the prompt"
| Input | Wire |
| --- | --- |
| `<text>` | `session/prompt`; buffered client-side if a turn is running
|
| `!steer <text>` | `_session/steering`, injected into the running turn
|
| `!queue <text>` | `session/prompt` sent mid-turn, so the agent queues
it |
| `!cancel`, Ctrl-C | `session/cancel` |
## Additional options
* `--debug-port=<port>` rebuilds with source maps and starts the agent
under
* `--inspect-brk`, paused, so a debugger can attach and step through
`src/*.ts` —
replacing a hand-written editor run configuration. Teardown cancels any
live
turn, closes the agent's stdin (its clean-exit path), waits, and only
then
closes the connection, so neither side dies of EPIPE and nothing is
orphaned.
npm may accept a package before the registry update stage can run, and
repeating the workflow would attempt to republish the same immutable
version.
Add an opt-out for npm publishing on manual dispatch so the repository
GitHub App can safely retry only the registry update. The default
remains `true`, preserving the normal manual release path.
Validation: Prettier workflow check.
A skipped `release-please` job propagates to downstream jobs during a
manual release, even when npm publishing succeeds through an `always()`
condition.
Explicitly evaluate the npm job result so successful manual publications
continue to update the agent registry.
Validation: Prettier workflow check.
Release-please cannot process the already-merged, untagged release PR
#943.
This adds an explicit workflow dispatch path for publishing a supplied
tag or commit while preserving the normal push-driven release flow, and
restores the 0.64.2 release metadata for the recovery tag.
After merge, I will create `v0.64.2` at this commit and dispatch the
publish workflow for that tag.
Validation:
- ESLint
- Prettier
- TypeScript build
- Vitest: 684 passed, 20 skipped
## Summary
- revert the ExitPlanMode plan_update integration from #938
- restore the previous single switch_mode tool-call representation
- keep plan Markdown and approval state on the same transcript item
## Why
Clients currently receive both a plan_update and the separate tool call
required by requestPermission. Without a protocol-level link between
those entries, clients can render the same final plan twice. Returning
to the legacy representation avoids the duplicate while preserving the
existing approval flow.
## Testing
- pnpm exec vitest run src/tests/tools.test.ts
src/tests/acp-agent.test.ts src/tests/session-config-options.test.ts
(482 passed, 9 skipped)
- pnpm run build
- pnpm run lint
- pnpm run format:check
## Summary
- publish `ExitPlanMode` Markdown through experimental ACP `plan_update`
when the client advertises `clientCapabilities.plan`
- keep `requestPermission` as the confirmation mechanism and retain
`rawInput.plan` on the `switch_mode` tool call
- fall back to the existing tool-call content for clients without plan
support
- serialize live plan publication through the permission path so
`plan_update` and the referenced `tool_call` are delivered before
`requestPermission`
- use stable per-scope plan IDs so main-agent and subagent plans cannot
overwrite each other
- replay capable-client plans through `plan_update` without duplicating
Markdown in tool content
## Testing
- permission-first and stream-first event ordering
- approve, reject, and cancel outcomes
- capable-client Markdown payload and legacy fallback
- empty plan suppression, replay, deduplication, and subagent plan IDs
- `vitest run` (697 passed, 20 skipped)
- `tsc --noEmit`
- ESLint and Prettier on changed files
## Summary
Expose Claude Code permission-update suggestions through the same
versioned option-level metadata contract used by other ACP agents:
```json
{
"_meta": {
"permission": {
"version": 1,
"changes": []
}
}
}
```
The approval actions are presented as `Deny`, `Allow Once`, and `Always
Allow`. Exact scope and policy details live in metadata instead of being
encoded into the button label.
## Why
ACP already transports button semantics via `PermissionOption.kind`,
display text via `name`, and the selected value via `optionId`. It does
not currently expose the exact persistent policy update.
Claude Code suggestions can do considerably more than add one allow
rule: they may add, remove, or replace allow/deny/ask rule sets, add or
remove directories, change permission mode, and target different storage
destinations. Flattening those suggestions into labels or a list of
scopes loses mutation semantics and can incorrectly describe a narrow or
restrictive update as permission for the whole tool.
## Contract
Every change carries a producer-supplied human-readable `description`.
Structured fields preserve:
- ordered `add`, `remove`, and atomic `replace` operations
- `allow`, `deny`, and `ask` rule sets through `ruleBehavior`
- whole-tool targets and provider-rule matchers
- filesystem directory targets
- permission-mode changes
- session, process, user, project, and project-local destinations as
lifetime/storage
Example scoped Bash rule:
```json
{
"type": "policy_rule",
"operation": "add",
"ruleBehavior": "allow",
"description": "Allow Bash calls matching npm test:*",
"lifetime": { "scope": "session" },
"targets": [
{
"type": "tool",
"toolName": "Bash",
"matcher": {
"type": "provider_rule",
"provider": "claudeCode",
"value": "npm test:*"
}
}
]
}
```
A tool target without a matcher means the whole tool. A provider rule is
intentionally opaque; clients should show `description` rather than
reverse-engineering Claude Code rule syntax.
When Claude Code supplies no suggestions, the adapter preserves its
existing fallback behavior by describing the exact session rule it
returns: allow the whole requested tool for the session.
## Compatibility
This remains on the current ACP protocol and uses only `_meta`. Clients
that do not understand `_meta.permission` continue rendering and
dispatching the standard options. Option IDs and permission outcomes are
unchanged.
## Tests
- full suite: 682 passed, 20 skipped
- lint passed
- Prettier check passed
- TypeScript build passed
- coverage includes whole-tool fallback, scoped rules, directories,
replace/remove, deny rules, destinations, and mode changes
## Why
AskUserQuestion emits a per-question free-text field that should be
rendered as the custom-answer companion for the preceding select
question. ACP clients need a stable metadata marker for that
relationship instead of guessing from field ids, titles, or
descriptions.
## What changed
- Mark each AskUserQuestion custom-answer companion field with
`_meta._askUserQuestionCustomAnswer`.
- Use the same non-agent-specific key that Codex and other bridges can
emit, so clients can parse one shared marker instead of maintaining
per-agent metadata names.
- Keep the existing response folding behavior unchanged.
## Tests
- Updated `includes a per-question optional free-text custom-answer
field` to assert the shared `_askUserQuestionCustomAnswer` marker on
each companion field.
```sh
npm test -- src/tests/elicitation.test.ts
```
`permission_denied` forwarded an SDK frame as a `tool_call_update`
without checking that the referenced `tool_call` was ever announced,
leaving it the last emitter without that check after #916.
The id is the executing call's own, and the frame is enqueued from
inside canUseTool, so it lands between the call's `tool_use` and the
`tool_result` carrying the rejection — verified against the bundled CLI,
where the deny short-circuit only emits for pre-ask decisions (rules,
mode, classifier, asyncAgent) and fires exactly once per denial. In that
flow the call is announced and in flight, so the guard changes nothing.
It changes the denials that arrive outside that window. The
cancelled-turn guard drops the assistant message carrying the tool_use,
so no `tool_call` is emitted, and a denial for it can still land
afterwards — the same premise the `tool_result` fallback in
`toAcpNotifications` gates on `wasEmitted` for. Ids leave
`emittedToolCalls` at `tool_result`, so the check also stops a denial
trailing its own result from flipping a call the client has seen finish
back to failed.
While here: a denial raised inside a subagent identifies it by
`agent_id`, never by the Agent/Task call that spawned it, so the update
went out unattributed while the `tool_call` it resolves sits in the
subagent's transcript. Resolve the parent through `liveBackgroundTasks`,
as the canUseTool path already does, and leave the update unattributed
rather than dropped when `task_started` was never seen for that agent
id.
`permission_denied` had no test coverage. Add cases for the in-flight
resolve, the reason fallback, the never-announced and already-resolved
drops, and subagent attribution with and without a recorded parent.
Fixes#918
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Heartbeat beats reach the bridge under a derived
`<tool_use_id>-heartbeat-<n>` id that no `tool_call` was ever emitted
for, and the handler forwarded it verbatim. Clients that expect a
`tool_call_update` to reference a tool call they have been told about
saw a reference they could not resolve, and since the counter makes
every beat a fresh id, nothing deduplicated them: a ten-minute Bash call
produced roughly twenty phantom entries. Zed renders each as a failed
"Tool call not found" card; compozy/compozy#257 and
agent-of-empires/agent-of-empires#3084 report the same shape.
Strip the derived suffix so the beat is reported against the call it
describes, and drop it when that call is not in `emittedToolCalls`. Ids
enter that set at `tool_use` and leave it at `tool_result`, so the guard
covers both an id that was never announced and a straggling beat that
races past completion, which would otherwise flip a call the client has
seen finish back to `in_progress`.
The SDK sets `heartbeat: true` on these messages, but that flag alone
cannot recover the original id, and `parent_tool_use_id` is the subagent
parent rather than the call being reported on, so the suffix still has
to be stripped.
`tool_progress` had no test coverage. Add cases for the retarget across
a climbing counter, the not-in-flight drop, meta pass-through, and an
unsuffixed id being left alone.
Fixes#913
---------
Signed-off-by: Daan De Meyer <daan@amutable.com>
Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
## Problem
The `Bash` branch of `toolUpdateFromToolResult` derives its terminal id
from the result block and falls back to the empty string:
```ts
const terminalId = "tool_use_id" in toolResult ? String(toolResult.tool_use_id) : "";
```
On that fallback it still emits the whole terminal payload — `content:
[{ type: "terminal", terminalId: "" }]` plus `terminal_info`,
`terminal_output` and `terminal_exit`, every one keyed on `""`.
No client has a terminal under that id. `toolInfoFromToolUse` announces
the terminal as `toolUse.id` (`src/tools.ts:161`), so the empty id
matches nothing that was created. A client that buffers output for
terminals it has not been told about then holds the data indefinitely
behind an id that never arrives — Zed keeps it in
`pending_terminal_output` / `pending_terminal_exit` and drains only on a
matching create — so the command's output is silently stranded and the
user is left looking at an empty terminal.
It fails quietly, which is what makes it worth fixing: nothing logs, and
the update looks well-formed on the wire.
## Change
Prefer `toolUse.id` — the id that was actually announced — and keep the
result block's `tool_use_id` as a fallback. The two agree whenever both
are present, since the caller looks the tool_use up by that id, so this
only changes behaviour when one is missing.
When neither yields an id, fall through to the code-block rendering that
already exists immediately below rather than emitting a terminal
reference the client cannot resolve.
## Tests
Three cases added to `src/tests/tools.test.ts`:
- metas are keyed off the tool_use id even when the result block
disagrees
- the result block's `tool_use_id` is still used when the tool_use is
unavailable
- no id at all degrades to the `console` code block, with no `_meta`
Two of the three fail on `main` and pass with the change; the third
guards the preserved fallback. `npm run build`, `npm run check` and
`vitest run src/tests/tools.test.ts` (112 passed) are clean.
Note: `src/tests/create-session-options.test.ts > session/load seeds the
window from the resumed session's getContextUsage report` fails on a
clean `main` checkout here too — pre-existing and unrelated.
## How I got here
Found while tracing the "Tool call not found" rows in #913 — unrelated
cause, same file. The `terminal_id: ""` path came up while ruling the
terminal-streaming path out as the source of those.
---------
Co-authored-by: Ben Brandt <benjamin.j.brandt@gmail.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
## Motivation
ACP clients currently have two gaps when rendering Claude Code activity:
1. Bash tool calls expose the shell command as the standard ACP title,
but the concise human-readable `description` produced by Claude Code is
lost.
2. ACP 1.2 has no standard subagent tool kind or nested-message
relationship, so subagent prose and child tools are either flattened
into the main conversation or filtered out entirely.
This PR adds namespaced metadata and an explicit client capability so
richer clients can render both cases without changing the standard ACP
schema or regressing legacy clients.
## What changed
### Bash descriptions
- Keeps the shell command in the standard ACP `title`, preserving
command-oriented clients.
- Exposes the optional Claude Code Bash `description` as
`_meta.claudeCode.title`.
- Applies the metadata consistently to eager permission tool calls,
normal tool calls, and streamed input refinements.
- Falls back to the command title when no description is available.
### Nested subagent transcripts
- Adds the opt-in client capability
`clientCapabilities._meta["subagent-transcript"] = true`.
- Enables the Claude Agent SDK `forwardSubagentText` option when the
client advertises support.
- Preserves the pre-existing caller-provided `forwardSubagentText: true`
option for compatibility.
- Marks Agent and legacy Task launches with `_meta.claudeCode.subagent =
true`.
- Relates nested text, thinking, and child tool calls to the launching
Agent/Task call through `_meta.claudeCode.parentToolUseId`.
- Preserves parent attribution during session-history replay, not only
during live streaming.
- Handles nested Agent-to-Agent launches without inferring subagents
from the generic ACP `think` kind.
## Compatibility
Clients that do not advertise `subagent-transcript` retain the previous
behavior: subagent text and thinking remain filtered from the top-level
feed.
The normal Agent/Task tool result is still emitted in every mode as the
protocol-compatible fallback. No existing result or standard ACP field
is removed or redefined.
## Validation
- `npm run build`
- `npm run check`
- `npm run test:run`
- 623 tests passed, 20 skipped
Coverage includes live and replayed nested text/thinking, child tool
attribution, Agent/Task launch markers, nested Agent launches, legacy
filtering, and SDK-option compatibility.
Bumps [@hono/node-server](https://github.com/honojs/node-server) from
1.19.14 to 1.19.15.
<details>
<summary>Commits</summary>
<ul>
<li>See full diff in <a
href="https://github.com/honojs/node-server/commits">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>
Bumps the minor group with 2 updates:
[@anthropic-ai/sdk](https://github.com/anthropics/anthropic-sdk-typescript)
and [hono](https://github.com/honojs/hono).
Updates `@anthropic-ai/sdk` from 0.113.0 to 0.114.0
<details>
<summary>Release notes</summary>
<p><em>Sourced from <a
href="https://github.com/anthropics/anthropic-sdk-typescript/releases">@anthropic-ai/sdk's
releases</a>.</em></p>
<blockquote>
<h2>sdk: v0.114.0</h2>
<h2>0.114.0 (2026-07-23)</h2>
<p>Full Changelog: <a
href="https://github.com/anthropics/anthropic-sdk-typescript/compare/sdk-v0.113.0...sdk-v0.114.0">sdk-v0.113.0...sdk-v0.114.0</a></p>
<h3>Features</h3>
<ul>
<li><strong>api:</strong> add new stop reason
'model_context_window_exceeded' (<a
href="1ec71c165d">1ec71c1</a>)</li>
</ul>
</blockquote>
</details>
<details>
<summary>Changelog</summary>
<p><em>Sourced from <a
href="https://github.com/anthropics/anthropic-sdk-typescript/blob/main/CHANGELOG.md">@anthropic-ai/sdk's
changelog</a>.</em></p>
<blockquote>
<h2>0.114.0 (2026-07-23)</h2>
<p>Full Changelog: <a
href="https://github.com/anthropics/anthropic-sdk-typescript/compare/sdk-v0.113.0...sdk-v0.114.0">sdk-v0.113.0...sdk-v0.114.0</a></p>
<h3>Features</h3>
<ul>
<li><strong>api:</strong> add new stop reason
'model_context_window_exceeded' (<a
href="1ec71c165d">1ec71c1</a>)</li>
</ul>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="2d314b4127"><code>2d314b4</code></a>
chore: release main</li>
<li><a
href="3d051dfe49"><code>3d051df</code></a>
feat(api): add new stop reason 'model_context_window_exceeded'</li>
<li>See full diff in <a
href="https://github.com/anthropics/anthropic-sdk-typescript/compare/sdk-v0.113.0...sdk-v0.114.0">compare
view</a></li>
</ul>
</details>
<br />
Updates `hono` from 4.12.31 to 4.12.32
<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.12.32</h2>
<h2>What's Changed</h2>
<ul>
<li>ci: enable reports for type & bundle size check in <a
href="https://redirect.github.com/honojs/hono/pull/5148">honojs/hono#5148</a></li>
<li>fix(aws-lambda): add jwt and lambda authorizer types for API Gateway
v2 in <a
href="https://redirect.github.com/honojs/hono/pull/5142">honojs/hono#5142</a></li>
<li>fix(sse): emit empty id field to reset Last-Event-ID in <a
href="https://redirect.github.com/honojs/hono/pull/5138">honojs/hono#5138</a></li>
<li>test(cloudflare-workers): add coverage for onClose, onError, send,
and close in Cloudflare Workers websocket adapter in <a
href="https://redirect.github.com/honojs/hono/pull/5145">honojs/hono#5145</a></li>
<li>fix: use <code>Object.create(null)</code> when parsing query,
headers, and params in <a
href="https://redirect.github.com/honojs/hono/pull/5161">honojs/hono#5161</a></li>
<li>fix(secure-headers): keep CSP callbacks scoped to their header in <a
href="https://redirect.github.com/honojs/hono/pull/5147">honojs/hono#5147</a></li>
</ul>
<p><strong>Full Changelog</strong>: <a
href="https://github.com/honojs/hono/compare/v4.12.31...v4.12.32">https://github.com/honojs/hono/compare/v4.12.31...v4.12.32</a></p>
</blockquote>
</details>
<details>
<summary>Commits</summary>
<ul>
<li><a
href="26d8e42bff"><code>26d8e42</code></a>
4.12.32</li>
<li><a
href="402eb3abe5"><code>402eb3a</code></a>
fix(secure-headers): keep CSP callbacks scoped to their header (<a
href="https://redirect.github.com/honojs/hono/issues/5147">#5147</a>)</li>
<li><a
href="c85aead088"><code>c85aead</code></a>
fix: use <code>Object.create(null)</code> when parsing query, headers,
and params (<a
href="https://redirect.github.com/honojs/hono/issues/5161">#5161</a>)</li>
<li><a
href="a88c89dac6"><code>a88c89d</code></a>
test(cloudflare-workers): add coverage for onClose, onError, send, and
close ...</li>
<li><a
href="44f884321a"><code>44f8843</code></a>
fix(sse): emit empty id field to reset Last-Event-ID (<a
href="https://redirect.github.com/honojs/hono/issues/5138">#5138</a>)</li>
<li><a
href="e36f57dac0"><code>e36f57d</code></a>
fix(aws-lambda): add jwt and lambda authorizer types for API Gateway v2
(<a
href="https://redirect.github.com/honojs/hono/issues/5142">#5142</a>)</li>
<li><a
href="bf8608cb77"><code>bf8608c</code></a>
ci: enable reports for type & bundle size check (<a
href="https://redirect.github.com/honojs/hono/issues/5148">#5148</a>)</li>
<li>See full diff in <a
href="https://github.com/honojs/hono/compare/v4.12.31...v4.12.32">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>
nikita-ashihmin