chore(main): release 0.58.0 (#847)

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


##
[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](f664ced76d))


### Bug Fixes

* Preserve live model on resumed sessions
([#848](https://github.com/agentclientprotocol/claude-agent-acp/issues/848))
([f3d8ae3](f3d8ae3eb3)),
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](b03318f59c)),
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](e944ceddea))
* Use SDK guards for elicitation validation
([#850](https://github.com/agentclientprotocol/claude-agent-acp/issues/850))
([32b9350](32b93501d7))

---
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,7 +44,7 @@ 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:

.release-please-manifest.json

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

CHANGELOG.md

@@ -1,5 +1,152 @@
 # Changelog
 
+## [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.58.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.205",
     "zod": "^3.25.0 || ^4.0.0"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "0.104.2",
+    "@anthropic-ai/sdk": "0.110.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.6.0",
     "eslint-config-prettier": "10.1.8",
-    "globals": "17.6.0",
-    "prettier": "3.8.4",
+    "globals": "17.7.0",
+    "prettier": "3.9.4",
     "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,7 @@ 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";
 
 const { querySpy } = vi.hoisted(() => ({
   querySpy: vi.fn(),
@@ -21,13 +20,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() {
@@ -812,6 +811,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 () => {

src/tests/additional-roots.test.ts

@@ -1,9 +1,9 @@
 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;
@@ -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,6 +1,5 @@
 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";
 
 const mockQuery = vi.hoisted(() =>
   vi.fn(() => ({
@@ -39,7 +38,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,7 +1,7 @@
 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";
@@ -47,13 +47,13 @@ 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 () => {
@@ -550,14 +550,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 +613,127 @@ describe("createSession options merging", () => {
       expect(capturedOptions!.disallowedTools).not.toContain("AskUserQuestion");
     });
   });
+
+  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();
+
+      const result = await onUserDialog(
+        { dialogKind: "refusal_fallback_prompt", payload: { fallbackModel: 42 } },
+        signal(),
+      );
+
+      expect(result).toEqual({ behavior: "cancelled" });
+      expect(createElicitation).not.toHaveBeenCalled();
+    });
+
+    it("cancels when the elicitation request fails", async () => {
+      const { onUserDialog, createElicitation } = await setupDialog();
+      createElicitation.mockRejectedValue(new Error("client exploded"));
+
+      const result = await onUserDialog(
+        {
+          dialogKind: "refusal_fallback_prompt",
+          payload: { originalModel: "a", fallbackModel: "b" },
+        },
+        signal(),
+      );
+
+      expect(result).toEqual({ behavior: "cancelled" });
+    });
+  });
 });

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/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,7 @@
 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";
 
 const { registerHookCallbackSpy } = vi.hoisted(() => ({
   registerHookCallbackSpy: vi.fn(),
@@ -84,7 +84,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 +92,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() {
@@ -113,17 +113,17 @@ describe("session config options", () => {
       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" });
 
@@ -1113,6 +1192,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 +1227,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 +1259,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,55 @@ 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" },
+    });
+  });
+});

src/tools.ts

@@ -15,6 +15,7 @@ import {
   FileWriteInput,
   GlobInput,
   GrepInput,
+  ReportFindingsInput,
   TaskCreateInput,
   TaskCreateOutput,
   TaskUpdateInput,
@@ -371,6 +372,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 {
@@ -530,7 +550,9 @@ export function toolUpdateFromToolResult(
       // 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: "..." }])
+      // 3. 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;
 
@@ -545,13 +567,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) {

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,