chore(main): release 0.59.0 (#860)

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


##
[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](e67dacdcac))
* **deps:** bump @anthropic-ai/claude-agent-sdk to 0.3.207
([#874](https://github.com/agentclientprotocol/claude-agent-acp/issues/874))
([c7f5b8f](c7f5b8fe76))


### Bug Fixes

* Add subagent parent tool use attribution
([#859](https://github.com/agentclientprotocol/claude-agent-acp/issues/859))
([9cd48c5](9cd48c597a))
* forward result text when the turn emitted no assistant message
([#858](https://github.com/agentclientprotocol/claude-agent-acp/issues/858))
([61ae860](61ae8609d4))
* hold a turn open while its background subagents are still live
([#870](https://github.com/agentclientprotocol/claude-agent-acp/issues/870))
([7a70f82](7a70f82739))
* Refine tool calls from streamed input
([#867](https://github.com/agentclientprotocol/claude-agent-acp/issues/867))
([2c19974](2c19974d5b))
* Seed context window from SDK usage report
([#868](https://github.com/agentclientprotocol/claude-agent-acp/issues/868))
([3ba2d36](3ba2d367a2)),
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](c7dff3cf7e)),
closes
[#863](https://github.com/agentclientprotocol/claude-agent-acp/issues/863)

---
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@df4cb1c069e1874edd31b4311f1884172cec0e10
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
 
       - name: Use Node.js
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e

.github/workflows/publish.yml

@@ -44,14 +44,12 @@ jobs:
       contents: read
       id-token: write
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
       # Setup .npmrc file to publish to npm
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
         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

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.46.0"
+  ".": "0.59.0"
 }

CHANGELOG.md

@@ -1,5 +1,177 @@
 # Changelog
 
+## [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)
+
+
+### Bug Fixes
+
+* apply modelOverrides when resolving availableModels allowlist ([#827](https://github.com/agentclientprotocol/claude-agent-acp/issues/827)) ([98c284b](https://github.com/agentclientprotocol/claude-agent-acp/commit/98c284bb871a96710596dfdc2b9ea25d2400f6b2))
+
+## [0.54.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.53.0...v0.54.0) (2026-06-30)
+
+
+### Features
+
+* Add Fast mode session config support ([#828](https://github.com/agentclientprotocol/claude-agent-acp/issues/828)) ([fa949a2](https://github.com/agentclientprotocol/claude-agent-acp/commit/fa949a20db0e33f2d63aebeb37e9fea212d8ee95))
+* **deps-dev:** bump prettier from 3.9.1 to 3.9.3 in the minor group ([#821](https://github.com/agentclientprotocol/claude-agent-acp/issues/821)) ([b8df8e0](https://github.com/agentclientprotocol/claude-agent-acp/commit/b8df8e0e5460fd782214f4dde488f7476c80c454))
+* **deps:** bump @anthropic-ai/claude-agent-sdk to 0.3.197 for Sonnet 5 ([#826](https://github.com/agentclientprotocol/claude-agent-acp/issues/826)) ([ef42c46](https://github.com/agentclientprotocol/claude-agent-acp/commit/ef42c46e5aea3bb53f433b9f9dd36a62a9f2df6a))
+* **deps:** bump fast-uri from 3.1.2 to 3.1.3 ([#822](https://github.com/agentclientprotocol/claude-agent-acp/issues/822)) ([64aa130](https://github.com/agentclientprotocol/claude-agent-acp/commit/64aa130c66c299f9835193796ba372b3ed40e7c1))
+
+## [0.53.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.52.0...v0.53.0) (2026-06-29)
+
+
+### Features
+
+* Add ACP logout support ([#816](https://github.com/agentclientprotocol/claude-agent-acp/issues/816)) ([0a0468c](https://github.com/agentclientprotocol/claude-agent-acp/commit/0a0468c72092b7ceccc551b4353dd92f9c22cbb8))
+* **deps:** bump @anthropic-ai/claude-agent-sdk to 0.3.195 ([#818](https://github.com/agentclientprotocol/claude-agent-acp/issues/818)) ([5dd8746](https://github.com/agentclientprotocol/claude-agent-acp/commit/5dd87462376597eb7b695200f4c716af46e764d6))
+
+
+### Bug Fixes
+
+* Emit tool_call before permission request ([#820](https://github.com/agentclientprotocol/claude-agent-acp/issues/820)) ([c95fc88](https://github.com/agentclientprotocol/claude-agent-acp/commit/c95fc884e82e5a297d1b17b8965690260867835b))
+
+## [0.52.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.51.0...v0.52.0) (2026-06-25)
+
+
+### Features
+
+* Add version flag handling ([#813](https://github.com/agentclientprotocol/claude-agent-acp/issues/813)) ([9616bda](https://github.com/agentclientprotocol/claude-agent-acp/commit/9616bdac47505e4a14c36d667fcffc9ae97e1f2a)), closes [#809](https://github.com/agentclientprotocol/claude-agent-acp/issues/809)
+* **deps-dev:** bump expect-type from 1.3.0 to 1.4.0 in the minor group ([#814](https://github.com/agentclientprotocol/claude-agent-acp/issues/814)) ([61272ac](https://github.com/agentclientprotocol/claude-agent-acp/commit/61272acb30dcafaa2455d334b11ce2ad97339707))
+* **deps:** Update @anthropic-ai/claude-agent-sdk to 0.3.191 ([#810](https://github.com/agentclientprotocol/claude-agent-acp/issues/810)) ([228f02e](https://github.com/agentclientprotocol/claude-agent-acp/commit/228f02ecfb23be16e59e121c6b42c0f2b2f40a4e))
+* Push session title updates at turn end ([#812](https://github.com/agentclientprotocol/claude-agent-acp/issues/812)) ([1fe7ec0](https://github.com/agentclientprotocol/claude-agent-acp/commit/1fe7ec09a3a7bcb7501231dae4b0ffe6ef9b70a4))
+
+## [0.51.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.50.0...v0.51.0) (2026-06-24)
+
+
+### Features
+
+* **deps:** bump the minor group with 11 updates ([#807](https://github.com/agentclientprotocol/claude-agent-acp/issues/807)) ([8f6ebd1](https://github.com/agentclientprotocol/claude-agent-acp/commit/8f6ebd1d9198edf723f4c8c1aa2b49b906c46646))
+
+## [0.50.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.49.0...v0.50.0) (2026-06-23)
+
+
+### Features
+
+* **acp:** Handle ACP request cancellation signals ([#801](https://github.com/agentclientprotocol/claude-agent-acp/issues/801)) ([9013d1d](https://github.com/agentclientprotocol/claude-agent-acp/commit/9013d1d46883a7f3774a63a9dca16c4a0f634a97))
+* **deps:** bump actions/checkout from 6.0.3 to 7.0.0 ([#803](https://github.com/agentclientprotocol/claude-agent-acp/issues/803)) ([044c43e](https://github.com/agentclientprotocol/claude-agent-acp/commit/044c43e0c894082b9e747c01e9dbde6e21036823))
+* **deps:** upgrade to @anthropic-ai/claude-agent-sdk@0.3.186 ([#806](https://github.com/agentclientprotocol/claude-agent-acp/issues/806)) ([a7e6137](https://github.com/agentclientprotocol/claude-agent-acp/commit/a7e6137f6877b72b8daa39e74971c3559db8d28f))
+
+## [0.49.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.48.0...v0.49.0) (2026-06-22)
+
+
+### Features
+
+* Update to claude-agent-sdk 0.3.185 ([#798](https://github.com/agentclientprotocol/claude-agent-acp/issues/798)) ([8dc8c86](https://github.com/agentclientprotocol/claude-agent-acp/commit/8dc8c864263fa50d03bec7ebff7aee776604cb3d))
+
+
+### Bug Fixes
+
+* Deduplicate streamed assistant blocks by content ([#800](https://github.com/agentclientprotocol/claude-agent-acp/issues/800)) ([960f62d](https://github.com/agentclientprotocol/claude-agent-acp/commit/960f62d76582ae5c9c5575ab66974809049ce1d0))
+* Infer 1M context from model descriptions ([#799](https://github.com/agentclientprotocol/claude-agent-acp/issues/799)) ([508453c](https://github.com/agentclientprotocol/claude-agent-acp/commit/508453c288b4a12701abd507199e7fa0ab172171))
+
+## [0.48.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.47.0...v0.48.0) (2026-06-19)
+
+
+### Features
+
+* Agent selection dropdown in config options ([#794](https://github.com/agentclientprotocol/claude-agent-acp/issues/794)) ([5729c47](https://github.com/agentclientprotocol/claude-agent-acp/commit/5729c471f92e1d2a191eb2a6d18c2be47821e9ec))
+* **deps:** bump the minor group with 11 updates ([#787](https://github.com/agentclientprotocol/claude-agent-acp/issues/787)) ([ad3b5fe](https://github.com/agentclientprotocol/claude-agent-acp/commit/ad3b5fe74527f83964695a1e8056d010b981fc79))
+* Update to claude-agent-sdk 0.3.183 ([#791](https://github.com/agentclientprotocol/claude-agent-acp/issues/791)) ([744b2d4](https://github.com/agentclientprotocol/claude-agent-acp/commit/744b2d41128f67091d4136283594c0db11ea4db5))
+* Update to new ACP SDK patterns ([#790](https://github.com/agentclientprotocol/claude-agent-acp/issues/790)) ([2554c7b](https://github.com/agentclientprotocol/claude-agent-acp/commit/2554c7bf980472760a6e7810b826f030d2c3af25))
+
+
+### Bug Fixes
+
+* duplicate assistant text when turn activates mid-message ([#789](https://github.com/agentclientprotocol/claude-agent-acp/issues/789)) ([1c80bf8](https://github.com/agentclientprotocol/claude-agent-acp/commit/1c80bf8e56a9279dc799e7bbdcae87241e99c18b))
+* Skip empty thinking chunks ([#793](https://github.com/agentclientprotocol/claude-agent-acp/issues/793)) ([15fdf26](https://github.com/agentclientprotocol/claude-agent-acp/commit/15fdf26fc7d3a6c51e89d3e56fc91dd00cb3d7ae))
+* surface Bash tool image output instead of dropping it ([#617](https://github.com/agentclientprotocol/claude-agent-acp/issues/617)) ([a759e64](https://github.com/agentclientprotocol/claude-agent-acp/commit/a759e64ef6d9b7c5bfe9a6e6b182db835f8ed3b6))
+
+## [0.47.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.46.0...v0.47.0) (2026-06-17)
+
+
+### Features
+
+* Update to claude-agent-sdk 0.3.179 ([#783](https://github.com/agentclientprotocol/claude-agent-acp/issues/783)) ([59a098c](https://github.com/agentclientprotocol/claude-agent-acp/commit/59a098c2b530bbae034e9a2dfbd31f8b4ef2a4d0))
+
+
+### Bug Fixes
+
+* Duplicate assistant messages in feed ([#785](https://github.com/agentclientprotocol/claude-agent-acp/issues/785)) ([12d34e6](https://github.com/agentclientprotocol/claude-agent-acp/commit/12d34e64e53564602ac1c38a30127e234c5c25ff))
+
 ## [0.46.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.45.1...v0.46.0) (2026-06-16)
 
 

eslint.config.js

@@ -40,7 +40,7 @@ export default [
       "default-case": "error",
       "prefer-const": "error",
       "no-var": "error",
-      eqeqeq: ["error", "always"],
+      eqeqeq: ["error", "smart"],
       curly: ["error", "all"],
     },
   },

package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.46.0",
+  "version": "0.59.0",
   "description": "An ACP-compatible coding agent powered by the Claude Agent SDK (TypeScript)",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
@@ -59,23 +59,27 @@
   },
   "author": "Zed Industries",
   "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22"
+  },
   "dependencies": {
-    "@agentclientprotocol/sdk": "0.26.0",
-    "@anthropic-ai/claude-agent-sdk": "0.3.178",
+    "@agentclientprotocol/sdk": "1.2.1",
+    "@anthropic-ai/claude-agent-sdk": "0.3.207",
     "zod": "^3.25.0 || ^4.0.0"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "0.104.2",
+    "@anthropic-ai/sdk": "0.111.0",
     "@eslint/js": "10.0.1",
-    "@types/node": "25.9.3",
-    "@typescript-eslint/eslint-plugin": "8.61.1",
-    "@typescript-eslint/parser": "8.61.1",
-    "eslint": "10.5.0",
+    "@tsconfig/node22": "22.0.5",
+    "@types/node": "26.1.1",
+    "@typescript-eslint/eslint-plugin": "8.63.0",
+    "@typescript-eslint/parser": "8.63.0",
+    "eslint": "10.7.0",
     "eslint-config-prettier": "10.1.8",
-    "globals": "17.6.0",
-    "prettier": "3.8.4",
+    "globals": "17.7.0",
+    "prettier": "3.9.5",
     "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;
     });
@@ -232,8 +225,7 @@ export function askUserQuestionsToCreateRequest(
 
 /** Outcome of an AskUserQuestion elicitation, decoupled from any transport. */
 export type AskUserQuestionOutcome =
-  | { action: "answered"; updatedInput: Record<string, unknown> }
-  | { action: "cancel" };
+  { action: "answered"; updatedInput: Record<string, unknown> } | { action: "cancel" };
 
 /**
  * Fold an ACP elicitation response into the AskUserQuestion tool's input.
@@ -244,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"] = {};
@@ -299,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/index.ts

@@ -2,7 +2,11 @@
 
 import { resolveSettings } from "@anthropic-ai/claude-agent-sdk";
 import { claudeCliPath, runAcp } from "./acp-agent.js";
+import packageJson from "../package.json" with { type: "json" };
 
+// `--cli` is checked first so that `--version`/`-v` (and any other flags) are
+// forwarded to the wrapped native CLI rather than swallowed by our own version
+// handler below. Our version flag only applies when not delegating.
 if (process.argv.includes("--cli")) {
   const { spawn } = await import("node:child_process");
   const args = process.argv.slice(2).filter((arg) => arg !== "--cli");
@@ -33,6 +37,9 @@ if (process.argv.includes("--cli")) {
     console.error(err);
     process.exit(1);
   });
+} else if (process.argv.includes("--version") || process.argv.includes("-v")) {
+  console.log(packageJson.version);
+  process.exit(0);
 } else {
   // Apply env vars from the managed-policy tier before any SDK call so the
   // SDK subprocess inherits them. Going through resolveSettings (vs. a raw

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

@@ -2,8 +2,8 @@ import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
-import type { AgentSideConnection } from "@agentclientprotocol/sdk";
-import type { ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
+import type { AcpClient, ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
+import { makeMockQuery } from "./helpers.js";
 
 const { querySpy } = vi.hoisted(() => ({
   querySpy: vi.fn(),
@@ -21,13 +21,13 @@ describe("ClaudeAcpAgent settings", () => {
   let tempDir: string;
   let originalClaudeConfigDir: string | undefined;
 
-  function createMockClient(): AgentSideConnection {
+  function createMockClient(): AcpClient {
     return {
       sessionUpdate: async () => {},
       requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
       readTextFile: async () => ({ content: "" }),
       writeTextFile: async () => ({}),
-    } as unknown as AgentSideConnection;
+    } as unknown as AcpClient;
   }
 
   function mockQuery() {
@@ -35,7 +35,7 @@ describe("ClaudeAcpAgent settings", () => {
     const setModelSpy = vi.fn();
     querySpy.mockImplementation(({ options }: any) => {
       capturedOptions = options;
-      return {
+      return makeMockQuery({
         initializationResult: async () => ({
           models: [
             {
@@ -46,8 +46,7 @@ describe("ClaudeAcpAgent settings", () => {
           ],
         }),
         setModel: setModelSpy,
-        supportedCommands: async () => [],
-      } as any;
+      }) as any;
     });
     return { getCapturedOptions: () => capturedOptions, setModelSpy };
   }
@@ -241,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,
@@ -397,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 };
     }
@@ -812,6 +809,55 @@ describe("ClaudeAcpAgent settings", () => {
         }
       }
     });
+
+    it("maps allowlist aliases through modelOverrides to provider IDs", async () => {
+      // Bedrock/Vertex deployments enforce short aliases in availableModels
+      // but require provider-specific IDs at the API. Without applying
+      // modelOverrides during allowlist resolution, the alias is surfaced as
+      // the model value and passed verbatim to setModel, which the provider
+      // API rejects with a 400 "invalid model identifier".
+      await fs.promises.writeFile(
+        path.join(tempDir, "settings.json"),
+        JSON.stringify({
+          availableModels: ["claude-opus-4-6", "claude-sonnet-4-6"],
+          model: "claude-opus-4-6",
+          modelOverrides: {
+            "claude-opus-4-6": "global.anthropic.claude-opus-4-6-v1[1m]",
+            "claude-sonnet-4-6": "global.anthropic.claude-sonnet-4-6[1m]",
+          },
+        }),
+      );
+
+      const projectDir = path.join(tempDir, "project");
+      await fs.promises.mkdir(projectDir, { recursive: true });
+
+      const { setModelSpy } = mockQueryWithModels([
+        { value: "default", displayName: "Default", description: "Default model" },
+        { value: "opus", displayName: "Opus", description: "Claude Opus 4.6" },
+        { value: "sonnet", displayName: "Sonnet", description: "Claude Sonnet 4.6" },
+      ]);
+
+      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");
+      expect(modelOption.options.map((o: any) => o.value)).toEqual([
+        "default",
+        "global.anthropic.claude-opus-4-6-v1[1m]",
+        "global.anthropic.claude-sonnet-4-6[1m]",
+      ]);
+      // The allowlist synthesized the overridden ID (the SDK only surfaced the
+      // `opus` alias), so the adapter syncs the provider ID via setModel — never
+      // the raw alias that Bedrock would reject.
+      expect(setModelSpy).toHaveBeenCalledWith("global.anthropic.claude-opus-4-6-v1[1m]");
+      expect(modelOption.currentValue).toBe("global.anthropic.claude-opus-4-6-v1[1m]");
+    });
   });
 
   it("resolves model aliases like opus[1m] to the correct model", async () => {
@@ -827,7 +873,7 @@ describe("ClaudeAcpAgent settings", () => {
 
     const setModelSpy = vi.fn();
     querySpy.mockImplementation(({ options: _options }: any) => {
-      return {
+      return makeMockQuery({
         initializationResult: async () => ({
           models: [
             {
@@ -843,8 +889,7 @@ describe("ClaudeAcpAgent settings", () => {
           ],
         }),
         setModel: setModelSpy,
-        supportedCommands: async () => [],
-      } as any;
+      }) as any;
     });
 
     const { ClaudeAcpAgent } = await import("../acp-agent.js");
@@ -875,7 +920,7 @@ describe("ClaudeAcpAgent settings", () => {
 
     const setModelSpy = vi.fn();
     querySpy.mockImplementation(() => {
-      return {
+      return makeMockQuery({
         initializationResult: async () => ({
           models: [
             { value: "default", displayName: "Default", description: "" },
@@ -884,8 +929,7 @@ describe("ClaudeAcpAgent settings", () => {
           ],
         }),
         setModel: setModelSpy,
-        supportedCommands: async () => [],
-      } as any;
+      }) as any;
     });
 
     try {
@@ -929,7 +973,7 @@ describe("ClaudeAcpAgent settings", () => {
 
     const setModelSpy = vi.fn();
     querySpy.mockImplementation(() => {
-      return {
+      return makeMockQuery({
         initializationResult: async () => ({
           models: [
             { value: "default", displayName: "Default", description: "" },
@@ -937,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

@@ -1,36 +1,36 @@
 import { mkdtemp, rm } from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
-import { AgentSideConnection, SessionNotification } from "@agentclientprotocol/sdk";
+import { SessionNotification } from "@agentclientprotocol/sdk";
 import type { Options } from "@anthropic-ai/claude-agent-sdk";
-import type { ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
+import type { AcpClient, ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
 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(),
@@ -52,7 +52,7 @@ describe("additionalRoots", () => {
       requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
       readTextFile: async () => ({ content: "" }),
       writeTextFile: async () => ({}),
-    } as unknown as AgentSideConnection);
+    } as unknown as AcpClient);
   });
 
   afterEach(

src/tests/agent-discovery.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from "vitest";
+import { randomUUID } from "crypto";
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import type { SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import { Pushable } from "../utils.js";
+import { discoverCustomAgents, BUILTIN_AGENT_NAMES } from "../acp-agent.js";
+
+// `discoverCustomAgents` distinguishes user/plugin-configured agents from
+// Claude Code's built-in subagents by name (BUILTIN_AGENT_NAMES), since the
+// SDK's `AgentInfo` carries no built-in/source flag. That hardcoded set drifts
+// silently if the SDK changes its default roster: a newly added built-in would
+// leak into the ACP "Agent" picker as if the user had configured it. This
+// integration test runs the real SDK so the set is flagged the moment it does.
+describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("agent discovery (SDK)", () => {
+  it("BUILTIN_AGENT_NAMES exactly covers the SDK's default agent roster", async () => {
+    const input = new Pushable<SDKUserMessage>();
+    const q = query({
+      prompt: input,
+      options: {
+        systemPrompt: { type: "preset", preset: "claude_code" },
+        sessionId: randomUUID(),
+        // No setting sources → no user/project/local custom agents are loaded,
+        // so `supportedAgents()` reports exactly the intrinsic built-ins
+        // regardless of what the developer has in ~/.claude/agents.
+        settingSources: [],
+        includePartialMessages: true,
+      },
+    });
+
+    try {
+      const reported = (await q.supportedAgents()).map((a) => a.name).sort();
+      expect(reported).toEqual([...BUILTIN_AGENT_NAMES].sort());
+
+      // With the built-ins being the only agents present, discovery surfaces
+      // nothing — the ACP "Agent" picker is correctly omitted.
+      expect(await discoverCustomAgents(q)).toEqual([]);
+    } finally {
+      input.end();
+      q.return(undefined);
+    }
+  }, 30000);
+});

src/tests/authorization.test.ts

@@ -1,19 +1,8 @@
 import { describe, expect, it, Mock, vi, afterEach, beforeEach } from "vitest";
-import { ClaudeAcpAgent } from "../acp-agent.js";
-import { AgentSideConnection } from "@agentclientprotocol/sdk";
+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")>(
@@ -25,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(() => {
@@ -39,7 +44,7 @@ describe("authorization", () => {
   async function createAgentMock(): Promise<[ClaudeAcpAgent, Mock]> {
     const connectionMock = {
       sessionUpdate: async (_: any) => {},
-    } as AgentSideConnection;
+    } as AcpClient;
 
     const agent = new ClaudeAcpAgent(connectionMock);
 

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

@@ -1,21 +1,23 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
-import { AgentSideConnection, RequestError, SessionNotification } from "@agentclientprotocol/sdk";
+import { RequestError, SessionNotification } from "@agentclientprotocol/sdk";
 import type { Options } from "@anthropic-ai/claude-agent-sdk";
-import type { ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
+import type { AcpClient, ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
 let capturedOptions: Options | undefined;
+let contextUsageResult: (() => Promise<{ rawMaxTokens: number }>) | 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),
+      });
     },
   };
 });
@@ -47,17 +47,18 @@ describe("createSession options merging", () => {
   let agent: ClaudeAcpAgentType;
   let ClaudeAcpAgent: typeof ClaudeAcpAgentType;
 
-  function createMockClient(): AgentSideConnection {
+  function createMockClient(): AcpClient {
     return {
       sessionUpdate: async (_notification: SessionNotification) => {},
       requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
       readTextFile: async () => ({ content: "" }),
       writeTextFile: async () => ({}),
-    } as unknown as AgentSideConnection;
+    } as unknown as AcpClient;
   }
 
   beforeEach(async () => {
     capturedOptions = undefined;
+    contextUsageResult = undefined;
 
     vi.resetModules();
     const acpAgent = await import("../acp-agent.js");
@@ -514,8 +515,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 () => {
@@ -550,14 +556,15 @@ describe("createSession options merging", () => {
     });
 
     it("rejects a cwd that points at a file with invalidParams", async () => {
-      const file = path.join(os.tmpdir(), "claude-acp-cwd-is-a-file.txt");
+      const dir = fs.mkdtempSync(path.join(os.tmpdir(), "claude-acp-cwd-is-a-file-"));
+      const file = path.join(dir, "not-a-directory.txt");
       fs.writeFileSync(file, "not a directory");
       try {
         await expect(agent.newSession({ cwd: file, mcpServers: [] })).rejects.toMatchObject({
           code: RequestError.invalidParams().code,
         });
       } finally {
-        fs.rmSync(file, { force: true });
+        fs.rmSync(dir, { recursive: true, force: true });
       }
     });
 
@@ -612,4 +619,177 @@ 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("seeds contextWindowSize from the SDK's getContextUsage report", async () => {
+      // Aliases like `sonnet` can resolve to an extended-context model with no
+      // "1m" token anywhere in id/displayName/description, so the authoritative
+      // report must win over text inference (issue #596).
+      contextUsageResult = async () => ({ rawMaxTokens: 967000 });
+
+      const response = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(sessionFor(response.sessionId).contextWindowSize).toBe(967000);
+    });
+
+    it("falls back to the default window when getContextUsage fails and inference misses", async () => {
+      // getContextUsage rejects, and the mock model ("claude-sonnet-4-6" /
+      // "Claude Sonnet" / "Fast") has no "1m" hint.
+      contextUsageResult = () => Promise.reject(new Error("no context usage mocked"));
+      // The rejection 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 response = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(sessionFor(response.sessionId).contextWindowSize).toBe(200000);
+      expect(errorSpy).toHaveBeenCalled();
+    });
+
+    it("ignores a nonsensical (non-positive) reported window", async () => {
+      contextUsageResult = async () => ({ rawMaxTokens: 0 });
+
+      const response = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(sessionFor(response.sessionId).contextWindowSize).toBe(200000);
+    });
+  });
+
+  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

@@ -0,0 +1,341 @@
+import { describe, it, expect, vi } from "vitest";
+import type { ClientCapabilities, SessionNotification } from "@agentclientprotocol/sdk";
+import type { ModelInfo } from "@anthropic-ai/claude-agent-sdk";
+import {
+  buildConfigOptions,
+  clientSupportsBooleanConfigOptions,
+  createFastModeConfigOption,
+  fastModeStateEnabled,
+  resolveFastModeEnabled,
+  FAST_MODE_CONFIG_ID,
+  FAST_MODE_ON,
+  FAST_MODE_OFF,
+  ClaudeAcpAgent,
+  type AcpClient,
+} from "../acp-agent.js";
+
+const MODES = {
+  currentModeId: "default",
+  availableModes: [{ id: "default", name: "Default", description: "Standard behavior" }],
+};
+
+const MODELS = {
+  currentModelId: "claude-opus-4-8",
+  availableModels: [
+    { modelId: "claude-opus-4-8", name: "Claude Opus", description: "Most capable" },
+  ],
+};
+
+const MODEL_INFOS: ModelInfo[] = [
+  { value: "claude-opus-4-8", displayName: "Claude Opus", description: "Most capable" },
+];
+
+describe("createFastModeConfigOption", () => {
+  it("produces a native boolean toggle when the client opted in", () => {
+    expect(createFastModeConfigOption(true, true)).toEqual({
+      id: FAST_MODE_CONFIG_ID,
+      name: "Fast mode",
+      description: expect.any(String),
+      category: "model_config",
+      type: "boolean",
+      currentValue: true,
+    });
+  });
+
+  it("falls back to an on/off select when the client did not opt in", () => {
+    const option = createFastModeConfigOption(false, false);
+    expect(option).toMatchObject({
+      id: FAST_MODE_CONFIG_ID,
+      type: "select",
+      category: "model_config",
+      currentValue: FAST_MODE_OFF,
+      options: [
+        { value: FAST_MODE_ON, name: "On" },
+        { value: FAST_MODE_OFF, name: "Off" },
+      ],
+    });
+    expect(option).not.toHaveProperty("currentValue", true);
+  });
+});
+
+describe("clientSupportsBooleanConfigOptions", () => {
+  it("is true only when session.configOptions.boolean is present", () => {
+    expect(
+      clientSupportsBooleanConfigOptions({ session: { configOptions: { boolean: {} } } }),
+    ).toBe(true);
+  });
+
+  it("is false when the capability is omitted or null at any level", () => {
+    expect(clientSupportsBooleanConfigOptions(undefined)).toBe(false);
+    expect(clientSupportsBooleanConfigOptions(null)).toBe(false);
+    expect(clientSupportsBooleanConfigOptions({})).toBe(false);
+    expect(clientSupportsBooleanConfigOptions({ session: { configOptions: {} } })).toBe(false);
+    expect(
+      clientSupportsBooleanConfigOptions({ session: { configOptions: { boolean: null } } }),
+    ).toBe(false);
+  });
+});
+
+describe("resolveFastModeEnabled", () => {
+  const base = { sessionId: "s", configId: FAST_MODE_CONFIG_ID };
+
+  it("accepts native boolean values", () => {
+    expect(resolveFastModeEnabled({ ...base, type: "boolean", value: true })).toBe(true);
+    expect(resolveFastModeEnabled({ ...base, type: "boolean", value: false })).toBe(false);
+  });
+
+  it("accepts the on/off select fallback", () => {
+    expect(resolveFastModeEnabled({ ...base, value: FAST_MODE_ON })).toBe(true);
+    expect(resolveFastModeEnabled({ ...base, value: FAST_MODE_OFF })).toBe(false);
+  });
+
+  it("rejects any other value", () => {
+    expect(() => resolveFastModeEnabled({ ...base, value: "maybe" })).toThrow(
+      /Invalid value for config option fast/,
+    );
+  });
+});
+
+describe("fastModeStateEnabled", () => {
+  it("treats cooldown as on (the user's intent persists through rate-limit cooldown)", () => {
+    expect(fastModeStateEnabled("on")).toBe(true);
+    expect(fastModeStateEnabled("cooldown")).toBe(true);
+    expect(fastModeStateEnabled("off")).toBe(false);
+  });
+});
+
+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", {
+      supported: false,
+      enabled: false,
+      useBooleanOption: true,
+    });
+    expect(options.find((o) => o.id === FAST_MODE_CONFIG_ID)).toBeUndefined();
+  });
+
+  it("omits the Fast mode option when no fast mode state is provided", () => {
+    const options = buildConfigOptions(MODES, MODELS, MODEL_INFOS, undefined, [], "default");
+    expect(options.find((o) => o.id === FAST_MODE_CONFIG_ID)).toBeUndefined();
+  });
+
+  it("surfaces a boolean toggle when supported and the client opted in", () => {
+    const options = buildConfigOptions(MODES, MODELS, MODEL_INFOS, undefined, [], "default", {
+      supported: true,
+      enabled: true,
+      useBooleanOption: true,
+    });
+    expect(options).toContainEqual(createFastModeConfigOption(true, true));
+  });
+
+  it("surfaces a select fallback when supported but the client did not opt in", () => {
+    const options = buildConfigOptions(MODES, MODELS, MODEL_INFOS, undefined, [], "default", {
+      supported: true,
+      enabled: false,
+      useBooleanOption: false,
+    });
+    expect(options).toContainEqual(createFastModeConfigOption(false, false));
+  });
+});
+
+describe("setSessionConfigOption Fast mode toggle", () => {
+  const SESSION_ID = "fast-session";
+
+  function setup(opts: { useBooleanOption: boolean }) {
+    const sessionUpdates: SessionNotification[] = [];
+    const client = {
+      sessionUpdate: async (n: SessionNotification) => {
+        sessionUpdates.push(n);
+      },
+      requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+      readTextFile: async () => ({ content: "" }),
+      writeTextFile: async () => ({}),
+    } as unknown as AcpClient;
+
+    const agent = new ClaudeAcpAgent(client);
+    const clientCapabilities: ClientCapabilities = opts.useBooleanOption
+      ? { session: { configOptions: { boolean: {} } } }
+      : {};
+    (agent as unknown as { clientCapabilities: ClientCapabilities }).clientCapabilities =
+      clientCapabilities;
+
+    const applyFlagSettings = vi.fn();
+    (agent as unknown as { sessions: Record<string, unknown> }).sessions[SESSION_ID] = {
+      query: { applyFlagSettings },
+      fastModeEnabled: false,
+      configOptions: [createFastModeConfigOption(false, opts.useBooleanOption)],
+    };
+
+    return { agent, applyFlagSettings, sessionUpdates };
+  }
+
+  it("toggles Fast mode on/off through a boolean value", async () => {
+    const { agent, applyFlagSettings } = setup({ useBooleanOption: true });
+
+    const onResponse = await agent.setSessionConfigOption({
+      sessionId: SESSION_ID,
+      configId: FAST_MODE_CONFIG_ID,
+      type: "boolean",
+      value: true,
+    });
+    expect(applyFlagSettings).toHaveBeenCalledWith({ fastMode: true });
+    expect(onResponse.configOptions).toContainEqual(createFastModeConfigOption(true, true));
+    expect(
+      (agent as unknown as { sessions: Record<string, { fastModeEnabled: boolean }> }).sessions[
+        SESSION_ID
+      ].fastModeEnabled,
+    ).toBe(true);
+
+    const offResponse = await agent.setSessionConfigOption({
+      sessionId: SESSION_ID,
+      configId: FAST_MODE_CONFIG_ID,
+      type: "boolean",
+      value: false,
+    });
+    expect(applyFlagSettings).toHaveBeenLastCalledWith({ fastMode: false });
+    expect(offResponse.configOptions).toContainEqual(createFastModeConfigOption(false, true));
+  });
+
+  it("toggles Fast mode through the on/off select fallback", async () => {
+    const { agent, applyFlagSettings } = setup({ useBooleanOption: false });
+
+    const response = await agent.setSessionConfigOption({
+      sessionId: SESSION_ID,
+      configId: FAST_MODE_CONFIG_ID,
+      value: FAST_MODE_ON,
+    });
+    expect(applyFlagSettings).toHaveBeenCalledWith({ fastMode: true });
+    expect(response.configOptions).toContainEqual(createFastModeConfigOption(true, false));
+  });
+
+  it("does not change session state when the SDK rejects the flag", async () => {
+    const { agent, applyFlagSettings } = setup({ useBooleanOption: true });
+    applyFlagSettings.mockRejectedValueOnce(new Error("nope"));
+
+    await expect(
+      agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: FAST_MODE_CONFIG_ID,
+        type: "boolean",
+        value: true,
+      }),
+    ).rejects.toThrow("nope");
+
+    const session = (agent as unknown as { sessions: Record<string, { fastModeEnabled: boolean }> })
+      .sessions[SESSION_ID];
+    expect(session.fastModeEnabled).toBe(false);
+  });
+});
+
+describe("syncFastModeState (SDK-driven state changes)", () => {
+  const SESSION_ID = "fast-session";
+
+  function setup(opts: { fastModeEnabled: boolean; withOption: boolean }) {
+    const sessionUpdates: SessionNotification[] = [];
+    const client = {
+      sessionUpdate: async (n: SessionNotification) => {
+        sessionUpdates.push(n);
+      },
+      requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+      readTextFile: async () => ({ content: "" }),
+      writeTextFile: async () => ({}),
+    } as unknown as AcpClient;
+
+    const agent = new ClaudeAcpAgent(client);
+    (agent as unknown as { clientCapabilities: ClientCapabilities }).clientCapabilities = {
+      session: { configOptions: { boolean: {} } },
+    };
+
+    const session = {
+      query: {},
+      fastModeEnabled: opts.fastModeEnabled,
+      configOptions: opts.withOption
+        ? [createFastModeConfigOption(opts.fastModeEnabled, true)]
+        : [],
+    };
+    (agent as unknown as { sessions: Record<string, unknown> }).sessions[SESSION_ID] = session;
+
+    const sync = (
+      agent as unknown as {
+        syncFastModeState: (
+          sessionId: string,
+          session: unknown,
+          state: string | undefined,
+        ) => Promise<void>;
+      }
+    ).syncFastModeState.bind(agent);
+
+    return { sync, session, sessionUpdates };
+  }
+
+  it("emits a config_option_update when the SDK reports a new state", async () => {
+    const { sync, session, sessionUpdates } = setup({ fastModeEnabled: false, withOption: true });
+
+    await sync(SESSION_ID, session, "on");
+
+    expect(session.fastModeEnabled).toBe(true);
+    expect(session.configOptions).toContainEqual(createFastModeConfigOption(true, true));
+    expect(sessionUpdates).toHaveLength(1);
+    expect(sessionUpdates[0].update).toMatchObject({
+      sessionUpdate: "config_option_update",
+    });
+    const updated = (
+      sessionUpdates[0].update as { configOptions: ReturnType<typeof createFastModeConfigOption>[] }
+    ).configOptions;
+    expect(updated).toContainEqual(createFastModeConfigOption(true, true));
+  });
+
+  it("leaves the toggle on and quiet during a rate-limit cooldown", async () => {
+    const { sync, session, sessionUpdates } = setup({ fastModeEnabled: true, withOption: true });
+
+    // cooldown is a transient suspension of an already-enabled fast mode.
+    await sync(SESSION_ID, session, "cooldown");
+
+    expect(session.fastModeEnabled).toBe(true);
+    expect(sessionUpdates).toHaveLength(0);
+  });
+
+  it("never lets a stray cooldown spuriously enable a toggle the user has off", async () => {
+    const { sync, session, sessionUpdates } = setup({ fastModeEnabled: false, withOption: true });
+
+    await sync(SESSION_ID, session, "cooldown");
+
+    expect(session.fastModeEnabled).toBe(false);
+    expect(sessionUpdates).toHaveLength(0);
+  });
+
+  it("clears the toggle when the SDK reports off", async () => {
+    const { sync, session, sessionUpdates } = setup({ fastModeEnabled: true, withOption: true });
+
+    await sync(SESSION_ID, session, "off");
+
+    expect(session.fastModeEnabled).toBe(false);
+    expect(session.configOptions).toContainEqual(createFastModeConfigOption(false, true));
+    expect(sessionUpdates).toHaveLength(1);
+  });
+
+  it("is a no-op when the reported state is undefined or unchanged", async () => {
+    const { sync, session, sessionUpdates } = setup({ fastModeEnabled: false, withOption: true });
+
+    await sync(SESSION_ID, session, undefined);
+    await sync(SESSION_ID, session, "off");
+
+    expect(sessionUpdates).toHaveLength(0);
+  });
+
+  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
+    // correct when a supporting model is reselected — reconciling here was the
+    // original intent-clobber bug.
+    const enabledCase = setup({ fastModeEnabled: true, withOption: false });
+    await enabledCase.sync(SESSION_ID, enabledCase.session, "off");
+    expect(enabledCase.session.fastModeEnabled).toBe(true);
+    expect(enabledCase.sessionUpdates).toHaveLength(0);
+
+    const disabledCase = setup({ fastModeEnabled: false, withOption: false });
+    await disabledCase.sync(SESSION_ID, disabledCase.session, "on");
+    expect(disabledCase.session.fastModeEnabled).toBe(false);
+    expect(disabledCase.sessionUpdates).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,272 @@
+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,
+  matchResumedModel,
+} from "../acp-agent.js";
+
+// Mirrors a real `supportedModels()` response: alias rows carry
+// `resolvedModel`, and "Sonnet 5" has no `major.minor` dot unlike older
+// "claude-opus-4-6"-style ids.
+const LIVE_SHAPED_MODELS: ModelInfo[] = [
+  {
+    value: "default",
+    resolvedModel: "claude-opus-4-8[1m]",
+    displayName: "Default (recommended)",
+    description: "Use the default model (currently Opus 4.8 (1M context))",
+  },
+  {
+    value: "opus[1m]",
+    resolvedModel: "claude-opus-4-8[1m]",
+    displayName: "Opus",
+    description: "Opus 4.8 with 1M context · Best for everyday, complex tasks",
+  },
+  {
+    value: "sonnet",
+    resolvedModel: "claude-sonnet-5",
+    displayName: "Sonnet",
+    description: "Sonnet 5 · Efficient for routine tasks",
+  },
+  {
+    value: "haiku",
+    resolvedModel: "claude-haiku-4-5-20251001",
+    displayName: "Haiku",
+    description: "Haiku 4.5 · Fastest for quick answers",
+  },
+];
+
+describe("resolveModelPreference - resolvedModel matching", () => {
+  it("matches a preference that equals an alias's resolvedModel exactly", () => {
+    expect(resolveModelPreference(LIVE_SHAPED_MODELS, "claude-sonnet-5")?.value).toBe("sonnet");
+    expect(resolveModelPreference(LIVE_SHAPED_MODELS, "claude-opus-4-8[1m]")?.value).toBe(
+      "opus[1m]",
+    );
+    expect(resolveModelPreference(LIVE_SHAPED_MODELS, "claude-haiku-4-5-20251001")?.value).toBe(
+      "haiku",
+    );
+  });
+
+  it("is case-insensitive", () => {
+    expect(resolveModelPreference(LIVE_SHAPED_MODELS, "CLAUDE-SONNET-5")?.value).toBe("sonnet");
+  });
+
+  it("still resolves plain aliases via the direct-match tier", () => {
+    expect(resolveModelPreference(LIVE_SHAPED_MODELS, "sonnet")?.value).toBe("sonnet");
+    expect(resolveModelPreference(LIVE_SHAPED_MODELS, "opus[1m]")?.value).toBe("opus[1m]");
+  });
+
+  it("does not let a retired dated id drift onto a same-family alias of a different generation", () => {
+    expect(resolveModelPreference(LIVE_SHAPED_MODELS, "claude-sonnet-4-6")).toBeNull();
+  });
+
+  // "opus[1m]"'s `value` has no dotted version, just the context-hint digit
+  // in "[1m]" — unstripped, that reads as version "1" and blocks the match
+  // before the matcher reaches the description's real "4.8".
+  it("does not mistake an alias's context-hint suffix for its version", () => {
+    expect(resolveModelPreference(LIVE_SHAPED_MODELS, "claude-opus-4-8")?.value).toBe("opus[1m]");
+  });
+
+  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", () => {
+  it("resolves an allowlist entry pinned to a canonical resolvedModel id", () => {
+    const result = applyAvailableModelsAllowlist(LIVE_SHAPED_MODELS, ["claude-sonnet-5"]);
+    const entry = result.find((m) => m.value === "claude-sonnet-5");
+    expect(entry).toBeDefined();
+    expect(entry?.displayName).toBe("Sonnet");
+  });
+});
+
+describe("applyAvailableModelsAllowlist - modelOverrides", () => {
+  const SDK_MODELS: ModelInfo[] = [
+    { value: "default", displayName: "Default", description: "Default model" },
+    {
+      value: "opus",
+      displayName: "Opus",
+      description: "Claude Opus 4.6",
+      supportsEffort: true,
+      supportedEffortLevels: ["low", "high"],
+    },
+  ];
+
+  it("surfaces the override target as the value while keeping the alias's display metadata", () => {
+    // The override target is an opaque Bedrock ARN with no "opus" substring,
+    // so matching against it (instead of the "claude-opus-4-6" alias) would
+    // find nothing and silently drop displayName/description/supportsEffort.
+    const overrides = {
+      "claude-opus-4-6": "arn:aws:bedrock:us-west-2:111122223333:inference-profile/custom-7f3a",
+    };
+    const result = applyAvailableModelsAllowlist(SDK_MODELS, ["claude-opus-4-6"], overrides);
+
+    const entry = result.find((m) => m.value === overrides["claude-opus-4-6"]);
+    expect(entry).toEqual({
+      value: overrides["claude-opus-4-6"],
+      displayName: "Opus",
+      description: "Claude Opus 4.6",
+      supportsEffort: true,
+      supportedEffortLevels: ["low", "high"],
+    });
+  });
+});
+
+// Runs against the real SDK (no mocks) so the fixture above is flagged the
+// moment the SDK's actual model list shape drifts from it. Requires a usable
+// ANTHROPIC_API_KEY, hence opt-in via RUN_INTEGRATION_TESTS.
+describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("model resolution (real SDK)", () => {
+  it("every model's resolvedModel (when present) resolves back to that same row", async () => {
+    const q = query({ prompt: "hi", options: { sessionId: randomUUID() } });
+    try {
+      const models = await q.supportedModels();
+      expect(models.length).toBeGreaterThan(0);
+
+      for (const model of models) {
+        // "default" shares a resolvedModel with the CLI's recommended named
+        // alias, and resolution intentionally prefers that alias on a tie.
+        if (!model.resolvedModel || model.value === "default") continue;
+        const resolved = resolveModelPreference(models, model.resolvedModel);
+        expect(resolved?.value).toBe(model.value);
+      }
+    } finally {
+      q.return(undefined);
+    }
+  }, 30000);
+
+  it("resolves the well-known 'sonnet' and 'opus' aliases to a model bearing their family name", async () => {
+    const q = query({ prompt: "hi", options: { sessionId: randomUUID() } });
+    try {
+      const models = await q.supportedModels();
+
+      const sonnet = resolveModelPreference(models, "sonnet");
+      expect(sonnet?.resolvedModel?.toLowerCase()).toContain("sonnet");
+
+      const opus = resolveModelPreference(models, "opus");
+      expect(opus?.resolvedModel?.toLowerCase()).toContain("opus");
+    } finally {
+      q.return(undefined);
+    }
+  }, 30000);
+});

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

@@ -1,7 +1,8 @@
 import { describe, it, expect, beforeEach, vi } from "vitest";
-import { AgentSideConnection, SessionNotification } from "@agentclientprotocol/sdk";
+import { SessionNotification } from "@agentclientprotocol/sdk";
 import type { ModelInfo } from "@anthropic-ai/claude-agent-sdk";
-import type { ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
+import type { AcpClient, ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
+import { makeMockQuery } from "./helpers.js";
 
 const { registerHookCallbackSpy } = vi.hoisted(() => ({
   registerHookCallbackSpy: vi.fn(),
@@ -84,7 +85,7 @@ describe("session config options", () => {
   let setModelSpy: ReturnType<typeof vi.fn>;
   let applyFlagSettingsSpy: ReturnType<typeof vi.fn>;
 
-  function createMockClient(): AgentSideConnection {
+  function createMockClient(): AcpClient {
     return {
       sessionUpdate: async (notification: SessionNotification) => {
         sessionUpdates.push(notification);
@@ -92,7 +93,7 @@ describe("session config options", () => {
       requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
       readTextFile: async () => ({ content: "" }),
       writeTextFile: async () => ({}),
-    } as unknown as AgentSideConnection;
+    } as unknown as AcpClient;
   }
 
   function populateSession() {
@@ -101,29 +102,28 @@ 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",
       settingsManager: {},
       modes: structuredClone(MOCK_MODES),
       models: structuredClone(MOCK_MODELS),
-      modelInfos: MOCK_MODELS.availableModels.map(
-        (m): ModelInfo => ({
-          value: m.modelId,
-          displayName: m.name,
-          description: m.description,
-          supportsEffort: true,
-          supportedEffortLevels: ["low", "medium", "high"],
-        }),
-      ),
+      modelInfos: MOCK_MODELS.availableModels.map((m): ModelInfo => ({
+        value: m.modelId,
+        displayName: m.name,
+        description: m.description,
+        supportsEffort: true,
+        supportedEffortLevels: ["low", "medium", "high"],
+      })),
       configOptions: structuredClone(MOCK_CONFIG_OPTIONS),
       contextWindowSize: 200000,
+      toolUseCache: {},
+      emittedToolCalls: new Set(),
     };
   }
 
@@ -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,85 @@ 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("refreshes contextWindowSize from getContextUsage when the model changes", async () => {
+      const session = getSession();
+      session.query.getContextUsage = vi.fn(async () => ({ rawMaxTokens: 967000 }));
+
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-4-6",
+      });
+
+      expect(session.query.getContextUsage).toHaveBeenCalled();
+      expect(session.contextWindowSize).toBe(967000);
+    });
+
+    it("falls back to resolvedModel text inference when getContextUsage fails", async () => {
+      const session = getSession();
+      session.query.getContextUsage = vi.fn().mockRejectedValue(new Error("boom"));
+      session.modelInfos = session.modelInfos.map((m: ModelInfo) =>
+        m.value === "claude-sonnet-4-6" ? { ...m, resolvedModel: "claude-sonnet-5[1m]" } : m,
+      );
+      // The rejection 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.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-4-6",
+      });
+
+      expect(session.contextWindowSize).toBe(1_000_000);
+      expect(errorSpy).toHaveBeenCalled();
+    });
+
+    it("falls back to the default window when the SDK and inference both miss", async () => {
+      const session = getSession();
+      session.contextWindowSize = 1_000_000;
+      session.query.getContextUsage = vi.fn().mockRejectedValue(new Error("boom"));
+      // The rejection 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.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-4-6",
+      });
+
+      expect(session.contextWindowSize).toBe(200000);
+      expect(errorSpy).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
@@ -1113,6 +1271,10 @@ describe("session config options", () => {
         ],
       };
 
+      // The tool_call was already surfaced (by the streamed tool_use chunk), so
+      // the permission request won't re-emit one — keep this focused on options.
+      session.emittedToolCalls.add("toolu_1");
+
       const canUseTool = (agent as any).canUseTool(SESSION_ID);
       const signal = new AbortController().signal;
       try {
@@ -1144,6 +1306,10 @@ describe("session config options", () => {
         ],
       };
       permissionResponse = { outcome: { outcome: "selected", optionId: "auto" } };
+      // The tool_call was already surfaced (by the streamed tool_use chunk), so
+      // the permission request won't re-emit one — the deny path below should
+      // produce no session updates at all.
+      session.emittedToolCalls.add("toolu_2");
 
       const canUseTool = (agent as any).canUseTool(SESSION_ID);
       const result = await canUseTool(
@@ -1172,6 +1338,10 @@ describe("session config options", () => {
         ],
       };
 
+      // The tool_call was already surfaced (by the streamed tool_use chunk), so
+      // the permission request won't re-emit one — keep this focused on options.
+      session.emittedToolCalls.add("toolu_3");
+
       const canUseTool = (agent as any).canUseTool(SESSION_ID);
       const signal = new AbortController().signal;
       try {

src/tests/session-load.test.ts

@@ -1,18 +1,20 @@
 import { describe, it, expect } from "vitest";
 import { randomUUID } from "crypto";
-import { AgentSideConnection, RequestError, SessionNotification } from "@agentclientprotocol/sdk";
+import { RequestError, SessionNotification } from "@agentclientprotocol/sdk";
 import { query, getSessionMessages } from "@anthropic-ai/claude-agent-sdk";
-import { ClaudeAcpAgent } from "../acp-agent.js";
+import { AcpClient, ClaudeAcpAgent } from "../acp-agent.js";
 import { Pushable } from "../utils.js";
 import type { SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
 
-function createMockClient(): AgentSideConnection {
+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 () => ({}),
-  } as unknown as AgentSideConnection;
+  } as unknown as AcpClient;
 }
 
 describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("session load/resume lifecycle", () => {
@@ -165,7 +167,7 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("session load/resume lifecyc
       requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
       readTextFile: async () => ({ content: "" }),
       writeTextFile: async () => ({}),
-    } as unknown as AgentSideConnection;
+    } as unknown as AcpClient;
 
     const commandName =
       "<command-name>/model</command-name>\n            <command-message>model</command-message>\n            <command-args>opus</command-args>";
@@ -274,7 +276,7 @@ describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("session load/resume lifecyc
       requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
       readTextFile: async () => ({ content: "" }),
       writeTextFile: async () => ({}),
-    } as unknown as AgentSideConnection;
+    } as unknown as AcpClient;
 
     // Exact shape from https://github.com/zed-industries/claude-code-acp/issues/579.
     const concatenated =
@@ -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/settings.test.ts

@@ -7,13 +7,26 @@ import * as os from "node:os";
 describe("SettingsManager", () => {
   let tempDir: string;
   let settingsManager: SettingsManager;
+  let originalConfigDir: string | undefined;
 
   beforeEach(async () => {
     tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "settings-test-"));
+    // Isolate the user tier. resolveSettings reads the user settings.json from
+    // CLAUDE_CONFIG_DIR at call time; without this it falls back to the real
+    // ~/.claude and the developer's own settings (e.g. availableModels) leak
+    // into the merge, making union-based assertions fail on their machine.
+    originalConfigDir = process.env.CLAUDE_CONFIG_DIR;
+    process.env.CLAUDE_CONFIG_DIR = path.join(tempDir, "user-config");
+    await fs.promises.mkdir(process.env.CLAUDE_CONFIG_DIR, { recursive: true });
   });
 
   afterEach(async () => {
     settingsManager?.dispose();
+    if (originalConfigDir === undefined) {
+      delete process.env.CLAUDE_CONFIG_DIR;
+    } else {
+      process.env.CLAUDE_CONFIG_DIR = originalConfigDir;
+    }
     await fs.promises.rm(tempDir, { recursive: true, force: true });
   });
 

src/tests/tools.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeEach } from "vitest";
-import { AgentSideConnection, ClientCapabilities } from "@agentclientprotocol/sdk";
+import { ClientCapabilities } from "@agentclientprotocol/sdk";
 import { ImageBlockParam, ToolResultBlockParam } from "@anthropic-ai/sdk/resources";
 import {
   BetaMCPToolResultBlock,
@@ -10,7 +10,7 @@ import {
   BetaBashCodeExecutionResultBlock,
   BetaBashCodeExecutionToolResultBlockParam,
 } from "@anthropic-ai/sdk/resources/beta.mjs";
-import { toAcpNotifications, ToolUseCache, Logger } from "../acp-agent.js";
+import { AcpClient, toAcpNotifications, ToolUseCache, Logger } from "../acp-agent.js";
 import {
   toolUpdateFromToolResult,
   createPostToolUseHook,
@@ -25,7 +25,7 @@ import {
 } from "../tools.js";
 
 describe("rawOutput in tool call updates", () => {
-  const mockClient = {} as AgentSideConnection;
+  const mockClient = {} as AcpClient;
   const mockLogger: Logger = { log: () => {}, error: () => {} };
 
   it("should include rawOutput with string content for tool_result", () => {
@@ -425,7 +425,7 @@ describe("rawOutput in tool call updates", () => {
 });
 
 describe("Bash terminal output", () => {
-  const mockClient = {} as AgentSideConnection;
+  const mockClient = {} as AcpClient;
   const mockLogger: Logger = { log: () => {}, error: () => {} };
 
   const bashToolUse = {
@@ -702,6 +702,77 @@ describe("Bash terminal output", () => {
         });
       });
     });
+
+    describe("with image array tool_result (local Bash image output path)", () => {
+      // The local Bash tool emits image content as
+      // `[{ type: "image", source: { type: "base64", ... } }]` when a
+      // command produces an image (e.g. piping a base64 data URI).
+      const makeImageBashResult = (
+        data: string,
+        media_type: "image/png" | "image/jpeg" | "image/gif" | "image/webp" = "image/png",
+      ): ToolResultBlockParam => ({
+        type: "tool_result",
+        tool_use_id: "toolu_bash",
+        content: [
+          {
+            type: "image",
+            source: { type: "base64", media_type, data },
+          } as ImageBlockParam,
+        ],
+      });
+
+      it("should surface image content as ACP image content (terminal disabled)", () => {
+        const toolResult = makeImageBashResult("iVBORw0KGgo=");
+        const update = toolUpdateFromToolResult(toolResult, bashToolUse, false);
+
+        expect(update.content).toEqual([
+          {
+            type: "content",
+            content: { type: "image", data: "iVBORw0KGgo=", mimeType: "image/png" },
+          },
+        ]);
+        expect(update._meta).toBeUndefined();
+      });
+
+      it("should bypass terminal _meta even when supportsTerminalOutput is true", () => {
+        // Binary content cannot be streamed through the terminal-output
+        // _meta channel, so the fix returns ACP content directly and skips
+        // the terminal info/output/exit triple.
+        const toolResult = makeImageBashResult("iVBORw0KGgo=", "image/jpeg");
+        const update = toolUpdateFromToolResult(toolResult, bashToolUse, true);
+
+        expect(update.content).toEqual([
+          {
+            type: "content",
+            content: { type: "image", data: "iVBORw0KGgo=", mimeType: "image/jpeg" },
+          },
+        ]);
+        expect(update._meta).toBeUndefined();
+      });
+
+      it("should still surface multi-block content with text + image mixed", () => {
+        const toolResult: ToolResultBlockParam = {
+          type: "tool_result",
+          tool_use_id: "toolu_bash",
+          content: [
+            { type: "text", text: "generated:" },
+            {
+              type: "image",
+              source: { type: "base64", media_type: "image/png", data: "AAAA" },
+            } as ImageBlockParam,
+          ],
+        };
+        const update = toolUpdateFromToolResult(toolResult, bashToolUse, false);
+
+        expect(update.content).toEqual([
+          { type: "content", content: { type: "text", text: "generated:" } },
+          {
+            type: "content",
+            content: { type: "image", data: "AAAA", mimeType: "image/png" },
+          },
+        ]);
+      });
+    });
   });
 
   describe("toAcpNotifications with clientCapabilities", () => {
@@ -929,7 +1000,7 @@ describe("Bash terminal output", () => {
         sessionUpdate: async (notification: any) => {
           hookUpdates.push(notification);
         },
-      } as unknown as AgentSideConnection;
+      } as unknown as AcpClient;
 
       // Register hook callback by processing tool_use
       toAcpNotifications(
@@ -1008,7 +1079,7 @@ describe("Bash terminal output", () => {
         sessionUpdate: async (notification: any) => {
           hookUpdates.push(notification);
         },
-      } as unknown as AgentSideConnection;
+      } as unknown as AcpClient;
 
       toAcpNotifications(
         [
@@ -1093,7 +1164,7 @@ describe("Bash terminal output", () => {
         sessionUpdate: async (notification: any) => {
           hookUpdates.push(notification);
         },
-      } as unknown as AgentSideConnection;
+      } as unknown as AcpClient;
 
       toAcpNotifications(
         [
@@ -1147,7 +1218,7 @@ describe("Bash terminal output", () => {
         sessionUpdate: async (notification: any) => {
           hookUpdates.push(notification);
         },
-      } as unknown as AgentSideConnection;
+      } as unknown as AcpClient;
 
       toAcpNotifications(
         [
@@ -1223,7 +1294,7 @@ describe("Bash terminal output", () => {
         sessionUpdate: async (notification: any) => {
           hookUpdates.push(notification);
         },
-      } as unknown as AgentSideConnection;
+      } as unknown as AcpClient;
 
       toAcpNotifications(
         [
@@ -1304,7 +1375,7 @@ describe("Bash terminal output", () => {
         sessionUpdate: async (notification: any) => {
           hookUpdates.push(notification);
         },
-      } as unknown as AgentSideConnection;
+      } as unknown as AcpClient;
 
       // Step 1: Process tool_use chunk — registers the PostToolUse hook callback
       const toolUseChunk = {
@@ -1404,7 +1475,7 @@ describe("Bash terminal output", () => {
         sessionUpdate: async (notification: any) => {
           hookUpdates.push(notification);
         },
-      } as unknown as AgentSideConnection;
+      } as unknown as AcpClient;
 
       // Process tool_use (registers hook)
       toAcpNotifications(
@@ -1543,6 +1614,68 @@ describe("toolInfoFromToolUse - undefined input regression", () => {
     const info = toolInfoFromToolUse(toolUse, false);
     expect(info.title).toBe("Update TODOs");
   });
+
+  it("ReportFindings with undefined input should not throw", () => {
+    const toolUse = { name: "ReportFindings", id: "toolu_findings_undef", input: undefined };
+    const info = toolInfoFromToolUse(toolUse, false);
+    expect(info.title).toBe("Report findings: none found");
+    expect(info.content).toEqual([]);
+  });
+});
+
+describe("toolInfoFromToolUse - ReportFindings", () => {
+  it("should summarize findings count and list each in content", () => {
+    const toolUse = {
+      name: "ReportFindings",
+      id: "toolu_findings_1",
+      input: {
+        findings: [
+          {
+            file: "src/foo.ts",
+            line: 42,
+            summary: "Off-by-one in loop bound",
+            failure_scenario: "Empty array → index out of bounds crash",
+          },
+          {
+            file: "src/bar.ts",
+            summary: "Unhandled promise rejection",
+            failure_scenario: "Network failure → unhandled rejection",
+          },
+        ],
+      },
+    };
+
+    const info = toolInfoFromToolUse(toolUse, false);
+
+    expect(info.kind).toBe("think");
+    expect(info.title).toBe("Report 2 findings");
+    expect(info.content).toEqual([
+      {
+        type: "content",
+        content: { type: "text", text: "**src/foo.ts:42** — Off-by-one in loop bound" },
+      },
+      {
+        type: "content",
+        content: { type: "text", text: "**src/bar.ts** — Unhandled promise rejection" },
+      },
+    ]);
+  });
+
+  it("should report a singular title and empty findings array", () => {
+    const oneFinding = {
+      name: "ReportFindings",
+      id: "toolu_findings_2",
+      input: { findings: [{ file: "src/baz.ts", summary: "Leak", failure_scenario: "..." }] },
+    };
+    expect(toolInfoFromToolUse(oneFinding, false).title).toBe("Report 1 finding");
+
+    const noFindings = {
+      name: "ReportFindings",
+      id: "toolu_findings_3",
+      input: { findings: [] },
+    };
+    expect(toolInfoFromToolUse(noFindings, false).title).toBe("Report findings: none found");
+  });
 });
 
 describe("planEntries - undefined input regression", () => {
@@ -1569,7 +1702,7 @@ describe("planEntries - undefined input regression", () => {
 });
 
 describe("toAcpNotifications - TodoWrite with undefined input regression", () => {
-  const mockClient = {} as AgentSideConnection;
+  const mockClient = {} as AcpClient;
   const mockLogger: Logger = { log: () => {}, error: () => {} };
 
   it("should not throw when TodoWrite tool_use has undefined input", () => {
@@ -1704,7 +1837,7 @@ describe("applyTaskCreate / applyTaskUpdate", () => {
 });
 
 describe("toAcpNotifications - Task* tools", () => {
-  const mockClient = {} as AgentSideConnection;
+  const mockClient = {} as AcpClient;
   const mockLogger: Logger = { log: () => {}, error: () => {} };
 
   it("suppresses tool_call for TaskCreate/TaskUpdate/TaskList/TaskGet on tool_use", () => {
@@ -2020,3 +2153,512 @@ 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("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("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,19 +8,24 @@ import {
 import { HookCallback } from "@anthropic-ai/claude-agent-sdk";
 import {
   AgentInput,
+  AgentOutput,
   AskUserQuestionInput,
   BashInput,
+  BashOutput,
   FileEditInput,
   FileReadInput,
+  FileReadOutput,
   FileWriteInput,
   GlobInput,
   GrepInput,
+  ReportFindingsInput,
   TaskCreateInput,
   TaskCreateOutput,
   TaskUpdateInput,
   TodoWriteInput,
   WebFetchInput,
   WebSearchInput,
+  WebSearchOutput,
 } from "@anthropic-ai/claude-agent-sdk/sdk-tools.js";
 import {
   ImageBlockParam,
@@ -371,6 +376,25 @@ export function toolInfoFromToolUse(
       };
     }
 
+    case "ReportFindings": {
+      const input = toolUse.input as ReportFindingsInput | undefined;
+      const findings = input?.findings ?? [];
+      return {
+        title:
+          findings.length === 0
+            ? "Report findings: none found"
+            : `Report ${findings.length} finding${findings.length === 1 ? "" : "s"}`,
+        kind: "think",
+        content: findings.map((finding) => ({
+          type: "content" as const,
+          content: {
+            type: "text" as const,
+            text: `**${finding.file}${finding.line ? `:${finding.line}` : ""}** — ${finding.summary}`,
+          },
+        })),
+      };
+    }
+
     case "TaskCreate": {
       const input = toolUse.input as TaskCreateInput | undefined;
       return {
@@ -466,6 +490,55 @@ 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 text
+    .replace(/\n?<usage>[\s\S]*?<\/usage>\s*$/, "")
+    .replace(/\n?agentId: [\w-]+ \([^)]*\)\s*$/, "");
+}
+
+/** 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
@@ -480,6 +553,7 @@ export function toolUpdateFromToolResult(
     | BetaToolSearchToolResultBlockParam,
   toolUse: any | undefined,
   supportsTerminalOutput: boolean = false,
+  toolUseResult?: unknown,
 ): ToolUpdate {
   if (
     "is_error" in toolResult &&
@@ -492,8 +566,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) => ({
@@ -521,6 +650,7 @@ export function toolUpdateFromToolResult(
         };
       }
       return {};
+    }
 
     case "Bash": {
       const result = toolResult.content;
@@ -528,13 +658,57 @@ export function toolUpdateFromToolResult(
       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: "..." }])
+      // 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 &&
@@ -545,13 +719,20 @@ export function toolUpdateFromToolResult(
         exitCode = bashResult.return_code;
       } else if (typeof result === "string") {
         output = result;
-      } else if (
-        Array.isArray(result) &&
-        result.length > 0 &&
-        "text" in result[0] &&
-        typeof result[0].text === "string"
-      ) {
-        output = result.map((c: any) => c.text).join("\n");
+      } else if (Array.isArray(result) && result.length > 0) {
+        const textOnly = result.every(
+          (c: any) => c && typeof c === "object" && typeof c.text === "string",
+        );
+        if (textOnly) {
+          output = result.map((c: any) => c.text).join("\n");
+        } else {
+          // Image (or mixed non-text) content. Binary payloads can't be
+          // streamed through the terminal-output _meta channel, so bypass
+          // it and surface the blocks as ACP content. This handles the
+          // local Bash tool's image output, which previously failed the
+          // text-only guard and was silently dropped.
+          return toAcpContentUpdate(result, isError);
+        }
       }
 
       if (supportsTerminalOutput) {
@@ -590,6 +771,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 {};
@@ -599,15 +819,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,
@@ -682,7 +941,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":

tsconfig.json

@@ -1,13 +1,7 @@
 {
+  "extends": "@tsconfig/node22/tsconfig.json",
   "compilerOptions": {
-    "target": "ES2021",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "lib": ["ES2021"],
-    "strict": true,
-    "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
-    "skipLibCheck": true,
     "outDir": "dist",
     "rootDir": "src",
     "declaration": true,