chore(main): release 0.63.0 (#922)

🤖 I have created a release *beep* *boop*
---


##
[0.63.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.62.0...v0.63.0)
(2026-07-27)


### Features

* Update to claude agent sdk v0.3.220
([#921](https://github.com/agentclientprotocol/claude-agent-acp/issues/921))
([4c7b897](4c7b897183))


### Bug Fixes

* Only resolve a denied tool call the client was told about
([#923](https://github.com/agentclientprotocol/claude-agent-acp/issues/923))
([8f67b6a](8f67b6a92b)),
closes
[#918](https://github.com/agentclientprotocol/claude-agent-acp/issues/918)
* Report tool_progress heartbeats against the tool call they describe
([#916](https://github.com/agentclientprotocol/claude-agent-acp/issues/916))
([5559ba8](5559ba890c))
* **tools:** key Bash terminal metas off the announced tool_use id
([#917](https://github.com/agentclientprotocol/claude-agent-acp/issues/917))
([d060414](d0604140f9))

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).

Co-authored-by: acp-release-bot[bot] <246668977+acp-release-bot[bot]@users.noreply.github.com>

.github/workflows/ci.yml

@@ -24,7 +24,7 @@ jobs:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
 
       - name: Use Node.js
-        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
         with:
           node-version: "lts/*"
           cache: "npm"

.github/workflows/publish.yml

@@ -46,12 +46,35 @@ jobs:
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
       # Setup .npmrc file to publish to npm
-      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
         with:
           node-version: "lts/*"
           registry-url: "https://registry.npmjs.org"
-      - name: Update npm
-        run: npm install -g npm@latest
       - run: npm ci
       - run: npm run build
       - run: npm publish
+
+  trigger-registry-update:
+    needs: publish-npm
+    runs-on: ubuntu-latest
+    environment: release
+    permissions: {}
+    steps:
+      - name: Generate token scoped to the registry repo
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1
+        id: registry-token
+        with:
+          app-id: ${{ secrets.REGISTRY_UPDATER_APP_ID }}
+          private-key: ${{ secrets.REGISTRY_UPDATER_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: registry
+
+      - name: Dispatch registry version update
+        env:
+          GH_TOKEN: ${{ steps.registry-token.outputs.token }}
+        run: |
+          gh workflow run update-versions.yml \
+            --repo ${{ github.repository_owner }}/registry \
+            --ref main \
+            -f apply=true \
+            -f agents=claude-acp

.gitignore

@@ -3,3 +3,4 @@ dist
 .DS_Store
 .claude/*.local.*
 CLAUDE.local.md
+.idea/

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.54.1"
+  ".": "0.63.0"
 }

CHANGELOG.md

@@ -1,5 +1,127 @@
 # Changelog
 
+## [0.63.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.62.0...v0.63.0) (2026-07-27)
+
+
+### Features
+
+* Update to claude agent sdk v0.3.220 ([#921](https://github.com/agentclientprotocol/claude-agent-acp/issues/921)) ([4c7b897](https://github.com/agentclientprotocol/claude-agent-acp/commit/4c7b89718306229254879e5045a183233b5ed073))
+
+
+### Bug Fixes
+
+* Only resolve a denied tool call the client was told about ([#923](https://github.com/agentclientprotocol/claude-agent-acp/issues/923)) ([8f67b6a](https://github.com/agentclientprotocol/claude-agent-acp/commit/8f67b6a92bec24ae43b3dfbd087fe35df0531857)), closes [#918](https://github.com/agentclientprotocol/claude-agent-acp/issues/918)
+* Report tool_progress heartbeats against the tool call they describe ([#916](https://github.com/agentclientprotocol/claude-agent-acp/issues/916)) ([5559ba8](https://github.com/agentclientprotocol/claude-agent-acp/commit/5559ba890ca614cdaa189500aba65d81cc4cd51a))
+* **tools:** key Bash terminal metas off the announced tool_use id ([#917](https://github.com/agentclientprotocol/claude-agent-acp/issues/917)) ([d060414](https://github.com/agentclientprotocol/claude-agent-acp/commit/d0604140f907adbf9747f26a070690926e1de82d))
+
+## [0.62.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.61.0...v0.62.0) (2026-07-24)
+
+
+### Features
+
+* **deps:** Bump @hono/node-server from 1.19.14 to 1.19.15 ([#908](https://github.com/agentclientprotocol/claude-agent-acp/issues/908)) ([5193604](https://github.com/agentclientprotocol/claude-agent-acp/commit/51936049e175274de8e0fd90bc1be2af988c3ca6))
+* **deps:** Bump media-typer from 1.1.0 to 1.1.1 ([#909](https://github.com/agentclientprotocol/claude-agent-acp/issues/909)) ([5d35001](https://github.com/agentclientprotocol/claude-agent-acp/commit/5d35001563ffd702a29c3bac3b7ca134e40c77f8))
+* **deps:** Bump the minor group with 2 updates ([#900](https://github.com/agentclientprotocol/claude-agent-acp/issues/900)) ([809d41c](https://github.com/agentclientprotocol/claude-agent-acp/commit/809d41c6b7c9e7ba3cb5b206d00793a70edba64a))
+* **deps:** Bump the minor group with 2 updates ([#907](https://github.com/agentclientprotocol/claude-agent-acp/issues/907)) ([14d0627](https://github.com/agentclientprotocol/claude-agent-acp/commit/14d06273c01ad4ae944912e36700f6b5599c4c4d))
+* Update to claude-agent-sdk 0.3.218 ([#904](https://github.com/agentclientprotocol/claude-agent-acp/issues/904)) ([8cbaf97](https://github.com/agentclientprotocol/claude-agent-acp/commit/8cbaf97254576089a3b5ee6ae222fb763003c01d))
+
+## [0.61.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.60.0...v0.61.0) (2026-07-22)
+
+
+### Features
+
+* **deps:** Bump actions/setup-node from 6.4.0 to 7.0.0 ([#897](https://github.com/agentclientprotocol/claude-agent-acp/issues/897)) ([d9bd36d](https://github.com/agentclientprotocol/claude-agent-acp/commit/d9bd36d8b06764d63656d0387ad9430ec9fcb27d))
+* **deps:** Update to @anthropic-ai/claude-agent-sdk 0.3.217 ([#899](https://github.com/agentclientprotocol/claude-agent-acp/issues/899)) ([edf3af0](https://github.com/agentclientprotocol/claude-agent-acp/commit/edf3af043b6d00e5caca2cc81a2285c477c8b2ab))
+
+## [0.60.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.59.0...v0.60.0) (2026-07-20)
+
+
+### Features
+
+* **deps:** Update to claude-agent-sdk 0.3.215 ([#890](https://github.com/agentclientprotocol/claude-agent-acp/issues/890)) ([92548f0](https://github.com/agentclientprotocol/claude-agent-acp/commit/92548f043547b0ddac95921ece020e69f7c12c5f))
+* implement configurable LLM providers ([#853](https://github.com/agentclientprotocol/claude-agent-acp/issues/853)) ([82cd692](https://github.com/agentclientprotocol/claude-agent-acp/commit/82cd692e500eedec182f817b18cebb005c4b98ce))
+
+
+### Bug Fixes
+
+* parse Agent/Task trailers without regex ([#879](https://github.com/agentclientprotocol/claude-agent-acp/issues/879)) ([06c3d7b](https://github.com/agentclientprotocol/claude-agent-acp/commit/06c3d7bdbd8cc9415c8cabac060a50e0951c758b))
+* remove ~15s stall on session/new and model switch by seeding the context window synchronously ([#894](https://github.com/agentclientprotocol/claude-agent-acp/issues/894)) ([ff9b96d](https://github.com/agentclientprotocol/claude-agent-acp/commit/ff9b96d462831b1c3b96722ea20215ff6e529cb1))
+* Silence missing PostToolUse callbacks ([#895](https://github.com/agentclientprotocol/claude-agent-acp/issues/895)) ([1887ada](https://github.com/agentclientprotocol/claude-agent-acp/commit/1887ada215b27bb1025d9b7696a46ae7a4ac0f7a)), closes [#889](https://github.com/agentclientprotocol/claude-agent-acp/issues/889)
+
+## [0.59.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.58.1...v0.59.0) (2026-07-13)
+
+
+### Features
+
+* **deps-dev:** bump nanoid from 3.3.15 to 3.3.16 ([#875](https://github.com/agentclientprotocol/claude-agent-acp/issues/875)) ([e67dacd](https://github.com/agentclientprotocol/claude-agent-acp/commit/e67dacdcac629b00e5bdcda94b3de57459696b1e))
+* **deps:** bump @anthropic-ai/claude-agent-sdk to 0.3.207 ([#874](https://github.com/agentclientprotocol/claude-agent-acp/issues/874)) ([c7f5b8f](https://github.com/agentclientprotocol/claude-agent-acp/commit/c7f5b8fe768507afa28cdffe5cc3c054c56306ad))
+
+
+### Bug Fixes
+
+* Add subagent parent tool use attribution ([#859](https://github.com/agentclientprotocol/claude-agent-acp/issues/859)) ([9cd48c5](https://github.com/agentclientprotocol/claude-agent-acp/commit/9cd48c597af68f630774ec00bc3adc85f6b0fd4b))
+* forward result text when the turn emitted no assistant message ([#858](https://github.com/agentclientprotocol/claude-agent-acp/issues/858)) ([61ae860](https://github.com/agentclientprotocol/claude-agent-acp/commit/61ae8609d4343da6758c2376c6cf684c7fb0956a))
+* hold a turn open while its background subagents are still live ([#870](https://github.com/agentclientprotocol/claude-agent-acp/issues/870)) ([7a70f82](https://github.com/agentclientprotocol/claude-agent-acp/commit/7a70f82739e085014cad878f08513cdef7b7fe16))
+* Refine tool calls from streamed input ([#867](https://github.com/agentclientprotocol/claude-agent-acp/issues/867)) ([2c19974](https://github.com/agentclientprotocol/claude-agent-acp/commit/2c19974d5b80d3178b35e80a4bb0a1050588aab9))
+* Seed context window from SDK usage report ([#868](https://github.com/agentclientprotocol/claude-agent-acp/issues/868)) ([3ba2d36](https://github.com/agentclientprotocol/claude-agent-acp/commit/3ba2d367a282fe3053a73804a416a435cb01ee08)), closes [#596](https://github.com/agentclientprotocol/claude-agent-acp/issues/596)
+* Skip synthetic login messages on replay ([#869](https://github.com/agentclientprotocol/claude-agent-acp/issues/869)) ([c7dff3c](https://github.com/agentclientprotocol/claude-agent-acp/commit/c7dff3cf7eeb03cb993493efafa96344f18de81b)), closes [#863](https://github.com/agentclientprotocol/claude-agent-acp/issues/863)
+
+## [0.58.1](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.58.0...v0.58.1) (2026-07-09)
+
+
+### Bug Fixes
+
+* Use valid npm version for publish ([#855](https://github.com/agentclientprotocol/claude-agent-acp/issues/855)) ([8b366d8](https://github.com/agentclientprotocol/claude-agent-acp/commit/8b366d8e9ad55e9237bf2d618cfc99b57fac570d))
+
+## [0.58.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.57.0...v0.58.0) (2026-07-09)
+
+
+### Features
+
+* **deps:** update to @anthropic-ai/claude-agent-sdk 0.3.205 ([#854](https://github.com/agentclientprotocol/claude-agent-acp/issues/854)) ([f664ced](https://github.com/agentclientprotocol/claude-agent-acp/commit/f664ced76df00674d88aedd018a4261da3bc3f3a))
+
+
+### Bug Fixes
+
+* Preserve live model on resumed sessions ([#848](https://github.com/agentclientprotocol/claude-agent-acp/issues/848)) ([f3d8ae3](https://github.com/agentclientprotocol/claude-agent-acp/commit/f3d8ae3eb389ee9367f48c8762562a55280ade0a)), closes [#845](https://github.com/agentclientprotocol/claude-agent-acp/issues/845)
+* Report usage for cancelled active turns ([#846](https://github.com/agentclientprotocol/claude-agent-acp/issues/846)) ([b03318f](https://github.com/agentclientprotocol/claude-agent-acp/commit/b03318f59c6165146c8d8e036227f35c3abd0ff4)), closes [#844](https://github.com/agentclientprotocol/claude-agent-acp/issues/844)
+* tolerate missing text in streamed thinking chunks ([#852](https://github.com/agentclientprotocol/claude-agent-acp/issues/852)) ([e944ced](https://github.com/agentclientprotocol/claude-agent-acp/commit/e944ceddea79950d6bfb6339266862507c4b964f))
+* Use SDK guards for elicitation validation ([#850](https://github.com/agentclientprotocol/claude-agent-acp/issues/850)) ([32b9350](https://github.com/agentclientprotocol/claude-agent-acp/commit/32b93501d7a35a3b405b5022b4caaad492eed11c))
+
+## [0.57.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.56.0...v0.57.0) (2026-07-07)
+
+
+### Features
+
+* Update @anthropic-ai/claude-agent-sdk to 0.3.202 ([#843](https://github.com/agentclientprotocol/claude-agent-acp/issues/843)) ([1612c07](https://github.com/agentclientprotocol/claude-agent-acp/commit/1612c078953c134e12368a2d968a9bcf14d31b55))
+
+
+### Bug Fixes
+
+* don't emit empty agent_message_chunk ([#841](https://github.com/agentclientprotocol/claude-agent-acp/issues/841)) ([d74dd1d](https://github.com/agentclientprotocol/claude-agent-acp/commit/d74dd1d9d356050fc87f9fdab8599f1546b12a2c))
+
+## [0.56.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.55.0...v0.56.0) (2026-07-06)
+
+
+### Features
+
+* **deps:** bump @anthropic-ai/claude-agent-sdk to 0.3.201 ([#837](https://github.com/agentclientprotocol/claude-agent-acp/issues/837)) ([ff2a8a9](https://github.com/agentclientprotocol/claude-agent-acp/commit/ff2a8a963536a4265700e4f2003a0ffff93c9087))
+
+## [0.55.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.54.1...v0.55.0) (2026-07-02)
+
+
+### Features
+
+* Add refusal fallback consent dialog support ([#834](https://github.com/agentclientprotocol/claude-agent-acp/issues/834)) ([15dfd83](https://github.com/agentclientprotocol/claude-agent-acp/commit/15dfd83daa84ced98ecbaa7c83fd5a53124030c1))
+* **deps-dev:** bump the minor group with 3 updates ([#831](https://github.com/agentclientprotocol/claude-agent-acp/issues/831)) ([8d5febf](https://github.com/agentclientprotocol/claude-agent-acp/commit/8d5febf85485c1ad19b81501fb5c6d4275448a7c))
+* Update to claude-agent-sdk 0.3.198 ([#836](https://github.com/agentclientprotocol/claude-agent-acp/issues/836)) ([307ab82](https://github.com/agentclientprotocol/claude-agent-acp/commit/307ab82712213413446466d808e161073e94fc7f))
+
+
+### Bug Fixes
+
+* Handle model refusal fallback updates ([#833](https://github.com/agentclientprotocol/claude-agent-acp/issues/833)) ([648e3f6](https://github.com/agentclientprotocol/claude-agent-acp/commit/648e3f60bd7e6eadb5f86b0dc475104ab12e7b02))
+* Handle SDK idle turns without results ([#835](https://github.com/agentclientprotocol/claude-agent-acp/issues/835)) ([57b00cc](https://github.com/agentclientprotocol/claude-agent-acp/commit/57b00ccac610e2eeaf0a753934a0c3b78d27ccb0))
+
 ## [0.54.1](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.54.0...v0.54.1) (2026-06-30)
 
 

README.md

@@ -12,12 +12,24 @@ This tool implements an ACP agent by using the official [Claude Agent SDK](https
 - Following
 - Edit review
 - TODO lists
+- Nested subagent transcripts
 - Interactive (and background) terminals
 - Custom [Slash commands](https://docs.anthropic.com/en/docs/claude-code/slash-commands)
 - Client MCP servers
 
 Learn more about the [Agent Client Protocol](https://agentclientprotocol.com/).
 
+### Nested subagent transcripts
+
+ACP 1.2 has no standard subagent tool kind or nested-message relationship. Clients that can render
+nested transcripts can opt in with `clientCapabilities._meta["subagent-transcript"] = true`.
+The agent then forwards subagent text, thinking, and tool calls, relating nested updates to the
+launching Agent/Task call through `_meta.claudeCode.parentToolUseId`. Agent/Task calls are marked
+with `_meta.claudeCode.subagent = true`.
+
+Clients that do not advertise the capability retain the legacy flattened behavior. In both modes,
+the normal Agent/Task tool result is preserved as the protocol-compatible fallback.
+
 ## Contribution Policy
 
 This project does not require a Contributor License Agreement (CLA). Instead, contributions are accepted under the following terms:

examples/steering.ts

@@ -0,0 +1,191 @@
+/**
+ * Example: mid-turn steering over ACP with the `_session/steering` extension.
+ *
+ * "Steering" lets a client deliver a follow-up message to a turn that is still
+ * running, instead of waiting for it to finish and sending a fresh
+ * `session/prompt`. This is what powers "the user typed something while the
+ * agent was still working" — the new message joins the in-flight turn so the
+ * agent can adapt immediately (it shines in multi-step / tool-using turns,
+ * where the message slots in between tool calls).
+ *
+ * The wire protocol (see ../steering_protocol.md) has three moving parts:
+ *
+ *   1. The agent advertises support in its `initialize` response, at the
+ *      top-level `_meta.steering.supported` (a sibling of `agentCapabilities`).
+ *   2. The client calls the `_session/steering` request with `{ sessionId,
+ *      prompt }` while a turn is running.
+ *   3. The agent replies with an `outcome`:
+ *        - "injected"       the message joined the running turn;
+ *        - "startedNewTurn" the turn had already finished (an unavoidable race),
+ *                           so the message began a fresh turn instead.
+ *      Both are success outcomes — the message is never dropped and the race is
+ *      never surfaced as an error.
+ *
+ * This example launches the agent as a subprocess, starts a deliberately
+ * long-running prompt, and — as soon as the agent begins streaming — injects a
+ * steering message and prints the outcome. All agent output is streamed to
+ * stdout so you can watch the turn change course.
+ *
+ * Run (build the agent first so `dist/index.js` exists):
+ *
+ *   npm run build
+ *   node examples/steering.ts
+ *
+ * (Node < 22.18 needs `node --experimental-strip-types examples/steering.ts`.)
+ *
+ * Override the prompts with the PROMPT / STEER env vars. Requires the agent to
+ * be authenticated, since it talks to the real model.
+ */
+import { spawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { client as acpClient, methods, ndJsonStream } from "@agentclientprotocol/sdk";
+
+/** The steering extension method, per the ACP steering wire protocol. */
+const STEERING_METHOD = "_session/steering";
+
+/** Params for a `_session/steering` request — the same shape as the relevant
+ *  subset of a `session/prompt`. */
+type SteeringRequest = {
+  sessionId: string;
+  prompt: Array<{ type: "text"; text: string }>;
+};
+
+/** Result of a `_session/steering` request. Both values are successes: they
+ *  tell the client where the message landed, not whether it succeeded. */
+type SteeringResponse = {
+  outcome: "injected" | "startedNewTurn";
+};
+
+// The built agent entry. Run `npm run build` first so this exists.
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const AGENT_ENTRY = process.env.AGENT_ENTRY ?? path.join(repoRoot, "dist", "index.js");
+const CWD = process.env.CWD ?? process.cwd();
+
+// A deliberately long-running first prompt, and the follow-up injected while it
+// is still streaming. Override either via env vars to experiment.
+const PROMPT =
+  process.env.PROMPT ??
+  "Count slowly from 1 to 30, one number per line, with a short sentence of " +
+    "commentary after each. Do not stop early.";
+const STEER =
+  process.env.STEER ?? "Actually stop counting and instead reply with exactly one line: STEERED-OK";
+
+function log(msg: string) {
+  process.stderr.write(`\x1b[2m[client]\x1b[0m ${msg}\n`);
+}
+
+const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function main() {
+  // An ACP client launches the agent as a subprocess and speaks JSON-RPC over
+  // its stdin/stdout. stderr is inherited so the agent's own logs stay visible.
+  const child = spawn(process.execPath, [AGENT_ENTRY], {
+    stdio: ["pipe", "pipe", "inherit"],
+    env: process.env,
+  });
+  child.on("error", (err) => {
+    log(`failed to spawn agent (${AGENT_ENTRY}): ${err}`);
+    process.exit(1);
+  });
+
+  const stream = ndJsonStream(
+    Writable.toWeb(child.stdin!) as WritableStream<Uint8Array>,
+    Readable.toWeb(child.stdout!) as unknown as ReadableStream<Uint8Array>,
+  );
+
+  // Resolves the first time the agent streams assistant text — our signal that
+  // the turn is genuinely underway and therefore steerable.
+  let signalFirstOutput = () => {};
+  const firstOutput = new Promise<void>((resolve) => (signalFirstOutput = resolve));
+
+  const connection = acpClient({ name: "steering-example" })
+    .onNotification(methods.client.session.update, (ctx) => {
+      const update = ctx.params.update;
+      if (update.sessionUpdate === "agent_message_chunk" && update.content.type === "text") {
+        process.stdout.write(update.content.text);
+        signalFirstOutput();
+      }
+    })
+    // Auto-approve permission prompts so the turn is never blocked on us.
+    .onRequest(methods.client.session.requestPermission, (ctx) => {
+      const options = ctx.params.options;
+      const option = options.find((o) => o.kind === "allow_once") ?? options[0];
+      return { outcome: { outcome: "selected", optionId: option.optionId } };
+    })
+    // Minimal file-system stubs; the example prompts don't touch files.
+    .onRequest(methods.client.fs.readTextFile, () => ({ content: "" }))
+    .onRequest(methods.client.fs.writeTextFile, () => ({}))
+    .connect(stream);
+
+  const agent = connection.agent;
+
+  // 1. Initialize and confirm the agent advertises steering. Per the wire
+  //    protocol the capability lives at the TOP-LEVEL `_meta` of the initialize
+  //    result — a sibling of `agentCapabilities`, not nested inside it.
+  const init = await agent.request(methods.agent.initialize, {
+    protocolVersion: 1,
+    clientCapabilities: { fs: { readTextFile: true, writeTextFile: true } },
+  });
+  const meta = init._meta as { steering?: { supported?: boolean } } | null | undefined;
+  const steeringSupported = meta?.steering?.supported === true;
+  log(`agent advertises steering: ${steeringSupported}`);
+  if (!steeringSupported) {
+    log("agent does not advertise steering; the steering request may be rejected.");
+  }
+
+  // 2. Open a session.
+  const { sessionId } = await agent.request(methods.agent.session.new, {
+    cwd: CWD,
+    mcpServers: [],
+  });
+  log(`session: ${sessionId}`);
+
+  // 3. Start a long turn, but DON'T await it yet — we need it in flight so we
+  //    can steer it. Its output streams through the notification handler above.
+  log(`prompt: ${PROMPT}`);
+  process.stdout.write("\n----- agent output -----\n");
+  const turn = agent.request(methods.agent.session.prompt, {
+    sessionId,
+    prompt: [{ type: "text", text: PROMPT }],
+  });
+
+  // 4. Once the turn is producing output, inject the follow-up. Wait for the
+  //    first streamed chunk (with a fallback) plus a beat, so the steer clearly
+  //    lands mid-turn.
+  await Promise.race([firstOutput, delay(5000)]);
+  await delay(1000);
+
+  process.stdout.write("\n");
+  log(`steer: ${STEER}`);
+  const steerRequest: SteeringRequest = {
+    sessionId,
+    prompt: [{ type: "text", text: STEER }],
+  };
+  try {
+    const result = await agent.request<SteeringResponse>(STEERING_METHOD, steerRequest);
+    log(`steer outcome: ${result.outcome}`);
+  } catch (err) {
+    log(`steer rejected: ${err}`);
+  }
+
+  // 5. Await the turn. With outcome "injected" the steer already reshaped the
+  //    output above; with "startedNewTurn" the follow-up runs as a fresh turn
+  //    that may still be streaming, so linger briefly to capture it.
+  const response = await turn.catch((err: unknown) => {
+    log(`turn error: ${err}`);
+    return undefined;
+  });
+  if (response) log(`turn stopReason: ${response.stopReason}`);
+  await delay(3000);
+  process.stdout.write("\n----- end of agent output -----\n");
+
+  connection.close();
+  child.kill();
+}
+
+main().catch((err) => {
+  log(`fatal: ${err?.stack ?? err}`);
+  process.exit(1);
+});

package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.54.1",
+  "version": "0.63.0",
   "description": "An ACP-compatible coding agent powered by the Claude Agent SDK (TypeScript)",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
@@ -63,23 +63,23 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@agentclientprotocol/sdk": "1.1.0",
-    "@anthropic-ai/claude-agent-sdk": "0.3.197",
+    "@agentclientprotocol/sdk": "1.3.0",
+    "@anthropic-ai/claude-agent-sdk": "0.3.220",
     "zod": "^3.25.0 || ^4.0.0"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "0.108.0",
+    "@anthropic-ai/sdk": "0.115.0",
     "@eslint/js": "10.0.1",
     "@tsconfig/node22": "22.0.5",
-    "@types/node": "26.0.1",
-    "@typescript-eslint/eslint-plugin": "8.62.1",
-    "@typescript-eslint/parser": "8.62.1",
-    "eslint": "10.6.0",
+    "@types/node": "26.1.1",
+    "@typescript-eslint/eslint-plugin": "8.65.0",
+    "@typescript-eslint/parser": "8.65.0",
+    "eslint": "10.8.0",
     "eslint-config-prettier": "10.1.8",
-    "globals": "17.7.0",
-    "prettier": "3.9.4",
+    "globals": "17.8.0",
+    "prettier": "3.9.6",
     "ts-node": "10.9.2",
     "typescript": "6.0.3",
-    "vitest": "4.1.9"
+    "vitest": "4.1.10"
   }
 }

src/elicitation.ts

@@ -1,7 +1,8 @@
 import { randomUUID } from "node:crypto";
+import { CreateElicitationResponse } from "@agentclientprotocol/sdk";
 import type {
   CreateElicitationRequest,
-  CreateElicitationResponse,
+  ElicitationAcceptAction,
   ElicitationPropertySchema,
   ElicitationSchema,
   EnumOption,
@@ -68,6 +69,20 @@ export function mcpElicitationToCreateRequest(
   };
 }
 
+/**
+ * Content of an accepted elicitation response.
+ *
+ * Uses the SDK's validating guard rather than an `action === "accept"` check:
+ * the guard both narrows past the union's custom/future variant and validates
+ * the payload, so a malformed accept (right tag, ill-typed content) yields
+ * empty content — the same classification the SDK's wire validators apply.
+ */
+function acceptedElicitationContent(
+  response: CreateElicitationResponse,
+): NonNullable<ElicitationAcceptAction["content"]> {
+  return CreateElicitationResponse.isAccept(response) ? (response.content ?? {}) : {};
+}
+
 /**
  * Map an ACP elicitation response back to the MCP `ElicitResult` the SDK expects
  * to hand back to the requesting server.
@@ -77,7 +92,7 @@ export function createElicitationResponseToElicitResult(
 ): ElicitationResult {
   switch (response.action) {
     case "accept":
-      return { action: "accept", content: response.content ?? {} };
+      return { action: "accept", content: acceptedElicitationContent(response) };
     case "decline":
       return { action: "decline" };
     case "cancel":
@@ -126,33 +141,13 @@ function questionCustomFieldKey(index: number): string {
 }
 
 /**
- * `_meta` key under which a bridged enum option carries its structured
- * `description`/`preview`, since ACP's `EnumOption` has no field for either.
- * Namespaced like the agent's other `_meta` extensions (`_claude/...`).
+ * `_meta` key under which a bridged enum option carries its `preview`, the one
+ * option field ACP's `EnumOption` still has no slot for (descriptions are
+ * first-class as of schema 1.19). Namespaced like the agent's other `_meta`
+ * extensions (`_claude/...`).
  */
 const OPTION_META_KEY = "_claude/askUserQuestionOption";
 
-/** A single option as supplied by the AskUserQuestion tool. */
-type AskUserQuestionOption = AskUserQuestion["options"][number];
-
-/**
- * Build the `_meta` payload that carries an option's structured `description`
- * and optional `preview` for clients that can render them as distinct fields.
- * Returns `undefined` when neither is present, so we don't emit an empty `_meta`.
- */
-function askUserQuestionOptionMeta(
-  option: AskUserQuestionOption,
-): NonNullable<EnumOption["_meta"]> | undefined {
-  const detail: { description?: string; preview?: string } = {};
-  if (option.description) {
-    detail.description = option.description;
-  }
-  if (option.preview) {
-    detail.preview = option.preview;
-  }
-  return Object.keys(detail).length > 0 ? { [OPTION_META_KEY]: detail } : undefined;
-}
-
 /**
  * Render the AskUserQuestion tool's questions as an ACP form elicitation.
  *
@@ -160,7 +155,8 @@ function askUserQuestionOptionMeta(
  * question text, so the question text appears in exactly one place per field.
  * Single-select questions use a titled `oneOf` enum; multi-select questions use
  * an array with a titled `anyOf` item enum. The enum `const` is always the
- * option label, since that is what the tool records as the answer.
+ * option label, since that is what the tool records as the answer; an option's
+ * secondary text travels in the enum option's own `description` field.
  *
  * Each question is followed by its own optional free-text "custom answer" field
  * (`question_<n>_custom`), mirroring the CLI's per-question "Other" box: the
@@ -180,19 +176,16 @@ export function askUserQuestionsToCreateRequest(
     const options: EnumOption[] = question.options.map((option) => {
       const enumOption: EnumOption = {
         const: option.label,
-        // `title` stays a flattened "label — description" string so clients that
-        // only read `const`/`title` still surface the description. Clients that
-        // understand the `_meta` below should prefer its structured fields (and
-        // treat `const` as the clean label) rather than parsing this title.
-        title: option.description ? `${option.label} — ${option.description}` : option.label,
+        title: option.label,
       };
-      // The SDK option carries a `description` (secondary text) and an optional
-      // `preview` (mockups, code snippets, comparisons shown on focus). Neither
-      // has a structural slot in `EnumOption`, so forward them under ACP's
-      // reserved `_meta` extension point for clients that can render them.
-      const meta = askUserQuestionOptionMeta(option);
-      if (meta) {
-        enumOption._meta = meta;
+      if (option.description) {
+        enumOption.description = option.description;
+      }
+      // The SDK option's `preview` (mockups, code snippets, comparisons shown
+      // on focus) still has no structural slot in `EnumOption`, so forward it
+      // under ACP's reserved `_meta` extension point for clients that render it.
+      if (option.preview) {
+        enumOption._meta = { [OPTION_META_KEY]: { preview: option.preview } };
       }
       return enumOption;
     });
@@ -243,22 +236,23 @@ export type AskUserQuestionOutcome =
  * custom-answer field (`question_<n>_custom`) takes precedence over that
  * question's selection, since the user typed their own answer instead of
  * picking one. Decline yields empty answers (the model is told the user skipped
- * rather than the turn aborting); cancel aborts the tool call.
+ * rather than the turn aborting); cancel — and any custom/future action we
+ * don't understand — aborts the tool call.
  */
 export function applyAskElicitationResponse(
   response: CreateElicitationResponse,
   toolInput: Record<string, unknown>,
   questions: AskUserQuestion[],
 ): AskUserQuestionOutcome {
-  if (response.action === "cancel") {
-    return { action: "cancel" };
-  }
-
   if (response.action === "decline") {
     return { action: "answered", updatedInput: { ...toolInput, answers: {} } };
   }
 
-  const content = response.content ?? {};
+  if (response.action !== "accept") {
+    return { action: "cancel" };
+  }
+
+  const content = acceptedElicitationContent(response);
   // Typed against the tool's own output schema so the answer/response shapes
   // stay in sync with what the built-in tool's call() expects to read back.
   const answers: AskUserQuestionOutput["answers"] = {};
@@ -298,3 +292,113 @@ function normalizeElicitationSchema(
   }
   return { ...(schema as ElicitationSchema), type: "object" };
 }
+
+/**
+ * The `request_user_dialog` kind the CLI emits when a model refusal has a
+ * fallback available but needs user consent before retrying (e.g. Claude Fable
+ * declining a request with Opus available as the fallback). Declaring this
+ * kind in `supportedDialogKinds` is the opt-in: the CLI fails closed and never
+ * emits an undeclared kind — the flow degrades to the classic refusal error
+ * ending the turn.
+ */
+export const REFUSAL_FALLBACK_DIALOG_KIND = "refusal_fallback_prompt";
+
+/**
+ * Payload of the `refusal_fallback_prompt` dialog. The dialog protocol
+ * transports payloads opaquely, so this shape is recovered from the CLI's own
+ * schema (v2.1.177): `originalModel`/`fallbackModel` are required strings;
+ * `apiRefusalCategory` (nullable), `guidanceText`, and
+ * `retractedMessageUuids` are optional. We ignore `retractedMessageUuids` —
+ * ACP has no way to retract already-streamed chunks.
+ */
+export type RefusalFallbackPrompt = {
+  originalModel: string;
+  fallbackModel: string;
+  apiRefusalCategory: string | null;
+  guidanceText?: string;
+};
+
+/**
+ * Validate the opaque dialog payload into a {@link RefusalFallbackPrompt}.
+ * Returns `null` when the required fields are missing or mistyped (a newer CLI
+ * may reshape the payload), so the caller can cancel the dialog and let the
+ * CLI apply its default behavior instead of rendering something misleading.
+ */
+export function extractRefusalFallbackPrompt(
+  payload: Record<string, unknown>,
+): RefusalFallbackPrompt | null {
+  const { originalModel, fallbackModel, apiRefusalCategory, guidanceText } = payload;
+  if (typeof originalModel !== "string" || typeof fallbackModel !== "string") {
+    return null;
+  }
+  return {
+    originalModel,
+    fallbackModel,
+    apiRefusalCategory: typeof apiRefusalCategory === "string" ? apiRefusalCategory : null,
+    ...(typeof guidanceText === "string" && guidanceText ? { guidanceText } : {}),
+  };
+}
+
+/** Form-field key carrying the user's choice in the refusal-fallback form. */
+const REFUSAL_FALLBACK_CHOICE_KEY = "choice";
+
+/** Wire values of the dialog's result enum (CLI schema). `edit_prompt` is
+ *  deliberately not offered: in the CLI it prefills the composer with the
+ *  refused prompt for edit-and-retry, and ACP has no composer-prefill surface
+ *  — the user can simply edit and resend on their own. */
+const RETRY_FALLBACK_RESULT = "retry_fallback";
+const KEEP_REFUSAL_RESULT = "cancelled";
+
+/**
+ * Render the refusal-fallback consent prompt as an ACP form elicitation: a
+ * single-select between retrying on the fallback model and keeping the
+ * refusal. The enum `const`s are the dialog's wire result values, so the
+ * response maps back without a translation table.
+ */
+export function refusalFallbackToCreateRequest(
+  prompt: RefusalFallbackPrompt,
+  sessionId: string,
+): CreateElicitationRequest {
+  const category = prompt.apiRefusalCategory ? ` (${prompt.apiRefusalCategory})` : "";
+  const guidance = prompt.guidanceText ? `\n\n${prompt.guidanceText}` : "";
+  return {
+    mode: "form",
+    sessionId,
+    message:
+      `${prompt.originalModel} declined this request${category}. ` +
+      `Retry with ${prompt.fallbackModel}?` +
+      guidance,
+    requestedSchema: {
+      type: "object",
+      properties: {
+        [REFUSAL_FALLBACK_CHOICE_KEY]: {
+          type: "string",
+          oneOf: [
+            {
+              const: RETRY_FALLBACK_RESULT,
+              title: `Retry with ${prompt.fallbackModel}`,
+              description: `The session continues on ${prompt.fallbackModel}.`,
+            },
+            {
+              const: KEEP_REFUSAL_RESULT,
+              title: "Keep the refusal",
+              description: "You can send a new message.",
+            },
+          ],
+        },
+      },
+    },
+  };
+}
+
+/**
+ * Map the elicitation response back to the dialog's result enum. Only an
+ * explicit accept-with-retry resolves to `retry_fallback`; decline, cancel, a
+ * skipped field, or an unrecognized value all keep the refusal — the dialog's
+ * own default — so a dismissed or half-filled form can never trigger a model
+ * switch the user didn't ask for.
+ */
+export function refusalFallbackResultFromResponse(response: CreateElicitationResponse): string {
+  const choice = acceptedElicitationContent(response)[REFUSAL_FALLBACK_CHOICE_KEY];
+  return choice === RETRY_FALLBACK_RESULT ? RETRY_FALLBACK_RESULT : KEEP_REFUSAL_RESULT;
+}

src/tests/acp-agent-settings.test.ts

@@ -3,6 +3,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
 import type { AcpClient, ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
+import { makeMockQuery } from "./helpers.js";
 
 const { querySpy } = vi.hoisted(() => ({
   querySpy: vi.fn(),
@@ -34,7 +35,7 @@ describe("ClaudeAcpAgent settings", () => {
     const setModelSpy = vi.fn();
     querySpy.mockImplementation(({ options }: any) => {
       capturedOptions = options;
-      return {
+      return makeMockQuery({
         initializationResult: async () => ({
           models: [
             {
@@ -45,8 +46,7 @@ describe("ClaudeAcpAgent settings", () => {
           ],
         }),
         setModel: setModelSpy,
-        supportedCommands: async () => [],
-      } as any;
+      }) as any;
     });
     return { getCapturedOptions: () => capturedOptions, setModelSpy };
   }
@@ -240,12 +240,11 @@ describe("ClaudeAcpAgent settings", () => {
       const setPermissionModeSpy = vi.fn();
       querySpy.mockImplementation(({ options }: any) => {
         capturedOptions = options;
-        return {
+        return makeMockQuery({
           initializationResult: async () => ({ models }),
           setModel: setModelSpy,
           setPermissionMode: setPermissionModeSpy,
-          supportedCommands: async () => [],
-        } as any;
+        }) as any;
       });
       return {
         getCapturedOptions: () => capturedOptions,
@@ -396,11 +395,10 @@ describe("ClaudeAcpAgent settings", () => {
     } {
       const setModelSpy = vi.fn();
       querySpy.mockImplementation(() => {
-        return {
+        return makeMockQuery({
           initializationResult: async () => ({ models }),
           setModel: setModelSpy,
-          supportedCommands: async () => [],
-        } as any;
+        }) as any;
       });
       return { setModelSpy };
     }
@@ -875,7 +873,7 @@ describe("ClaudeAcpAgent settings", () => {
 
     const setModelSpy = vi.fn();
     querySpy.mockImplementation(({ options: _options }: any) => {
-      return {
+      return makeMockQuery({
         initializationResult: async () => ({
           models: [
             {
@@ -891,8 +889,7 @@ describe("ClaudeAcpAgent settings", () => {
           ],
         }),
         setModel: setModelSpy,
-        supportedCommands: async () => [],
-      } as any;
+      }) as any;
     });
 
     const { ClaudeAcpAgent } = await import("../acp-agent.js");
@@ -923,7 +920,7 @@ describe("ClaudeAcpAgent settings", () => {
 
     const setModelSpy = vi.fn();
     querySpy.mockImplementation(() => {
-      return {
+      return makeMockQuery({
         initializationResult: async () => ({
           models: [
             { value: "default", displayName: "Default", description: "" },
@@ -932,8 +929,7 @@ describe("ClaudeAcpAgent settings", () => {
           ],
         }),
         setModel: setModelSpy,
-        supportedCommands: async () => [],
-      } as any;
+      }) as any;
     });
 
     try {
@@ -977,7 +973,7 @@ describe("ClaudeAcpAgent settings", () => {
 
     const setModelSpy = vi.fn();
     querySpy.mockImplementation(() => {
-      return {
+      return makeMockQuery({
         initializationResult: async () => ({
           models: [
             { value: "default", displayName: "Default", description: "" },
@@ -985,8 +981,7 @@ describe("ClaudeAcpAgent settings", () => {
           ],
         }),
         setModel: setModelSpy,
-        supportedCommands: async () => [],
-      } as any;
+      }) as any;
     });
 
     const { ClaudeAcpAgent } = await import("../acp-agent.js");

src/tests/additional-roots.test.ts

@@ -7,30 +7,30 @@ import type { AcpClient, ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-age
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 let capturedOptions: Options | undefined;
-vi.mock("@anthropic-ai/claude-agent-sdk", async () => ({
-  ...(await vi.importActual<typeof import("@anthropic-ai/claude-agent-sdk")>(
+vi.mock("@anthropic-ai/claude-agent-sdk", async () => {
+  const actual = await vi.importActual<typeof import("@anthropic-ai/claude-agent-sdk")>(
     "@anthropic-ai/claude-agent-sdk",
-  )),
-  query: ({ options }: { options: Options }) => {
-    capturedOptions = options;
-    return {
-      initializationResult: async () => ({
-        models: [
-          {
-            value: "claude-sonnet-4-6",
-            displayName: "Claude Sonnet",
-            description: "Fast",
-            supportsAutoMode: true,
-          },
-        ],
-      }),
-      setModel: async () => {},
-      setPermissionMode: async () => {},
-      supportedCommands: async () => [],
-      [Symbol.asyncIterator]: async function* () {},
-    };
-  },
-}));
+  );
+  const { makeMockQuery } = await import("./helpers.js");
+  return {
+    ...actual,
+    query: ({ options }: { options: Options }) => {
+      capturedOptions = options;
+      return makeMockQuery({
+        initializationResult: async () => ({
+          models: [
+            {
+              value: "claude-sonnet-4-6",
+              displayName: "Claude Sonnet",
+              description: "Fast",
+              supportsAutoMode: true,
+            },
+          ],
+        }),
+      });
+    },
+  };
+});
 vi.mock("../tools.js", async () => ({
   ...(await vi.importActual<typeof import("../tools.js")>("../tools.js")),
   registerHookCallback: vi.fn(),

src/tests/authorization.test.ts

@@ -1,18 +1,8 @@
 import { describe, expect, it, Mock, vi, afterEach, beforeEach } from "vitest";
 import { AcpClient, ClaudeAcpAgent } from "../acp-agent.js";
+import { makeMockQuery } from "./helpers.js";
 
-const mockQuery = vi.hoisted(() =>
-  vi.fn(() => ({
-    initializationResult: vi.fn().mockResolvedValue({
-      models: [
-        { value: "id", displayName: "name", description: "description", supportsAutoMode: true },
-      ],
-    }),
-    setModel: vi.fn(),
-    setPermissionMode: vi.fn(),
-    supportedCommands: vi.fn().mockResolvedValue([]),
-  })),
-);
+const mockQuery = vi.hoisted(() => vi.fn());
 
 vi.mock("@anthropic-ai/claude-agent-sdk", async () => ({
   ...(await vi.importActual<typeof import("@anthropic-ai/claude-agent-sdk")>(
@@ -24,6 +14,22 @@ vi.mock("@anthropic-ai/claude-agent-sdk", async () => ({
 describe("authorization", () => {
   beforeEach(() => {
     vi.useFakeTimers();
+    // Set here (not in vi.fn(impl) at hoist time) so the helper import is
+    // available; afterEach's resetAllMocks clears it, beforeEach re-sets it.
+    mockQuery.mockImplementation(() =>
+      makeMockQuery({
+        initializationResult: async () => ({
+          models: [
+            {
+              value: "id",
+              displayName: "name",
+              description: "description",
+              supportsAutoMode: true,
+            },
+          ],
+        }),
+      }),
+    );
   });
 
   afterEach(() => {

src/tests/create-session-options.test.ts

@@ -7,15 +7,17 @@ import * as os from "node:os";
 import * as path from "node:path";
 
 let capturedOptions: Options | undefined;
+let contextUsageResult: (() => Promise<{ rawMaxTokens: number; model?: string }>) | undefined;
 vi.mock("@anthropic-ai/claude-agent-sdk", async () => {
   const actual = await vi.importActual<typeof import("@anthropic-ai/claude-agent-sdk")>(
     "@anthropic-ai/claude-agent-sdk",
   );
+  const { makeMockQuery, DEFAULT_CONTEXT_USAGE } = await import("./helpers.js");
   return {
     ...actual,
     query: (args: { prompt: unknown; options: Options }) => {
       capturedOptions = args.options;
-      return {
+      return makeMockQuery({
         initializationResult: async () => ({
           models: [
             {
@@ -26,11 +28,9 @@ vi.mock("@anthropic-ai/claude-agent-sdk", async () => {
             },
           ],
         }),
-        setModel: async () => {},
-        setPermissionMode: async () => {},
-        supportedCommands: async () => [],
-        [Symbol.asyncIterator]: async function* () {},
-      };
+        getContextUsage: () =>
+          contextUsageResult ? contextUsageResult() : Promise.resolve(DEFAULT_CONTEXT_USAGE),
+      });
     },
   };
 });
@@ -58,6 +58,7 @@ describe("createSession options merging", () => {
 
   beforeEach(async () => {
     capturedOptions = undefined;
+    contextUsageResult = undefined;
 
     vi.resetModules();
     const acpAgent = await import("../acp-agent.js");
@@ -262,6 +263,38 @@ describe("createSession options merging", () => {
     expect(capturedOptions!.tools).toEqual([]);
   });
 
+  describe("subagent transcript forwarding", () => {
+    it("keeps the legacy default when neither the client nor caller opts in", async () => {
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(capturedOptions!.forwardSubagentText).toBe(false);
+    });
+
+    it("preserves the pre-existing caller-provided SDK option", async () => {
+      await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [],
+        _meta: { claudeCode: { options: { forwardSubagentText: true } } },
+      });
+
+      expect(capturedOptions!.forwardSubagentText).toBe(true);
+    });
+
+    it("enables SDK forwarding when the ACP client advertises support", async () => {
+      await agent.initialize({
+        protocolVersion: 1,
+        clientCapabilities: { _meta: { "subagent-transcript": true } },
+      });
+      await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [],
+        _meta: { claudeCode: { options: { forwardSubagentText: false } } },
+      });
+
+      expect(capturedOptions!.forwardSubagentText).toBe(true);
+    });
+  });
+
   describe("systemPrompt via _meta", () => {
     it("defaults to the claude_code preset when not provided", async () => {
       await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
@@ -514,8 +547,13 @@ describe("createSession options merging", () => {
 
     it("ignores a non-numeric value", async () => {
       process.env.MAX_THINKING_TOKENS = "lots";
+      // The bad value is deliberate — capture the agent's warning instead of
+      // letting it hit the console.
+      const errorSpy = vi.fn();
+      (agent as any).logger = { log: () => {}, error: errorSpy };
       await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
       expect(capturedOptions!.thinking).toBeUndefined();
+      expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("MAX_THINKING_TOKENS"));
     });
 
     it("lets a user-provided thinking option override the env default", async () => {
@@ -613,4 +651,240 @@ describe("createSession options merging", () => {
       expect(capturedOptions!.disallowedTools).not.toContain("AskUserQuestion");
     });
   });
+
+  describe("context window seeding", () => {
+    function sessionFor(sessionId: string) {
+      return (agent as unknown as { sessions: Record<string, any> }).sessions[sessionId];
+    }
+
+    it("does not call getContextUsage during session creation", async () => {
+      // getContextUsage stalls until the session's first prompt turn has run
+      // (it is not serviced pre-turn), so session/new must never call it —
+      // awaiting it inline is what regressed session/new latency in 0.59.0.
+      const ctxSpy = vi.fn(async () => ({ rawMaxTokens: 967000 }));
+      contextUsageResult = ctxSpy;
+
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(ctxSpy).not.toHaveBeenCalled();
+    });
+
+    it("seeds contextWindowSize from text inference, falling back to the default when it misses", async () => {
+      // The mock model ("claude-sonnet-4-6" / "Claude Sonnet" / "Fast") carries
+      // no "1m" token anywhere, so inference misses and the window falls back to
+      // the default; the authoritative value arrives later via result.modelUsage.
+      contextUsageResult = async () => ({ rawMaxTokens: 967000 });
+
+      const response = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(sessionFor(response.sessionId).contextWindowSize).toBe(200000);
+      expect(sessionFor(response.sessionId).contextWindowAuthoritative).toBe(false);
+    });
+
+    it("session/load seeds the window from the resumed session's getContextUsage report", async () => {
+      // Resumed sessions get getContextUsage serviced pre-turn (issue #845 uses
+      // it to restore the live model), and the same response carries the
+      // authoritative window (`rawMaxTokens`). After a process restart the
+      // module cache is empty and text inference misses natively-1M aliases, so
+      // discarding this in-hand value would replay the issue-#596 flicker on
+      // every reload — the flagship scenario. 888_000 can only come from the
+      // report: inference on the mock model yields null → 200_000 default.
+      contextUsageResult = async () => ({ rawMaxTokens: 888_000, model: "claude-sonnet-4-6" });
+
+      await (
+        agent as unknown as {
+          createSession: (params: object, opts: { resume?: string }) => Promise<unknown>;
+        }
+      ).createSession({ cwd: process.cwd(), mcpServers: [] }, { resume: "resumed-window-probe" });
+
+      const session = sessionFor("resumed-window-probe");
+      expect(session.contextWindowSize).toBe(888_000);
+      expect(session.contextWindowAuthoritative).toBe(true);
+    });
+
+    it("scopes providerCacheKey by per-session env routing", async () => {
+      // The context-window cache key must distinguish backends exactly as the
+      // CLI will see them: a session routed to a proxy via _meta env shares a
+      // model id spelling with default-routed sessions but not a context lane,
+      // so it must land in its own cache bucket (and two default-routed
+      // sessions must share one).
+      const r1 = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+      const r2 = await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [],
+        _meta: {
+          claudeCode: {
+            options: { env: { ANTHROPIC_BASE_URL: "https://window-probe-proxy.example" } },
+          },
+        },
+      });
+      const r3 = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(sessionFor(r2.sessionId).providerCacheKey).not.toBe(
+        sessionFor(r1.sessionId).providerCacheKey,
+      );
+      expect(sessionFor(r3.sessionId).providerCacheKey).toBe(
+        sessionFor(r1.sessionId).providerCacheKey,
+      );
+    });
+
+    it("scopes providerCacheKey by provider headers: same endpoint, different headers → different buckets", async () => {
+      // Two providers/set configs sharing apiType+baseUrl but differing in
+      // headers (e.g. an `anthropic-beta: context-1m-…` routing header) can
+      // serve different context lanes for the same model id, so they must not
+      // share a window-cache bucket.
+      await agent.unstable_setProvider({
+        providerId: "main",
+        apiType: "anthropic",
+        baseUrl: "https://gw.example",
+        headers: {},
+      });
+      const plain = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      await agent.unstable_setProvider({
+        providerId: "main",
+        apiType: "anthropic",
+        baseUrl: "https://gw.example",
+        headers: { "anthropic-beta": "context-1m-2025-08-07" },
+      });
+      const beta = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(sessionFor(beta.sessionId).providerCacheKey).not.toBe(
+        sessionFor(plain.sessionId).providerCacheKey,
+      );
+    });
+  });
+
+  describe("refusal fallback dialog", () => {
+    it("declares the dialog kind and callback when the client supports form elicitation", async () => {
+      await agent.initialize({
+        protocolVersion: 1,
+        clientCapabilities: { elicitation: { form: {} } },
+      });
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(capturedOptions!.supportedDialogKinds).toEqual(["refusal_fallback_prompt"]);
+      expect(typeof capturedOptions!.onUserDialog).toBe("function");
+    });
+
+    it("omits the dialog wiring without form elicitation support (url-only included)", async () => {
+      await agent.initialize({
+        protocolVersion: 1,
+        clientCapabilities: { elicitation: { url: {} } },
+      });
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      // The CLI fails closed on the undeclared kind, so the flow degrades to
+      // the classic refusal error instead of parking a dialog we can't render.
+      expect(capturedOptions!.supportedDialogKinds).toBeUndefined();
+      expect(capturedOptions!.onUserDialog).toBeUndefined();
+    });
+
+    /** Wire the session up with form support and return the captured dialog
+     *  callback plus a mock the test can point the elicitation response at. */
+    async function setupDialog() {
+      await agent.initialize({
+        protocolVersion: 1,
+        clientCapabilities: { elicitation: { form: {} } },
+      });
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+      const createElicitation = vi.fn();
+      (
+        agent as unknown as { client: { unstable_createElicitation: unknown } }
+      ).client.unstable_createElicitation = createElicitation;
+      return { onUserDialog: capturedOptions!.onUserDialog!, createElicitation };
+    }
+
+    const signal = () => ({ signal: new AbortController().signal });
+
+    it("renders the prompt as a form elicitation and maps the retry choice", async () => {
+      const { onUserDialog, createElicitation } = await setupDialog();
+      createElicitation.mockResolvedValue({
+        action: "accept",
+        content: { choice: "retry_fallback" },
+      });
+
+      const result = await onUserDialog(
+        {
+          dialogKind: "refusal_fallback_prompt",
+          payload: {
+            originalModel: "claude-fable-5",
+            fallbackModel: "claude-opus-4-8",
+            apiRefusalCategory: "cyber",
+          },
+        },
+        signal(),
+      );
+
+      expect(result).toEqual({ behavior: "completed", result: "retry_fallback" });
+      const request = createElicitation.mock.calls[0][0];
+      expect(request.mode).toBe("form");
+      expect(request.message).toContain("claude-fable-5");
+      expect(request.message).toContain("claude-opus-4-8");
+    });
+
+    it("completes with cancelled when the user keeps the refusal", async () => {
+      const { onUserDialog, createElicitation } = await setupDialog();
+      createElicitation.mockResolvedValue({ action: "cancel" });
+
+      const result = await onUserDialog(
+        {
+          dialogKind: "refusal_fallback_prompt",
+          payload: { originalModel: "a", fallbackModel: "b" },
+        },
+        signal(),
+      );
+
+      expect(result).toEqual({ behavior: "completed", result: "cancelled" });
+    });
+
+    it("cancels unrecognized dialog kinds without presenting anything", async () => {
+      const { onUserDialog, createElicitation } = await setupDialog();
+
+      const result = await onUserDialog(
+        { dialogKind: "some_future_dialog", payload: {} },
+        signal(),
+      );
+
+      expect(result).toEqual({ behavior: "cancelled" });
+      expect(createElicitation).not.toHaveBeenCalled();
+    });
+
+    it("cancels on a malformed payload without presenting anything", async () => {
+      const { onUserDialog, createElicitation } = await setupDialog();
+      // The malformed payload is deliberate — capture the agent's warning
+      // instead of letting it hit the console.
+      const errorSpy = vi.fn();
+      (agent as any).logger = { log: () => {}, error: errorSpy };
+
+      const result = await onUserDialog(
+        { dialogKind: "refusal_fallback_prompt", payload: { fallbackModel: 42 } },
+        signal(),
+      );
+
+      expect(result).toEqual({ behavior: "cancelled" });
+      expect(createElicitation).not.toHaveBeenCalled();
+      expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("unexpected shape"));
+    });
+
+    it("cancels when the elicitation request fails", async () => {
+      const { onUserDialog, createElicitation } = await setupDialog();
+      createElicitation.mockRejectedValue(new Error("client exploded"));
+      // The client failure is deliberate — capture the agent's warning
+      // instead of letting it hit the console.
+      const errorSpy = vi.fn();
+      (agent as any).logger = { log: () => {}, error: errorSpy };
+
+      const result = await onUserDialog(
+        {
+          dialogKind: "refusal_fallback_prompt",
+          payload: { originalModel: "a", fallbackModel: "b" },
+        },
+        signal(),
+      );
+
+      expect(result).toEqual({ behavior: "cancelled" });
+      expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("client exploded"));
+    });
+  });
 });

src/tests/elicitation.test.ts

@@ -11,7 +11,10 @@ import {
   AskUserQuestion,
   createElicitationResponseToElicitResult,
   extractAskUserQuestions,
+  extractRefusalFallbackPrompt,
   mcpElicitationToCreateRequest,
+  refusalFallbackResultFromResponse,
+  refusalFallbackToCreateRequest,
 } from "../elicitation.js";
 
 const SESSION_ID = "session-1";
@@ -19,7 +22,7 @@ const SESSION_ID = "session-1";
 /**
  * Build a question matching the SDK's (strict) AskUserQuestion schema while
  * keeping test sites terse. Option descriptions default to "" (the tool always
- * provides one); pass a description to exercise the "label — description" title.
+ * provides one); pass a description to exercise the enum option's description.
  */
 function mkQuestion(
   question: string,
@@ -124,6 +127,14 @@ describe("createElicitationResponseToElicitResult", () => {
       createElicitationResponseToElicitResult({ action: "cancel" } as CreateElicitationResponse),
     ).toEqual({ action: "cancel" });
   });
+
+  it("maps a custom/future action to cancel", () => {
+    expect(
+      createElicitationResponseToElicitResult({
+        action: "_zed/snooze",
+      } as CreateElicitationResponse),
+    ).toEqual({ action: "cancel" });
+  });
 });
 
 describe("extractAskUserQuestions", () => {
@@ -187,14 +198,10 @@ describe("askUserQuestionsToCreateRequest", () => {
       title: "Library",
       description: undefined,
       oneOf: [
-        {
-          const: "date-fns",
-          title: "date-fns — Lightweight",
-          // Structured description forwarded under `_meta` so clients can render
-          // it as secondary text instead of parsing it out of the title.
-          _meta: { "_claude/askUserQuestionOption": { description: "Lightweight" } },
-        },
-        // No description → no `_meta` emitted.
+        // The description travels in the enum option's first-class field; the
+        // title stays the clean label (no "label — description" flattening).
+        { const: "date-fns", title: "date-fns", description: "Lightweight" },
+        // No description → the field is omitted entirely.
         { const: "luxon", title: "luxon" },
       ],
     });
@@ -202,7 +209,7 @@ describe("askUserQuestionsToCreateRequest", () => {
     expect(schema.properties?.["Which library?"]).toBeUndefined();
   });
 
-  it("forwards option description and preview under _meta for rich clients", () => {
+  it("carries descriptions structurally and forwards previews under _meta", () => {
     const questions = [
       mkQuestion("Which layout?", [
         {
@@ -223,24 +230,22 @@ describe("askUserQuestionsToCreateRequest", () => {
     ).requestedSchema;
     const oneOf = (schema.properties?.["question_0"] as { oneOf: EnumOption[] }).oneOf;
 
-    // Both description and preview travel structurally; the title still flattens
-    // the description for clients that only read const/title.
+    // The description uses the enum option's own field; only the preview —
+    // which still has no structural slot — rides under `_meta`.
     expect(oneOf[0]).toEqual({
       const: "Grid",
-      title: "Grid — Cards in a responsive grid",
+      title: "Grid",
+      description: "Cards in a responsive grid",
       _meta: {
         "_claude/askUserQuestionOption": {
-          description: "Cards in a responsive grid",
           preview: "```\n[ ] [ ] [ ]\n[ ] [ ] [ ]\n```",
         },
       },
     });
-    // Description only → preview omitted from _meta.
-    expect(oneOf[1]._meta).toEqual({
-      "_claude/askUserQuestionOption": { description: "Stacked rows" },
-    });
-    // Neither → no _meta at all.
-    expect(oneOf[2]._meta).toBeUndefined();
+    // Description only → no _meta needed.
+    expect(oneOf[1]).toEqual({ const: "List", title: "List", description: "Stacked rows" });
+    // Neither → just the label.
+    expect(oneOf[2]).toEqual({ const: "Plain", title: "Plain" });
   });
 
   it("includes a per-question optional free-text custom-answer field", () => {
@@ -376,6 +381,13 @@ describe("applyAskElicitationResponse", () => {
     });
   });
 
+  it("returns cancel for a custom/future action it does not understand", () => {
+    const response = { action: "_zed/snooze" } as CreateElicitationResponse;
+    expect(applyAskElicitationResponse(response, toolInput, questions)).toEqual({
+      action: "cancel",
+    });
+  });
+
   it("omits answers for questions the user left unanswered", () => {
     const response = {
       action: "accept",
@@ -389,3 +401,104 @@ describe("applyAskElicitationResponse", () => {
     );
   });
 });
+
+describe("extractRefusalFallbackPrompt", () => {
+  it("extracts required and optional fields", () => {
+    expect(
+      extractRefusalFallbackPrompt({
+        originalModel: "claude-fable-5",
+        fallbackModel: "claude-opus-4-8",
+        apiRefusalCategory: "cyber",
+        guidanceText: "You can retry with the fallback model.",
+        retractedMessageUuids: ["u1"],
+      }),
+    ).toEqual({
+      originalModel: "claude-fable-5",
+      fallbackModel: "claude-opus-4-8",
+      apiRefusalCategory: "cyber",
+      guidanceText: "You can retry with the fallback model.",
+    });
+  });
+
+  it("returns null when a required model field is missing or mistyped", () => {
+    expect(extractRefusalFallbackPrompt({ fallbackModel: "claude-opus-4-8" })).toBeNull();
+    expect(
+      extractRefusalFallbackPrompt({ originalModel: 5, fallbackModel: "claude-opus-4-8" }),
+    ).toBeNull();
+  });
+
+  it("normalizes a non-string category to null and drops empty guidance", () => {
+    expect(
+      extractRefusalFallbackPrompt({
+        originalModel: "a",
+        fallbackModel: "b",
+        apiRefusalCategory: null,
+        guidanceText: "",
+      }),
+    ).toEqual({ originalModel: "a", fallbackModel: "b", apiRefusalCategory: null });
+  });
+});
+
+describe("refusalFallbackToCreateRequest", () => {
+  const prompt = {
+    originalModel: "claude-fable-5",
+    fallbackModel: "claude-opus-4-8",
+    apiRefusalCategory: "cyber" as string | null,
+  };
+
+  it("builds a single-choice form whose enum consts are the dialog's wire results", () => {
+    const request = refusalFallbackToCreateRequest(prompt, SESSION_ID) as Extract<
+      CreateElicitationRequest,
+      { mode: "form" }
+    >;
+    expect(request.mode).toBe("form");
+    expect(request).toMatchObject({ sessionId: SESSION_ID });
+    expect(request.message).toContain("claude-fable-5");
+    expect(request.message).toContain("(cyber)");
+    expect(request.message).toContain("claude-opus-4-8");
+
+    const choice = request.requestedSchema.properties?.choice as {
+      type: string;
+      oneOf: Array<{ const: string; title: string; description?: string }>;
+    };
+    expect(choice.type).toBe("string");
+    expect(choice.oneOf.map((o) => o.const)).toEqual(["retry_fallback", "cancelled"]);
+    expect(choice.oneOf[0].title).toContain("claude-opus-4-8");
+    // Each option explains its consequence in the description field.
+    expect(choice.oneOf[0].description).toContain("claude-opus-4-8");
+    expect(choice.oneOf[1].description).toBeTruthy();
+  });
+
+  it("omits the category marker and appends guidance when provided", () => {
+    const request = refusalFallbackToCreateRequest(
+      { ...prompt, apiRefusalCategory: null, guidanceText: "Consider rephrasing." },
+      SESSION_ID,
+    );
+    expect(request.message).not.toContain("(");
+    expect(request.message).toContain("Consider rephrasing.");
+  });
+});
+
+describe("refusalFallbackResultFromResponse", () => {
+  it("maps an accepted retry choice to retry_fallback", () => {
+    const response = {
+      action: "accept",
+      content: { choice: "retry_fallback" },
+    } as CreateElicitationResponse;
+    expect(refusalFallbackResultFromResponse(response)).toBe("retry_fallback");
+  });
+
+  it("keeps the refusal for every other outcome", () => {
+    const cases = [
+      { action: "accept", content: { choice: "cancelled" } },
+      { action: "accept", content: {} },
+      { action: "accept", content: { choice: "something-new" } },
+      { action: "accept" },
+      { action: "decline" },
+      { action: "cancel" },
+    ] as CreateElicitationResponse[];
+    for (const response of cases) {
+      expect(refusalFallbackResultFromResponse(response)).toBe("cancelled");
+    }
+  });
+});

src/tests/fast-mode-config.test.ts

@@ -1,11 +1,12 @@
 import { describe, it, expect, vi } from "vitest";
 import type { ClientCapabilities, SessionNotification } from "@agentclientprotocol/sdk";
-import type { ModelInfo } from "@anthropic-ai/claude-agent-sdk";
+import type { FastModeDisabledReason, ModelInfo } from "@anthropic-ai/claude-agent-sdk";
 import {
   buildConfigOptions,
   clientSupportsBooleanConfigOptions,
   createFastModeConfigOption,
   fastModeStateEnabled,
+  normalizeFastModeDisabledReason,
   resolveFastModeEnabled,
   FAST_MODE_CONFIG_ID,
   FAST_MODE_ON,
@@ -42,6 +43,28 @@ describe("createFastModeConfigOption", () => {
     });
   });
 
+  it("explains a blocking disabled reason while the toggle reads off", () => {
+    const option = createFastModeConfigOption(false, true, "free");
+    expect(option.description).toBe(
+      "Faster responses on supported models — not available on the free plan",
+    );
+  });
+
+  it("ignores routine and on-state reasons", () => {
+    // Every SDK session starts at `sdk_opt_in_required` — the toggle IS the
+    // opt-in, so it must not read as a blocker.
+    expect(createFastModeConfigOption(false, true, "sdk_opt_in_required").description).toBe(
+      "Faster responses on supported models",
+    );
+    expect(createFastModeConfigOption(false, true, "preference").description).toBe(
+      "Faster responses on supported models",
+    );
+    // A reason riding an `on` state isn't blocking anything right now.
+    expect(createFastModeConfigOption(true, true, "free").description).toBe(
+      "Faster responses on supported models",
+    );
+  });
+
   it("falls back to an on/off select when the client did not opt in", () => {
     const option = createFastModeConfigOption(false, false);
     expect(option).toMatchObject({
@@ -104,6 +127,28 @@ describe("fastModeStateEnabled", () => {
   });
 });
 
+describe("normalizeFastModeDisabledReason", () => {
+  it("retains only reasons we have an explanation for", () => {
+    expect(normalizeFastModeDisabledReason("free")).toBe("free");
+    expect(normalizeFastModeDisabledReason("extra_usage_disabled")).toBe("extra_usage_disabled");
+    expect(normalizeFastModeDisabledReason("model_not_allowed")).toBe("model_not_allowed");
+    expect(normalizeFastModeDisabledReason("not_first_party")).toBe("not_first_party");
+    expect(normalizeFastModeDisabledReason("disabled_by_env")).toBe("disabled_by_env");
+    expect(normalizeFastModeDisabledReason("network_error")).toBe("network_error");
+  });
+
+  it("drops routine states and unknown values", () => {
+    expect(normalizeFastModeDisabledReason("sdk_opt_in_required")).toBeUndefined();
+    expect(normalizeFastModeDisabledReason("preference")).toBeUndefined();
+    expect(normalizeFastModeDisabledReason("pending")).toBeUndefined();
+    expect(normalizeFastModeDisabledReason("unknown")).toBeUndefined();
+    expect(normalizeFastModeDisabledReason(undefined)).toBeUndefined();
+    expect(
+      normalizeFastModeDisabledReason("some_future_reason" as FastModeDisabledReason),
+    ).toBeUndefined();
+  });
+});
+
 describe("buildConfigOptions Fast mode", () => {
   it("omits the Fast mode option when the model does not support it", () => {
     const options = buildConfigOptions(MODES, MODELS, MODEL_INFOS, undefined, [], "default", {
@@ -249,6 +294,7 @@ describe("syncFastModeState (SDK-driven state changes)", () => {
     const session = {
       query: {},
       fastModeEnabled: opts.fastModeEnabled,
+      fastModeDisabledReason: undefined as FastModeDisabledReason | undefined,
       configOptions: opts.withOption
         ? [createFastModeConfigOption(opts.fastModeEnabled, true)]
         : [],
@@ -261,6 +307,7 @@ describe("syncFastModeState (SDK-driven state changes)", () => {
           sessionId: string,
           session: unknown,
           state: string | undefined,
+          reason?: FastModeDisabledReason,
         ) => Promise<void>;
       }
     ).syncFastModeState.bind(agent);
@@ -319,10 +366,65 @@ describe("syncFastModeState (SDK-driven state changes)", () => {
 
     await sync(SESSION_ID, session, undefined);
     await sync(SESSION_ID, session, "off");
+    // A routine reason normalizes away, so it's still "unchanged" — an
+    // `sdk_opt_in_required` on every turn's result must not churn the option.
+    await sync(SESSION_ID, session, "off", "sdk_opt_in_required");
 
     expect(sessionUpdates).toHaveLength(0);
   });
 
+  it("explains a blocking reason once when the SDK refuses a toggle the user turned on", async () => {
+    const { sync, session, sessionUpdates } = setup({ fastModeEnabled: true, withOption: true });
+
+    await sync(SESSION_ID, session, "off", "extra_usage_disabled");
+
+    expect(session.fastModeEnabled).toBe(false);
+    expect(session.fastModeDisabledReason).toBe("extra_usage_disabled");
+    expect(sessionUpdates).toHaveLength(2);
+    expect(sessionUpdates[0].update).toEqual({
+      sessionUpdate: "agent_message_chunk",
+      content: {
+        type: "text",
+        text: "**Fast mode turned off:** requires extra usage to be enabled for this account.",
+      },
+    });
+    expect(sessionUpdates[1].update).toMatchObject({ sessionUpdate: "config_option_update" });
+    expect(session.configOptions).toContainEqual(
+      createFastModeConfigOption(false, true, "extra_usage_disabled"),
+    );
+
+    // The same report again changes nothing the user can see: no repeat notice.
+    await sync(SESSION_ID, session, "off", "extra_usage_disabled");
+    expect(sessionUpdates).toHaveLength(2);
+  });
+
+  it("updates the description when only the reason changes", async () => {
+    const { sync, session, sessionUpdates } = setup({ fastModeEnabled: false, withOption: true });
+
+    await sync(SESSION_ID, session, "off", "not_first_party");
+
+    expect(session.fastModeEnabled).toBe(false);
+    // The toggle was already off, so the flip-time notice doesn't fire — only
+    // the description carries the explanation.
+    expect(sessionUpdates).toHaveLength(1);
+    expect(sessionUpdates[0].update).toMatchObject({ sessionUpdate: "config_option_update" });
+    expect(session.configOptions).toContainEqual(
+      createFastModeConfigOption(false, true, "not_first_party"),
+    );
+  });
+
+  it("drops a retained reason once fast mode comes back on", async () => {
+    const { sync, session } = setup({ fastModeEnabled: false, withOption: true });
+
+    await sync(SESSION_ID, session, "off", "network_error");
+    expect(session.fastModeDisabledReason).toBe("network_error");
+
+    await sync(SESSION_ID, session, "on");
+    expect(session.fastModeEnabled).toBe(true);
+    expect(session.fastModeDisabledReason).toBeUndefined();
+    expect(session.configOptions).toContainEqual(createFastModeConfigOption(true, true));
+  });
+
   it("preserves the retained setting (no clobber) when the model has no Fast mode option", async () => {
     // Model without fast support: the SDK reports a capability-driven state, not
     // the user's intent. We must leave session.fastModeEnabled untouched so it's

src/tests/helpers.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared test doubles. Deliberately vitest-free so `vi.mock` async factories
+ * can `await import("./helpers.js")` without ordering hazards; tests supply
+ * their own vi.fn spies via `overrides`.
+ */
+
+/** The context-usage report the base mock query returns. `rawMaxTokens`
+ *  matches the agent's DEFAULT_CONTEXT_WINDOW so window-related assertions
+ *  don't shift in tests that don't care about context usage. */
+export const DEFAULT_CONTEXT_USAGE = { totalTokens: 0, rawMaxTokens: 200000 };
+
+/**
+ * Base stub for the SDK `query()` return object, covering the surface
+ * ClaudeAcpAgent touches unconditionally at session creation. Tests pass
+ * `overrides` for the parts they assert on (spies, custom models, rejecting
+ * getContextUsage, …).
+ *
+ * When the agent starts calling a new SDK method on every session, add it
+ * here once — the getContextUsage adoption required hand-editing ~10 inline
+ * mocks across five files, and any missed copy didn't fail: it silently
+ * rerouted that test through the error-fallback branch and re-polluted test
+ * output.
+ */
+export function makeMockQuery(overrides: Record<string, unknown> = {}) {
+  return {
+    initializationResult: async () => ({ models: [] }),
+    setModel: async () => {},
+    setPermissionMode: async () => {},
+    supportedCommands: async () => [],
+    getContextUsage: async () => DEFAULT_CONTEXT_USAGE,
+    [Symbol.asyncIterator]: async function* () {},
+    ...overrides,
+  };
+}

src/tests/model-resolution.test.ts

@@ -2,7 +2,11 @@ import { describe, it, expect } from "vitest";
 import { randomUUID } from "crypto";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import type { ModelInfo } from "@anthropic-ai/claude-agent-sdk";
-import { resolveModelPreference, applyAvailableModelsAllowlist } from "../acp-agent.js";
+import {
+  resolveModelPreference,
+  applyAvailableModelsAllowlist,
+  matchResumedModel,
+} from "../acp-agent.js";
 
 // Mirrors a real `supportedModels()` response: alias rows carry
 // `resolvedModel`, and "Sonnet 5" has no `major.minor` dot unlike older
@@ -68,6 +72,124 @@ describe("resolveModelPreference - resolvedModel matching", () => {
   it("returns null for a preference that matches nothing", () => {
     expect(resolveModelPreference(LIVE_SHAPED_MODELS, "claude-gpt-99")).toBeNull();
   });
+
+  it("matches a '-1m' id-suffix preference against a '[1m]'-spelled resolvedModel", () => {
+    // Without hint canonicalization the exact tier misses and the substring
+    // tier lands on the bare 200k sibling, silently downgrading a 1M pin.
+    const models: ModelInfo[] = [
+      {
+        value: "sonnet",
+        resolvedModel: "claude-sonnet-5",
+        displayName: "Sonnet",
+        description: "Sonnet 5 · Efficient for routine tasks",
+      },
+      {
+        value: "sonnet[1m]",
+        resolvedModel: "claude-sonnet-5[1m]",
+        displayName: "Sonnet",
+        description: "Sonnet 5 with 1M context",
+      },
+    ];
+    expect(resolveModelPreference(models, "claude-sonnet-5-1m")?.value).toBe("sonnet[1m]");
+  });
+
+  it("matches a '-1m'-suffix alias directly against a '[1m]'-spelled value", () => {
+    expect(resolveModelPreference(LIVE_SHAPED_MODELS, "opus-1m")?.value).toBe("opus[1m]");
+  });
+
+  // Rows without resolvedModel (older SDKs, allowlist-synthesized entries,
+  // option-derived lists) can't use the exact resolved tier, so the hinted
+  // preference must not be absorbed by the bare sibling in the substring
+  // tier — the tokenized tier scores the hinted row correctly instead.
+  it("does not let a bare sibling absorb a hinted preference when resolvedModel is absent", () => {
+    const models: ModelInfo[] = [
+      { value: "sonnet", displayName: "Sonnet", description: "" },
+      { value: "sonnet[1m]", displayName: "Sonnet", description: "" },
+    ];
+    expect(resolveModelPreference(models, "claude-sonnet-5[1m]")?.value).toBe("sonnet[1m]");
+    expect(resolveModelPreference(models, "claude-sonnet-5-1m")?.value).toBe("sonnet[1m]");
+    // Bare preferences still land on the bare row via the substring tier.
+    expect(resolveModelPreference(models, "claude-sonnet-5")?.value).toBe("sonnet");
+  });
+});
+
+describe("matchResumedModel", () => {
+  // Environment shape from issue #845: the default resolves to Sonnet, the
+  // session was explicitly switched to Opus before the process restart.
+  const SONNET_DEFAULT_MODELS: ModelInfo[] = [
+    {
+      value: "default",
+      resolvedModel: "claude-sonnet-5",
+      displayName: "Default (recommended)",
+      description: "Use the default model (currently Sonnet 5)",
+    },
+    {
+      value: "opus",
+      resolvedModel: "claude-opus-4-6[1m]",
+      displayName: "Opus",
+      description: "Opus 4.6 · Most capable for complex work",
+    },
+    {
+      value: "sonnet",
+      resolvedModel: "claude-sonnet-5",
+      displayName: "Sonnet",
+      description: "Sonnet 5 · Efficient for routine tasks",
+    },
+    {
+      value: "sonnet[1m]",
+      resolvedModel: "claude-sonnet-5[1m]",
+      displayName: "Sonnet",
+      description: "Sonnet 5 with 1M context",
+    },
+  ];
+
+  it("maps an explicitly-switched session's live model to its picker alias", () => {
+    expect(matchResumedModel(SONNET_DEFAULT_MODELS, "claude-opus-4-6").value).toBe("opus");
+    expect(matchResumedModel(SONNET_DEFAULT_MODELS, "claude-opus-4-6[1m]").value).toBe("opus");
+  });
+
+  it("keeps Default selected when the live model is what Default resolves to", () => {
+    expect(matchResumedModel(SONNET_DEFAULT_MODELS, "claude-sonnet-5").value).toBe("default");
+  });
+
+  it("prefers an exact named-row resolvedModel match over the hint-stripped Default tier", () => {
+    // "claude-sonnet-5[1m]" differs from Default's "claude-sonnet-5" only by
+    // the context hint; stripping both would misreport the explicit 1M row as
+    // Default (and infer the wrong context window downstream). Both hint
+    // spellings must land on the row regardless of which one it uses.
+    expect(matchResumedModel(SONNET_DEFAULT_MODELS, "claude-sonnet-5[1m]").value).toBe(
+      "sonnet[1m]",
+    );
+    expect(matchResumedModel(SONNET_DEFAULT_MODELS, "claude-sonnet-5-1m").value).toBe("sonnet[1m]");
+  });
+
+  it("normalizes the '-1m' id-suffix hint form and casing against Default's resolution", () => {
+    expect(matchResumedModel(LIVE_SHAPED_MODELS, "claude-opus-4-8-1m").value).toBe("default");
+    expect(matchResumedModel(LIVE_SHAPED_MODELS, "Claude-Opus-4-8[1M]").value).toBe("default");
+  });
+
+  it("prefers Default over a named row sharing the identical resolvedModel", () => {
+    // "opus[1m]" carries the same resolvedModel as Default; the live id can't
+    // tell the two apart, so a never-customized session stays on Default.
+    expect(matchResumedModel(LIVE_SHAPED_MODELS, "claude-opus-4-8[1m]").value).toBe("default");
+  });
+
+  it("ignores '[1m]' context hints when comparing against Default's resolution", () => {
+    // The transcript-restored model drops the "[1m]" context hint, so a
+    // session that never left the 1M-context default resumes as the bare id.
+    expect(matchResumedModel(LIVE_SHAPED_MODELS, "claude-opus-4-8").value).toBe("default");
+  });
+
+  it("still resolves non-default live models against the picker entries", () => {
+    expect(matchResumedModel(LIVE_SHAPED_MODELS, "claude-sonnet-5").value).toBe("sonnet");
+    expect(matchResumedModel(LIVE_SHAPED_MODELS, "claude-haiku-4-5-20251001").value).toBe("haiku");
+  });
+
+  it("tracks a live model with no picker counterpart verbatim", () => {
+    const result = matchResumedModel(LIVE_SHAPED_MODELS, "claude-gpt-99");
+    expect(result.value).toBe("claude-gpt-99");
+    expect(result.displayName).toBe("claude-gpt-99");
+  });
 });
 
 describe("applyAvailableModelsAllowlist - resolvedModel matching", () => {

src/tests/providers.test.ts

@@ -0,0 +1,303 @@
+import { describe, expect, it, Mock, vi, afterEach, beforeEach } from "vitest";
+import { AcpClient, ClaudeAcpAgent } from "../acp-agent.js";
+
+const mockQuery = vi.hoisted(() =>
+  vi.fn(() => ({
+    initializationResult: vi.fn().mockResolvedValue({
+      models: [
+        { value: "id", displayName: "name", description: "description", supportsAutoMode: true },
+      ],
+    }),
+    setModel: vi.fn(),
+    setPermissionMode: vi.fn(),
+    supportedCommands: vi.fn().mockResolvedValue([]),
+  })),
+);
+
+vi.mock("@anthropic-ai/claude-agent-sdk", async () => ({
+  ...(await vi.importActual<typeof import("@anthropic-ai/claude-agent-sdk")>(
+    "@anthropic-ai/claude-agent-sdk",
+  )),
+  query: mockQuery,
+}));
+
+// `logout` shells out to `claude auth logout`; make execFile succeed so the
+// real logout body runs (and clears provider config) without a live CLI.
+vi.mock("node:child_process", async () => {
+  const actual = await vi.importActual<typeof import("node:child_process")>("node:child_process");
+  return {
+    ...actual,
+    execFile: vi.fn((_file: string, _args: string[], cb: (...a: unknown[]) => void) =>
+      cb(null, { stdout: "", stderr: "" }),
+    ),
+  };
+});
+
+describe("providers", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.runAllTimers();
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+    vi.resetAllMocks();
+  });
+
+  async function createAgentMock(): Promise<[ClaudeAcpAgent, Mock]> {
+    const connectionMock = {
+      sessionUpdate: async (_: any) => {},
+    } as AcpClient;
+    const agent = new ClaudeAcpAgent(connectionMock);
+    return [agent, mockQuery];
+  }
+
+  it("advertises the providers capability in initialize", async () => {
+    const [agent] = await createAgentMock();
+    const response = await agent.initialize({ protocolVersion: 1, clientCapabilities: {} });
+    expect(response.agentCapabilities?.providers).toEqual({});
+  });
+
+  it("lists a single optional 'main' provider, unconfigured by default", async () => {
+    const [agent] = await createAgentMock();
+    const response = await agent.unstable_listProviders({});
+    expect(response.providers).toEqual([
+      {
+        providerId: "main",
+        supported: ["anthropic", "bedrock", "vertex"],
+        required: false,
+        current: null,
+      },
+    ]);
+  });
+
+  it("reflects apiType/baseUrl after set, and never echoes headers", async () => {
+    const [agent] = await createAgentMock();
+    await agent.unstable_setProvider({
+      providerId: "main",
+      apiType: "anthropic",
+      baseUrl: "https://gateway.example/v1",
+      headers: { authorization: "Bearer secret" },
+    });
+
+    const response = await agent.unstable_listProviders({});
+    expect(response.providers[0].current).toEqual({
+      apiType: "anthropic",
+      baseUrl: "https://gateway.example/v1",
+    });
+    // headers must not leak through list
+    expect(JSON.stringify(response.providers)).not.toContain("secret");
+  });
+
+  it("rejects set for an unknown providerId", async () => {
+    const [agent] = await createAgentMock();
+    await expect(
+      agent.unstable_setProvider({
+        providerId: "openai",
+        apiType: "anthropic",
+        baseUrl: "https://gateway.example",
+      }),
+    ).rejects.toMatchObject({ code: -32602 });
+  });
+
+  it("rejects set for an unsupported apiType", async () => {
+    const [agent] = await createAgentMock();
+    await expect(
+      agent.unstable_setProvider({
+        providerId: "main",
+        apiType: "openai",
+        baseUrl: "https://gateway.example",
+      }),
+    ).rejects.toMatchObject({ code: -32602 });
+  });
+
+  it("rejects set for an empty or non-http baseUrl", async () => {
+    const [agent] = await createAgentMock();
+    await expect(
+      agent.unstable_setProvider({ providerId: "main", apiType: "anthropic", baseUrl: "" }),
+    ).rejects.toMatchObject({ code: -32602 });
+    await expect(
+      agent.unstable_setProvider({
+        providerId: "main",
+        apiType: "anthropic",
+        baseUrl: "ftp://nope.example",
+      }),
+    ).rejects.toMatchObject({ code: -32602 });
+  });
+
+  it("disables the 'main' provider by clearing config and reporting current: null", async () => {
+    const [agent] = await createAgentMock();
+    await agent.unstable_setProvider({
+      providerId: "main",
+      apiType: "anthropic",
+      baseUrl: "https://gateway.example/v1",
+    });
+    expect((await agent.unstable_listProviders({})).providers[0].current).not.toBeNull();
+
+    await expect(agent.unstable_disableProvider({ providerId: "main" })).resolves.toEqual({});
+
+    expect((await agent.unstable_listProviders({})).providers[0].current).toBeNull();
+  });
+
+  it("treats disabling an unknown provider as an idempotent no-op", async () => {
+    const [agent] = await createAgentMock();
+    await expect(agent.unstable_disableProvider({ providerId: "openai" })).resolves.toEqual({});
+  });
+
+  it("routes anthropic provider config into session env", async () => {
+    const [agent, mockQuery] = await createAgentMock();
+    await agent.initialize({ protocolVersion: 1, clientCapabilities: {} });
+    await agent.unstable_setProvider({
+      providerId: "main",
+      apiType: "anthropic",
+      baseUrl: "https://gateway.example",
+      headers: { "x-api-key": "test" },
+    });
+
+    await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.objectContaining({
+        options: expect.objectContaining({
+          env: expect.objectContaining({
+            ANTHROPIC_AUTH_TOKEN: " ",
+            ANTHROPIC_BASE_URL: "https://gateway.example",
+            ANTHROPIC_CUSTOM_HEADERS: "x-api-key: test",
+          }),
+        }),
+      }),
+    );
+  });
+
+  it("routes bedrock provider config into session env", async () => {
+    const [agent, mockQuery] = await createAgentMock();
+    await agent.initialize({ protocolVersion: 1, clientCapabilities: {} });
+    await agent.unstable_setProvider({
+      providerId: "main",
+      apiType: "bedrock",
+      baseUrl: "https://gateway.example",
+      headers: { "custom-header": "test" },
+    });
+
+    await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.objectContaining({
+        options: expect.objectContaining({
+          env: expect.objectContaining({
+            CLAUDE_CODE_USE_BEDROCK: "1",
+            AWS_BEARER_TOKEN_BEDROCK: " ",
+            ANTHROPIC_BEDROCK_BASE_URL: "https://gateway.example",
+            ANTHROPIC_CUSTOM_HEADERS: "custom-header: test",
+          }),
+        }),
+      }),
+    );
+  });
+
+  it("accepts vertex config via _meta and routes it into session env", async () => {
+    const [agent, mockQuery] = await createAgentMock();
+    await agent.initialize({ protocolVersion: 1, clientCapabilities: {} });
+    await agent.unstable_setProvider({
+      providerId: "main",
+      apiType: "vertex",
+      baseUrl: "https://vertex.example",
+      headers: { "custom-header": "test" },
+      _meta: { claudeCode: { vertex: { projectId: "my-project", region: "us-east5" } } },
+    });
+
+    // list surfaces apiType/baseUrl but not the _meta extras
+    const listed = await agent.unstable_listProviders({});
+    expect(listed.providers[0].current).toEqual({
+      apiType: "vertex",
+      baseUrl: "https://vertex.example",
+    });
+
+    await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.objectContaining({
+        options: expect.objectContaining({
+          env: expect.objectContaining({
+            CLAUDE_CODE_USE_VERTEX: "1",
+            ANTHROPIC_VERTEX_BASE_URL: "https://vertex.example",
+            ANTHROPIC_VERTEX_PROJECT_ID: "my-project",
+            CLOUD_ML_REGION: "us-east5",
+            ANTHROPIC_CUSTOM_HEADERS: "custom-header: test",
+          }),
+        }),
+      }),
+    );
+  });
+
+  it("rejects vertex set without _meta project/region", async () => {
+    const [agent] = await createAgentMock();
+    await expect(
+      agent.unstable_setProvider({
+        providerId: "main",
+        apiType: "vertex",
+        baseUrl: "https://vertex.example",
+      }),
+    ).rejects.toMatchObject({ code: -32602 });
+
+    // partial _meta (missing region) is also rejected
+    await expect(
+      agent.unstable_setProvider({
+        providerId: "main",
+        apiType: "vertex",
+        baseUrl: "https://vertex.example",
+        _meta: { claudeCode: { vertex: { projectId: "my-project" } } } as any,
+      }),
+    ).rejects.toMatchObject({ code: -32602 });
+  });
+
+  it("providers/set takes precedence over gateway auth", async () => {
+    const [agent, mockQuery] = await createAgentMock();
+    await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: { auth: { terminal: true, _meta: { gateway: true } } } as any,
+    });
+
+    // Gateway auth first...
+    await agent.authenticate({
+      methodId: "gateway",
+      _meta: { gateway: { baseUrl: "https://gateway.example", headers: {} } },
+    });
+    // ...then providers/set wins.
+    await agent.unstable_setProvider({
+      providerId: "main",
+      apiType: "anthropic",
+      baseUrl: "https://provider.example",
+    });
+
+    await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.objectContaining({
+        options: expect.objectContaining({
+          env: expect.objectContaining({
+            ANTHROPIC_BASE_URL: "https://provider.example",
+          }),
+        }),
+      }),
+    );
+  });
+
+  it("clears provider config on logout", async () => {
+    const [agent] = await createAgentMock();
+    // Avoids resolving the native CLI binary in claudeCliPath().
+    vi.stubEnv("CLAUDE_CODE_EXECUTABLE", "/bin/true");
+
+    await agent.unstable_setProvider({
+      providerId: "main",
+      apiType: "anthropic",
+      baseUrl: "https://provider.example",
+    });
+    expect((await agent.unstable_listProviders({})).providers[0].current).not.toBeNull();
+
+    await agent.logout({});
+
+    expect((await agent.unstable_listProviders({})).providers[0].current).toBeNull();
+  });
+});

src/tests/resolve-permission-mode.test.ts

@@ -29,6 +29,13 @@ describe("resolvePermissionMode", () => {
     expect(resolvePermissionMode("bypass")).toBe("bypassPermissions");
   });
 
+  it("resolves 'manual' as an alias for 'default'", () => {
+    const { logger, error } = mockLogger();
+    expect(resolvePermissionMode("manual", logger)).toBe("default");
+    expect(resolvePermissionMode("Manual", logger)).toBe("default");
+    expect(error).not.toHaveBeenCalled();
+  });
+
   it("trims whitespace", () => {
     expect(resolvePermissionMode("  dontAsk  ")).toBe("dontAsk");
   });

src/tests/session-config-options.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach, vi } from "vitest";
 import { SessionNotification } from "@agentclientprotocol/sdk";
 import type { ModelInfo } from "@anthropic-ai/claude-agent-sdk";
 import type { AcpClient, ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
+import { makeMockQuery } from "./helpers.js";
 
 const { registerHookCallbackSpy } = vi.hoisted(() => ({
   registerHookCallbackSpy: vi.fn(),
@@ -101,12 +102,11 @@ describe("session config options", () => {
     applyFlagSettingsSpy = vi.fn();
 
     (agent as unknown as { sessions: Record<string, unknown> }).sessions[SESSION_ID] = {
-      query: {
+      query: makeMockQuery({
         setPermissionMode: setPermissionModeSpy,
         setModel: setModelSpy,
         applyFlagSettings: applyFlagSettingsSpy,
-        supportedCommands: async () => [],
-      },
+      }),
       input: null,
       cancelled: false,
       permissionMode: "default",
@@ -819,6 +819,85 @@ describe("session config options", () => {
       expect(setModelSpy).toHaveBeenCalledWith("claude-sonnet-4-6");
     });
 
+    // Option entries carry no resolvedModel, so alias resolution must consult
+    // session.modelInfos — otherwise a full model id in either hint spelling
+    // ("[1m]"/"-1m") falls to the substring tier and lands on the bare 200k
+    // sibling, silently downgrading the session's context lane.
+    it("resolves a full model id onto its hinted row via session.modelInfos", async () => {
+      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
+      session.models = {
+        currentModelId: "sonnet",
+        availableModels: [
+          { modelId: "sonnet", name: "Sonnet", description: "" },
+          { modelId: "sonnet[1m]", name: "Sonnet", description: "" },
+        ],
+      };
+      session.modelInfos = [
+        {
+          value: "sonnet",
+          resolvedModel: "claude-sonnet-5",
+          displayName: "Sonnet",
+          description: "",
+        },
+        {
+          value: "sonnet[1m]",
+          resolvedModel: "claude-sonnet-5[1m]",
+          displayName: "Sonnet",
+          description: "",
+        },
+      ];
+      session.configOptions = session.configOptions.map((o: { id: string }) =>
+        o.id === "model"
+          ? {
+              ...o,
+              currentValue: "sonnet",
+              options: [
+                { value: "sonnet", name: "Sonnet" },
+                { value: "sonnet[1m]", name: "Sonnet" },
+              ],
+            }
+          : o,
+      );
+
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-5[1m]",
+      });
+      expect(setModelSpy).toHaveBeenCalledWith("sonnet[1m]");
+
+      setModelSpy.mockClear();
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-5-1m",
+      });
+      expect(setModelSpy).toHaveBeenCalledWith("sonnet[1m]");
+    });
+
+    // A session can be running a model with no picker entry (resumed onto a
+    // model excluded by the availableModels allowlist, or a refusal
+    // fallback); its verbatim id is then the option's currentValue. A client
+    // round-tripping that reported value must not get "Invalid value".
+    it("accepts the reported currentValue even when it has no options entry", async () => {
+      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
+      session.models = { ...session.models, currentModelId: "claude-offlist-9" };
+      session.configOptions = session.configOptions.map((o: { id: string }) =>
+        o.id === "model" ? { ...o, currentValue: "claude-offlist-9" } : o,
+      );
+
+      const response = await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-offlist-9",
+      });
+
+      expect(setModelSpy).toHaveBeenCalledWith("claude-offlist-9");
+      expect(response.configOptions?.find((o) => o.id === "model")?.currentValue).toBe(
+        "claude-offlist-9",
+      );
+    });
+
     it("setSessionMode also syncs configOptions", async () => {
       await agent.setSessionMode({ sessionId: SESSION_ID, modeId: "plan" });
 
@@ -848,6 +927,84 @@ describe("session config options", () => {
     });
   });
 
+  describe("context window on model change", () => {
+    beforeEach(() => {
+      populateSession();
+    });
+
+    function getSession() {
+      return (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
+    }
+
+    it("sets the window from text inference on model switch, without any getContextUsage IPC", async () => {
+      // getContextUsage stalls until the session's first prompt turn, so the
+      // switch path must never call it; the window is seeded from the text
+      // heuristic (here via the new model's resolvedModel) and later confirmed
+      // by result.modelUsage.
+      const session = getSession();
+      session.query.getContextUsage = vi.fn(async () => ({ rawMaxTokens: 967000 }));
+      session.modelInfos = session.modelInfos.map((m: ModelInfo) =>
+        m.value === "claude-sonnet-4-6" ? { ...m, resolvedModel: "claude-sonnet-5[1m]" } : m,
+      );
+
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-4-6",
+      });
+
+      expect(session.query.getContextUsage).not.toHaveBeenCalled();
+      expect(session.contextWindowSize).toBe(1_000_000);
+    });
+
+    it("falls back to the default window when inference misses, without any getContextUsage IPC", async () => {
+      const session = getSession();
+      session.contextWindowSize = 1_000_000;
+      // Present but must NOT be called; the switch never consults it.
+      session.query.getContextUsage = vi.fn(async () => ({ rawMaxTokens: 967000 }));
+      // claude-sonnet-4-6 carries no "1m" token in its id, resolvedModel,
+      // displayName, or description, so inference misses → default window.
+
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-4-6",
+      });
+
+      expect(session.query.getContextUsage).not.toHaveBeenCalled();
+      expect(session.contextWindowSize).toBe(200000);
+    });
+
+    it("does not call getContextUsage even when switching to a fresh model", async () => {
+      const session = getSession();
+      const spy = vi.fn(async () => ({ rawMaxTokens: 967000 }));
+      session.query.getContextUsage = spy;
+
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-4-6",
+      });
+
+      expect(spy).not.toHaveBeenCalled();
+    });
+
+    it("keeps the learned window when re-asserting the current model", async () => {
+      const session = getSession();
+      session.contextWindowSize = 1_000_000;
+      session.query.getContextUsage = vi.fn(async () => ({ rawMaxTokens: 200000 }));
+
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-opus-4-5",
+      });
+
+      expect(session.query.getContextUsage).not.toHaveBeenCalled();
+      expect(session.contextWindowSize).toBe(1_000_000);
+    });
+  });
+
   describe("auto mode availability per model", () => {
     /**
      * Augment the session populated by `populateSession()` with a Haiku entry

src/tests/session-load.test.ts

@@ -6,9 +6,11 @@ import { AcpClient, ClaudeAcpAgent } from "../acp-agent.js";
 import { Pushable } from "../utils.js";
 import type { SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
 
-function createMockClient(): AcpClient {
+function createMockClient(
+  sessionUpdate: (notification: SessionNotification) => Promise<void> = async () => {},
+): AcpClient {
   return {
-    sessionUpdate: async (_notification: SessionNotification) => {},
+    sessionUpdate,
     requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
     readTextFile: async () => ({ content: "" }),
     writeTextFile: async () => ({}),
@@ -330,4 +332,52 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("session load/resume lifecyc
     }
     expect(recordedUserChunks.some((c) => c.includes("hi"))).toBe(true);
   }, 60000);
+
+  // Regression test for https://github.com/agentclientprotocol/claude-agent-acp/issues/845
+  // On resume the CLI restores the model the session's transcript was running,
+  // so loadSession must report that live model instead of recomputing the
+  // env/settings/default choice from scratch. Haiku is used because no account
+  // resolves its default there, so the restored model provably differs from
+  // the freshly-computed default. Requires no ANTHROPIC_MODEL env var and no
+  // "model" key in settings.json (either would pin the model on resume and
+  // mask the reconciliation this test covers).
+  it("ACP: loadSession reports the model the resumed session is actually running", async () => {
+    const agentChunks: string[] = [];
+    const client = createMockClient(async (notification) => {
+      if (notification.update.sessionUpdate === "agent_message_chunk") {
+        const content = notification.update.content;
+        if (content.type === "text") agentChunks.push(content.text);
+      }
+    });
+
+    const modelOf = (opts: { id: string; currentValue?: unknown }[] | null | undefined) =>
+      opts?.find((o) => o.id === "model")?.currentValue;
+
+    const agent = new ClaudeAcpAgent(client);
+    try {
+      const cwd = process.cwd();
+      const { sessionId, configOptions } = await agent.newSession({ cwd, mcpServers: [] });
+      expect(modelOf(configOptions)).not.toBe("haiku");
+
+      await agent.setSessionConfigOption({ sessionId, configId: "model", value: "haiku" });
+      // A real turn on Haiku, so the transcript's last assistant message —
+      // which is what the CLI restores the model from — records it.
+      await agent.prompt({
+        sessionId,
+        prompt: [{ type: "text", text: "Reply with only the word OK" }],
+      });
+      await agent.closeSession({ sessionId });
+
+      const loadResp = await agent.loadSession({ sessionId, cwd, mcpServers: [] });
+      expect(modelOf(loadResp.configOptions)).toBe("haiku");
+
+      // And the reported option agrees with the live session (`/context`).
+      agentChunks.length = 0;
+      await agent.prompt({ sessionId, prompt: [{ type: "text", text: "/context" }] });
+      const liveModel = agentChunks.join("\n").match(/\*\*Model:\*\*\s*(\S+)/)?.[1];
+      expect(liveModel).toContain("haiku");
+    } finally {
+      await agent.dispose();
+    }
+  }, 120000);
 });

src/tests/tools.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach } from "vitest";
+import { describe, it, expect, beforeEach, vi } from "vitest";
 import { ClientCapabilities } from "@agentclientprotocol/sdk";
 import { ImageBlockParam, ToolResultBlockParam } from "@anthropic-ai/sdk/resources";
 import {
@@ -491,6 +491,94 @@ describe("Bash terminal output", () => {
       });
     });
 
+    it("keys the terminal metas off the tool_use id, which is what was announced", () => {
+      // `toolInfoFromToolUse` announces the terminal as `toolUse.id`, so the
+      // result's metas have to use the same value for the client to match them
+      // up. A result block that disagrees (or omits `tool_use_id`) must not be
+      // allowed to retarget them.
+      const toolResult = {
+        ...makeBashResult("out", "", 0),
+        tool_use_id: "toolu_something_else",
+      };
+      const update = toolUpdateFromToolResult(toolResult, bashToolUse, true);
+
+      expect(update.content).toEqual([{ type: "terminal", terminalId: "toolu_bash" }]);
+      expect(update._meta).toEqual({
+        terminal_info: { terminal_id: "toolu_bash" },
+        terminal_output: { terminal_id: "toolu_bash", data: "out" },
+        terminal_exit: { terminal_id: "toolu_bash", exit_code: 0, signal: null },
+      });
+    });
+
+    it("falls back to the result's tool_use_id when the tool_use is unavailable", () => {
+      const toolResult = makeBashResult("out", "", 0);
+      const update = toolUpdateFromToolResult(toolResult, { name: "Bash" }, true);
+
+      expect(update.content).toEqual([{ type: "terminal", terminalId: "toolu_bash" }]);
+      expect(update._meta).toEqual({
+        terminal_info: { terminal_id: "toolu_bash" },
+        terminal_output: { terminal_id: "toolu_bash", data: "out" },
+        terminal_exit: { terminal_id: "toolu_bash", exit_code: 0, signal: null },
+      });
+    });
+
+    it("renders a code block instead of a dangling terminal when no id is available", () => {
+      // Previously this emitted `terminal_id: ""` for all three metas. Nothing
+      // on the client has a terminal under that id, so the output was stranded
+      // (Zed buffers output/exit for unknown terminals indefinitely) and the
+      // user saw an empty terminal. Degrade to the non-terminal rendering.
+      // `tool_use_id` is required on every result-block type, so a block without
+      // it can only arrive at runtime (an older or non-conforming emitter). The
+      // source guards for it with `"tool_use_id" in toolResult`, so exercise that
+      // path with a cast rather than pretending the type allows it.
+      const { content, type } = makeBashResult("out", "", 0);
+      const update = toolUpdateFromToolResult(
+        { content, type } as unknown as Parameters<typeof toolUpdateFromToolResult>[0],
+        { name: "Bash" },
+        true,
+      );
+
+      expect(update._meta).toBeUndefined();
+      expect(update.content).toEqual([
+        {
+          type: "content",
+          content: { type: "text", text: "```console\nout\n```" },
+        },
+      ]);
+    });
+
+    it("treats an empty tool_use id as no id and falls back to the result block", () => {
+      const toolResult = makeBashResult("out", "", 0);
+      const update = toolUpdateFromToolResult(toolResult, { id: "", name: "Bash" }, true);
+
+      expect(update.content).toEqual([{ type: "terminal", terminalId: "toolu_bash" }]);
+      expect(update._meta).toEqual({
+        terminal_info: { terminal_id: "toolu_bash" },
+        terminal_output: { terminal_id: "toolu_bash", data: "out" },
+        terminal_exit: { terminal_id: "toolu_bash", exit_code: 0, signal: null },
+      });
+    });
+
+    it("renders a code block when neither id is a usable string", () => {
+      // A present-but-undefined `tool_use_id` still satisfies an `in` check, and
+      // stringifying it would key all three metas on the literal "undefined" — an
+      // id no client ever created a terminal for, so the output strands exactly as
+      // it did under the old empty-string id.
+      const toolResult = {
+        ...makeBashResult("out", "", 0),
+        tool_use_id: undefined,
+      } as unknown as Parameters<typeof toolUpdateFromToolResult>[0];
+      const update = toolUpdateFromToolResult(toolResult, { id: "", name: "Bash" }, true);
+
+      expect(update._meta).toBeUndefined();
+      expect(update.content).toEqual([
+        {
+          type: "content",
+          content: { type: "text", text: "```console\nout\n```" },
+        },
+      ]);
+    });
+
     it("should include exit_code from return_code in terminal_exit", () => {
       const toolResult = makeBashResult("", "command not found", 127);
       const update = toolUpdateFromToolResult(toolResult, bashToolUse, true);
@@ -1024,7 +1112,7 @@ describe("Bash terminal output", () => {
       );
 
       // Fire PostToolUse hook with a structuredPatch in tool_response
-      const hook = createPostToolUseHook(mockLogger);
+      const hook = createPostToolUseHook();
       await hook(
         {
           hook_event_name: "PostToolUse",
@@ -1102,7 +1190,7 @@ describe("Bash terminal output", () => {
         mockLogger,
       );
 
-      const hook = createPostToolUseHook(mockLogger);
+      const hook = createPostToolUseHook();
       await hook(
         {
           hook_event_name: "PostToolUse",
@@ -1182,7 +1270,7 @@ describe("Bash terminal output", () => {
         mockLogger,
       );
 
-      const hook = createPostToolUseHook(mockLogger);
+      const hook = createPostToolUseHook();
       await hook(
         {
           hook_event_name: "PostToolUse",
@@ -1203,6 +1291,36 @@ describe("Bash terminal output", () => {
       expect(hookUpdate.content).toBeUndefined();
       expect(hookUpdate.locations).toBeUndefined();
     });
+
+    // Regression for issue #889: tool uses that never register a callback
+    // (TodoWrite/Task* are rendered as plan updates, not tool_calls) fire the
+    // PostToolUse hook too. That's expected — the hook must stay silent
+    // instead of spamming "No onPostToolUseHook found" to stderr.
+    it("should not log an error when no callback is registered for the tool use", async () => {
+      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+      try {
+        const hook = createPostToolUseHook();
+        const result = await hook(
+          {
+            hook_event_name: "PostToolUse",
+            tool_name: "TodoWrite",
+            tool_input: { todos: [] },
+            tool_response: { success: true },
+            tool_use_id: "toolu_todo_no_callback",
+            session_id: "test-session",
+            transcript_path: "/tmp/test",
+            cwd: "/tmp",
+          },
+          "toolu_todo_no_callback",
+          { signal: AbortSignal.abort() },
+        );
+
+        expect(result).toEqual({ continue: true });
+        expect(errorSpy).not.toHaveBeenCalled();
+      } finally {
+        errorSpy.mockRestore();
+      }
+    });
   });
 
   describe("post-tool-use hook sends diff content for Write tool", () => {
@@ -1239,7 +1357,7 @@ describe("Bash terminal output", () => {
         mockLogger,
       );
 
-      const hook = createPostToolUseHook(mockLogger);
+      const hook = createPostToolUseHook();
       await hook(
         {
           hook_event_name: "PostToolUse",
@@ -1315,7 +1433,7 @@ describe("Bash terminal output", () => {
         mockLogger,
       );
 
-      const hook = createPostToolUseHook(mockLogger);
+      const hook = createPostToolUseHook();
       await hook(
         {
           hook_event_name: "PostToolUse",
@@ -1438,7 +1556,7 @@ describe("Bash terminal output", () => {
       expect((resultNotifications[1].update as any).status).toBe("completed");
 
       // Step 3: Fire the PostToolUse hook (simulates what Claude Code SDK does)
-      const hook = createPostToolUseHook(mockLogger);
+      const hook = createPostToolUseHook();
       await hook(
         {
           hook_event_name: "PostToolUse",
@@ -1519,7 +1637,7 @@ describe("Bash terminal output", () => {
       );
 
       // Fire hook
-      const hook = createPostToolUseHook(mockLogger);
+      const hook = createPostToolUseHook();
       await hook(
         {
           hook_event_name: "PostToolUse",
@@ -2153,3 +2271,716 @@ describe("createTaskHook", () => {
     expect(changes).toBe(0);
   });
 });
+
+describe("empty message content is not emitted", () => {
+  const mockClient = {} as AcpClient;
+  const mockLogger: Logger = { log: () => {}, error: () => {} };
+
+  it("drops an empty string content instead of emitting an empty agent_message_chunk", () => {
+    const notifications = toAcpNotifications(
+      "",
+      "assistant",
+      "test-session",
+      {},
+      mockClient,
+      mockLogger,
+    );
+    expect(notifications).toHaveLength(0);
+  });
+
+  it("still emits non-empty string content", () => {
+    const notifications = toAcpNotifications(
+      "hello",
+      "assistant",
+      "test-session",
+      {},
+      mockClient,
+      mockLogger,
+    );
+    expect(notifications).toHaveLength(1);
+    expect(notifications[0].update).toMatchObject({
+      sessionUpdate: "agent_message_chunk",
+      content: { type: "text", text: "hello" },
+    });
+  });
+
+  it("drops an empty streamed text block but keeps a non-empty one", () => {
+    const notifications = toAcpNotifications(
+      [
+        { type: "text", text: "" },
+        { type: "text", text: "real" },
+      ] as any,
+      "assistant",
+      "test-session",
+      {},
+      mockClient,
+      mockLogger,
+    );
+    expect(notifications).toHaveLength(1);
+    expect(notifications[0].update).toMatchObject({
+      sessionUpdate: "agent_message_chunk",
+      content: { type: "text", text: "real" },
+    });
+  });
+});
+
+describe("Agent/Task tool_result rendering from tool_use_result", () => {
+  const mockClient = {} as AcpClient;
+  const mockLogger: Logger = { log: () => {}, error: () => {} };
+
+  const TRAILER =
+    "\nagentId: a0e1eff08fcb6e2e8 (use SendMessage with to: 'a0e1eff08fcb6e2e8', summary: '<5-10 word recap>' to continue this agent)\n<usage>subagent_tokens: 11735\ntool_uses: 2\nduration_ms: 21237</usage>";
+
+  const agentToolUse = {
+    type: "tool_use" as const,
+    id: "toolu_agent",
+    name: "Task",
+    input: { description: "Explore", prompt: "look around" },
+  };
+
+  const rawResult: ToolResultBlockParam = {
+    type: "tool_result",
+    tool_use_id: "toolu_agent",
+    content: [{ type: "text", text: `The report.${TRAILER}` }],
+  };
+
+  const structured = {
+    status: "completed",
+    agentId: "a0e1eff08fcb6e2e8",
+    content: [{ type: "text", text: "The structured report." }],
+    totalTokens: 11735,
+    totalToolUseCount: 2,
+    totalDurationMs: 21237,
+  };
+
+  it("renders the structured subagent report instead of the raw trailer text", () => {
+    const update = toolUpdateFromToolResult(rawResult, agentToolUse, false, structured);
+
+    expect(update).toEqual({
+      content: [{ type: "content", content: { type: "text", text: "The structured report." } }],
+    });
+  });
+
+  it("strips the trailer from the raw fallback when tool_use_result is absent", () => {
+    // Replayed sessions and older CLIs have no structured report; the
+    // tail-anchored strip is the only cleanup available there.
+    const update = toolUpdateFromToolResult(rawResult, agentToolUse, false);
+
+    expect(update).toEqual({
+      content: [{ type: "content", content: { type: "text", text: "The report." } }],
+    });
+  });
+
+  it("strips only matching trailer parts and leaves unrecognized text alone", () => {
+    const oddResult: ToolResultBlockParam = {
+      type: "tool_result",
+      tool_use_id: "toolu_agent",
+      content: [
+        { type: "text", text: "Report A.\n<usage>subagent_tokens: 5</usage>" },
+        { type: "text", text: "Report B.\nagentId: abc-123 (for resuming)" },
+        { type: "text", text: "agentId mentioned mid-text (not a trailer) stays.\nDone." },
+      ],
+    };
+    const update = toolUpdateFromToolResult(oddResult, agentToolUse, false);
+
+    expect(update.content).toEqual([
+      { type: "content", content: { type: "text", text: "Report A." } },
+      { type: "content", content: { type: "text", text: "Report B." } },
+      {
+        type: "content",
+        content: { type: "text", text: "agentId mentioned mid-text (not a trailer) stays.\nDone." },
+      },
+    ]);
+  });
+
+  it("leaves malformed trailers alone", () => {
+    // Incomplete trailers are ordinary report text, not metadata to strip.
+    const malformedResult: ToolResultBlockParam = {
+      type: "tool_result",
+      tool_use_id: "toolu_agent",
+      content: [
+        { type: "text", text: "Report.\n<usage>missing closing tag" },
+        { type: "text", text: "Report.\nagentId: abc-123 (missing closing paren" },
+      ],
+    };
+
+    const update = toolUpdateFromToolResult(malformedResult, agentToolUse, false);
+
+    expect(update.content).toEqual([
+      { type: "content", content: { type: "text", text: "Report.\n<usage>missing closing tag" } },
+      {
+        type: "content",
+        content: { type: "text", text: "Report.\nagentId: abc-123 (missing closing paren" },
+      },
+    ]);
+  });
+
+  it("strips only the trailer when the report itself mentions <usage>", () => {
+    const result: ToolResultBlockParam = {
+      type: "tool_result",
+      tool_use_id: "toolu_agent",
+      content: "Grep for <usage> found 3 hits.\n<usage>subagent_tokens: 5</usage>",
+    };
+    const update = toolUpdateFromToolResult(result, agentToolUse, false);
+
+    expect(update.content).toEqual([
+      { type: "content", content: { type: "text", text: "Grep for <usage> found 3 hits." } },
+    ]);
+  });
+
+  it("handles adversarial trailer-shaped input in linear time", () => {
+    // Regression: the old regex-based strip backtracked quadratically on
+    // these shapes (CodeQL js/polynomial-redos) — at this size it would
+    // blow the test timeout rather than merely run slow.
+    const result: ToolResultBlockParam = {
+      type: "tool_result",
+      tool_use_id: "toolu_agent",
+      content: [
+        { type: "text", text: "agentId: - (".repeat(20000) },
+        { type: "text", text: "<usage>".repeat(30000) },
+      ],
+    };
+    const update = toolUpdateFromToolResult(result, agentToolUse, false);
+
+    // Neither is a real trailer, so both come through unchanged.
+    expect(update.content).toEqual([
+      { type: "content", content: { type: "text", text: "agentId: - (".repeat(20000) } },
+      { type: "content", content: { type: "text", text: "<usage>".repeat(30000) } },
+    ]);
+  });
+
+  it("falls back (trailer-stripped) when tool_use_result is the async_launched variant", () => {
+    const update = toolUpdateFromToolResult(rawResult, agentToolUse, false, {
+      status: "async_launched",
+      agentId: "a0e1eff08fcb6e2e8",
+      description: "Explore",
+    });
+
+    expect(update.content).toEqual([
+      { type: "content", content: { type: "text", text: "The report." } },
+    ]);
+  });
+
+  it("falls back (trailer-stripped) when the structured content array is empty", () => {
+    // A completed subagent can end with zero text blocks — an empty
+    // structured render must not beat the raw fallback.
+    const update = toolUpdateFromToolResult(rawResult, agentToolUse, false, {
+      ...structured,
+      content: [],
+    });
+
+    expect(update.content).toEqual([
+      { type: "content", content: { type: "text", text: "The report." } },
+    ]);
+  });
+
+  it("threads options.toolUseResult through toAcpNotifications for a lone tool_result", () => {
+    const toolUseCache: ToolUseCache = { toolu_agent: agentToolUse };
+
+    const notifications = toAcpNotifications(
+      [rawResult] as any,
+      "user",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+      { toolUseResult: structured },
+    );
+
+    expect(notifications).toHaveLength(1);
+    expect(notifications[0].update).toMatchObject({
+      sessionUpdate: "tool_call_update",
+      toolCallId: "toolu_agent",
+      status: "completed",
+      content: [{ type: "content", content: { type: "text", text: "The structured report." } }],
+    });
+  });
+
+  it("ignores options.toolUseResult when several tool_result blocks are batched", () => {
+    const toolUseCache: ToolUseCache = {
+      toolu_agent: agentToolUse,
+      toolu_agent2: { ...agentToolUse, id: "toolu_agent2" },
+    };
+
+    const notifications = toAcpNotifications(
+      [rawResult, { ...rawResult, tool_use_id: "toolu_agent2" }] as any,
+      "user",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+      { toolUseResult: structured },
+    );
+
+    expect(notifications).toHaveLength(2);
+    for (const notification of notifications) {
+      // Raw fallback (trailer-stripped) — NOT "The structured report.", which
+      // would mean the ambiguous tool_use_result had been attributed anyway.
+      expect(notification.update).toMatchObject({
+        content: [{ type: "content", content: { type: "text", text: "The report." } }],
+      });
+    }
+  });
+});
+
+describe("tool_result_meta non-execution stamping", () => {
+  const mockClient = {} as AcpClient;
+  const mockLogger: Logger = { log: () => {}, error: () => {} };
+
+  const bashToolUse = {
+    type: "tool_use" as const,
+    id: "toolu_bash",
+    name: "Bash",
+    input: { command: "rm -rf build" },
+  };
+
+  const deniedResult: ToolResultBlockParam = {
+    type: "tool_result",
+    tool_use_id: "toolu_bash",
+    is_error: true,
+    content: "The user doesn't want to proceed with this tool use.",
+  };
+
+  it("stamps nonExecutionKind and userFeedback on the failed tool_call_update", () => {
+    const toolUseCache: ToolUseCache = { toolu_bash: bashToolUse };
+
+    const notifications = toAcpNotifications(
+      [deniedResult] as any,
+      "user",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+      {
+        toolResultMeta: [
+          { id: "toolu_bash", non_execution_kind: "user-rejected", user_feedback: "use npm" },
+        ],
+      },
+    );
+
+    expect(notifications).toHaveLength(1);
+    expect(notifications[0].update).toMatchObject({
+      sessionUpdate: "tool_call_update",
+      toolCallId: "toolu_bash",
+      status: "failed",
+      _meta: {
+        claudeCode: {
+          toolName: "Bash",
+          nonExecutionKind: "user-rejected",
+          userFeedback: "use npm",
+        },
+      },
+    });
+  });
+
+  it("attributes entries by tool_use_id, so only the flagged result in a batch is stamped", () => {
+    const toolUseCache: ToolUseCache = {
+      toolu_bash: bashToolUse,
+      toolu_bash2: { ...bashToolUse, id: "toolu_bash2" },
+    };
+
+    const notifications = toAcpNotifications(
+      [
+        deniedResult,
+        {
+          type: "tool_result",
+          tool_use_id: "toolu_bash2",
+          content: "ok",
+        },
+      ] as any,
+      "user",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+      { toolResultMeta: [{ id: "toolu_bash", non_execution_kind: "user-rejected" }] },
+    );
+
+    expect(notifications).toHaveLength(2);
+    const [denied, ran] = notifications.map((n) => n.update) as any[];
+    expect(denied._meta.claudeCode).toMatchObject({ nonExecutionKind: "user-rejected" });
+    // No user_feedback on the wire entry → no userFeedback key at all.
+    expect(denied._meta.claudeCode).not.toHaveProperty("userFeedback");
+    expect(ran._meta.claudeCode).not.toHaveProperty("nonExecutionKind");
+  });
+
+  it("ignores a malformed sidecar and malformed entries", () => {
+    for (const malformed of [
+      "user-rejected", // not an array
+      [{ non_execution_kind: "user-rejected" }], // entry missing id
+      [{ id: "toolu_bash", non_execution_kind: 7 }], // kind not a string
+      [null, 42], // entries not objects
+    ]) {
+      const toolUseCache: ToolUseCache = { toolu_bash: bashToolUse };
+      const notifications = toAcpNotifications(
+        [deniedResult] as any,
+        "user",
+        "test-session",
+        toolUseCache,
+        mockClient,
+        mockLogger,
+        { toolResultMeta: malformed },
+      );
+
+      expect(notifications).toHaveLength(1);
+      expect((notifications[0].update as any)._meta.claudeCode).not.toHaveProperty(
+        "nonExecutionKind",
+      );
+    }
+  });
+
+  it("stamps the resolve of a permission-surfaced suppressed tool (Task*)", () => {
+    // A TaskGet surfaced as a real tool_call by the permission flow never gets
+    // a tool_call_update from the suppressed Task* branch; the wasEmitted
+    // resolve must carry the denial kind too.
+    const taskGetToolUse = {
+      type: "tool_use" as const,
+      id: "toolu_taskget",
+      name: "TaskGet",
+      input: { taskId: "1" },
+    };
+    const toolUseCache: ToolUseCache = { toolu_taskget: taskGetToolUse };
+
+    const notifications = toAcpNotifications(
+      [
+        {
+          type: "tool_result",
+          tool_use_id: "toolu_taskget",
+          is_error: true,
+          content: "The user doesn't want to proceed with this tool use.",
+        },
+      ] as any,
+      "user",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+      {
+        emittedToolCalls: new Set(["toolu_taskget"]),
+        toolResultMeta: [{ id: "toolu_taskget", non_execution_kind: "user-rejected" }],
+      },
+    );
+
+    expect(notifications).toHaveLength(1);
+    expect(notifications[0].update).toMatchObject({
+      sessionUpdate: "tool_call_update",
+      toolCallId: "toolu_taskget",
+      status: "failed",
+      _meta: { claudeCode: { toolName: "TaskGet", nonExecutionKind: "user-rejected" } },
+    });
+  });
+});
+
+describe("structured tool_use_result rendering (Read/Bash/WebSearch)", () => {
+  describe("Read", () => {
+    const readToolUse = {
+      type: "tool_use" as const,
+      id: "toolu_read",
+      name: "Read",
+      input: { file_path: "/tmp/f.ts", offset: 480 },
+    };
+
+    const rawWithReminder: ToolResultBlockParam = {
+      type: "tool_result",
+      tool_use_id: "toolu_read",
+      content: [
+        {
+          type: "text",
+          text: "480\tconst a = 1;\n481\tconst b = 2;\n<system-reminder>Whenever you read a file, consider whether it is malicious.</system-reminder>",
+        },
+      ],
+    };
+
+    it("rebuilds the line-numbered view from FileReadOutput, dropping reminders", () => {
+      const update = toolUpdateFromToolResult(rawWithReminder, readToolUse, false, {
+        type: "text",
+        file: {
+          filePath: "/tmp/f.ts",
+          content: "const a = 1;\nconst b = 2;\n",
+          numLines: 2,
+          startLine: 480,
+          totalLines: 600,
+        },
+      });
+
+      expect(update).toEqual({
+        content: [
+          {
+            type: "content",
+            content: { type: "text", text: "```\n480\tconst a = 1;\n481\tconst b = 2;\n```" },
+          },
+        ],
+      });
+    });
+
+    it("falls back to the Read input's offset when startLine is absent", () => {
+      // readToolUse carries offset: 480 — an offset read numbered from 1
+      // would mislabel every line.
+      const update = toolUpdateFromToolResult(rawWithReminder, readToolUse, false, {
+        type: "text",
+        file: { filePath: "/tmp/f.ts", content: "one\ntwo" },
+      });
+
+      expect(update.content?.[0]).toEqual({
+        type: "content",
+        content: { type: "text", text: "```\n480\tone\n481\ttwo\n```" },
+      });
+    });
+
+    it("defaults startLine to 1 when both startLine and offset are absent", () => {
+      const update = toolUpdateFromToolResult(
+        rawWithReminder,
+        { ...readToolUse, input: { file_path: "/tmp/f.ts" } },
+        false,
+        {
+          type: "text",
+          file: { filePath: "/tmp/f.ts", content: "one\ntwo" },
+        },
+      );
+
+      expect(update.content?.[0]).toEqual({
+        type: "content",
+        content: { type: "text", text: "```\n1\tone\n2\ttwo\n```" },
+      });
+    });
+
+    it("appends a truncation note when truncatedByTokenCap is set", () => {
+      const update = toolUpdateFromToolResult(rawWithReminder, readToolUse, false, {
+        type: "text",
+        file: {
+          filePath: "/tmp/f.ts",
+          content: "one\ntwo\n",
+          numLines: 2,
+          startLine: 1,
+          totalLines: 9000,
+          truncatedByTokenCap: true,
+        },
+      });
+
+      expect(update.content?.[0]).toEqual({
+        type: "content",
+        content: {
+          type: "text",
+          text: "```\n1\tone\n2\ttwo\n[File truncated: showing 2 of 9000 lines]\n```",
+        },
+      });
+    });
+
+    it("falls back to raw content for non-text variants", () => {
+      const update = toolUpdateFromToolResult(rawWithReminder, readToolUse, false, {
+        type: "image",
+        file: { base64: "aGk=", type: "image/png", originalSize: 3 },
+      });
+
+      // Raw path: markdown-escaped raw text (reminder included — image reads
+      // don't carry reminders in practice).
+      expect(update.content).toHaveLength(1);
+      expect((update.content?.[0] as any).content.text).toContain("const a = 1;");
+    });
+  });
+
+  describe("Bash", () => {
+    const bashToolUse = {
+      type: "tool_use" as const,
+      id: "toolu_bash",
+      name: "Bash",
+      input: { command: "git push" },
+    };
+
+    const HINT =
+      "\n[This command modified 1 file you've previously read: src/foo.ts. Call Read before editing.]";
+
+    const rawWithHint: ToolResultBlockParam = {
+      type: "tool_result",
+      tool_use_id: "toolu_bash",
+      content: `pushed ok${HINT}`,
+    };
+
+    const structured = {
+      stdout: "pushed ok",
+      stderr: "",
+      interrupted: false,
+      isImage: false,
+    };
+
+    it("prefers structured stdout/stderr over raw text with model-directed hints", () => {
+      const update = toolUpdateFromToolResult(rawWithHint, bashToolUse, true, structured);
+
+      expect(update._meta?.terminal_output).toEqual({
+        terminal_id: "toolu_bash",
+        data: "pushed ok",
+      });
+      expect(update._meta?.terminal_exit).toEqual({
+        terminal_id: "toolu_bash",
+        exit_code: 0,
+        signal: null,
+      });
+    });
+
+    it("joins stderr after stdout like the code-execution path", () => {
+      const update = toolUpdateFromToolResult(rawWithHint, bashToolUse, false, {
+        ...structured,
+        stderr: "warning: something",
+      });
+
+      expect(update.content).toEqual([
+        {
+          type: "content",
+          content: { type: "text", text: "```console\npushed ok\nwarning: something\n```" },
+        },
+      ]);
+    });
+
+    it("falls back to raw text for backgrounded commands", () => {
+      const update = toolUpdateFromToolResult(rawWithHint, bashToolUse, true, {
+        ...structured,
+        stdout: "",
+        backgroundTaskId: "bash_1",
+      });
+
+      expect(update._meta?.terminal_output?.data).toBe(`pushed ok${HINT}`);
+    });
+
+    it("falls back to the raw content array for image output", () => {
+      const imageResult: ToolResultBlockParam = {
+        type: "tool_result",
+        tool_use_id: "toolu_bash",
+        content: [
+          { type: "image", source: { type: "base64", data: "aGk=", media_type: "image/png" } },
+        ],
+      };
+      const update = toolUpdateFromToolResult(imageResult, bashToolUse, true, {
+        ...structured,
+        isImage: true,
+      });
+
+      expect(update.content).toEqual([
+        {
+          type: "content",
+          content: { type: "image", data: "aGk=", mimeType: "image/png" },
+        },
+      ]);
+    });
+
+    it("re-establishes the abort notice and a failing exit code for interrupted commands", () => {
+      const update = toolUpdateFromToolResult(rawWithHint, bashToolUse, true, {
+        ...structured,
+        stdout: "partial output",
+        interrupted: true,
+      });
+
+      expect(update._meta?.terminal_output).toEqual({
+        terminal_id: "toolu_bash",
+        data: "partial output\n[Command was aborted before completion]",
+      });
+      expect(update._meta?.terminal_exit).toEqual({
+        terminal_id: "toolu_bash",
+        exit_code: 1,
+        signal: null,
+      });
+    });
+
+    it("re-establishes the truncation note and persisted path for too-large outputs", () => {
+      const update = toolUpdateFromToolResult(rawWithHint, bashToolUse, true, {
+        ...structured,
+        stdout: "clipped stdout",
+        persistedOutputPath: "/tmp/tool-results/abc.txt",
+        persistedOutputSize: 38100,
+      });
+
+      expect(update._meta?.terminal_output).toEqual({
+        terminal_id: "toolu_bash",
+        data: "clipped stdout\n[Output truncated (38100 bytes total): full output saved to /tmp/tool-results/abc.txt]",
+      });
+    });
+  });
+
+  describe("WebSearch", () => {
+    const searchToolUse = {
+      type: "tool_use" as const,
+      id: "toolu_search",
+      name: "WebSearch",
+      input: { query: "npm sigstore bug" },
+    };
+
+    const rawDump: ToolResultBlockParam = {
+      type: "tool_result",
+      tool_use_id: "toolu_search",
+      content:
+        'Web search results for query: "npm sigstore bug"\n\nLinks: [{"title":"Issue #9722","url":"https://github.com/npm/cli/issues/9722"}]',
+    };
+
+    it("renders hits as Title (url) lines from WebSearchOutput", () => {
+      const update = toolUpdateFromToolResult(rawDump, searchToolUse, false, {
+        query: "npm sigstore bug",
+        durationSeconds: 5.5,
+        results: [
+          "I found one relevant issue:",
+          {
+            tool_use_id: "srvtoolu_1",
+            content: [
+              { title: "Issue #9722", url: "https://github.com/npm/cli/issues/9722" },
+              { title: "sigstore-js", url: "https://github.com/sigstore/sigstore-js" },
+            ],
+          },
+        ],
+      });
+
+      expect(update).toEqual({
+        content: [
+          {
+            type: "content",
+            content: {
+              type: "text",
+              text: "I found one relevant issue:\nIssue #9722 (https://github.com/npm/cli/issues/9722)\nsigstore-js (https://github.com/sigstore/sigstore-js)",
+            },
+          },
+        ],
+      });
+    });
+
+    it("falls back to the raw dump when tool_use_result is absent", () => {
+      const update = toolUpdateFromToolResult(rawDump, searchToolUse, false);
+
+      expect((update.content?.[0] as any).content.text).toContain("Web search results for query");
+    });
+
+    it("skips off-spec hits instead of rendering undefined fields", () => {
+      const update = toolUpdateFromToolResult(rawDump, searchToolUse, false, {
+        query: "npm sigstore bug",
+        durationSeconds: 5.5,
+        results: [
+          {
+            tool_use_id: "srvtoolu_1",
+            content: [
+              { error_code: "provider_error" },
+              { title: "Issue #9722", url: "https://github.com/npm/cli/issues/9722" },
+            ],
+          },
+        ],
+      });
+
+      expect(update).toEqual({
+        content: [
+          {
+            type: "content",
+            content: {
+              type: "text",
+              text: "Issue #9722 (https://github.com/npm/cli/issues/9722)",
+            },
+          },
+        ],
+      });
+    });
+
+    it("falls back to the raw dump when every hit is off-spec", () => {
+      const update = toolUpdateFromToolResult(rawDump, searchToolUse, false, {
+        query: "npm sigstore bug",
+        durationSeconds: 5.5,
+        results: [{ tool_use_id: "srvtoolu_1", content: [{ error_code: "provider_error" }] }],
+      });
+
+      expect((update.content?.[0] as any).content.text).toContain("Web search results for query");
+    });
+  });
+});

src/tools.ts

@@ -8,10 +8,13 @@ import {
 import { HookCallback } from "@anthropic-ai/claude-agent-sdk";
 import {
   AgentInput,
+  AgentOutput,
   AskUserQuestionInput,
   BashInput,
+  BashOutput,
   FileEditInput,
   FileReadInput,
+  FileReadOutput,
   FileWriteInput,
   GlobInput,
   GrepInput,
@@ -22,6 +25,7 @@ import {
   TodoWriteInput,
   WebFetchInput,
   WebSearchInput,
+  WebSearchOutput,
 } from "@anthropic-ai/claude-agent-sdk/sdk-tools.js";
 import {
   ImageBlockParam,
@@ -56,7 +60,6 @@ import {
   BetaWebSearchToolResultBlockParam,
 } from "@anthropic-ai/sdk/resources/beta.mjs";
 import path from "node:path";
-import { Logger } from "./acp-agent.js";
 
 /**
  * Union of all possible content types that can appear in tool results from the Anthropic SDK.
@@ -486,6 +489,88 @@ export function toolInfoFromToolUse(
   }
 }
 
+/**
+ * Narrow the untyped message-level `tool_use_result` toward a per-tool Output
+ * shape: rejects everything but a plain non-null object (arrays pass a bare
+ * `typeof === "object"` check, so they're excluded here). The returned value
+ * is only *nominally* typed — it arrives over the wire from arbitrary CLI
+ * versions, so each caller must still guard the specific fields it reads
+ * before trusting them.
+ */
+function structuredResult<T extends object>(toolUseResult: unknown): T | undefined {
+  return toolUseResult !== null &&
+    typeof toolUseResult === "object" &&
+    !Array.isArray(toolUseResult)
+    ? (toolUseResult as T)
+    : undefined;
+}
+
+/**
+ * Strip the model-directed trailer from a raw Agent/Task tool_result text:
+ * a `<usage>…</usage>` totals block and/or an
+ * `agentId: <id> (use SendMessage …)` continuation line at the end of the
+ * text. Both patterns are tail-anchored and independent (older CLIs emit
+ * variants with only one of them), so a format change makes them stop
+ * matching rather than mangle the report.
+ */
+function stripAgentTrailer(text: string): string {
+  return stripAgentIdLine(stripUsageBlock(text));
+}
+
+const USAGE_OPEN = "<usage>";
+const USAGE_CLOSE = "</usage>";
+
+/** Remove a trailing `<usage>…</usage>` block, plus trailing whitespace and
+ *  one preceding newline. Matches from the *last* `<usage>` so a report that
+ *  merely mentions the marker earlier isn't truncated at the mention. */
+function stripUsageBlock(text: string): string {
+  const body = text.trimEnd();
+  if (!body.endsWith(USAGE_CLOSE)) {
+    return text;
+  }
+  const open = body.lastIndexOf(USAGE_OPEN, body.length - USAGE_CLOSE.length - USAGE_OPEN.length);
+  if (open === -1) {
+    return text;
+  }
+  return body.slice(0, open > 0 && body[open - 1] === "\n" ? open - 1 : open);
+}
+
+/** The continuation line, anchored to a whole line so the regex has a single
+ *  start position and no ambiguous repetition (`[\w-]+` can't consume the
+ *  following space, `[^)]*` can't consume the closing paren) — it runs in
+ *  linear time on any input. */
+const AGENT_ID_LINE = /^agentId: [\w-]+ \([^)]*\)$/;
+
+/** Remove a final `agentId: <id> (…)` line, plus trailing whitespace and the
+ *  newline that preceded the line. */
+function stripAgentIdLine(text: string): string {
+  const body = text.trimEnd();
+  const lineStart = body.lastIndexOf("\n") + 1;
+  if (!AGENT_ID_LINE.test(body.slice(lineStart))) {
+    return text;
+  }
+  return body.slice(0, Math.max(lineStart - 1, 0));
+}
+
+/** Apply {@link stripAgentTrailer} across a raw tool_result `content` (plain
+ *  string or block array), leaving non-text blocks untouched. */
+function stripAgentTrailerFromContent(content: unknown): unknown {
+  if (typeof content === "string") {
+    return stripAgentTrailer(content);
+  }
+  if (Array.isArray(content)) {
+    return content.map((block) =>
+      block !== null &&
+      typeof block === "object" &&
+      block.type === "text" &&
+      typeof block.text === "string"
+        ? { ...block, text: stripAgentTrailer(block.text) }
+        : block,
+    );
+  }
+  return content;
+}
+
 export function toolUpdateFromToolResult(
   toolResult:
     | ToolResultBlockParam
@@ -500,6 +585,7 @@ export function toolUpdateFromToolResult(
     | BetaToolSearchToolResultBlockParam,
   toolUse: any | undefined,
   supportsTerminalOutput: boolean = false,
+  toolUseResult?: unknown,
 ): ToolUpdate {
   if (
     "is_error" in toolResult &&
@@ -512,8 +598,63 @@ export function toolUpdateFromToolResult(
     return toAcpContentUpdate(toolResult.content, true);
   }
 
+  // Shared raw-text fallback: renders the tool_result content the model saw.
+  // The structured cases below fall back to this when `tool_use_result` is
+  // absent or fails its shape guard (older CLIs, replayed sessions).
+  const rawContentUpdate = () =>
+    toAcpContentUpdate(toolResult.content, "is_error" in toolResult ? toolResult.is_error : false);
+
   switch (toolUse?.name) {
-    case "Read":
+    case "Read": {
+      // The raw tool_result text is the model-facing view: line-numbered
+      // content plus any appended <system-reminder> blocks (malicious-code
+      // checks, memory staleness notes, …) that clients shouldn't see. The
+      // structured FileReadOutput carries the clean content — rebuild the
+      // line-numbered view from it. Non-text variants (image/notebook/pdf)
+      // fall back to the raw content blocks, which already render fine.
+      const structuredRead = structuredResult<FileReadOutput>(toolUseResult);
+      if (
+        structuredRead?.type === "text" &&
+        typeof structuredRead.file?.content === "string" &&
+        // An empty file has nothing to line-number; keep the raw view (the
+        // model-facing "file is empty" note) rather than a phantom blank line.
+        structuredRead.file.content.length > 0
+      ) {
+        // startLine is typed non-optional but defended anyway; a Read's
+        // `offset` input is the same 1-based starting line, so it beats a
+        // blind 1 when an emitter omits the field.
+        const startLine =
+          structuredRead.file.startLine ??
+          (toolUse.input as FileReadInput | undefined)?.offset ??
+          1;
+        // A trailing newline is a line terminator, not an extra line — don't
+        // number a phantom empty line after it.
+        let numbered = structuredRead.file.content
+          .replace(/\n$/, "")
+          .split("\n")
+          .map((line, i) => `${startLine + i}\t${line}`)
+          .join("\n");
+        // The model-facing truncation banner doesn't survive reconstruction
+        // from file.content (the SDK flag exists for exactly this case) —
+        // re-establish it so a partial first page doesn't read as the whole
+        // file.
+        if (structuredRead.file.truncatedByTokenCap) {
+          const { numLines, totalLines } = structuredRead.file;
+          const detail =
+            typeof numLines === "number" && typeof totalLines === "number"
+              ? `: showing ${numLines} of ${totalLines} lines`
+              : "";
+          numbered += `\n[File truncated${detail}]`;
+        }
+        return {
+          content: [
+            {
+              type: "content",
+              content: { type: "text", text: markdownEscape(numbered) },
+            },
+          ],
+        };
+      }
       if (Array.isArray(toolResult.content) && toolResult.content.length > 0) {
         return {
           content: toolResult.content.map((content: any) => ({
@@ -541,22 +682,77 @@ export function toolUpdateFromToolResult(
         };
       }
       return {};
+    }
 
     case "Bash": {
       const result = toolResult.content;
-      const terminalId = "tool_use_id" in toolResult ? String(toolResult.tool_use_id) : "";
+      // The terminal was announced under the tool_use's own id (see
+      // `toolInfoFromToolUse`), so key the output/exit metas off that: it is the
+      // id the client actually created a terminal for. `toolResult.tool_use_id`
+      // is the same value whenever present — the caller looks the tool_use up by
+      // it — so preferring `toolUse.id` only adds a source for the case where the
+      // result block carries no id at all. Anything that isn't a non-empty
+      // string is no id at all: `""` matches no terminal, and stringifying a
+      // present-but-undefined field would invent the literal `"undefined"`.
+      const terminalIdOf = (id: unknown): string | undefined =>
+        typeof id === "string" && id.length > 0 ? id : undefined;
+      const terminalId: string | undefined =
+        terminalIdOf(toolUse?.id) ??
+        terminalIdOf("tool_use_id" in toolResult ? toolResult.tool_use_id : undefined);
       const isError = "is_error" in toolResult && toolResult.is_error;
 
       // Extract output and exit code from either format:
-      // 1. BetaBashCodeExecutionResultBlock: { type: "bash_code_execution_result", stdout, stderr, return_code }
-      // 2. Plain string content from a regular tool_result
-      // 3. Array content (e.g. [{ type: "text", text: "..." }] for stdout,
+      // 1. The structured BashOutput (message-level tool_use_result): its
+      //    stdout/stderr exclude the model-directed suffixes the raw text
+      //    carries (stale-read hints, gh rate-limit hints, the
+      //    persisted-output wrapper for too-large outputs — the interruption
+      //    and truncation facts those carried are re-established from the
+      //    structured flags below). Skipped for image output (the raw content
+      //    array carries the actual image blocks) and backgrounded commands
+      //    (the raw text carries the background-task notice; structured
+      //    stdout may be empty).
+      // 2. BetaBashCodeExecutionResultBlock: { type: "bash_code_execution_result", stdout, stderr, return_code }
+      // 3. Plain string content from a regular tool_result
+      // 4. Array content (e.g. [{ type: "text", text: "..." }] for stdout,
       //    or [{ type: "image", source: {...} }] when the local Bash tool
       //    produces an image, e.g. piping a base64 data URI)
       let output = "";
       let exitCode = isError ? 1 : 0;
 
+      const structuredBash = structuredResult<BashOutput>(toolUseResult);
       if (
+        structuredBash &&
+        typeof structuredBash.stdout === "string" &&
+        typeof structuredBash.stderr === "string" &&
+        !structuredBash.isImage &&
+        structuredBash.backgroundTaskId === undefined
+      ) {
+        output = [structuredBash.stdout, structuredBash.stderr].filter(Boolean).join("\n");
+        // Two raw-text notices don't survive the structured stdout/stderr —
+        // re-establish them so the client isn't shown a clean-looking result:
+        // the CLI appends its abort marker only to the model-facing text, and
+        // an aborted command isn't a success, so synthesize a failing exit
+        // code when the result wasn't already an error.
+        if (structuredBash.interrupted) {
+          output = [output, "[Command was aborted before completion]"].filter(Boolean).join("\n");
+          exitCode = 1;
+        }
+        // Structured stdout is clipped (~30k chars) when the full output was
+        // persisted to disk; without this note the clip is silent and the
+        // path to the full output is lost.
+        if (typeof structuredBash.persistedOutputPath === "string") {
+          const size =
+            typeof structuredBash.persistedOutputSize === "number"
+              ? ` (${structuredBash.persistedOutputSize} bytes total)`
+              : "";
+          output = [
+            output,
+            `[Output truncated${size}: full output saved to ${structuredBash.persistedOutputPath}]`,
+          ]
+            .filter(Boolean)
+            .join("\n");
+        }
+      } else if (
         result &&
         typeof result === "object" &&
         "type" in result &&
@@ -583,7 +779,14 @@ export function toolUpdateFromToolResult(
         }
       }
 
-      if (supportsTerminalOutput) {
+      // Without a terminal id there is nothing the client can reconcile these
+      // metas against, and emitting them anyway strands the output: a client that
+      // buffers output/exit for terminals it has not been told about (Zed keeps
+      // them in `pending_terminal_output`/`pending_terminal_exit`, drained only on
+      // a matching create) would hold them forever behind an id that never
+      // arrives, showing an empty terminal. Fall through to the code-block
+      // rendering below instead.
+      if (supportsTerminalOutput && terminalId !== undefined) {
         return {
           content: [{ type: "terminal" as const, terminalId }],
           _meta: {
@@ -619,6 +822,45 @@ export function toolUpdateFromToolResult(
       return {};
     }
 
+    case "Agent":
+    case "Task": {
+      // The raw tool_result text ends with a model-directed trailer (an
+      // `agentId: … (use SendMessage …)` line plus a `<usage>` totals block)
+      // that ACP clients shouldn't see. The message-level `tool_use_result`
+      // carries the structured AgentOutput whose `content` is the subagent's
+      // report without the trailer — render from it when present (per the SDK
+      // 0.3.207 guidance) and fall back to the raw text otherwise (older CLIs,
+      // replayed sessions).
+      // Narrowed to the full union, not the completed variant — the status
+      // check below is what discriminates it, and pre-narrowing would let
+      // future field reads typecheck against a variant the runtime value may
+      // not be.
+      const structured = structuredResult<AgentOutput>(toolUseResult);
+      if (
+        structured?.status === "completed" &&
+        Array.isArray(structured.content) &&
+        // A completed subagent can end with zero text blocks; an empty
+        // structured render would beat the raw fallback for no benefit.
+        structured.content.length > 0
+      ) {
+        return toAcpContentUpdate(
+          structured.content,
+          "is_error" in toolResult ? toolResult.is_error : false,
+        );
+      }
+      // No structured report to render from (replayed sessions —
+      // getSessionMessages doesn't expose the transcript's toolUseResult —
+      // and older CLIs). The SDK advises rendering from tool_use_result
+      // instead of parsing the text, but with no structured value the
+      // tail-anchored strip is the only cleanup available; if the trailer
+      // format changes it simply stops matching and the full raw text
+      // renders, no worse than before.
+      return toAcpContentUpdate(
+        stripAgentTrailerFromContent(toolResult.content),
+        "is_error" in toolResult ? toolResult.is_error : false,
+      );
+    }
+
     case "Edit": // Edit is handled in hooks
     case "Write": {
       return {};
@@ -628,15 +870,54 @@ export function toolUpdateFromToolResult(
       return { title: "Exited Plan Mode" };
     }
 
+    case "WebSearch": {
+      // The raw tool_result text is a model-directed dump ("Web search
+      // results for query: …\n\nLinks: [{…json…}]"). The structured
+      // WebSearchOutput carries the hits — render them the way server-side
+      // web_search_result blocks render ("Title (url)").
+      const structuredSearch = structuredResult<WebSearchOutput>(toolUseResult);
+      if (structuredSearch && Array.isArray(structuredSearch.results)) {
+        const lines = structuredSearch.results.flatMap((entry) =>
+          typeof entry === "string"
+            ? [entry]
+            : Array.isArray(entry?.content)
+              ? // tool_use_result arrives untyped across CLI version skew —
+                // skip off-spec hits rather than rendering
+                // "undefined (undefined)" lines.
+                entry.content.flatMap((hit) =>
+                  typeof hit?.title === "string" && typeof hit?.url === "string"
+                    ? [formatWebSearchHit(hit)]
+                    : [],
+                )
+              : [],
+        );
+        if (lines.length > 0) {
+          return {
+            content: [
+              {
+                type: "content",
+                content: { type: "text", text: lines.join("\n") },
+              },
+            ],
+          };
+        }
+      }
+      return rawContentUpdate();
+    }
+
     default: {
-      return toAcpContentUpdate(
-        toolResult.content,
-        "is_error" in toolResult ? toolResult.is_error : false,
-      );
+      return rawContentUpdate();
     }
   }
 }
 
+/** One display format for a web-search hit, shared by the structured
+ *  WebSearchOutput render and the server-side `web_search_result` block so
+ *  the two paths can't drift. */
+function formatWebSearchHit(hit: { title: string; url: string }): string {
+  return `${hit.title} (${hit.url})`;
+}
+
 function toAcpContentUpdate(
   content: any,
   isError: boolean = false,
@@ -711,7 +992,7 @@ function toAcpContentBlock(content: ToolResultContent, isError: boolean): Conten
         `Error: ${content.error_code}${content.error_message ? ` - ${content.error_message}` : ""}`,
       );
     case "web_search_result":
-      return wrapText(`${content.title} (${content.url})`);
+      return wrapText(formatWebSearchHit(content));
     case "web_search_tool_result_error":
       return wrapText(`Error: ${content.error_code}`);
     case "web_fetch_result":
@@ -954,12 +1235,7 @@ export const registerHookCallback = (
 
 /* A callback for Claude Code that is called when receiving a PostToolUse hook */
 export const createPostToolUseHook =
-  (
-    logger: Logger = console,
-    options?: {
-      onEnterPlanMode?: () => Promise<void>;
-    },
-  ): HookCallback =>
+  (options?: { onEnterPlanMode?: () => Promise<void> }): HookCallback =>
   async (input: any, toolUseID: string | undefined): Promise<{ continue: boolean }> => {
     if (input.hook_event_name === "PostToolUse") {
       // Handle EnterPlanMode tool - notify client of mode change after successful execution
@@ -971,11 +1247,8 @@ export const createPostToolUseHook =
         const onPostToolUseHook = toolUseCallbacks[toolUseID]?.onPostToolUseHook;
         if (onPostToolUseHook) {
           await onPostToolUseHook(toolUseID, input.tool_input, input.tool_response);
-          delete toolUseCallbacks[toolUseID]; // Cleanup after execution
-        } else {
-          logger.error(`No onPostToolUseHook found for tool use ID: ${toolUseID}`);
-          delete toolUseCallbacks[toolUseID];
         }
+        delete toolUseCallbacks[toolUseID]; // Cleanup after execution
       }
     }
     return { continue: true };