chore(main): release 0.42.0 (#745)

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


##
[0.42.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.41.0...v0.42.0)
(2026-06-05)


### Features

* **deps-dev:** bump obug from 2.1.1 to 2.1.2 in the minor group
([#743](https://github.com/agentclientprotocol/claude-agent-acp/issues/743))
([7ffb78c](7ffb78c572))
* Send message ids for assistant and user messages
([#750](https://github.com/agentclientprotocol/claude-agent-acp/issues/750))
([18516a3](18516a3088))
* Update Claude Agent SDK to 0.3.165
([#746](https://github.com/agentclientprotocol/claude-agent-acp/issues/746))
([23cbe6f](23cbe6f58f))


### Bug Fixes

* Prevent cross-family model matching in resolveModelPreference
([#731](https://github.com/agentclientprotocol/claude-agent-acp/issues/731))
([f4704c1](f4704c168f))
* Prune tool cache per session after results
([#748](https://github.com/agentclientprotocol/claude-agent-acp/issues/748))
([ec14211](ec14211056))
* Update to better utilize existing SDK data
([#747](https://github.com/agentclientprotocol/claude-agent-acp/issues/747))
([398f763](398f763f71))

---
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

@@ -21,7 +21,7 @@ jobs:
     timeout-minutes: 5
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10
 
       - name: Use Node.js
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e

.github/workflows/publish.yml

@@ -44,7 +44,7 @@ jobs:
       contents: read
       id-token: write
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10
       # Setup .npmrc file to publish to npm
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
         with:

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.36.1"
+  ".": "0.42.0"
 }

CHANGELOG.md

@@ -1,5 +1,86 @@
 # Changelog
 
+## [0.42.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.41.0...v0.42.0) (2026-06-05)
+
+
+### Features
+
+* **deps-dev:** bump obug from 2.1.1 to 2.1.2 in the minor group ([#743](https://github.com/agentclientprotocol/claude-agent-acp/issues/743)) ([7ffb78c](https://github.com/agentclientprotocol/claude-agent-acp/commit/7ffb78c57280fc32af77862896c0035ce0e690b7))
+* Send message ids for assistant and user messages ([#750](https://github.com/agentclientprotocol/claude-agent-acp/issues/750)) ([18516a3](https://github.com/agentclientprotocol/claude-agent-acp/commit/18516a3088f847a38f5eee0fe81ad5ca3e2a751c))
+* Update Claude Agent SDK to 0.3.165 ([#746](https://github.com/agentclientprotocol/claude-agent-acp/issues/746)) ([23cbe6f](https://github.com/agentclientprotocol/claude-agent-acp/commit/23cbe6f58fa9e10ad736f664c4cf94dbd1c6ad65))
+
+
+### Bug Fixes
+
+* Prevent cross-family model matching in resolveModelPreference ([#731](https://github.com/agentclientprotocol/claude-agent-acp/issues/731)) ([f4704c1](https://github.com/agentclientprotocol/claude-agent-acp/commit/f4704c168f917e6710f2b3cd49e1fef49613a469))
+* Prune tool cache per session after results ([#748](https://github.com/agentclientprotocol/claude-agent-acp/issues/748)) ([ec14211](https://github.com/agentclientprotocol/claude-agent-acp/commit/ec142110561f680330c6976783805685c5c069ec))
+* Update to better utilize existing SDK data ([#747](https://github.com/agentclientprotocol/claude-agent-acp/issues/747)) ([398f763](https://github.com/agentclientprotocol/claude-agent-acp/commit/398f763f71bd2fe2ca9e8269de120d26a744b7a8))
+
+## [0.41.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.40.0...v0.41.0) (2026-06-04)
+
+
+### Features
+
+* **deps:** upgrade to @anthropic-ai/claude-agent-sdk@0.3.162 ([#740](https://github.com/agentclientprotocol/claude-agent-acp/issues/740)) ([add7e31](https://github.com/agentclientprotocol/claude-agent-acp/commit/add7e31704581aa70febb6341ca0e8cee5d93b43))
+
+
+### Bug Fixes
+
+* Force cancellation when SDK query hangs ([#742](https://github.com/agentclientprotocol/claude-agent-acp/issues/742)) ([cffea4b](https://github.com/agentclientprotocol/claude-agent-acp/commit/cffea4be28e6def91027110433a99e80b1be8a0c)), closes [#680](https://github.com/agentclientprotocol/claude-agent-acp/issues/680)
+
+## [0.40.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.39.0...v0.40.0) (2026-06-02)
+
+
+### Features
+
+* **deps-dev:** bump the minor group with 2 updates ([#726](https://github.com/agentclientprotocol/claude-agent-acp/issues/726)) ([51a370e](https://github.com/agentclientprotocol/claude-agent-acp/commit/51a370e4feb8a74279698b156e35b96631a74d74))
+* **deps:** bump actions/checkout from 6.0.2 to 6.0.3 ([#736](https://github.com/agentclientprotocol/claude-agent-acp/issues/736)) ([9cda07b](https://github.com/agentclientprotocol/claude-agent-acp/commit/9cda07ba9df27b48bd94332e365eed982e3f5613))
+* **deps:** bump the minor group with 50 updates ([#737](https://github.com/agentclientprotocol/claude-agent-acp/issues/737)) ([32175b8](https://github.com/agentclientprotocol/claude-agent-acp/commit/32175b83a0227d0baa1f7d7eedabe743b4b870e8))
+
+
+### Bug Fixes
+
+* Optimize local command marker stripping ([#738](https://github.com/agentclientprotocol/claude-agent-acp/issues/738)) ([895422c](https://github.com/agentclientprotocol/claude-agent-acp/commit/895422c72d5f955903f227dc6887df823d2730e6)), closes [#727](https://github.com/agentclientprotocol/claude-agent-acp/issues/727)
+
+## [0.39.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.38.0...v0.39.0) (2026-05-29)
+
+
+### Features
+
+* **deps:** update Claude Agent SDK to 0.3.156 ([#722](https://github.com/agentclientprotocol/claude-agent-acp/issues/722)) ([3fb6db4](https://github.com/agentclientprotocol/claude-agent-acp/commit/3fb6db4e5ee5bd1f431cf5d2ce5331ce983f9597))
+
+## [0.38.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.37.0...v0.38.0) (2026-05-28)
+
+
+### Features
+
+* **deps:** bump to @anthropic-ai/claude-agent-sdk 0.3.154 (Opus 4.8) ([#716](https://github.com/agentclientprotocol/claude-agent-acp/issues/716)) ([a172885](https://github.com/agentclientprotocol/claude-agent-acp/commit/a172885c80fc32c108a8501268a543641088f543))
+* Support Opus 4.8 ([#718](https://github.com/agentclientprotocol/claude-agent-acp/issues/718)) ([98b54a0](https://github.com/agentclientprotocol/claude-agent-acp/commit/98b54a02c267cdef619becceccf6ef519fbf8f6f))
+
+
+### Bug Fixes
+
+* Remove hide Claude auth flag handling ([#707](https://github.com/agentclientprotocol/claude-agent-acp/issues/707)) ([7ed1daf](https://github.com/agentclientprotocol/claude-agent-acp/commit/7ed1daf7b42088ad149e9bf742f764752b82d093))
+
+## [0.37.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.36.1...v0.37.0) (2026-05-21)
+
+
+### Features
+
+* add 'Default' option to effort level config ([#701](https://github.com/agentclientprotocol/claude-agent-acp/issues/701)) ([9e259d1](https://github.com/agentclientprotocol/claude-agent-acp/commit/9e259d128aa58dbb8107e53362781ca4e8ee071e))
+* **deps:** bump the claude-agent-sdk to 0.3.146 ([#700](https://github.com/agentclientprotocol/claude-agent-acp/issues/700)) ([72875b2](https://github.com/agentclientprotocol/claude-agent-acp/commit/72875b248c7b90a89638de2f1709eec9e2153e7e))
+* **deps:** bump the minor group with 13 updates ([#689](https://github.com/agentclientprotocol/claude-agent-acp/issues/689)) ([f66bc31](https://github.com/agentclientprotocol/claude-agent-acp/commit/f66bc31ae4bea73b48eeeb7f1db90c7d69cc0dac))
+* Emit tool calls for memory recall events ([#703](https://github.com/agentclientprotocol/claude-agent-acp/issues/703)) ([a0bfb98](https://github.com/agentclientprotocol/claude-agent-acp/commit/a0bfb98ba73eaf37e9c071e886c054f90a5d5629)), closes [#650](https://github.com/agentclientprotocol/claude-agent-acp/issues/650)
+
+
+### Bug Fixes
+
+* Avoid cross-version model alias matches ([#702](https://github.com/agentclientprotocol/claude-agent-acp/issues/702)) ([e1e1c69](https://github.com/agentclientprotocol/claude-agent-acp/commit/e1e1c69029ef08579c841e6fbdffb32a5b94df06))
+* Avoid redundant initial model sync ([#704](https://github.com/agentclientprotocol/claude-agent-acp/issues/704)) ([b275f6f](https://github.com/agentclientprotocol/claude-agent-acp/commit/b275f6ff7f0f2e21adedbd8e63a6fc3d63cbbb8d)), closes [#646](https://github.com/agentclientprotocol/claude-agent-acp/issues/646)
+* Don't expose /clear in commands ([#705](https://github.com/agentclientprotocol/claude-agent-acp/issues/705)) ([cfce130](https://github.com/agentclientprotocol/claude-agent-acp/commit/cfce1307076e93f43a3ed8cc0134f9bb14a0f2d6))
+* emit  "cancelled" instead of "end_turn" when the session was interrupted. ([#694](https://github.com/agentclientprotocol/claude-agent-acp/issues/694)) ([2414a6f](https://github.com/agentclientprotocol/claude-agent-acp/commit/2414a6f98bec5bf50f3a13af528aa38d5a0fc974))
+* Recover prompt stream after a failed turn ([#706](https://github.com/agentclientprotocol/claude-agent-acp/issues/706)) ([2711f50](https://github.com/agentclientprotocol/claude-agent-acp/commit/2711f506d5799f0ae25160de311a4459ffb46c49)), closes [#654](https://github.com/agentclientprotocol/claude-agent-acp/issues/654)
+
 ## [0.36.1](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.36.0...v0.36.1) (2026-05-18)
 
 

package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.36.1",
+  "version": "0.42.0",
   "description": "An ACP-compatible coding agent powered by the Claude Agent SDK (TypeScript)",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
@@ -60,22 +60,22 @@
   "author": "Zed Industries",
   "license": "Apache-2.0",
   "dependencies": {
-    "@agentclientprotocol/sdk": "0.22.0",
-    "@anthropic-ai/claude-agent-sdk": "0.3.143",
+    "@agentclientprotocol/sdk": "0.24.0",
+    "@anthropic-ai/claude-agent-sdk": "0.3.165",
     "zod": "^3.25.0 || ^4.0.0"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "0.96.0",
+    "@anthropic-ai/sdk": "0.100.1",
     "@eslint/js": "10.0.1",
-    "@types/node": "25.8.0",
-    "@typescript-eslint/eslint-plugin": "8.59.3",
-    "@typescript-eslint/parser": "8.59.3",
-    "eslint": "10.4.0",
+    "@types/node": "25.9.1",
+    "@typescript-eslint/eslint-plugin": "8.60.1",
+    "@typescript-eslint/parser": "8.60.1",
+    "eslint": "10.4.1",
     "eslint-config-prettier": "10.1.8",
     "globals": "17.6.0",
     "prettier": "3.8.3",
     "ts-node": "10.9.2",
     "typescript": "6.0.3",
-    "vitest": "4.1.6"
+    "vitest": "4.1.8"
   }
 }

src/tests/.claude/commands/say-hello.md

@@ -3,4 +3,4 @@ description: Say hello
 argument-hint: name
 ---
 
-Respond with "Hello $1" and nothing else.
+Respond with "Hello $ARGUMENTS" and nothing else.

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

@@ -222,8 +222,12 @@ describe("ClaudeAcpAgent settings", () => {
     });
 
     // Bad model is ignored at the usage site; falls back to the first SDK model.
-    expect(setModelSpy).toHaveBeenCalledWith("claude-sonnet-4-6");
-    expect(response.models.currentModelId).toBe("claude-sonnet-4-6");
+    // No setModel call is needed because no override was applied — the SDK is
+    // already on its own default.
+    expect(setModelSpy).not.toHaveBeenCalled();
+    expect(response.configOptions?.find((o: any) => o.id === "model")?.currentValue).toBe(
+      "claude-sonnet-4-6",
+    );
   });
 
   describe("auto mode availability per model", () => {
@@ -576,7 +580,125 @@ describe("ClaudeAcpAgent settings", () => {
       });
 
       expect(setModelSpy).toHaveBeenCalledWith("claude-haiku-4-5");
-      expect(response.models.currentModelId).toBe("claude-haiku-4-5");
+      expect(response.configOptions?.find((o: any) => o.id === "model")?.currentValue).toBe(
+        "claude-haiku-4-5",
+      );
+    });
+
+    it("does not inherit display info across mismatched model versions", async () => {
+      // https://github.com/agentclientprotocol/claude-agent-acp/issues/639:
+      // when the SDK's `opus` alias resolves to Opus 4.7, an allowlist entry
+      // of `claude-opus-4-6` (or `claude-opus-4-6[1m]`) used to substring-match
+      // `opus` and inherit the "Opus 4.7" display info. With version-aware
+      // matching, these entries fall back to showing their literal ID rather
+      // than a misleading newer name.
+      await fs.promises.writeFile(
+        path.join(tempDir, "settings.json"),
+        JSON.stringify({
+          availableModels: [
+            "claude-opus-4-6",
+            "claude-opus-4-6[1m]",
+            "claude-opus-4-7",
+            "claude-opus-4-7[1m]",
+          ],
+        }),
+      );
+
+      const projectDir = path.join(tempDir, "project");
+      await fs.promises.mkdir(projectDir, { recursive: true });
+
+      mockQueryWithModels([
+        { value: "default", displayName: "Default", description: "Default model" },
+        {
+          value: "opus",
+          displayName: "Opus 4.7",
+          description: "Claude Opus 4.7 — complex tasks, higher cost",
+        },
+        {
+          value: "opus[1m]",
+          displayName: "Opus 4.7 (1M context)",
+          description: "Opus 4.7 with 1M context",
+        },
+      ]);
+
+      const { ClaudeAcpAgent } = await import("../acp-agent.js");
+      const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+      const response = await (agent as any).createSession({
+        cwd: projectDir,
+        mcpServers: [],
+        _meta: { disableBuiltInTools: true },
+      });
+
+      const modelOption = response.configOptions.find((o: any) => o.id === "model");
+      const byValue: Record<string, { name: string; description?: string }> = {};
+      for (const opt of modelOption.options) {
+        byValue[opt.value] = { name: opt.name, description: opt.description };
+      }
+
+      // 4-6 entries must NOT inherit the 4.7 SDK alias display info.
+      expect(byValue["claude-opus-4-6"].name).toBe("claude-opus-4-6");
+      expect(byValue["claude-opus-4-6"].description).toBe("");
+      expect(byValue["claude-opus-4-6[1m]"].name).toBe("claude-opus-4-6[1m]");
+      expect(byValue["claude-opus-4-6[1m]"].description).toBe("");
+
+      // 4-7 entries continue to inherit display info from a 4.7 SDK alias.
+      expect(byValue["claude-opus-4-7"].name).toBe("Opus 4.7");
+      expect(byValue["claude-opus-4-7[1m]"].name).toMatch(/Opus 4\.7/);
+    });
+
+    it("does not inherit display info across mismatched model families", async () => {
+      // https://github.com/agentclientprotocol/claude-agent-acp/issues/639:
+      // when the SDK's `opus` alias resolves to Opus 4.8, `claude-opus-4-6[1m]`
+      // fails the version check against `opus` but the tokenized matcher
+      // falls through to `sonnet[1m]` because the `1m` context hint alone
+      // is enough to score a match.
+      await fs.promises.writeFile(
+        path.join(tempDir, "settings.json"),
+        JSON.stringify({
+          availableModels: ["claude-opus-4-6", "claude-opus-4-6[1m]"],
+        }),
+      );
+
+      const projectDir = path.join(tempDir, "project");
+      await fs.promises.mkdir(projectDir, { recursive: true });
+
+      mockQueryWithModels([
+        { value: "default", displayName: "Default", description: "Default model" },
+        {
+          value: "sonnet",
+          displayName: "Sonnet",
+          description: "Sonnet 4.6 · Best for everyday tasks",
+        },
+        {
+          value: "sonnet[1m]",
+          displayName: "Sonnet (1M context)",
+          description: "Sonnet 4.6 for long sessions",
+        },
+        {
+          value: "opus",
+          displayName: "Opus 4.8",
+          description: "Claude Opus 4.8",
+        },
+      ]);
+
+      const { ClaudeAcpAgent } = await import("../acp-agent.js");
+      const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+      const response = await (agent as any).createSession({
+        cwd: projectDir,
+        mcpServers: [],
+        _meta: { disableBuiltInTools: true },
+      });
+
+      const modelOption = response.configOptions.find((o: any) => o.id === "model");
+      const byValue: Record<string, { name: string; description?: string }> = {};
+      for (const opt of modelOption.options) {
+        byValue[opt.value] = { name: opt.name, description: opt.description };
+      }
+
+      expect(byValue["claude-opus-4-6[1m]"].name).toBe("claude-opus-4-6[1m]");
+      expect(byValue["claude-opus-4-6"].name).toBe("claude-opus-4-6");
     });
   });
 
@@ -623,6 +745,102 @@ describe("ClaudeAcpAgent settings", () => {
     });
 
     expect(setModelSpy).toHaveBeenCalledWith("claude-opus-4-6-1m");
-    expect(response.models.currentModelId).toBe("claude-opus-4-6-1m");
+    expect(response.configOptions?.find((o: any) => o.id === "model")?.currentValue).toBe(
+      "claude-opus-4-6-1m",
+    );
+  });
+
+  it("skips the initial setModel when the resolved value matches the SDK's model list verbatim", async () => {
+    // Covers the launcher case from PR #646: the launcher bakes the model into
+    // ANTHROPIC_MODEL, the SDK already starts on that model, and a second
+    // setModel call would be a redundant round-trip (and on some launcher
+    // setups, more fragile than launch-time selection).
+    const originalEnv = process.env.ANTHROPIC_MODEL;
+    process.env.ANTHROPIC_MODEL = "claude-opus-4-6";
+
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(projectDir, { recursive: true });
+
+    const setModelSpy = vi.fn();
+    querySpy.mockImplementation(() => {
+      return {
+        initializationResult: async () => ({
+          models: [
+            { value: "default", displayName: "Default", description: "" },
+            { value: "claude-sonnet-4-6", displayName: "Claude Sonnet 4.6", description: "" },
+            { value: "claude-opus-4-6", displayName: "Claude Opus 4.6", description: "" },
+          ],
+        }),
+        setModel: setModelSpy,
+        supportedCommands: async () => [],
+      } as any;
+    });
+
+    try {
+      const { ClaudeAcpAgent } = await import("../acp-agent.js");
+      const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+      const response = await (agent as any).createSession({
+        cwd: projectDir,
+        mcpServers: [],
+        _meta: { disableBuiltInTools: true },
+      });
+
+      expect(setModelSpy).not.toHaveBeenCalled();
+      expect(response.configOptions?.find((o: any) => o.id === "model")?.currentValue).toBe(
+        "claude-opus-4-6",
+      );
+    } finally {
+      if (originalEnv === undefined) {
+        delete process.env.ANTHROPIC_MODEL;
+      } else {
+        process.env.ANTHROPIC_MODEL = originalEnv;
+      }
+    }
+  });
+
+  it("still calls setModel when the allowlist synthesizes a value the SDK has not surfaced", async () => {
+    // The allowlist may rewrite a model's `value` to the user's literal ID
+    // (e.g., `claude-haiku-4-5`) even when the SDK only exposed an alias
+    // (`haiku`). In that case the SDK has not independently arrived at the
+    // user's preferred ID, so we must sync via setModel.
+    await fs.promises.writeFile(
+      path.join(tempDir, "settings.json"),
+      JSON.stringify({
+        availableModels: ["claude-haiku-4-5"],
+        model: "claude-haiku-4-5",
+      }),
+    );
+
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(projectDir, { recursive: true });
+
+    const setModelSpy = vi.fn();
+    querySpy.mockImplementation(() => {
+      return {
+        initializationResult: async () => ({
+          models: [
+            { value: "default", displayName: "Default", description: "" },
+            { value: "haiku", displayName: "Haiku", description: "Fast" },
+          ],
+        }),
+        setModel: setModelSpy,
+        supportedCommands: async () => [],
+      } as any;
+    });
+
+    const { ClaudeAcpAgent } = await import("../acp-agent.js");
+    const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+    const response = await (agent as any).createSession({
+      cwd: projectDir,
+      mcpServers: [],
+      _meta: { disableBuiltInTools: true },
+    });
+
+    expect(setModelSpy).toHaveBeenCalledWith("claude-haiku-4-5");
+    expect(response.configOptions?.find((o: any) => o.id === "model")?.currentValue).toBe(
+      "claude-haiku-4-5",
+    );
   });
 });

src/tests/acp-agent.test.ts

@@ -32,10 +32,17 @@ import {
   ClaudeAcpAgent,
   claudeCliPath,
   describeAlwaysAllow,
+  streamEventToAcpNotifications,
+  messageIdForGrouping,
   type SDKMessageFilter,
 } from "../acp-agent.js";
 import { Pushable } from "../utils.js";
-import { deleteSession, query, SDKAssistantMessage } from "@anthropic-ai/claude-agent-sdk";
+import {
+  deleteSession,
+  getSessionMessages,
+  query,
+  SDKAssistantMessage,
+} from "@anthropic-ai/claude-agent-sdk";
 import { randomUUID } from "crypto";
 
 vi.mock("@anthropic-ai/claude-agent-sdk", async (importOriginal) => {
@@ -238,13 +245,15 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("ACP subprocess integration"
       name: "compact",
     });
 
-    // Send something
-    await connection.prompt({
-      prompt: [{ type: "text", text: "Hi" }],
-      sessionId: newSessionResponse.sessionId,
-    });
-    // Clear response
-    client.takeReceivedText();
+    // Build up enough conversation that there's something to compact. The SDK
+    // refuses to compact a conversation with too few message groups.
+    for (let i = 0; i < 6; i++) {
+      await connection.prompt({
+        prompt: [{ type: "text", text: `Reply with just the number ${i}.` }],
+        sessionId: newSessionResponse.sessionId,
+      });
+      client.takeReceivedText();
+    }
 
     await connection.prompt({
       prompt: [
@@ -257,7 +266,7 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("ACP subprocess integration"
     });
 
     expect(client.takeReceivedText()).toContain("Compacting...\n\nCompacting completed.");
-  }, 30000);
+  }, 60000);
 });
 
 describe("tool conversions", () => {
@@ -662,6 +671,7 @@ describe("tool conversions", () => {
           server_tool_use: null,
           inference_geo: null,
           iterations: null,
+          output_tokens_details: null,
           speed: null,
         },
         context_management: null,
@@ -1314,6 +1324,67 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("SDK behavior", () => {
     const { value } = await q.next();
     expect(value).toMatchObject({ type: "system", session_id: sessionId });
   }, 10000);
+
+  // Pins the SDK invariant our `messageId` plumbing relies on: the Anthropic
+  // API message id is available at `message_start` (before any delta), is the
+  // same on the consolidated assistant message, and is recoverable from the
+  // persisted transcript — so a turn keeps one stable id across streaming and
+  // replay. The per-`stream_event` uuid is NOT used because it is unique per
+  // event and never persisted; this test would fail if a future SDK regressed
+  // any of those properties.
+  it("uses the API message id as a stable anchor across streaming and replay", async () => {
+    const sessionId = randomUUID();
+    const q = query({
+      prompt: "Reply with exactly these words and nothing else: hello there my friend",
+      options: {
+        systemPrompt: { type: "preset", preset: "claude_code" },
+        sessionId,
+        includePartialMessages: true,
+        maxTurns: 1,
+        allowedTools: [],
+      },
+    });
+
+    let messageStartApiId: string | undefined;
+    let consolidatedApiId: string | undefined;
+    let sawDelta = false;
+    let allPartialsTopLevel = true;
+
+    for await (const message of q) {
+      if (message.type === "assistant") {
+        consolidatedApiId = message.message.id;
+      }
+      if (message.type !== "stream_event") continue;
+      // Every streaming partial must belong to the top-level agent
+      // (parent_tool_use_id === null). Subagent work is folded into tool-result
+      // messages rather than surfaced as partial streams, which is what lets us
+      // track a single anchor without keying by parent_tool_use_id.
+      if (message.parent_tool_use_id !== null) allPartialsTopLevel = false;
+      if (message.event.type === "message_start") {
+        messageStartApiId = message.event.message.id;
+      } else if (message.event.type === "content_block_delta") {
+        sawDelta = true;
+      }
+    }
+
+    // The API message id is present at message_start (before deltas), so we can
+    // tag every streamed chunk with it, and it is identical on the consolidated
+    // assistant message.
+    expect(messageStartApiId).toBeTruthy();
+    expect(sawDelta).toBe(true);
+    expect(allPartialsTopLevel).toBe(true);
+    expect(consolidatedApiId).toBe(messageStartApiId);
+
+    // ...and the SAME id is recoverable from the persisted transcript, so chunks
+    // grouped live keep their id when the session is replayed.
+    const persisted = await getSessionMessages(sessionId);
+    const replayedAssistant = persisted.find((m) => m.type === "assistant");
+    expect(replayedAssistant).toBeDefined();
+    expect((replayedAssistant!.message as { id?: string }).id).toBe(messageStartApiId);
+    // The helper used in production must derive that same id from the replayed
+    // message.
+    expect(messageIdForGrouping(replayedAssistant!)).toBe(messageStartApiId);
+  }, 30000);
 });
 
 describe("permission requests", () => {
@@ -1544,6 +1615,8 @@ describe("stop reason propagation", () => {
       emitRawSDKMessages: false,
       contextWindowSize: 200000,
       taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
     };
   }
 
@@ -1688,6 +1761,8 @@ describe("stop reason propagation", () => {
       emitRawSDKMessages: false,
       contextWindowSize: 200000,
       taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
     };
 
     const response = await agent.prompt({
@@ -1847,6 +1922,8 @@ describe("session/close", () => {
       emitRawSDKMessages: false,
       contextWindowSize: 200000,
       taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
     };
     return agent.sessions[sessionId]!;
   }
@@ -1931,6 +2008,8 @@ describe("session/delete", () => {
       emitRawSDKMessages: false,
       contextWindowSize: 200000,
       taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
     };
     return agent.sessions[sessionId]!;
   }
@@ -2032,6 +2111,8 @@ describe("getOrCreateSession param change detection", () => {
       emitRawSDKMessages: false,
       contextWindowSize: 200000,
       taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
     };
     return agent.sessions[sessionId]!;
   }
@@ -2267,6 +2348,8 @@ describe("usage_update computation", () => {
       emitRawSDKMessages: false,
       contextWindowSize: 200000,
       taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
     };
   }
 
@@ -3104,6 +3187,49 @@ describe("usage_update computation", () => {
     // size should be 1000000 (Opus), not 200000 (the fallback if <synthetic> overrode the model)
     expect(usageUpdate.update.size).toBe(1000000);
   });
+
+  it("compact_boundary uses authoritative getContextUsage for used, keeps session window for size", async () => {
+    const { agent, updates } = createMockAgentWithCapture();
+    injectSession(agent, [
+      { type: "system", subtype: "compact_boundary", session_id: "test-session" },
+      { type: "system", subtype: "session_state_changed", state: "idle" },
+    ]);
+    const session = agent.sessions["test-session"];
+    // A 1M window learned earlier (e.g. from modelUsage) must survive compaction
+    // — getContextUsage's window field under-reports it, so we don't use it.
+    session.contextWindowSize = 1000000;
+    (session.query as any).getContextUsage = vi
+      .fn()
+      .mockResolvedValue({ totalTokens: 12345, rawMaxTokens: 200000 });
+
+    await agent.prompt({ sessionId: "test-session", prompt: [{ type: "text", text: "test" }] });
+
+    const usageUpdate = updates.find((u: any) => u.update?.sessionUpdate === "usage_update");
+    expect(usageUpdate).toBeDefined();
+    expect(usageUpdate.update.used).toBe(12345);
+    // size stays at the session's learned window, NOT getContextUsage's value.
+    expect(usageUpdate.update.size).toBe(1000000);
+    expect(session.contextWindowSize).toBe(1000000);
+  });
+
+  it("compact_boundary falls back to used:0 when getContextUsage fails", async () => {
+    const { agent, updates } = createMockAgentWithCapture();
+    injectSession(agent, [
+      { type: "system", subtype: "compact_boundary", session_id: "test-session" },
+      { type: "system", subtype: "session_state_changed", state: "idle" },
+    ]);
+    const session = agent.sessions["test-session"];
+    session.contextWindowSize = 200000;
+    (session.query as any).getContextUsage = vi.fn().mockRejectedValue(new Error("boom"));
+
+    await agent.prompt({ sessionId: "test-session", prompt: [{ type: "text", text: "test" }] });
+
+    const usageUpdate = updates.find((u: any) => u.update?.sessionUpdate === "usage_update");
+    expect(usageUpdate).toBeDefined();
+    expect(usageUpdate.update.used).toBe(0);
+    expect(usageUpdate.update.size).toBe(200000);
+    expect(session.contextWindowSize).toBe(200000);
+  });
 });
 
 describe("emitRawSDKMessages", () => {
@@ -3167,6 +3293,8 @@ describe("emitRawSDKMessages", () => {
       emitRawSDKMessages,
       contextWindowSize: 200000,
       taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
     };
   }
 
@@ -3395,6 +3523,8 @@ describe("result origin handling", () => {
       emitRawSDKMessages: false,
       contextWindowSize: 200000,
       taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
     };
   }
 
@@ -3516,3 +3646,740 @@ describe("result origin handling", () => {
     expect(response.stopReason).toBe("max_tokens");
   });
 });
+
+describe("memory_recall handling", () => {
+  function createMockAgentWithCapture() {
+    const updates: any[] = [];
+    const mockClient = {
+      sessionUpdate: async (notification: any) => {
+        updates.push(notification);
+      },
+    } as unknown as AgentSideConnection;
+    const agent = new ClaudeAcpAgent(mockClient, { log: () => {}, error: () => {} });
+    return { agent, updates };
+  }
+
+  function injectSession(agent: ClaudeAcpAgent, messages: any[]) {
+    const input = new Pushable<any>();
+    async function* messageGenerator() {
+      const iter = input[Symbol.asyncIterator]();
+      const { value: userMessage, done } = await iter.next();
+      if (!done && userMessage) {
+        yield {
+          type: "user",
+          message: userMessage.message,
+          parent_tool_use_id: null,
+          uuid: userMessage.uuid,
+          session_id: "test-session",
+          isReplay: true,
+        };
+      }
+      yield* messages;
+    }
+    agent.sessions["test-session"] = {
+      query: messageGenerator() as any,
+      input,
+      cancelled: false,
+      cwd: "/test",
+      sessionFingerprint: JSON.stringify({ cwd: "/test", mcpServers: [] }),
+      modes: { currentModeId: "default", availableModes: [] },
+      models: { currentModelId: "default", availableModels: [] },
+      modelInfos: [],
+      settingsManager: { dispose: vi.fn() } as any,
+      accumulatedUsage: {
+        inputTokens: 0,
+        outputTokens: 0,
+        cachedReadTokens: 0,
+        cachedWriteTokens: 0,
+      },
+      configOptions: [],
+      promptRunning: false,
+      pendingMessages: new Map(),
+      nextPendingOrder: 0,
+      abortController: new AbortController(),
+      emitRawSDKMessages: false,
+      contextWindowSize: 200000,
+      taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
+    };
+  }
+
+  function createResult() {
+    return {
+      type: "result" as const,
+      subtype: "success" as const,
+      stop_reason: "end_turn",
+      is_error: false,
+      result: "",
+      errors: [],
+      duration_ms: 0,
+      duration_api_ms: 0,
+      num_turns: 1,
+      total_cost_usd: 0,
+      usage: {
+        input_tokens: 10,
+        output_tokens: 5,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+      },
+      modelUsage: {},
+      permission_denials: [],
+      uuid: randomUUID(),
+      session_id: "test-session",
+    };
+  }
+
+  it("emits a synthetic tool_call for select mode with one location per memory", async () => {
+    const { agent, updates } = createMockAgentWithCapture();
+    const recallUuid = randomUUID();
+    injectSession(agent, [
+      {
+        type: "system",
+        subtype: "memory_recall",
+        mode: "select",
+        memories: [
+          { path: "/Users/test/.claude/memory/user_role.md", scope: "personal" },
+          { path: "/Users/test/.claude/memory/feedback_testing.md", scope: "personal" },
+          { path: "/Users/test/.claude/team/conventions.md", scope: "team" },
+        ],
+        uuid: recallUuid,
+        session_id: "test-session",
+      },
+      createResult(),
+      { type: "system", subtype: "session_state_changed", state: "idle" },
+    ]);
+
+    await agent.prompt({ sessionId: "test-session", prompt: [{ type: "text", text: "hi" }] });
+
+    const toolCall = updates.find((u: any) => u.update?.sessionUpdate === "tool_call");
+    expect(toolCall).toBeDefined();
+    expect(toolCall.update).toMatchObject({
+      sessionUpdate: "tool_call",
+      toolCallId: recallUuid,
+      title: "Recalled 3 memories",
+      kind: "read",
+      status: "completed",
+      locations: [
+        { path: "/Users/test/.claude/memory/user_role.md" },
+        { path: "/Users/test/.claude/memory/feedback_testing.md" },
+        { path: "/Users/test/.claude/team/conventions.md" },
+      ],
+      _meta: {
+        claudeCode: { toolName: "memory_recall", toolResponse: { mode: "select" } },
+      },
+    });
+    expect(toolCall.update.content).toBeUndefined();
+  });
+
+  it("uses singular 'memory' in title when exactly one entry", async () => {
+    const { agent, updates } = createMockAgentWithCapture();
+    injectSession(agent, [
+      {
+        type: "system",
+        subtype: "memory_recall",
+        mode: "select",
+        memories: [{ path: "/Users/test/.claude/memory/user_role.md", scope: "personal" }],
+        uuid: randomUUID(),
+        session_id: "test-session",
+      },
+      createResult(),
+      { type: "system", subtype: "session_state_changed", state: "idle" },
+    ]);
+
+    await agent.prompt({ sessionId: "test-session", prompt: [{ type: "text", text: "hi" }] });
+
+    const toolCall = updates.find((u: any) => u.update?.sessionUpdate === "tool_call");
+    expect(toolCall.update.title).toBe("Recalled 1 memory");
+  });
+
+  it("emits synthesis content and no locations for synthesize mode", async () => {
+    const { agent, updates } = createMockAgentWithCapture();
+    injectSession(agent, [
+      {
+        type: "system",
+        subtype: "memory_recall",
+        mode: "synthesize",
+        memories: [
+          {
+            path: "<synthesis:/Users/test/.claude/memory>",
+            scope: "personal",
+            content: "The user prefers terse responses and writes Go.",
+          },
+        ],
+        uuid: randomUUID(),
+        session_id: "test-session",
+      },
+      createResult(),
+      { type: "system", subtype: "session_state_changed", state: "idle" },
+    ]);
+
+    await agent.prompt({ sessionId: "test-session", prompt: [{ type: "text", text: "hi" }] });
+
+    const toolCall = updates.find((u: any) => u.update?.sessionUpdate === "tool_call");
+    expect(toolCall).toBeDefined();
+    expect(toolCall.update.title).toBe("Recalled synthesized memory");
+    expect(toolCall.update.locations).toBeUndefined();
+    expect(toolCall.update.content).toEqual([
+      {
+        type: "content",
+        content: { type: "text", text: "The user prefers terse responses and writes Go." },
+      },
+    ]);
+    expect(toolCall.update._meta.claudeCode.toolResponse).toEqual({ mode: "synthesize" });
+  });
+});
+
+describe("post-error recovery", () => {
+  function createMockAgent() {
+    const mockClient = {
+      sessionUpdate: async () => {},
+    } as unknown as AgentSideConnection;
+    return new ClaudeAcpAgent(mockClient, { log: () => {}, error: () => {} });
+  }
+
+  function createResultMessage(overrides: {
+    subtype: "success" | "error_during_execution";
+    stop_reason: string | null;
+    is_error: boolean;
+    result?: string;
+    errors?: string[];
+  }) {
+    return {
+      type: "result" as const,
+      subtype: overrides.subtype,
+      stop_reason: overrides.stop_reason,
+      is_error: overrides.is_error,
+      result: overrides.result ?? "",
+      errors: overrides.errors ?? [],
+      duration_ms: 0,
+      duration_api_ms: 0,
+      num_turns: 1,
+      total_cost_usd: 0,
+      usage: {
+        input_tokens: 10,
+        output_tokens: 5,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+      },
+      modelUsage: {},
+      permission_denials: [],
+      uuid: randomUUID(),
+      session_id: "test-session",
+    };
+  }
+
+  // Two-turn generator: turn 1 yields the caller-supplied `firstTurn`
+  // messages (including a trailing idle that the drain must consume).
+  // Turn 2 yields a clean success + idle, used to verify the next prompt
+  // sees real messages rather than the stale idle.
+  function injectTwoTurnSession(agent: ClaudeAcpAgent, firstTurn: unknown[]) {
+    const input = new Pushable<any>();
+    const interrupt = vi.fn(async () => {});
+    const close = vi.fn();
+    async function* messageGenerator() {
+      const iter = input[Symbol.asyncIterator]();
+
+      const first = await iter.next();
+      if (!first.done && first.value) {
+        yield {
+          type: "user",
+          message: first.value.message,
+          parent_tool_use_id: null,
+          uuid: first.value.uuid,
+          session_id: "test-session",
+          isReplay: true,
+        };
+      }
+      yield* firstTurn;
+
+      const second = await iter.next();
+      if (!second.done && second.value) {
+        yield {
+          type: "user",
+          message: second.value.message,
+          parent_tool_use_id: null,
+          uuid: second.value.uuid,
+          session_id: "test-session",
+          isReplay: true,
+        };
+      }
+      yield createResultMessage({ subtype: "success", stop_reason: null, is_error: false });
+      yield { type: "system", subtype: "session_state_changed", state: "idle" };
+    }
+    const gen = Object.assign(messageGenerator(), { interrupt, close });
+    agent.sessions["test-session"] = {
+      query: gen as any,
+      input,
+      cancelled: false,
+      cwd: "/test",
+      sessionFingerprint: JSON.stringify({ cwd: "/test", mcpServers: [] }),
+      modes: { currentModeId: "default", availableModes: [] },
+      models: { currentModelId: "default", availableModels: [] },
+      modelInfos: [],
+      settingsManager: { dispose: vi.fn() } as any,
+      accumulatedUsage: {
+        inputTokens: 0,
+        outputTokens: 0,
+        cachedReadTokens: 0,
+        cachedWriteTokens: 0,
+      },
+      configOptions: [],
+      promptRunning: false,
+      pendingMessages: new Map(),
+      nextPendingOrder: 0,
+      abortController: new AbortController(),
+      emitRawSDKMessages: false,
+      contextWindowSize: 200000,
+      taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
+    };
+    return { interrupt };
+  }
+
+  it("drains a failed turn's trailing idle so the next prompt is not short-circuited", async () => {
+    const agent = createMockAgent();
+    const { interrupt } = injectTwoTurnSession(agent, [
+      createResultMessage({
+        subtype: "success",
+        stop_reason: "end_turn",
+        is_error: true,
+        result: "boom",
+      }),
+      // Trailing idle from the failed turn. Without draining, the next
+      // prompt's first query.next() would consume this and short-circuit
+      // to end_turn with zero usage (issue #654).
+      { type: "system", subtype: "session_state_changed", state: "idle" },
+    ]);
+
+    await expect(
+      agent.prompt({
+        sessionId: "test-session",
+        prompt: [{ type: "text", text: "first" }],
+      }),
+    ).rejects.toThrow();
+
+    expect(interrupt).toHaveBeenCalled();
+
+    const second = await agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: "second" }],
+    });
+    expect(second.stopReason).toBe("end_turn");
+    expect(second.usage?.inputTokens).toBe(10);
+    expect(second.usage?.outputTokens).toBe(5);
+  });
+
+  it("cancels all queued pending prompts when a turn errors", async () => {
+    const agent = createMockAgent();
+    injectTwoTurnSession(agent, [
+      createResultMessage({
+        subtype: "success",
+        stop_reason: "end_turn",
+        is_error: true,
+        result: "boom",
+      }),
+      { type: "system", subtype: "session_state_changed", state: "idle" },
+    ]);
+
+    // Simulate two prompts already queued behind the running turn. Both
+    // resolvers should fire with `true` (cancelled) when the running
+    // prompt errors, and the map should be cleared.
+    const session = agent.sessions["test-session"];
+    let resolveA!: (cancelled: boolean) => void;
+    let resolveB!: (cancelled: boolean) => void;
+    const pendingA = new Promise<boolean>((r) => (resolveA = r));
+    const pendingB = new Promise<boolean>((r) => (resolveB = r));
+    session.pendingMessages.set("uuid-a", { resolve: resolveA, order: 0 });
+    session.pendingMessages.set("uuid-b", { resolve: resolveB, order: 1 });
+
+    await expect(
+      agent.prompt({
+        sessionId: "test-session",
+        prompt: [{ type: "text", text: "first" }],
+      }),
+    ).rejects.toThrow();
+
+    await expect(pendingA).resolves.toBe(true);
+    await expect(pendingB).resolves.toBe(true);
+    expect(session.pendingMessages.size).toBe(0);
+  });
+});
+
+describe("session/cancel wedge recovery (issue #680)", () => {
+  function createMockAgent() {
+    const mockClient = {
+      sessionUpdate: async () => {},
+    } as unknown as AgentSideConnection;
+    return new ClaudeAcpAgent(mockClient, { log: () => {}, error: () => {} });
+  }
+
+  // Generator that replays the prompt's user message and then blocks forever,
+  // simulating the SDK wedged in a `TaskOutput { block: true }` poll against a
+  // hung background task. `interrupt()` is a no-op — it does NOT unblock the
+  // generator, matching the SDK behavior described in the issue.
+  function injectWedgedSession(agent: ClaudeAcpAgent, opts: { interruptUnblocks?: boolean } = {}) {
+    const input = new Pushable<any>();
+    const interrupt = vi.fn(async () => {});
+    const close = vi.fn();
+    // A promise the wedged poll awaits. When `interruptUnblocks` is set, the
+    // mocked interrupt() resolves it so the generator yields a trailing idle —
+    // the normal, healthy interrupt path.
+    let releaseBlock!: () => void;
+    const blocked = new Promise<void>((resolve) => {
+      releaseBlock = resolve;
+    });
+    if (opts.interruptUnblocks) {
+      interrupt.mockImplementation(async () => {
+        releaseBlock();
+      });
+    }
+
+    async function* messageGenerator() {
+      const iter = input[Symbol.asyncIterator]();
+      const first = await iter.next();
+      if (!first.done && first.value) {
+        yield {
+          type: "user",
+          message: first.value.message,
+          parent_tool_use_id: null,
+          uuid: first.value.uuid,
+          session_id: "test-session",
+          isReplay: true,
+        };
+      }
+      // Wedge: never yield again unless interrupt() releases us.
+      await blocked;
+      yield { type: "system", subtype: "session_state_changed", state: "idle" };
+    }
+
+    const gen = Object.assign(messageGenerator(), { interrupt, close });
+    agent.sessions["test-session"] = {
+      query: gen as any,
+      input,
+      cancelled: false,
+      cwd: "/test",
+      sessionFingerprint: JSON.stringify({ cwd: "/test", mcpServers: [] }),
+      modes: { currentModeId: "default", availableModes: [] },
+      models: { currentModelId: "default", availableModels: [] },
+      modelInfos: [],
+      settingsManager: { dispose: vi.fn() } as any,
+      accumulatedUsage: {
+        inputTokens: 0,
+        outputTokens: 0,
+        cachedReadTokens: 0,
+        cachedWriteTokens: 0,
+      },
+      configOptions: [],
+      promptRunning: false,
+      pendingMessages: new Map(),
+      nextPendingOrder: 0,
+      abortController: new AbortController(),
+      emitRawSDKMessages: false,
+      contextWindowSize: 200000,
+      taskState: new Map(),
+      toolUseCache: {},
+      messageIdToUuid: new Map(),
+    };
+    return { interrupt };
+  }
+
+  it("resolves the pending prompt with cancelled when the SDK never yields after interrupt", async () => {
+    const agent = createMockAgent();
+    // Shrink the grace period so the test doesn't wait the production default.
+    agent.forceCancelGraceMs = 20;
+    const { interrupt } = injectWedgedSession(agent);
+
+    const promptPromise = agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: "run cargo test" }],
+    });
+
+    // Let the loop consume the replay and block on the wedged query.next().
+    await new Promise((r) => setTimeout(r, 5));
+
+    await agent.cancel({ sessionId: "test-session" });
+
+    const response = await promptPromise;
+    expect(response.stopReason).toBe("cancelled");
+    expect(interrupt).toHaveBeenCalled();
+  });
+
+  it("returns cancelled through the normal idle path without waiting the grace period when interrupt works", async () => {
+    const agent = createMockAgent();
+    // Large grace so that if the test ever falls through to the backstop it
+    // would hang past the test timeout instead of passing by accident.
+    agent.forceCancelGraceMs = 60_000;
+    const { interrupt } = injectWedgedSession(agent, { interruptUnblocks: true });
+
+    const promptPromise = agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: "run cargo test" }],
+    });
+
+    await new Promise((r) => setTimeout(r, 5));
+
+    await agent.cancel({ sessionId: "test-session" });
+
+    const response = await promptPromise;
+    expect(response.stopReason).toBe("cancelled");
+    expect(interrupt).toHaveBeenCalled();
+    // Backstop timer must have been cleared so it can't fire later.
+    expect(agent.sessions["test-session"].forceCancelTimer).toBeUndefined();
+  });
+
+  it("does not arm the backstop when no prompt is running", async () => {
+    const agent = createMockAgent();
+    injectWedgedSession(agent);
+
+    await agent.cancel({ sessionId: "test-session" });
+
+    const session = agent.sessions["test-session"];
+    expect(session.cancelled).toBe(true);
+    expect(session.forceCancelTimer).toBeUndefined();
+  });
+
+  it("does not reset the force-cancel floor on repeated cancels", async () => {
+    const agent = createMockAgent();
+    // Long floor so the timer handle stays observable across both cancels.
+    agent.forceCancelGraceMs = 60_000;
+    injectWedgedSession(agent);
+
+    const promptPromise = agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: "run cargo test" }],
+    });
+    await new Promise((r) => setTimeout(r, 5));
+
+    await agent.cancel({ sessionId: "test-session" });
+    const firstTimer = agent.sessions["test-session"].forceCancelTimer;
+    expect(firstTimer).toBeDefined();
+
+    await agent.cancel({ sessionId: "test-session" });
+    // Same handle: the second cancel did not clear-and-rearm (which would push
+    // the floor out). The deadline stays anchored to the first cancel.
+    expect(agent.sessions["test-session"].forceCancelTimer).toBe(firstTimer);
+
+    // Clean up the wedged prompt + long timer.
+    await agent.closeSession({ sessionId: "test-session" });
+    await expect(promptPromise).resolves.toEqual({ stopReason: "cancelled" });
+  });
+
+  it("resolves an in-flight wedged prompt immediately when the session is closed", async () => {
+    const agent = createMockAgent();
+    // Large floor: if closeSession relied on the force-cancel timer this would
+    // hang past the test timeout. Teardown must wake the loop via
+    // cancelController instead.
+    agent.forceCancelGraceMs = 60_000;
+    injectWedgedSession(agent);
+
+    const promptPromise = agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: "run cargo test" }],
+    });
+    await new Promise((r) => setTimeout(r, 5));
+
+    await agent.closeSession({ sessionId: "test-session" });
+
+    await expect(promptPromise).resolves.toEqual({ stopReason: "cancelled" });
+    expect(agent.sessions["test-session"]).toBeUndefined();
+  });
+});
+
+describe("streamEventToAcpNotifications", () => {
+  it("treats `ping` keep-alive events as no-ops without logging to stderr", () => {
+    const errors: unknown[][] = [];
+    const logger = {
+      log: () => {},
+      error: (...args: unknown[]) => {
+        errors.push(args);
+      },
+    };
+    const pingMessage = {
+      type: "stream_event",
+      parent_tool_use_id: null,
+      uuid: randomUUID(),
+      session_id: "test-session",
+      // The SDK's typed `BetaRawMessageStreamEvent` union doesn't include
+      // `ping`, but the API emits it on the wire and the SDK passes it
+      // through. Cast through `unknown` to feed the realistic runtime shape.
+      event: { type: "ping" } as unknown,
+    } as Parameters<typeof streamEventToAcpNotifications>[0];
+
+    const result = streamEventToAcpNotifications(
+      pingMessage,
+      "test-session",
+      {},
+      { sessionUpdate: async () => {} } as unknown as Parameters<
+        typeof streamEventToAcpNotifications
+      >[3],
+      logger,
+    );
+
+    expect(result).toEqual([]);
+    expect(errors).toEqual([]);
+  });
+
+  it("attaches the supplied messageId to streamed text chunks", () => {
+    const messageId = randomUUID();
+    const message = {
+      type: "stream_event",
+      parent_tool_use_id: null,
+      uuid: randomUUID(),
+      session_id: "test-session",
+      event: {
+        type: "content_block_delta",
+        index: 0,
+        delta: { type: "text_delta", text: "hello" },
+      },
+    } as Parameters<typeof streamEventToAcpNotifications>[0];
+
+    const result = streamEventToAcpNotifications(
+      message,
+      "test",
+      {},
+      {} as AgentSideConnection,
+      console,
+      { messageId },
+    );
+
+    expect(result).toEqual([
+      {
+        sessionId: "test",
+        update: {
+          sessionUpdate: "agent_message_chunk",
+          content: { type: "text", text: "hello" },
+          messageId,
+        },
+      },
+    ]);
+  });
+});
+
+describe("toAcpNotifications messageId", () => {
+  const messageId = "11111111-2222-3333-4444-555555555555";
+
+  it("sets messageId on agent message chunks from string content", () => {
+    const result = toAcpNotifications(
+      "hello world",
+      "assistant",
+      "test",
+      {},
+      {} as AgentSideConnection,
+      console,
+      { messageId },
+    );
+
+    expect(result).toEqual([
+      {
+        sessionId: "test",
+        update: {
+          sessionUpdate: "agent_message_chunk",
+          content: { type: "text", text: "hello world" },
+          messageId,
+        },
+      },
+    ]);
+  });
+
+  it("sets messageId on user message chunks and thought chunks", () => {
+    const userResult = toAcpNotifications(
+      [{ type: "text", text: "hi" }],
+      "user",
+      "test",
+      {},
+      {} as AgentSideConnection,
+      console,
+      { messageId },
+    );
+    expect(userResult[0].update).toMatchObject({
+      sessionUpdate: "user_message_chunk",
+      messageId,
+    });
+
+    const thoughtResult = toAcpNotifications(
+      [{ type: "thinking", thinking: "hmm", signature: "" }],
+      "assistant",
+      "test",
+      {},
+      {} as AgentSideConnection,
+      console,
+      { messageId },
+    );
+    expect(thoughtResult[0].update).toMatchObject({
+      sessionUpdate: "agent_thought_chunk",
+      messageId,
+    });
+  });
+
+  it("omits messageId when none is supplied", () => {
+    const result = toAcpNotifications(
+      "hello",
+      "assistant",
+      "test",
+      {},
+      {} as AgentSideConnection,
+      console,
+    );
+    expect(result[0].update).not.toHaveProperty("messageId");
+  });
+
+  it("never sets messageId on non-chunk updates (tool_call)", () => {
+    const result = toAcpNotifications(
+      [
+        {
+          type: "tool_use",
+          id: "toolu_abc",
+          name: "Read",
+          input: { file_path: "/tmp/x" },
+        },
+      ],
+      "assistant",
+      "test",
+      {},
+      {} as AgentSideConnection,
+      console,
+      { messageId, registerHooks: false },
+    );
+    expect(result[0].update.sessionUpdate).toBe("tool_call");
+    expect(result[0].update).not.toHaveProperty("messageId");
+  });
+});
+
+describe("messageIdForGrouping", () => {
+  it("uses the Anthropic API message id for assistant messages", () => {
+    const message = {
+      type: "assistant",
+      uuid: "de242400-cdb3-4af7-9856-d3b114b20af9",
+      message: { id: "msg_018DQGVuZbGYwVnvDakAP9Do", role: "assistant" },
+    };
+    // The API id is identical at message_start, on the consolidated message,
+    // and in the persisted transcript — so it stays stable across replay,
+    // unlike the per-message uuid.
+    expect(messageIdForGrouping(message)).toBe("msg_018DQGVuZbGYwVnvDakAP9Do");
+  });
+
+  it("falls back to the uuid for assistant messages without an API id", () => {
+    const message = {
+      type: "assistant",
+      uuid: "de242400-cdb3-4af7-9856-d3b114b20af9",
+      message: { role: "assistant" },
+    };
+    expect(messageIdForGrouping(message)).toBe("de242400-cdb3-4af7-9856-d3b114b20af9");
+  });
+
+  it("uses the uuid for user messages (they carry no API id and aren't streamed)", () => {
+    const message = {
+      type: "user",
+      uuid: "11111111-2222-3333-4444-555555555555",
+      message: { id: "msg_should_be_ignored", role: "user" },
+    };
+    expect(messageIdForGrouping(message)).toBe("11111111-2222-3333-4444-555555555555");
+  });
+
+  it("returns undefined when there is no usable id", () => {
+    expect(messageIdForGrouping({ type: "system", message: {} })).toBeUndefined();
+    expect(messageIdForGrouping({ type: "assistant", uuid: "", message: {} })).toBeUndefined();
+  });
+});

src/tests/authorization.test.ts

@@ -15,7 +15,10 @@ const mockQuery = vi.hoisted(() =>
   })),
 );
 
-vi.mock("@anthropic-ai/claude-agent-sdk", () => ({
+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,
 }));
 

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

@@ -473,4 +473,62 @@ describe("createSession options merging", () => {
     // ACP-provided MCP server should also be present
     expect(capturedOptions!.mcpServers).toHaveProperty("acp-server");
   });
+
+  describe("thinking config from MAX_THINKING_TOKENS", () => {
+    let originalMaxThinking: string | undefined;
+
+    beforeEach(() => {
+      originalMaxThinking = process.env.MAX_THINKING_TOKENS;
+      delete process.env.MAX_THINKING_TOKENS;
+    });
+
+    afterEach(() => {
+      if (originalMaxThinking !== undefined) {
+        process.env.MAX_THINKING_TOKENS = originalMaxThinking;
+      } else {
+        delete process.env.MAX_THINKING_TOKENS;
+      }
+    });
+
+    it("leaves thinking unset (SDK default) when env var is absent", async () => {
+      await agent.newSession({ cwd: "/test", mcpServers: [] });
+      expect(capturedOptions!.thinking).toBeUndefined();
+      // The deprecated option must not be set either.
+      expect(capturedOptions!.maxThinkingTokens).toBeUndefined();
+    });
+
+    it("maps 0 to disabled thinking", async () => {
+      process.env.MAX_THINKING_TOKENS = "0";
+      await agent.newSession({ cwd: "/test", mcpServers: [] });
+      expect(capturedOptions!.thinking).toEqual({ type: "disabled" });
+    });
+
+    it("maps a positive value to a fixed thinking budget", async () => {
+      process.env.MAX_THINKING_TOKENS = "12000";
+      await agent.newSession({ cwd: "/test", mcpServers: [] });
+      expect(capturedOptions!.thinking).toEqual({ type: "enabled", budgetTokens: 12000 });
+    });
+
+    it("ignores a non-numeric value", async () => {
+      process.env.MAX_THINKING_TOKENS = "lots";
+      await agent.newSession({ cwd: "/test", mcpServers: [] });
+      expect(capturedOptions!.thinking).toBeUndefined();
+    });
+
+    it("lets a user-provided thinking option override the env default", async () => {
+      process.env.MAX_THINKING_TOKENS = "12000";
+      await agent.newSession({
+        cwd: "/test",
+        mcpServers: [],
+        _meta: {
+          claudeCode: {
+            options: {
+              thinking: { type: "adaptive" },
+            },
+          },
+        },
+      });
+      expect(capturedOptions!.thinking).toEqual({ type: "adaptive" });
+    });
+  });
 });

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

@@ -65,8 +65,9 @@ const MOCK_CONFIG_OPTIONS = [
     description: "Available effort levels for this model",
     type: "select",
     category: "effort",
-    currentValue: "high",
+    currentValue: "default",
     options: [
+      { value: "default", name: "Default" },
       { value: "low", name: "Low" },
       { value: "medium", name: "Medium" },
       { value: "high", name: "High" },
@@ -376,33 +377,30 @@ describe("session config options", () => {
     });
   });
 
-  describe("unstable_setSessionModel sends config_option_update", () => {
+  describe("setSessionConfigOption(model) returns updated configOptions", () => {
     beforeEach(() => {
       populateSession();
     });
 
-    it("sends config_option_update when model is changed via setSessionModel", async () => {
-      await agent.unstable_setSessionModel({
+    it("returns configOptions with the new model when changed", async () => {
+      const response = await agent.setSessionConfigOption({
         sessionId: SESSION_ID,
-        modelId: "claude-sonnet-4-6",
+        configId: "model",
+        value: "claude-sonnet-4-6",
       });
 
-      const configUpdate = sessionUpdates.find(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      expect(configUpdate).toBeDefined();
-      expect(configUpdate?.update).toMatchObject({
-        sessionUpdate: "config_option_update",
-        configOptions: expect.arrayContaining([
+      expect(response.configOptions).toEqual(
+        expect.arrayContaining([
           expect.objectContaining({ id: "model", currentValue: "claude-sonnet-4-6" }),
         ]),
-      });
+      );
     });
 
     it("updates stored configOptions currentValue when model changes", async () => {
-      await agent.unstable_setSessionModel({
+      await agent.setSessionConfigOption({
         sessionId: SESSION_ID,
-        modelId: "claude-sonnet-4-6",
+        configId: "model",
+        value: "claude-sonnet-4-6",
       });
 
       const session = (
@@ -414,7 +412,7 @@ describe("session config options", () => {
       expect(modelOption?.currentValue).toBe("claude-sonnet-4-6");
     });
 
-    it("includes updated effort in config_option_update when model drops effort support", async () => {
+    it("drops effort from returned configOptions when model drops effort support", async () => {
       const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
       session.modelInfos = [
         {
@@ -432,23 +430,18 @@ describe("session config options", () => {
         },
       ];
 
-      await agent.unstable_setSessionModel({
+      const response = await agent.setSessionConfigOption({
         sessionId: SESSION_ID,
-        modelId: "claude-sonnet-4-6",
+        configId: "model",
+        value: "claude-sonnet-4-6",
       });
 
-      const configUpdate = sessionUpdates.find(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      expect(configUpdate).toBeDefined();
-      const effortOption = (configUpdate?.update as any).configOptions.find(
-        (o: any) => o.id === "effort",
-      );
+      const effortOption = response.configOptions.find((o) => o.id === "effort");
       expect(effortOption).toBeUndefined();
-      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: undefined });
+      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: null });
     });
 
-    it("clamps effort in config_option_update when new model has different supported levels", async () => {
+    it("clamps effort in returned configOptions when new model has different supported levels", async () => {
       // Set current effort to "max" which the new model won't support
       const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
       const effortOpt = session.configOptions.find((o: any) => o.id === "effort");
@@ -471,39 +464,31 @@ describe("session config options", () => {
         },
       ];
 
-      await agent.unstable_setSessionModel({
+      const response = await agent.setSessionConfigOption({
         sessionId: SESSION_ID,
-        modelId: "claude-sonnet-4-6",
+        configId: "model",
+        value: "claude-sonnet-4-6",
       });
 
-      const configUpdate = sessionUpdates.find(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      const effortOption = (configUpdate?.update as any).configOptions.find(
-        (o: any) => o.id === "effort",
-      );
+      const effortOption = response.configOptions.find((o) => o.id === "effort");
       expect(effortOption).toBeDefined();
-      expect(effortOption.currentValue).toBe("high");
-      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: "high" });
+      expect(effortOption?.currentValue).toBe("default");
+      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: null });
     });
 
-    it("preserves effort in config_option_update when new model supports same level", async () => {
+    it("preserves effort in returned configOptions when new model supports same level", async () => {
       // Set effort to "low" first
       const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
       const effortOpt = session.configOptions.find((o: any) => o.id === "effort");
       if (effortOpt) effortOpt.currentValue = "low";
 
-      await agent.unstable_setSessionModel({
+      const response = await agent.setSessionConfigOption({
         sessionId: SESSION_ID,
-        modelId: "claude-sonnet-4-6",
+        configId: "model",
+        value: "claude-sonnet-4-6",
       });
 
-      const configUpdate = sessionUpdates.find(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      const effortOption = (configUpdate?.update as any).configOptions.find(
-        (o: any) => o.id === "effort",
-      );
+      const effortOption = response.configOptions.find((o) => o.id === "effort");
       expect(effortOption?.currentValue).toBe("low");
       // Effort didn't change, so applyFlagSettings should NOT be called
       expect(applyFlagSettingsSpy).not.toHaveBeenCalled();
@@ -557,6 +542,31 @@ describe("session config options", () => {
       expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: "low" });
     });
 
+    it("calls applyFlagSettings with null effortLevel for 'default'", async () => {
+      // Set effort to a non-default value first
+      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
+      const effortOpt = session.configOptions.find((o: any) => o.id === "effort");
+      if (effortOpt) effortOpt.currentValue = "high";
+
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "effort",
+        value: "default",
+      });
+
+      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: null });
+
+      // The SDK's applyFlagSettings travels over a JSON pipe and only clears a
+      // flag-layer key when an explicit `null` is sent — `undefined` is
+      // dropped during JSON.stringify, which would leave the previous effort
+      // override in place. Round-trip the call args through JSON to make sure
+      // the key actually reaches the SDK.
+      const calls = applyFlagSettingsSpy.mock.calls;
+      const lastCallArgs = calls[calls.length - 1]?.[0];
+      const serialized = JSON.parse(JSON.stringify(lastCallArgs));
+      expect(serialized).toHaveProperty("effortLevel", null);
+    });
+
     it("updates effort currentValue in returned configOptions", async () => {
       const response = await agent.setSessionConfigOption({
         sessionId: SESSION_ID,
@@ -663,7 +673,7 @@ describe("session config options", () => {
         value: "claude-sonnet-4-6",
       });
 
-      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: undefined });
+      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: null });
     });
 
     it("adds effort option when switching to a model that supports effort", async () => {
@@ -696,8 +706,8 @@ describe("session config options", () => {
 
       const effortOption = response.configOptions.find((o) => o.id === "effort");
       expect(effortOption).toBeDefined();
-      // No previous effort, so defaults to "high" (the API default)
-      expect(effortOption?.currentValue).toBe("high");
+      // No previous effort, so defaults to "default" (no effort override)
+      expect(effortOption?.currentValue).toBe("default");
     });
 
     it("clamps effort to valid value when new model has different supported levels", async () => {
@@ -731,10 +741,10 @@ describe("session config options", () => {
 
       const effortOption = response.configOptions.find((o) => o.id === "effort");
       expect(effortOption).toBeDefined();
-      // "max" is not in sonnet's levels, so should fall back to "high" (the API default)
-      expect(effortOption?.currentValue).toBe("high");
-      // SDK should be told about the clamped value
-      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: "high" });
+      // "max" is not in sonnet's levels, so should fall back to "default" (no effort override)
+      expect(effortOption?.currentValue).toBe("default");
+      // SDK should be told to clear the effort override
+      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: null });
     });
 
     it("preserves effort value when new model supports the same level", async () => {
@@ -795,10 +805,11 @@ describe("session config options", () => {
       expect(session.configOptions.find((o) => o.id === "mode")?.currentValue).toBe("plan");
     });
 
-    it("setSessionModel also syncs configOptions", async () => {
-      await agent.unstable_setSessionModel({
+    it("setSessionConfigOption(model) also syncs configOptions", async () => {
+      await agent.setSessionConfigOption({
         sessionId: SESSION_ID,
-        modelId: "claude-sonnet-4-6",
+        configId: "model",
+        value: "claude-sonnet-4-6",
       });
 
       const session = (
@@ -921,58 +932,21 @@ describe("session config options", () => {
     it("drops `auto` from available modes when switching to Haiku", async () => {
       setupHaikuOpusSession("default");
 
-      await agent.unstable_setSessionModel({
+      const response = await agent.setSessionConfigOption({
         sessionId: SESSION_ID,
-        modelId: "claude-haiku-4-5",
+        configId: "model",
+        value: "claude-haiku-4-5",
       });
 
-      const configUpdate = sessionUpdates.find(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      expect(configUpdate).toBeDefined();
-      const modeOption = (configUpdate?.update as any).configOptions.find(
-        (o: any) => o.id === "mode",
-      );
+      const modeOption = response.configOptions.find((o) => o.id === "mode");
       expect(modeOption).toBeDefined();
-      const modeValues = modeOption.options.map((o: any) => o.value);
+      const modeValues = (modeOption as any).options.map((o: any) => o.value);
       expect(modeValues).not.toContain("auto");
       expect(modeValues).toEqual(
         expect.arrayContaining(["default", "acceptEdits", "plan", "dontAsk"]),
       );
     });
 
-    it("clamps to `default` and emits current_mode_update when Opus(auto) → Haiku", async () => {
-      setupHaikuOpusSession("auto");
-
-      await agent.unstable_setSessionModel({
-        sessionId: SESSION_ID,
-        modelId: "claude-haiku-4-5",
-      });
-
-      // SDK was synced to "default".
-      expect(setPermissionModeSpy).toHaveBeenCalledWith("default");
-
-      // current_mode_update was emitted before config_option_update so a
-      // client applying notifications in order observes the mode change
-      // before re-rendering the config-option list.
-      const modeUpdateIdx = sessionUpdates.findIndex(
-        (n) => n.update.sessionUpdate === "current_mode_update",
-      );
-      const configUpdateIdx = sessionUpdates.findIndex(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      expect(modeUpdateIdx).toBeGreaterThanOrEqual(0);
-      expect(configUpdateIdx).toBeGreaterThanOrEqual(0);
-      expect(modeUpdateIdx).toBeLessThan(configUpdateIdx);
-      expect((sessionUpdates[modeUpdateIdx].update as any).currentModeId).toBe("default");
-
-      // configOptions reflect the clamped mode.
-      const modeOption = (sessionUpdates[configUpdateIdx].update as any).configOptions.find(
-        (o: any) => o.id === "mode",
-      );
-      expect(modeOption.currentValue).toBe("default");
-    });
-
     it("re-adds `auto` when switching from Haiku back to Opus", async () => {
       const session = setupHaikuOpusSession("default");
       // Pretend Haiku is the current model with no `auto`.
@@ -987,19 +961,15 @@ describe("session config options", () => {
         description: m.description,
       }));
 
-      await agent.unstable_setSessionModel({
+      const response = await agent.setSessionConfigOption({
         sessionId: SESSION_ID,
-        modelId: "claude-opus-4-5",
+        configId: "model",
+        value: "claude-opus-4-5",
       });
 
-      const configUpdate = sessionUpdates.find(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      expect(configUpdate).toBeDefined();
-      const modeOption = (configUpdate?.update as any).configOptions.find(
-        (o: any) => o.id === "mode",
-      );
-      const modeValues = modeOption.options.map((o: any) => o.value);
+      const modeOption = response.configOptions.find((o) => o.id === "mode");
+      expect(modeOption).toBeDefined();
+      const modeValues = (modeOption as any).options.map((o: any) => o.value);
       expect(modeValues).toContain("auto");
 
       // The current mode ("default") is still valid on Opus, so no
@@ -1013,9 +983,10 @@ describe("session config options", () => {
     it("preserves the current mode when it remains valid after a model switch", async () => {
       setupHaikuOpusSession("plan");
 
-      await agent.unstable_setSessionModel({
+      const response = await agent.setSessionConfigOption({
         sessionId: SESSION_ID,
-        modelId: "claude-haiku-4-5",
+        configId: "model",
+        value: "claude-haiku-4-5",
       });
 
       // `plan` is in availableModes for both Opus and Haiku, so no clamp.
@@ -1026,20 +997,15 @@ describe("session config options", () => {
       );
       expect(modeUpdates).toHaveLength(0);
 
-      const configUpdate = sessionUpdates.find(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      const modeOption = (configUpdate?.update as any).configOptions.find(
-        (o: any) => o.id === "mode",
-      );
-      expect(modeOption.currentValue).toBe("plan");
+      const modeOption = response.configOptions.find((o) => o.id === "mode");
+      expect((modeOption as any).currentValue).toBe("plan");
     });
 
     it("clamps mode and emits current_mode_update via setSessionConfigOption(model)", async () => {
-      // Mirrors the unstable_setSessionModel(auto → Haiku) test, but goes
-      // through the request/response API. The `current_mode_update` side
-      // effect must still fire so clients learn about the clamp regardless of
-      // which entry point triggered the model switch.
+      // Switching Opus(auto) → Haiku clamps the mode to "default". The
+      // `current_mode_update` side effect must fire so clients learn about the
+      // clamp even though the request/response API returns the new
+      // configOptions rather than emitting a config_option_update.
       setupHaikuOpusSession("auto");
 
       const response = await agent.setSessionConfigOption({

src/tests/tools.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, beforeEach } from "vitest";
 import { AgentSideConnection, ClientCapabilities } from "@agentclientprotocol/sdk";
 import { ImageBlockParam, ToolResultBlockParam } from "@anthropic-ai/sdk/resources";
 import {
@@ -673,14 +673,19 @@ describe("Bash terminal output", () => {
   });
 
   describe("toAcpNotifications with clientCapabilities", () => {
-    const toolUseCache: ToolUseCache = {
-      toolu_bash: {
-        type: "tool_use",
-        id: "toolu_bash",
-        name: "Bash",
-        input: { command: "ls -la" },
-      },
-    };
+    // Reset before each test: toAcpNotifications prunes the cache entry once it
+    // maps the tool_result, so a shared object would be empty by the 2nd test.
+    let toolUseCache: ToolUseCache;
+    beforeEach(() => {
+      toolUseCache = {
+        toolu_bash: {
+          type: "tool_use",
+          id: "toolu_bash",
+          name: "Bash",
+          input: { command: "ls -la" },
+        },
+      };
+    });
 
     const bashResult: BetaBashCodeExecutionResultBlock = {
       type: "bash_code_execution_result",
@@ -792,11 +797,21 @@ describe("Bash terminal output", () => {
         { clientCapabilities: { _meta: { terminal_output: true } } },
       );
 
+      // Fresh cache: the withSupport call above already consumed the entry,
+      // since toAcpNotifications prunes the tool_use once it maps the result.
+      const toolUseCacheWithoutSupport: ToolUseCache = {
+        toolu_bash: {
+          type: "tool_use",
+          id: "toolu_bash",
+          name: "Bash",
+          input: { command: "ls -la" },
+        },
+      };
       const withoutSupport = toAcpNotifications(
         [toolResult],
         "assistant",
         "test-session",
-        toolUseCache,
+        toolUseCacheWithoutSupport,
         mockClient,
         mockLogger,
       );
@@ -848,6 +863,31 @@ describe("Bash terminal output", () => {
     });
   });
 
+  describe("toolUseCache pruning", () => {
+    it("retains the tool_use entry until its result, then prunes it", () => {
+      const toolUseCache: ToolUseCache = {};
+      const toolUse = {
+        type: "tool_use" as const,
+        id: "toolu_read",
+        name: "Read",
+        input: { file_path: "/tmp/x.txt" },
+      };
+
+      // tool_use is cached and kept (the matching result hasn't arrived yet).
+      toAcpNotifications([toolUse], "assistant", "s", toolUseCache, mockClient, mockLogger);
+      expect(toolUseCache.toolu_read).toBeDefined();
+
+      // tool_result resolves it, so the entry is pruned to bound memory.
+      const toolResult: ToolResultBlockParam = {
+        type: "tool_result",
+        tool_use_id: "toolu_read",
+        content: [{ type: "text", text: "hello" }],
+      };
+      toAcpNotifications([toolResult], "assistant", "s", toolUseCache, mockClient, mockLogger);
+      expect(toolUseCache.toolu_read).toBeUndefined();
+    });
+  });
+
   describe("post-tool-use hook sends diff content for Edit tool", () => {
     it("should include content and locations from structuredPatch in hook update", async () => {
       const toolUseCache: ToolUseCache = {};