wait for the first tool_use chunk in canUseTool

Before, if a subagent requested a tool permission, we'd send the
permission request with the tool_call_update before the initial
tool_call.

.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      # Check for updates to GitHub Actions every week
+      interval: "weekly"
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    allow:
+      - dependency-type: "all"
+    groups:
+      minor:
+        update-types:
+          - "minor"
+          - "patch"

.github/workflows/ci.yml

@@ -21,12 +21,12 @@ jobs:
     timeout-minutes: 5
 
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
 
       - name: Use Node.js
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
         with:
-          node-version: latest
+          node-version: "lts/*"
           cache: "npm"
 
       - name: Install dependencies

.github/workflows/publish.yml

@@ -1,19 +1,52 @@
-name: Publish Package to npmjs
+name: Publish and Release
 on:
   push:
-    tags:
-      - "v*.*.*"
+    branches:
+      - main
+
 jobs:
-  publish-npm:
+  release-please:
     runs-on: ubuntu-latest
     environment: release # Optional: for enhanced security
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+    steps:
+      # Generating a GitHub token, so that PRs and tags created by
+      # the release-please-action can trigger actions workflows.
+      - name: Generate GitHub token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1
+        id: generate-token
+        with:
+          # GitHub App ID secret name
+          app-id: ${{ secrets.RELEASE_PLZ_APP_ID }}
+          # GitHub App private key secret name
+          private-key: ${{ secrets.RELEASE_PLZ_APP_PRIVATE_KEY }}
+      - uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7
+        id: release
+        with:
+          token: ${{ steps.generate-token.outputs.token }}
+          release-type: node
+          config-file: release-please-config.json
+          manifest-file: .release-please-manifest.json
+    outputs:
+      release_created: ${{ steps.release.outputs.release_created }}
+      tag_name: ${{ steps.release.outputs.tag_name }}
+
+  publish-npm:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    needs: [release-please]
+    if: ${{ needs.release-please.outputs.release_created }}
+    environment: release # Optional: for enhanced security
     permissions:
       contents: read
       id-token: write
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
       # Setup .npmrc file to publish to npm
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
         with:
           node-version: "lts/*"
           registry-url: "https://registry.npmjs.org"
@@ -22,15 +55,3 @@ jobs:
       - run: npm ci
       - run: npm run build
       - run: npm publish
-  release:
-    runs-on: ubuntu-latest
-    needs: [publish-npm]
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8
-      - name: Create Release
-        id: create_release
-        uses: softprops/action-gh-release@6da8fa9354ddfdc4aeace5fc48d7f679b5214090
-        with:
-          generate_release_notes: true

.prettierignore

@@ -0,0 +1,7 @@
+node_modules
+dist
+.agent-shell
+
+.release-please-manifest.json
+release-please-config.json
+CHANGELOG.md

.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.51.0"
+}

CHANGELOG.md

@@ -1,5 +1,528 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* Update to claude-agent-sdk 0.3.178 ([#777](https://github.com/agentclientprotocol/claude-agent-acp/issues/777)) ([58549ff](https://github.com/agentclientprotocol/claude-agent-acp/commit/58549ffe6a8b02ce59894e567407bd4299c11428))
+
+
+### Bug Fixes
+
+* Better handle out of turn events ([#780](https://github.com/agentclientprotocol/claude-agent-acp/issues/780)) ([4f273a2](https://github.com/agentclientprotocol/claude-agent-acp/commit/4f273a20d870c9c69f71556b8e0519f1de30f285))
+* Forward option details in elicitation meta ([#779](https://github.com/agentclientprotocol/claude-agent-acp/issues/779)) ([b364059](https://github.com/agentclientprotocol/claude-agent-acp/commit/b3640599ae685beecacd93e012d5bbc9dac716f7)), closes [#764](https://github.com/agentclientprotocol/claude-agent-acp/issues/764)
+
+## [0.45.1](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.45.0...v0.45.1) (2026-06-16)
+
+
+### Bug Fixes
+
+* Fix terminal error printing as text instead of terminal output ([#776](https://github.com/agentclientprotocol/claude-agent-acp/issues/776)) ([db6eaaf](https://github.com/agentclientprotocol/claude-agent-acp/commit/db6eaaf71484a321e47093ad65bcf8994943cb31))
+* Scope custom answers per question ([#774](https://github.com/agentclientprotocol/claude-agent-acp/issues/774)) ([d58004a](https://github.com/agentclientprotocol/claude-agent-acp/commit/d58004a34880e0a76833697319eb2a9efa6a43c7))
+
+## [0.45.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.44.0...v0.45.0) (2026-06-15)
+
+
+### Features
+
+* **deps-dev:** bump the minor group with 3 updates ([#763](https://github.com/agentclientprotocol/claude-agent-acp/issues/763)) ([7de5e4b](https://github.com/agentclientprotocol/claude-agent-acp/commit/7de5e4bcca9bfea70593092060f82bc8abe33e0e))
+* **deps:** bump @anthropic-ai/claude-agent-sdk to 0.3.177 ([#771](https://github.com/agentclientprotocol/claude-agent-acp/issues/771)) ([1be5ca5](https://github.com/agentclientprotocol/claude-agent-acp/commit/1be5ca57ee772fe90e41126365dc4186a18ad257))
+
+
+### Bug Fixes
+
+* preserve ANTHROPIC_CUSTOM_MODEL_OPTION when availableModels is set ([#768](https://github.com/agentclientprotocol/claude-agent-acp/issues/768)) ([cc2885f](https://github.com/agentclientprotocol/claude-agent-acp/commit/cc2885f6a9993cf61e759c3c770015f94c218627))
+
+## [0.44.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.43.0...v0.44.0) (2026-06-09)
+
+
+### Features
+
+* **deps:** bump the minor group with 14 updates ([#758](https://github.com/agentclientprotocol/claude-agent-acp/issues/758)) ([7a70162](https://github.com/agentclientprotocol/claude-agent-acp/commit/7a701623df2e05aec8e552bdfd1cf573413c3471))
+* **deps:** update to @anthropic-ai/claude-agent-sdk 0.3.170 ([#761](https://github.com/agentclientprotocol/claude-agent-acp/issues/761)) ([d8af943](https://github.com/agentclientprotocol/claude-agent-acp/commit/d8af943a1efef9be27d771cec089d2f1cb56c523))
+
+## [0.43.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.42.0...v0.43.0) (2026-06-09)
+
+
+### Features
+
+* Add experimental elicitation support ([#756](https://github.com/agentclientprotocol/claude-agent-acp/issues/756)) ([12bd276](https://github.com/agentclientprotocol/claude-agent-acp/commit/12bd2762d9ba0ccb7497a3848a5928b8bb2ce820))
+* **deps:** update to @anthropic-ai/claude-agent-sdk 0.3.169 ([#754](https://github.com/agentclientprotocol/claude-agent-acp/issues/754)) ([bd0ae4d](https://github.com/agentclientprotocol/claude-agent-acp/commit/bd0ae4dde160f59559ab4ac1bf703fcf151eff17))
+* Update ACP SDK to 0.25.0 ([#753](https://github.com/agentclientprotocol/claude-agent-acp/issues/753)) ([0dbccf5](https://github.com/agentclientprotocol/claude-agent-acp/commit/0dbccf588ff702015494dd29969d47f0b7402feb))
+
+
+### Bug Fixes
+
+* Forward unstreamed assistant text blocks ([#757](https://github.com/agentclientprotocol/claude-agent-acp/issues/757)) ([7ff6b7f](https://github.com/agentclientprotocol/claude-agent-acp/commit/7ff6b7fd6b157aedbce0c636087f51ae7d1df3a7))
+* Validate cwd before creating sessions ([#751](https://github.com/agentclientprotocol/claude-agent-acp/issues/751)) ([9854b0c](https://github.com/agentclientprotocol/claude-agent-acp/commit/9854b0c6790ebafff514e3c4c8e03a131f065a4a)), closes [#749](https://github.com/agentclientprotocol/claude-agent-acp/issues/749)
+
+## [0.42.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.41.0...v0.42.0) (2026-06-05)
+
+
+### Features
+
+* **deps-dev:** bump obug from 2.1.1 to 2.1.2 in the minor group ([#743](https://github.com/agentclientprotocol/claude-agent-acp/issues/743)) ([7ffb78c](https://github.com/agentclientprotocol/claude-agent-acp/commit/7ffb78c57280fc32af77862896c0035ce0e690b7))
+* Send message ids for assistant and user messages ([#750](https://github.com/agentclientprotocol/claude-agent-acp/issues/750)) ([18516a3](https://github.com/agentclientprotocol/claude-agent-acp/commit/18516a3088f847a38f5eee0fe81ad5ca3e2a751c))
+* Update Claude Agent SDK to 0.3.165 ([#746](https://github.com/agentclientprotocol/claude-agent-acp/issues/746)) ([23cbe6f](https://github.com/agentclientprotocol/claude-agent-acp/commit/23cbe6f58fa9e10ad736f664c4cf94dbd1c6ad65))
+
+
+### Bug Fixes
+
+* Prevent cross-family model matching in resolveModelPreference ([#731](https://github.com/agentclientprotocol/claude-agent-acp/issues/731)) ([f4704c1](https://github.com/agentclientprotocol/claude-agent-acp/commit/f4704c168f917e6710f2b3cd49e1fef49613a469))
+* Prune tool cache per session after results ([#748](https://github.com/agentclientprotocol/claude-agent-acp/issues/748)) ([ec14211](https://github.com/agentclientprotocol/claude-agent-acp/commit/ec142110561f680330c6976783805685c5c069ec))
+* Update to better utilize existing SDK data ([#747](https://github.com/agentclientprotocol/claude-agent-acp/issues/747)) ([398f763](https://github.com/agentclientprotocol/claude-agent-acp/commit/398f763f71bd2fe2ca9e8269de120d26a744b7a8))
+
+## [0.41.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.40.0...v0.41.0) (2026-06-04)
+
+
+### Features
+
+* **deps:** upgrade to @anthropic-ai/claude-agent-sdk@0.3.162 ([#740](https://github.com/agentclientprotocol/claude-agent-acp/issues/740)) ([add7e31](https://github.com/agentclientprotocol/claude-agent-acp/commit/add7e31704581aa70febb6341ca0e8cee5d93b43))
+
+
+### Bug Fixes
+
+* Force cancellation when SDK query hangs ([#742](https://github.com/agentclientprotocol/claude-agent-acp/issues/742)) ([cffea4b](https://github.com/agentclientprotocol/claude-agent-acp/commit/cffea4be28e6def91027110433a99e80b1be8a0c)), closes [#680](https://github.com/agentclientprotocol/claude-agent-acp/issues/680)
+
+## [0.40.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.39.0...v0.40.0) (2026-06-02)
+
+
+### Features
+
+* **deps-dev:** bump the minor group with 2 updates ([#726](https://github.com/agentclientprotocol/claude-agent-acp/issues/726)) ([51a370e](https://github.com/agentclientprotocol/claude-agent-acp/commit/51a370e4feb8a74279698b156e35b96631a74d74))
+* **deps:** bump actions/checkout from 6.0.2 to 6.0.3 ([#736](https://github.com/agentclientprotocol/claude-agent-acp/issues/736)) ([9cda07b](https://github.com/agentclientprotocol/claude-agent-acp/commit/9cda07ba9df27b48bd94332e365eed982e3f5613))
+* **deps:** bump the minor group with 50 updates ([#737](https://github.com/agentclientprotocol/claude-agent-acp/issues/737)) ([32175b8](https://github.com/agentclientprotocol/claude-agent-acp/commit/32175b83a0227d0baa1f7d7eedabe743b4b870e8))
+
+
+### Bug Fixes
+
+* Optimize local command marker stripping ([#738](https://github.com/agentclientprotocol/claude-agent-acp/issues/738)) ([895422c](https://github.com/agentclientprotocol/claude-agent-acp/commit/895422c72d5f955903f227dc6887df823d2730e6)), closes [#727](https://github.com/agentclientprotocol/claude-agent-acp/issues/727)
+
+## [0.39.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.38.0...v0.39.0) (2026-05-29)
+
+
+### Features
+
+* **deps:** update Claude Agent SDK to 0.3.156 ([#722](https://github.com/agentclientprotocol/claude-agent-acp/issues/722)) ([3fb6db4](https://github.com/agentclientprotocol/claude-agent-acp/commit/3fb6db4e5ee5bd1f431cf5d2ce5331ce983f9597))
+
+## [0.38.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.37.0...v0.38.0) (2026-05-28)
+
+
+### Features
+
+* **deps:** bump to @anthropic-ai/claude-agent-sdk 0.3.154 (Opus 4.8) ([#716](https://github.com/agentclientprotocol/claude-agent-acp/issues/716)) ([a172885](https://github.com/agentclientprotocol/claude-agent-acp/commit/a172885c80fc32c108a8501268a543641088f543))
+* Support Opus 4.8 ([#718](https://github.com/agentclientprotocol/claude-agent-acp/issues/718)) ([98b54a0](https://github.com/agentclientprotocol/claude-agent-acp/commit/98b54a02c267cdef619becceccf6ef519fbf8f6f))
+
+
+### Bug Fixes
+
+* Remove hide Claude auth flag handling ([#707](https://github.com/agentclientprotocol/claude-agent-acp/issues/707)) ([7ed1daf](https://github.com/agentclientprotocol/claude-agent-acp/commit/7ed1daf7b42088ad149e9bf742f764752b82d093))
+
+## [0.37.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.36.1...v0.37.0) (2026-05-21)
+
+
+### Features
+
+* add 'Default' option to effort level config ([#701](https://github.com/agentclientprotocol/claude-agent-acp/issues/701)) ([9e259d1](https://github.com/agentclientprotocol/claude-agent-acp/commit/9e259d128aa58dbb8107e53362781ca4e8ee071e))
+* **deps:** bump the claude-agent-sdk to 0.3.146 ([#700](https://github.com/agentclientprotocol/claude-agent-acp/issues/700)) ([72875b2](https://github.com/agentclientprotocol/claude-agent-acp/commit/72875b248c7b90a89638de2f1709eec9e2153e7e))
+* **deps:** bump the minor group with 13 updates ([#689](https://github.com/agentclientprotocol/claude-agent-acp/issues/689)) ([f66bc31](https://github.com/agentclientprotocol/claude-agent-acp/commit/f66bc31ae4bea73b48eeeb7f1db90c7d69cc0dac))
+* Emit tool calls for memory recall events ([#703](https://github.com/agentclientprotocol/claude-agent-acp/issues/703)) ([a0bfb98](https://github.com/agentclientprotocol/claude-agent-acp/commit/a0bfb98ba73eaf37e9c071e886c054f90a5d5629)), closes [#650](https://github.com/agentclientprotocol/claude-agent-acp/issues/650)
+
+
+### Bug Fixes
+
+* Avoid cross-version model alias matches ([#702](https://github.com/agentclientprotocol/claude-agent-acp/issues/702)) ([e1e1c69](https://github.com/agentclientprotocol/claude-agent-acp/commit/e1e1c69029ef08579c841e6fbdffb32a5b94df06))
+* Avoid redundant initial model sync ([#704](https://github.com/agentclientprotocol/claude-agent-acp/issues/704)) ([b275f6f](https://github.com/agentclientprotocol/claude-agent-acp/commit/b275f6ff7f0f2e21adedbd8e63a6fc3d63cbbb8d)), closes [#646](https://github.com/agentclientprotocol/claude-agent-acp/issues/646)
+* Don't expose /clear in commands ([#705](https://github.com/agentclientprotocol/claude-agent-acp/issues/705)) ([cfce130](https://github.com/agentclientprotocol/claude-agent-acp/commit/cfce1307076e93f43a3ed8cc0134f9bb14a0f2d6))
+* emit  "cancelled" instead of "end_turn" when the session was interrupted. ([#694](https://github.com/agentclientprotocol/claude-agent-acp/issues/694)) ([2414a6f](https://github.com/agentclientprotocol/claude-agent-acp/commit/2414a6f98bec5bf50f3a13af528aa38d5a0fc974))
+* Recover prompt stream after a failed turn ([#706](https://github.com/agentclientprotocol/claude-agent-acp/issues/706)) ([2711f50](https://github.com/agentclientprotocol/claude-agent-acp/commit/2711f506d5799f0ae25160de311a4459ffb46c49)), closes [#654](https://github.com/agentclientprotocol/claude-agent-acp/issues/654)
+
+## [0.36.1](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.36.0...v0.36.1) (2026-05-18)
+
+
+### Bug Fixes
+
+* flaky authentication bypass for gateway ([#686](https://github.com/agentclientprotocol/claude-agent-acp/issues/686)) ([db852dc](https://github.com/agentclientprotocol/claude-agent-acp/commit/db852dcf7c8e3b461fabb1bdcf0c80a27d1da77d))
+
+## [0.36.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.35.0...v0.36.0) (2026-05-18)
+
+
+### Features
+
+* Add experimental session delete support ([#682](https://github.com/agentclientprotocol/claude-agent-acp/issues/682)) ([2162d5a](https://github.com/agentclientprotocol/claude-agent-acp/commit/2162d5af62d493a82381bd88bc8fc67d376e358b))
+* Support experimental additionalDirectories field ([#684](https://github.com/agentclientprotocol/claude-agent-acp/issues/684)) ([f37e9a0](https://github.com/agentclientprotocol/claude-agent-acp/commit/f37e9a0d47d8d201d98b2177083664a6781895cc))
+
+## [0.35.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.34.1...v0.35.0) (2026-05-16)
+
+
+### Features
+
+* **deps:** bump actions/create-github-app-token from 3.1.1 to 3.2.0 ([#669](https://github.com/agentclientprotocol/claude-agent-acp/issues/669)) ([47df1f2](https://github.com/agentclientprotocol/claude-agent-acp/commit/47df1f2a0be57ddb8873ae8e341f748471c7bc53))
+* **deps:** bump hono from 4.12.18 to 4.12.19 in the minor group ([#671](https://github.com/agentclientprotocol/claude-agent-acp/issues/671)) ([5d7165d](https://github.com/agentclientprotocol/claude-agent-acp/commit/5d7165d96158da2ddf3087676cdb0a19d1ff57aa))
+* **deps:** update to claude-agent-sdk 0.3.143 ([#664](https://github.com/agentclientprotocol/claude-agent-acp/issues/664)) ([27ca2e5](https://github.com/agentclientprotocol/claude-agent-acp/commit/27ca2e5d40917887671cc4c39a854fd8f92c01e6))
+* Use SDK settings resolution for defaults ([#677](https://github.com/agentclientprotocol/claude-agent-acp/issues/677)) ([eb1259c](https://github.com/agentclientprotocol/claude-agent-acp/commit/eb1259cf88375ca3c20a219ab99f12f5488fb360))
+
+
+### Bug Fixes
+
+* Add task hooks for plan state updates ([#676](https://github.com/agentclientprotocol/claude-agent-acp/issues/676)) ([5ff7d50](https://github.com/agentclientprotocol/claude-agent-acp/commit/5ff7d50f0ec7f34a7d9d901223aed73e2dbcce68))
+* render local-command-stdout messages instead of dropping them ([#649](https://github.com/agentclientprotocol/claude-agent-acp/issues/649)) ([3b9b7d5](https://github.com/agentclientprotocol/claude-agent-acp/commit/3b9b7d5a56defd925eb2038fa97b6484ad951587))
+
+## [0.34.1](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.34.0...v0.34.1) (2026-05-16)
+
+
+### Bug Fixes
+
+* load credential error for bedrock gateway ([#667](https://github.com/agentclientprotocol/claude-agent-acp/issues/667)) ([8d76be3](https://github.com/agentclientprotocol/claude-agent-acp/commit/8d76be356a3e74c58a7c93c3c201cca6a317d784))
+
+## [0.34.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.33.1...v0.34.0) (2026-05-15)
+
+
+### Features
+
+* add bedrock gateway authentication ([#665](https://github.com/agentclientprotocol/claude-agent-acp/issues/665)) ([002c63a](https://github.com/agentclientprotocol/claude-agent-acp/commit/002c63a78b844c168d3dfc744cf408362a6adf97))
+
+## [0.33.1](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.33.0...v0.33.1) (2026-05-07)
+
+
+### Bug Fixes
+
+* Honor availableModels settings allowlist ([#637](https://github.com/agentclientprotocol/claude-agent-acp/issues/637)) ([867a3a0](https://github.com/agentclientprotocol/claude-agent-acp/commit/867a3a0de2a050592d79aa76d7dd3dd5b478162d)), closes [#620](https://github.com/agentclientprotocol/claude-agent-acp/issues/620)
+
+## [0.33.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.32.0...v0.33.0) (2026-05-07)
+
+
+### Features
+
+* **deps:** bump the minor group with 14 updates ([#631](https://github.com/agentclientprotocol/claude-agent-acp/issues/631)) ([8b43ee8](https://github.com/agentclientprotocol/claude-agent-acp/commit/8b43ee813f05f5087a213a7f42154e39d6bc4a5a))
+* **deps:** Update to claude-agent-sdk 0.2.132 ([#636](https://github.com/agentclientprotocol/claude-agent-acp/issues/636)) ([0c8ff27](https://github.com/agentclientprotocol/claude-agent-acp/commit/0c8ff277f2af8d3085cc1b5cf33891630dede0b1))
+
+
+### Bug Fixes
+
+* Handle result origins in ACP agent ([#627](https://github.com/agentclientprotocol/claude-agent-acp/issues/627)) ([dba1998](https://github.com/agentclientprotocol/claude-agent-acp/commit/dba199839a25ba405f04b9d4409e647150fe0290))
+
+## [0.32.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.31.4...v0.32.0) (2026-05-03)
+
+
+### Features
+
+* **deps-dev:** Bump nanoid from 3.3.11 to 3.3.12 ([#622](https://github.com/agentclientprotocol/claude-agent-acp/issues/622)) ([c78ac62](https://github.com/agentclientprotocol/claude-agent-acp/commit/c78ac62d05283e5683b87b198923818f9f556a03))
+* **deps:** Bump the minor group with 2 updates ([#619](https://github.com/agentclientprotocol/claude-agent-acp/issues/619)) ([6ccd37c](https://github.com/agentclientprotocol/claude-agent-acp/commit/6ccd37ce947fbd55691f676344b15ef1266191ad))
+* **deps:** update to @anthropic-ai/claude-agent-sdk 0.2.126 ([#621](https://github.com/agentclientprotocol/claude-agent-acp/issues/621)) ([becc3b8](https://github.com/agentclientprotocol/claude-agent-acp/commit/becc3b86e60eb33e7823a0ef27d5aa99758750d7))
+* **deps:** Update to @anthropic-ai/claude-agent-sdk@0.2.123 ([#614](https://github.com/agentclientprotocol/claude-agent-acp/issues/614)) ([5b93119](https://github.com/agentclientprotocol/claude-agent-acp/commit/5b9311938d97f47400debd66f2b4792e50639c6b))
+
+
+### Bug Fixes
+
+* emit a real diff when Write overwrites an existing file ([#618](https://github.com/agentclientprotocol/claude-agent-acp/issues/618)) ([8d7e220](https://github.com/agentclientprotocol/claude-agent-acp/commit/8d7e22026e15d54208414bd9ad128eb86d41b451))
+
+## [0.31.4](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.31.3...v0.31.4) (2026-04-28)
+
+
+### Bug Fixes
+
+* gate auto mode on model support ([#604](https://github.com/agentclientprotocol/claude-agent-acp/issues/604)) ([ec47d34](https://github.com/agentclientprotocol/claude-agent-acp/commit/ec47d3446fa22e5895621f57c0a4497dbe044505))
+
+## [0.31.3](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.31.2...v0.31.3) (2026-04-28)
+
+
+### Bug Fixes
+
+* Rename effort config category to thought_level ([#609](https://github.com/agentclientprotocol/claude-agent-acp/issues/609)) ([76b4e96](https://github.com/agentclientprotocol/claude-agent-acp/commit/76b4e9650832e59a6b4915ad898fc66a065022fa))
+
+## [0.31.2](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.31.1...v0.31.2) (2026-04-28)
+
+
+### Bug Fixes
+
+* tolerate invalid values in settings.json ([#601](https://github.com/agentclientprotocol/claude-agent-acp/issues/601)) ([67af018](https://github.com/agentclientprotocol/claude-agent-acp/commit/67af018d0216238d8f3cd5bad04a55200518239b))
+
+## [0.31.1](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.31.0...v0.31.1) (2026-04-27)
+
+
+### Bug Fixes
+
+* detect glibc and use correct binary ([#599](https://github.com/agentclientprotocol/claude-agent-acp/issues/599)) ([f0801d5](https://github.com/agentclientprotocol/claude-agent-acp/commit/f0801d50b2390a3c48150b9b8507d30a70c18b84))
+
+## [0.31.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.30.0...v0.31.0) (2026-04-24)
+
+
+### Features
+
+* allow configuring models through env vars ([#586](https://github.com/agentclientprotocol/claude-agent-acp/issues/586)) ([1e15f3d](https://github.com/agentclientprotocol/claude-agent-acp/commit/1e15f3d8b0a06076ee62764ab576ac29fe056a38))
+* Support effort levels ([#464](https://github.com/agentclientprotocol/claude-agent-acp/issues/464)) ([9e1185b](https://github.com/agentclientprotocol/claude-agent-acp/commit/9e1185bfd55cbf83a653a0ff8c194f986cbd1574))
+* Update to acp sdk v0.20 ([#589](https://github.com/agentclientprotocol/claude-agent-acp/issues/589)) ([92adcbd](https://github.com/agentclientprotocol/claude-agent-acp/commit/92adcbd1ace2f2103742ffcf5c589eb1ca41b9b8))
+* Update to claude-agent-sdk 0.2.119 ([#587](https://github.com/agentclientprotocol/claude-agent-acp/issues/587)) ([ef1dbd1](https://github.com/agentclientprotocol/claude-agent-acp/commit/ef1dbd1cb457f0524d221ea07235abf49dc941a0))
+
+
+### Bug Fixes
+
+* Forward full systemPrompt preset options from _meta ([#591](https://github.com/agentclientprotocol/claude-agent-acp/issues/591)) ([b3ddfc3](https://github.com/agentclientprotocol/claude-agent-acp/commit/b3ddfc3b86703c23fe99d93611885c12b1e4812c))
+* Session Replay and Permission rendering ([#593](https://github.com/agentclientprotocol/claude-agent-acp/issues/593)) ([5faefab](https://github.com/agentclientprotocol/claude-agent-acp/commit/5faefab8ab9b725f7a3374808bf5579e411884bc)), closes [#579](https://github.com/agentclientprotocol/claude-agent-acp/issues/579)
+
+## [0.30.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.29.2...v0.30.0) (2026-04-20)
+
+
+### Features
+
+* Update to claude-agent-sdk 0.2.114 ([#572](https://github.com/agentclientprotocol/claude-agent-acp/issues/572)) ([e9dd452](https://github.com/agentclientprotocol/claude-agent-acp/commit/e9dd45207d396302f20de82561135bf9558c0e76))
+
+## [0.29.2](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.29.1...v0.29.2) (2026-04-17)
+
+
+### Bug Fixes
+
+* Guard against null usage tokens ([#565](https://github.com/agentclientprotocol/claude-agent-acp/issues/565)) ([f7dc300](https://github.com/agentclientprotocol/claude-agent-acp/commit/f7dc300a165e70f6426f53920f12e24c04033cdc)), closes [#564](https://github.com/agentclientprotocol/claude-agent-acp/issues/564)
+
+## [0.29.1](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.29.0...v0.29.1) (2026-04-17)
+
+
+### Bug Fixes
+
+* emit usage updates from Claude stream events ([#506](https://github.com/agentclientprotocol/claude-agent-acp/issues/506)) ([dd67450](https://github.com/agentclientprotocol/claude-agent-acp/commit/dd67450fd9bddc82db3e71273b535e07b2672804))
+* Remove dot from auto mode description ([#561](https://github.com/agentclientprotocol/claude-agent-acp/issues/561)) ([2ecfa83](https://github.com/agentclientprotocol/claude-agent-acp/commit/2ecfa83b26db58deaded210463fa6ff21d0dff70))
+* Update to claude-agent-sdk 0.2.112 to fix Auto bug with Opus 4.7 ([#562](https://github.com/agentclientprotocol/claude-agent-acp/issues/562)) ([079614a](https://github.com/agentclientprotocol/claude-agent-acp/commit/079614ab05afba17e2cce0d3d238df7b90e17389))
+
+## [0.29.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.28.0...v0.29.0) (2026-04-16)
+
+
+### Features
+
+* Update to claude-agent-sdk 0.2.111 (Opus 4.7) ([#557](https://github.com/agentclientprotocol/claude-agent-acp/issues/557)) ([85cd70c](https://github.com/agentclientprotocol/claude-agent-acp/commit/85cd70c9f3be47c9c404958547c4046d866db1c9))
+
+## [0.28.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.27.0...v0.28.0) (2026-04-15)
+
+
+### Features
+
+* Update to claude-agent-sdk 0.2.109 ([#549](https://github.com/agentclientprotocol/claude-agent-acp/issues/549)) ([07a0fbc](https://github.com/agentclientprotocol/claude-agent-acp/commit/07a0fbc2f6bc388541d064a436412bdd850772cb))
+
+## [0.27.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.26.0...v0.27.0) (2026-04-13)
+
+
+### Features
+
+* allow clients to opt into receiving raw SDK messages ([#527](https://github.com/agentclientprotocol/claude-agent-acp/issues/527)) ([403a668](https://github.com/agentclientprotocol/claude-agent-acp/commit/403a668078c067868062ed26cd4d3e36665b66b6))
+* Update to claude-agent-sdk 0.2.104 ([#537](https://github.com/agentclientprotocol/claude-agent-acp/issues/537)) ([6811943](https://github.com/agentclientprotocol/claude-agent-acp/commit/6811943f57ef08616be633a8197223d4072663cf))
+
+
+### Bug Fixes
+
+* Allow auto mode after plan mode and send description for auto mode ([#528](https://github.com/agentclientprotocol/claude-agent-acp/issues/528)) ([fb9aced](https://github.com/agentclientprotocol/claude-agent-acp/commit/fb9aced3151c40694f1f01fd95665c4f5d90eb67))
+* Better remote check for auth methods ([#538](https://github.com/agentclientprotocol/claude-agent-acp/issues/538)) ([93f58c0](https://github.com/agentclientprotocol/claude-agent-acp/commit/93f58c0d2fcf7365c7ca5a6e52f56663e2065ddb))
+* better shutdown logic ([#543](https://github.com/agentclientprotocol/claude-agent-acp/issues/543)) ([9fb631f](https://github.com/agentclientprotocol/claude-agent-acp/commit/9fb631f5d76a5c5f6f0a1b61bdef05fe368c754c))
+* exit process when ACP connection closes ([#530](https://github.com/agentclientprotocol/claude-agent-acp/issues/530)) ([5c81e99](https://github.com/agentclientprotocol/claude-agent-acp/commit/5c81e99fe5ccdf774819b7ff3a2bc78a6519d730))
+* guard tool info rendering when tool_use input is undefined ([#536](https://github.com/agentclientprotocol/claude-agent-acp/issues/536)) ([d627b8c](https://github.com/agentclientprotocol/claude-agent-acp/commit/d627b8c5e95be31ac03923ef67d91748ec8564c5))
+* Remove backup auth check from new session ([#544](https://github.com/agentclientprotocol/claude-agent-acp/issues/544)) ([32b16c1](https://github.com/agentclientprotocol/claude-agent-acp/commit/32b16c1ad99394238b0e5cd6c2f761c12debe142))
+
+## [0.26.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.25.3...v0.26.0) (2026-04-08)
+
+
+### Features
+
+* Update claude-agent-sdk to 0.2.96 ([#526](https://github.com/agentclientprotocol/claude-agent-acp/issues/526)) ([c073131](https://github.com/agentclientprotocol/claude-agent-acp/commit/c07313148808a55f27f385c10babbaf7511a7f12))
+
+
+### Bug Fixes
+
+* Remove bun builds from release ([#525](https://github.com/agentclientprotocol/claude-agent-acp/issues/525)) ([fcf5aaf](https://github.com/agentclientprotocol/claude-agent-acp/commit/fcf5aaf06dfe9f7d1b285b976eeb2d1e20ea8dec))
+* Use TUI login for remote environments ([#523](https://github.com/agentclientprotocol/claude-agent-acp/issues/523)) ([cc73e37](https://github.com/agentclientprotocol/claude-agent-acp/commit/cc73e37b41678aa67813c4fbef66ba33ca538743))
+
+## [0.25.3](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.25.2...v0.25.3) (2026-04-06)
+
+
+### Bug Fixes
+
+* Drop claude-agent-sdk back to 0.2.91 to fix broken import ([#513](https://github.com/agentclientprotocol/claude-agent-acp/issues/513)) ([26f3e8a](https://github.com/agentclientprotocol/claude-agent-acp/commit/26f3e8a5216295985fadb80fb3b977045c0c1b2c))
+* Recreate resumed sessions when params change ([#515](https://github.com/agentclientprotocol/claude-agent-acp/issues/515)) ([aa82193](https://github.com/agentclientprotocol/claude-agent-acp/commit/aa82193330026bae132fed8391c47dde777dcf5a))
+
+## [0.25.2](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.25.1...v0.25.2) (2026-04-06)
+
+
+### Bug Fixes
+
+* prioritize ANTHROPIC_MODEL env var over settings.model in model … ([#505](https://github.com/agentclientprotocol/claude-agent-acp/issues/505)) ([bea1a40](https://github.com/agentclientprotocol/claude-agent-acp/commit/bea1a40e9bfe1e06672b118a727f9339def3be23))
+
+## [0.25.1](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.25.0...v0.25.1) (2026-04-06)
+
+
+### Bug Fixes
+
+* add `auto` to valid modes in applySessionMode to fix mode cycling ([#507](https://github.com/agentclientprotocol/claude-agent-acp/issues/507)) ([15e91fb](https://github.com/agentclientprotocol/claude-agent-acp/commit/15e91fb5c3449de2600b583cb7a8d36b5b510443))
+
+## [0.25.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.24.2...v0.25.0) (2026-04-03)
+
+
+### Features
+
+* Add auto permission mode support ([#501](https://github.com/agentclientprotocol/claude-agent-acp/issues/501)) ([a161453](https://github.com/agentclientprotocol/claude-agent-acp/commit/a16145396fe2e6ead8734478961b2de65707e335))
+* Add separate Claude and Console terminal logins ([#502](https://github.com/agentclientprotocol/claude-agent-acp/issues/502)) ([063cd35](https://github.com/agentclientprotocol/claude-agent-acp/commit/063cd353809df8f3dda9e57d8ea848c0a6d44257))
+* Update to claude-agent-sdk 0.2.91 ([#500](https://github.com/agentclientprotocol/claude-agent-acp/issues/500)) ([65a2230](https://github.com/agentclientprotocol/claude-agent-acp/commit/65a223038576d72b74e1483fed10e982a1f842bd))
+
+
+### Bug Fixes
+
+* log warnings for malformed settings files instead of silent fallback ([#486](https://github.com/agentclientprotocol/claude-agent-acp/issues/486)) ([ae6c388](https://github.com/agentclientprotocol/claude-agent-acp/commit/ae6c38831415f9fc1de2d3dd1d4a247becbbd32f))
+* prevent race conditions in SettingsManager setCwd and debounce ([#485](https://github.com/agentclientprotocol/claude-agent-acp/issues/485)) ([7506223](https://github.com/agentclientprotocol/claude-agent-acp/commit/7506223cffb1aba4b4560feda11f69a1395a8c9d))
+* use current model's context window for usage_update size ([#412](https://github.com/agentclientprotocol/claude-agent-acp/issues/412)) ([d07799d](https://github.com/agentclientprotocol/claude-agent-acp/commit/d07799d7b3b4e438c8b158266c79723a0b592c07))
+
+## [0.24.2](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.24.1...v0.24.2) (2026-03-27)
+
+
+### Bug Fixes
+
+* Add explicit type checks for MCP servers (http/sse) ([#487](https://github.com/agentclientprotocol/claude-agent-acp/issues/487)) ([e00a439](https://github.com/agentclientprotocol/claude-agent-acp/commit/e00a43901fa2b4fd7d582e1de57277be88233007))
+
+## [0.24.1](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.24.0...v0.24.1) (2026-03-26)
+
+
+### Bug Fixes
+
+* Cleanup based on new idle state [#463](https://github.com/agentclientprotocol/claude-agent-acp/issues/463) ([#480](https://github.com/agentclientprotocol/claude-agent-acp/issues/480)) ([23b3073](https://github.com/agentclientprotocol/claude-agent-acp/commit/23b30730253752f0bc4e30b619a6236f16fafdb9))
+
+## 0.24.0
+
+Rename from `@zed-industries/claude-agent-acp` to `@agentclientprotocol/claude-agent-acp`.
+
+We are moving this to the main ACP org to better allow multiple teams to contribute and maintain this adapter.
+
+## 0.23.1
+
+- Add back error_during_execution break point (#469)
+
+## 0.23.0
+
+- Use idle session state as end of turn (#463)
+- Update claude-agent-sdk to 0.2.83 (#462)
+- Fix handling of local-only slash commands (#432)
+- fix: correct null check for gatewayAuthMeta in subscription validation (#455)
+- fix: include both stdout and stderr in Bash tool output (#456)
+- fix: prevent prompt loop hang when cancel races with first result (#458)
+- fix: dispose SettingsManager on session close to prevent resource leaks (#454)
+- fix: restore plan content in ExitPlanMode tool call (#451)
+
+## 0.22.2
+
+- Add experimental meta param for testing additional directories
+
+## 0.22.1
+
+- Fix: invalid auth required state in gateway mode
+
+## 0.22.0
+
+- Use stable list sessions method (#429)
+- Use correct Claude CLI path for static binaries (#428)
+- Update claude-agent-sdk to 0.2.76 (#427)
+- fix: resolve model aliases in setSessionConfigOption (#401) (#403)
+- Reuse existing sessions for load/resume if possible (#426)
+- Remove interrupt flag from deny responses (#425)
+- Allow Bypass permissions mode after Exiting plan (#410)
+- Don't get out of sync when background task creates new init/result (try 2) (#400)
+- Add session/close support (#409)
+
+## 0.21.0
+
+- Update to claude-agent-sdk 0.2.71
+- show project-relative paths in tool call titles
+- Lib: pass through tools array to control built-in tool availability
+- fix: skip user replay
+- fix: handle renamed Agent tool in toolInfoFromToolUse
+
+## 0.20.2
+
+- Update to @anthropic-ai/claude-agent-sdk@0.2.68
+
+## 0.20.1
+
+- fix: inherit process.env when spawning agent subprocess
+
+## 0.20.0
+
+- Update to @anthropic-ai/claude-agent-sdk@0.2.63
+- Respect user settings for permission mode and model selection
+- Better handling of concurrent prompts
+- Support --cli for node as well
+- Propagate max_tokens stop reason instead of throwing internal error
+- fix: throw resourceNotFound when loadSession fails to resume
+- fix: add missing zod dependency
+- Surface better error message when Claude Code process exits unexpectedly
+
+## 0.19.2
+
+- Fix for broken notifications when reloading session messages
+
+## 0.19.1
+
+- Support windows arm builds and clean up artifact files
+
+## 0.19.0
+
+- Update to @anthropic-ai/claude-agent-sdk@0.2.62
+- Use SDK functions for listing and loading session history
+- Build single-file executables using bun.
+- Fix for overwritten disallowed tools.
+
 ## 0.18.0
 
 - Switch over to built-in Claude tools. We no longer replicate specific ACP tools and just rely on sending updates based on Claude's internal tools. This means it won't use client capabilities for files or terminals, but also means there will be less difference and hopefully issues arising from the differences in behavior.

LICENSE

@@ -1,42 +1,18 @@
-Copyright 2022 - 2025 Zed Industries, Inc.
 
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
-
-
-
-
-Apache License
+                                 Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
 
-
    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
-
    1. Definitions.
 
-
       "License" shall mean the terms and conditions for use, reproduction,
       and distribution as defined by Sections 1 through 9 of this document.
 
-
       "Licensor" shall mean the copyright owner or entity authorized by
       the copyright owner that is granting the License.
 
-
       "Legal Entity" shall mean the union of the acting entity and all
       other entities that control, are controlled by, or are under common
       control with that entity. For the purposes of this definition,
@@ -45,28 +21,23 @@ Apache License
       otherwise, or (ii) ownership of fifty percent (50%) or more of the
       outstanding shares, or (iii) beneficial ownership of such entity.
 
-
       "You" (or "Your") shall mean an individual or Legal Entity
       exercising permissions granted by this License.
 
-
       "Source" form shall mean the preferred form for making modifications,
       including but not limited to software source code, documentation
       source, and configuration files.
 
-
       "Object" form shall mean any form resulting from mechanical
       transformation or translation of a Source form, including but
       not limited to compiled object code, generated documentation,
       and conversions to other media types.
 
-
       "Work" shall mean the work of authorship, whether in Source or
       Object form, made available under the License, as indicated by a
       copyright notice that is included in or attached to the work
       (an example is provided in the Appendix below).
 
-
       "Derivative Works" shall mean any work, whether in Source or Object
       form, that is based on (or derived from) the Work and for which the
       editorial revisions, annotations, elaborations, or other modifications
@@ -75,7 +46,6 @@ Apache License
       separable from, or merely link (or bind by name) to the interfaces of,
       the Work and Derivative Works thereof.
 
-
       "Contribution" shall mean any work of authorship, including
       the original version of the Work and any modifications or additions
       to that Work or Derivative Works thereof, that is intentionally
@@ -90,12 +60,10 @@ Apache License
       excluding communication that is conspicuously marked or otherwise
       designated in writing by the copyright owner as "Not a Contribution."
 
-
       "Contributor" shall mean Licensor and any individual or Legal Entity
       on behalf of whom a Contribution has been received by Licensor and
       subsequently incorporated within the Work.
 
-
    2. Grant of Copyright License. Subject to the terms and conditions of
       this License, each Contributor hereby grants to You a perpetual,
       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
@@ -103,7 +71,6 @@ Apache License
       publicly display, publicly perform, sublicense, and distribute the
       Work and such Derivative Works in Source or Object form.
 
-
    3. Grant of Patent License. Subject to the terms and conditions of
       this License, each Contributor hereby grants to You a perpetual,
       worldwide, non-exclusive, no-charge, royalty-free, irrevocable
@@ -120,28 +87,23 @@ Apache License
       granted to You under this License for that Work shall terminate
       as of the date such litigation is filed.
 
-
    4. Redistribution. You may reproduce and distribute copies of the
       Work or Derivative Works thereof in any medium, with or without
       modifications, and in Source or Object form, provided that You
       meet the following conditions:
 
-
       (a) You must give any other recipients of the Work or
           Derivative Works a copy of this License; and
 
-
       (b) You must cause any modified files to carry prominent notices
           stating that You changed the files; and
 
-
       (c) You must retain, in the Source form of any Derivative Works
           that You distribute, all copyright, patent, trademark, and
           attribution notices from the Source form of the Work,
           excluding those notices that do not pertain to any part of
           the Derivative Works; and
 
-
       (d) If the Work includes a "NOTICE" text file as part of its
           distribution, then any Derivative Works that You distribute must
           include a readable copy of the attribution notices contained
@@ -159,7 +121,6 @@ Apache License
           that such additional attribution notices cannot be construed
           as modifying the License.
 
-
       You may add Your own copyright statement to Your modifications and
       may provide additional or different license terms and conditions
       for use, reproduction, or distribution of Your modifications, or
@@ -167,7 +128,6 @@ Apache License
       reproduction, and distribution of the Work otherwise complies with
       the conditions stated in this License.
 
-
    5. Submission of Contributions. Unless You explicitly state otherwise,
       any Contribution intentionally submitted for inclusion in the Work
       by You to the Licensor shall be under the terms and conditions of
@@ -176,13 +136,11 @@ Apache License
       the terms of any separate license agreement you may have executed
       with Licensor regarding such Contributions.
 
-
    6. Trademarks. This License does not grant permission to use the trade
       names, trademarks, service marks, or product names of the Licensor,
       except as required for reasonable and customary use in describing the
       origin of the Work and reproducing the content of the NOTICE file.
 
-
    7. Disclaimer of Warranty. Unless required by applicable law or
       agreed to in writing, Licensor provides the Work (and each
       Contributor provides its Contributions) on an "AS IS" BASIS,
@@ -193,7 +151,6 @@ Apache License
       appropriateness of using or redistributing the Work and assume any
       risks associated with Your exercise of permissions under this License.
 
-
    8. Limitation of Liability. In no event and under no legal theory,
       whether in tort (including negligence), contract, or otherwise,
       unless required by applicable law (such as deliberate and grossly
@@ -206,7 +163,6 @@ Apache License
       other commercial damages or losses), even if such Contributor
       has been advised of the possibility of such damages.
 
-
    9. Accepting Warranty or Additional Liability. While redistributing
       the Work or Derivative Works thereof, You may choose to offer,
       and charge a fee for, acceptance of support, warranty, indemnity,
@@ -218,5 +174,18 @@ Apache License
       incurred by, or claims asserted against, such Contributor by reason
       of your accepting any such warranty or additional liability.
 
-
    END OF TERMS AND CONDITIONS
+
+   Copyright 2025 Zed Industries, Inc. and contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -1,8 +1,8 @@
 # ACP adapter for the Claude Agent SDK
 
-[![npm](https://img.shields.io/npm/v/%40zed-industries%2Fclaude-agent-acp)](https://www.npmjs.com/package/@zed-industries/claude-agent-acp)
+[![npm](https://img.shields.io/npm/v/%40agentclientprotocol%2Fclaude-agent-acp)](https://www.npmjs.com/package/@agentclientprotocol/claude-agent-acp)
 
-Use [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview#branding-guidelines) from [ACP-compatible](https://agentclientprotocol.com) clients such as [Zed](https://zed.dev)!
+Use [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview#branding-guidelines) from [ACP-compatible](https://agentclientprotocol.com) clients!
 
 This tool implements an ACP agent by using the official [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview), supporting:
 
@@ -18,36 +18,8 @@ This tool implements an ACP agent by using the official [Claude Agent SDK](https
 
 Learn more about the [Agent Client Protocol](https://agentclientprotocol.com/).
 
-## How to use
+## Contribution Policy
 
-### Zed
+This project does not require a Contributor License Agreement (CLA). Instead, contributions are accepted under the following terms:
 
-The latest version of Zed can already use this adapter out of the box.
-
-To use Claude Agent, open the Agent Panel and click "New Claude Agent Thread" from the `+` button menu in the top-right:
-
-https://github.com/user-attachments/assets/ddce66c7-79ac-47a3-ad59-4a6a3ca74903
-
-Read the docs on [External Agent](https://zed.dev/docs/ai/external-agents) support.
-
-### Other clients
-
-Or try it with any of the other [ACP compatible clients](https://agentclientprotocol.com/overview/clients)!
-
-#### Installation
-
-Install the adapter from `npm`:
-
-```bash
-npm install -g @zed-industries/claude-agent-acp
-```
-
-You can then use `claude-agent-acp` as a regular ACP agent:
-
-```
-ANTHROPIC_API_KEY=sk-... claude-agent-acp
-```
-
-## License
-
-Apache-2.0
+> By contributing to this project, you agree that your contributions will be licensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0). You affirm that you have the legal right to submit your work, that you are not including code you do not have rights to, and that you understand contributions are made without requiring a Contributor License Agreement (CLA).

docs/model-configuration.md

@@ -0,0 +1,56 @@
+# Model Configuration
+
+When using claude-agent-acp with alternative providers (e.g. AWS Bedrock), model IDs differ from the direct Anthropic API. The `CLAUDE_MODEL_CONFIG` environment variable lets you configure model overrides and availability at the deployment level.
+
+## `CLAUDE_MODEL_CONFIG`
+
+A JSON string with two optional fields:
+
+| Field             | Type                     | Description                                                                                                   |
+| ----------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `modelOverrides`  | `Record<string, string>` | Maps Anthropic model IDs to provider-specific model IDs (e.g. Bedrock model IDs or ARNs)                      |
+| `availableModels` | `string[]`               | Restricts which models are offered to users. Accepts aliases (`"opus"`), prefixes (`"opus-4-5"`), or full IDs |
+
+### Examples
+
+**Bedrock model overrides:**
+
+```bash
+CLAUDE_MODEL_CONFIG='{"modelOverrides":{"claude-opus-4-6":"us.anthropic.claude-opus-4-6-v1","claude-sonnet-4-5":"us.anthropic.claude-sonnet-4-5-v1"}}'
+```
+
+**Restrict available models:**
+
+```bash
+CLAUDE_MODEL_CONFIG='{"availableModels":["opus","sonnet"]}'
+```
+
+**Both together:**
+
+```bash
+CLAUDE_MODEL_CONFIG='{"modelOverrides":{"claude-opus-4-6":"us.anthropic.claude-opus-4-6-v1","claude-sonnet-4-5":"us.anthropic.claude-sonnet-4-5-v1"},"availableModels":["opus","sonnet"]}'
+```
+
+**Full Bedrock example:**
+
+```bash
+CLAUDE_CODE_USE_BEDROCK=1 \
+AWS_REGION=us-west-2 \
+CLAUDE_MODEL_CONFIG='{"modelOverrides":{"claude-opus-4-6":"us.anthropic.claude-opus-4-6-v1"}}' \
+node dist/index.js
+```
+
+## Precedence
+
+When an ACP caller provides `settings` via `_meta.claudeCode.options.settings` in the `sessions/create` request, `CLAUDE_MODEL_CONFIG` is ignored entirely. The env var is a deployment-level fallback for cases where the caller does not configure model settings itself.
+
+| Source                                       | Priority                                              |
+| -------------------------------------------- | ----------------------------------------------------- |
+| `_meta.claudeCode.options.settings` (caller) | Highest — used if present                             |
+| `CLAUDE_MODEL_CONFIG` (env var)              | Fallback — used only when caller provides no settings |
+
+## Format details
+
+- The value must be valid JSON. Invalid JSON will cause session creation to fail with a parse error.
+- Only `modelOverrides` and `availableModels` keys are read; other keys in the JSON are ignored.
+- Both fields map directly to the Claude Agent SDK's `Settings` type.

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

@@ -1,9 +1,9 @@
 {
-  "name": "@zed-industries/claude-agent-acp",
+  "name": "@agentclientprotocol/claude-agent-acp",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.18.0",
+  "version": "0.51.0",
   "description": "An ACP-compatible coding agent powered by the Claude Agent SDK (TypeScript)",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
@@ -49,32 +49,37 @@
     "sdk",
     "code"
   ],
-  "homepage": "https://github.com/zed-industries/claude-agent-acp#readme",
+  "homepage": "https://github.com/agentclientprotocol/claude-agent-acp#readme",
   "bugs": {
-    "url": "https://github.com/zed-industries/claude-agent-acp/issues"
+    "url": "https://github.com/agentclientprotocol/claude-agent-acp/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/zed-industries/claude-agent-acp.git"
+    "url": "git+https://github.com/agentclientprotocol/claude-agent-acp.git"
   },
   "author": "Zed Industries",
   "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22"
+  },
   "dependencies": {
-    "@agentclientprotocol/sdk": "0.14.1",
-    "@anthropic-ai/claude-agent-sdk": "0.2.45"
+    "@agentclientprotocol/sdk": "1.0.0",
+    "@anthropic-ai/claude-agent-sdk": "0.3.191",
+    "zod": "^3.25.0 || ^4.0.0"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "0.76.0",
+    "@anthropic-ai/sdk": "0.106.0",
     "@eslint/js": "10.0.1",
-    "@types/node": "25.2.3",
-    "@typescript-eslint/eslint-plugin": "8.56.0",
-    "@typescript-eslint/parser": "8.56.0",
-    "eslint": "10.0.0",
+    "@tsconfig/node22": "22.0.5",
+    "@types/node": "26.0.1",
+    "@typescript-eslint/eslint-plugin": "8.62.0",
+    "@typescript-eslint/parser": "8.62.0",
+    "eslint": "10.5.0",
     "eslint-config-prettier": "10.1.8",
-    "globals": "17.3.0",
-    "prettier": "3.8.1",
+    "globals": "17.7.0",
+    "prettier": "3.8.4",
     "ts-node": "10.9.2",
-    "typescript": "5.9.3",
-    "vitest": "4.0.18"
+    "typescript": "6.0.3",
+    "vitest": "4.1.9"
   }
 }

release-please-config.json

@@ -0,0 +1,13 @@
+{
+  "bump-minor-pre-major": true,
+  "bump-patch-for-minor-pre-major": true,
+  "packages": {
+    ".": {
+      "changelog-path": "CHANGELOG.md",
+      "release-type": "node",
+      "bump-minor-pre-major": true,
+      "bump-patch-for-minor-pre-major": true
+    }
+  },
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json"
+}

src/elicitation.ts

@@ -0,0 +1,301 @@
+import { randomUUID } from "node:crypto";
+import type {
+  CreateElicitationRequest,
+  CreateElicitationResponse,
+  ElicitationPropertySchema,
+  ElicitationSchema,
+  EnumOption,
+} from "@agentclientprotocol/sdk";
+import type { ElicitationRequest, ElicitationResult } from "@anthropic-ai/claude-agent-sdk";
+import type {
+  AskUserQuestionInput,
+  AskUserQuestionOutput,
+} from "@anthropic-ai/claude-agent-sdk/sdk-tools.js";
+
+/**
+ * Bridges between the Claude Agent SDK's elicitation/dialog callbacks and ACP's
+ * (unstable) elicitation protocol.
+ *
+ * Two distinct SDK surfaces flow through here:
+ *
+ *   1. `onElicitation` — fired when an MCP server requests user input. These map
+ *      directly onto ACP `session/create_elicitation` (form or url mode).
+ *   2. The built-in AskUserQuestion tool — when a `canUseTool` callback is
+ *      registered the SDK routes its permission check through `canUseTool`
+ *      (not the interactive `permission_ask_user_question` dialog). We render
+ *      its questions as an ACP form elicitation and feed the user's selections
+ *      back as the tool's `updatedInput`, which the tool's own `call()` reads.
+ */
+
+/** Modes the connected client advertised support for. */
+export type ElicitationSupport = {
+  form: boolean;
+  url: boolean;
+};
+
+/**
+ * Convert an MCP elicitation request (from the SDK's `onElicitation` callback)
+ * into an ACP `CreateElicitationRequest`. Returns `null` when the request can't
+ * be represented (e.g. a url-mode request with no url).
+ */
+export function mcpElicitationToCreateRequest(
+  request: ElicitationRequest,
+  sessionId: string,
+): CreateElicitationRequest | null {
+  if (request.mode === "url") {
+    if (!request.url) {
+      return null;
+    }
+    return {
+      mode: "url",
+      sessionId,
+      message: request.message,
+      url: request.url,
+      // URL elicitations need a stable id so the client can correlate the
+      // later `session/complete_elicitation` notification. MCP servers usually
+      // provide one; fall back to a generated id if not.
+      elicitationId: request.elicitationId ?? randomUUID(),
+    };
+  }
+
+  // Form mode (the default). The MCP `requestedSchema` is already a JSON Schema
+  // with primitive-typed properties, which is structurally what ACP expects.
+  return {
+    mode: "form",
+    sessionId,
+    message: request.message,
+    requestedSchema: normalizeElicitationSchema(request.requestedSchema),
+  };
+}
+
+/**
+ * Map an ACP elicitation response back to the MCP `ElicitResult` the SDK expects
+ * to hand back to the requesting server.
+ */
+export function createElicitationResponseToElicitResult(
+  response: CreateElicitationResponse,
+): ElicitationResult {
+  switch (response.action) {
+    case "accept":
+      return { action: "accept", content: response.content ?? {} };
+    case "decline":
+      return { action: "decline" };
+    case "cancel":
+    default:
+      return { action: "cancel" };
+  }
+}
+
+/**
+ * A single question as supplied by the AskUserQuestion tool. Derived from the
+ * SDK's input type so the shape stays in sync; the SDK validates the model's
+ * tool call against this schema before it reaches us.
+ */
+export type AskUserQuestion = AskUserQuestionInput["questions"][number];
+
+/**
+ * Pull the well-formed questions out of an AskUserQuestion tool input. Returns
+ * `null` when there are no usable questions — including the case where every
+ * entry is malformed and filtering leaves an empty list — so callers can treat
+ * "nothing to ask" uniformly.
+ */
+export function extractAskUserQuestions(input: Record<string, unknown>): AskUserQuestion[] | null {
+  const questions = (input as { questions?: unknown }).questions;
+  if (!Array.isArray(questions)) {
+    return null;
+  }
+  const valid = questions.filter(
+    (q): q is AskUserQuestion =>
+      !!q && typeof q.question === "string" && Array.isArray(q.options) && q.options.length > 0,
+  );
+  return valid.length > 0 ? valid : null;
+}
+
+/** Stable form-field key for the question at the given index. */
+function questionFieldKey(index: number): string {
+  return `question_${index}`;
+}
+
+/**
+ * Form-field key for the per-question free-text "custom answer" field that sits
+ * alongside `question_<n>`. Mirrors the first-party clients, where every
+ * question carries its own "Other" box rather than one form-level field.
+ */
+function questionCustomFieldKey(index: number): string {
+  return `question_${index}_custom`;
+}
+
+/**
+ * `_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/...`).
+ */
+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.
+ *
+ * Fields are keyed by a short stable id (`question_<n>`) rather than the full
+ * 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.
+ *
+ * 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
+ * user can type their own answer instead of picking an option, scoped to that
+ * specific question. Nothing is marked required, so the user can also just skip
+ * — matching the built-in tool, which always offers Skip + a free-text box.
+ */
+export function askUserQuestionsToCreateRequest(
+  questions: AskUserQuestion[],
+  sessionId: string,
+  toolCallId: string | undefined,
+): CreateElicitationRequest {
+  const single = questions.length === 1;
+  const properties: Record<string, ElicitationPropertySchema> = {};
+
+  questions.forEach((question, index) => {
+    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,
+      };
+      // 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;
+      }
+      return enumOption;
+    });
+
+    // For a single question the prompt is carried by `message`, so we don't
+    // repeat it in the field description. With multiple questions each field
+    // needs its own question text.
+    const description = single ? undefined : question.question;
+    const title = question.header || undefined;
+
+    properties[questionFieldKey(index)] = question.multiSelect
+      ? { type: "array", title, description, items: { anyOf: options } }
+      : { type: "string", title, description, oneOf: options };
+
+    properties[questionCustomFieldKey(index)] = {
+      type: "string",
+      title: "Other",
+      description: "Type your own answer instead of choosing an option above (optional).",
+    };
+  });
+
+  const requestedSchema: ElicitationSchema = {
+    type: "object",
+    properties,
+  };
+
+  const message = single ? questions[0].question : "Please answer the following questions.";
+
+  return {
+    mode: "form",
+    sessionId,
+    ...(toolCallId ? { toolCallId } : {}),
+    message,
+    requestedSchema,
+  };
+}
+
+/** Outcome of an AskUserQuestion elicitation, decoupled from any transport. */
+export type AskUserQuestionOutcome =
+  | { action: "answered"; updatedInput: Record<string, unknown> }
+  | { action: "cancel" };
+
+/**
+ * Fold an ACP elicitation response into the AskUserQuestion tool's input.
+ *
+ * Selected labels are read back from the indexed form fields and written into
+ * `answers` as a `{ [questionText]: label }` map (comma-joining multi-selects)
+ * — the key shape the tool's own `call()` reads. A non-empty per-question
+ * 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.
+ */
+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 ?? {};
+  // 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"] = {};
+  questions.forEach((question, index) => {
+    // A typed custom answer wins over the selection: the user chose to write
+    // their own answer for this question instead of picking an option.
+    const custom = content[questionCustomFieldKey(index)];
+    if (typeof custom === "string" && custom.trim() !== "") {
+      answers[question.question] = custom.trim();
+      return;
+    }
+
+    const value = content[questionFieldKey(index)];
+    if (value === undefined || value === null) {
+      return;
+    }
+    const text = Array.isArray(value) ? value.join(", ") : String(value);
+    if (text === "") {
+      return;
+    }
+    answers[question.question] = text;
+  });
+
+  return { action: "answered", updatedInput: { ...toolInput, answers } };
+}
+
+/**
+ * Coerce an arbitrary MCP `requestedSchema` into an ACP `ElicitationSchema`.
+ * The two are structurally compatible JSON Schemas; we just guarantee the
+ * `type: "object"` discriminator is present.
+ */
+function normalizeElicitationSchema(
+  schema: Record<string, unknown> | undefined,
+): ElicitationSchema {
+  if (!schema || typeof schema !== "object") {
+    return { type: "object", properties: {} };
+  }
+  return { ...(schema as ElicitationSchema), type: "object" };
+}

src/index.ts

@@ -1,26 +1,80 @@
 #!/usr/bin/env node
 
-// Load managed settings and apply environment variables
-import { loadManagedSettings, applyEnvironmentSettings } from "./utils.js";
+import { resolveSettings } from "@anthropic-ai/claude-agent-sdk";
+import { claudeCliPath, runAcp } from "./acp-agent.js";
+import packageJson from "../package.json" with { type: "json" };
 
-const managedSettings = loadManagedSettings();
-if (managedSettings) {
-  applyEnvironmentSettings(managedSettings);
+if (process.argv.includes("--version") || process.argv.includes("-v")) {
+  console.log(packageJson.version);
+  process.exit(0);
+} else if (process.argv.includes("--cli")) {
+  const { spawn } = await import("node:child_process");
+  const args = process.argv.slice(2).filter((arg) => arg !== "--cli");
+  const child = spawn(await claudeCliPath(), args, { stdio: "inherit" });
+
+  const signals =
+    process.platform === "win32"
+      ? (["SIGINT", "SIGTERM"] as const)
+      : (["SIGINT", "SIGTERM", "SIGHUP"] as const);
+  for (const sig of signals) {
+    process.on(sig, () => {
+      if (!child.killed) child.kill(sig);
+    });
+  }
+
+  child.on("exit", (code, signal) => {
+    if (signal && process.platform !== "win32") {
+      // Remove our listener so re-raising actually terminates instead of
+      // re-entering the no-op handler, which would let us exit with code 0
+      // instead of the signal's conventional 128+N.
+      process.removeAllListeners(signal);
+      process.kill(process.pid, signal);
+    } else {
+      process.exit(code ?? 1);
+    }
+  });
+  child.on("error", (err) => {
+    console.error(err);
+    process.exit(1);
+  });
+} 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
+  // read of managed-settings.json) also picks up MDM sources on macOS and
+  // HKLM/HKCU on Windows.
+  const policy = await resolveSettings({ settingSources: [] });
+  for (const [key, value] of Object.entries(policy.effective.env ?? {})) {
+    process.env[key] = value;
+  }
+
+  // stdout is used to send messages to the client
+  // we redirect everything else to stderr to make sure it doesn't interfere with ACP
+  console.log = console.error;
+  console.info = console.error;
+  console.warn = console.error;
+  console.debug = console.error;
+
+  process.on("unhandledRejection", (reason, promise) => {
+    console.error("Unhandled Rejection at:", promise, "reason:", reason);
+  });
+
+  const { connection, agent } = runAcp();
+
+  async function shutdown() {
+    await agent.dispose().catch((err) => {
+      console.error("Error during cleanup:", err);
+    });
+    process.exit(0);
+  }
+
+  // Exit cleanly when the ACP connection closes (e.g. stdin EOF, transport
+  // error). Without this, `process.stdin.resume()` keeps the event loop
+  // alive indefinitely, causing orphan process accumulation in oneshot mode.
+  connection.closed.then(shutdown);
+
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+
+  // Keep process alive while connection is open
+  process.stdin.resume();
 }
-
-// stdout is used to send messages to the client
-// we redirect everything else to stderr to make sure it doesn't interfere with ACP
-console.log = console.error;
-console.info = console.error;
-console.warn = console.error;
-console.debug = console.error;
-
-process.on("unhandledRejection", (reason, promise) => {
-  console.error("Unhandled Rejection at:", promise, "reason:", reason);
-});
-
-import { runAcp } from "./acp-agent.js";
-runAcp();
-
-// Keep process alive
-process.stdin.resume();

src/lib.ts

@@ -1,26 +1,23 @@
 // Export the main agent class and utilities for library usage
 export {
   ClaudeAcpAgent,
+  isLocalCommandMetadata,
+  stripLocalCommandMetadata,
   runAcp,
   toAcpNotifications,
   streamEventToAcpNotifications,
   type ToolUpdateMeta,
   type NewSessionMeta,
+  type SDKMessageFilter,
 } from "./acp-agent.js";
+export { nodeToWebReadable, nodeToWebWritable, Pushable, unreachable } from "./utils.js";
 export {
-  loadManagedSettings,
-  applyEnvironmentSettings,
-  nodeToWebReadable,
-  nodeToWebWritable,
-  Pushable,
-  unreachable,
-} from "./utils.js";
-export { toolInfoFromToolUse, planEntries, toolUpdateFromToolResult } from "./tools.js";
-export {
-  SettingsManager,
-  type ClaudeCodeSettings,
-  type SettingsManagerOptions,
-} from "./settings.js";
+  toolInfoFromToolUse,
+  toDisplayPath,
+  planEntries,
+  toolUpdateFromToolResult,
+} from "./tools.js";
+export { SettingsManager, type SettingsManagerOptions } from "./settings.js";
 
 // Export types
 export type { ClaudePlanEntry } from "./tools.js";

src/settings.ts

@@ -1,5 +1,12 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+// resolveSettings and filterEscalatingDefaultMode are marked @alpha in the
+// SDK; API may shift in a future release.
+import {
+  filterEscalatingDefaultMode,
+  resolveSettings,
+  type Settings,
+} from "@anthropic-ai/claude-agent-sdk";
 import { CLAUDE_CONFIG_DIR } from "./acp-agent.js";
 
 /**
@@ -14,36 +21,10 @@ import { CLAUDE_CONFIG_DIR } from "./acp-agent.js";
  * Docs: https://code.claude.com/docs/en/iam#tool-specific-permission-rules
  */
 
-export interface ClaudeCodeSettings {
-  env?: Record<string, string>;
-  model?: string;
-}
-
-/**
- * Reads and parses a JSON settings file, returning an empty object if not found or invalid
- */
-async function loadSettingsFile(filePath: string | null): Promise<ClaudeCodeSettings> {
-  if (!filePath) {
-    return {};
-  }
-
-  try {
-    const content = await fs.promises.readFile(filePath, "utf-8");
-    return JSON.parse(content) as ClaudeCodeSettings;
-  } catch {
-    return {};
-  }
-}
-
-/**
- * Gets the enterprise settings path based on the current platform
- */
-export function getManagedSettingsPath(): string {
+function getManagedSettingsPath(): string {
   switch (process.platform) {
     case "darwin":
       return "/Library/Application Support/ClaudeCode/managed-settings.json";
-    case "linux":
-      return "/etc/claude-code/managed-settings.json";
     case "win32":
       return "C:\\Program Files\\ClaudeCode\\managed-settings.json";
     default:
@@ -57,28 +38,24 @@ export interface SettingsManagerOptions {
 }
 
 /**
- * Manages Claude Code settings from multiple sources with proper precedence.
+ * Manages Claude Code settings using the SDK's `resolveSettings` merge engine
+ * so the values we see match what `query()` would observe.
  *
- * Settings are loaded from (in order of increasing precedence):
- * 1. User settings (~/.claude/settings.json)
- * 2. Project settings (<cwd>/.claude/settings.json)
- * 3. Local project settings (<cwd>/.claude/settings.local.json)
- * 4. Enterprise managed settings (platform-specific path)
- *
- * The manager watches all settings files for changes and automatically reloads.
+ * Watches the user/project/local/managed settings files for changes and
+ * re-resolves through the SDK on update. Escalating `permissions.defaultMode`
+ * values from repo-committed sources are filtered out via
+ * `filterEscalatingDefaultMode`, matching the CLI's trust policy.
  */
 export class SettingsManager {
   private cwd: string;
-  private userSettings: ClaudeCodeSettings = {};
-  private projectSettings: ClaudeCodeSettings = {};
-  private localSettings: ClaudeCodeSettings = {};
-  private enterpriseSettings: ClaudeCodeSettings = {};
-  private mergedSettings: ClaudeCodeSettings = {};
+  private effective: Settings = {};
   private watchers: fs.FSWatcher[] = [];
   private onChange?: () => void;
   private logger: { log: (...args: any[]) => void; error: (...args: any[]) => void };
   private initialized = false;
+  private disposed = false;
   private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private initPromise: Promise<void> | null = null;
 
   constructor(cwd: string, options?: SettingsManagerOptions) {
     this.cwd = cwd;
@@ -93,94 +70,53 @@ export class SettingsManager {
     if (this.initialized) {
       return;
     }
-
-    await this.loadAllSettings();
-    this.setupWatchers();
-    this.initialized = true;
-  }
-
-  /**
-   * Returns the path to the user settings file
-   */
-  private getUserSettingsPath(): string {
-    return path.join(CLAUDE_CONFIG_DIR, "settings.json");
-  }
-
-  /**
-   * Returns the path to the project settings file
-   */
-  private getProjectSettingsPath(): string {
-    return path.join(this.cwd, ".claude", "settings.json");
-  }
-
-  /**
-   * Returns the path to the local project settings file
-   */
-  private getLocalSettingsPath(): string {
-    return path.join(this.cwd, ".claude", "settings.local.json");
-  }
-
-  /**
-   * Loads settings from all sources
-   */
-  private async loadAllSettings(): Promise<void> {
-    const [userSettings, projectSettings, localSettings, enterpriseSettings] = await Promise.all([
-      loadSettingsFile(this.getUserSettingsPath()),
-      loadSettingsFile(this.getProjectSettingsPath()),
-      loadSettingsFile(this.getLocalSettingsPath()),
-      loadSettingsFile(getManagedSettingsPath()),
-    ]);
-
-    this.userSettings = userSettings;
-    this.projectSettings = projectSettings;
-    this.localSettings = localSettings;
-    this.enterpriseSettings = enterpriseSettings;
-
-    this.mergeSettings();
-  }
-
-  /**
-   * Merges all settings sources with proper precedence.
-   * For permissions, rules from all sources are combined.
-   * Deny rules always take precedence during permission checks.
-   */
-  private mergeSettings(): void {
-    const allSettings = [
-      this.userSettings,
-      this.projectSettings,
-      this.localSettings,
-      this.enterpriseSettings,
-    ];
-
-    const merged: ClaudeCodeSettings = {};
-
-    for (const settings of allSettings) {
-      if (settings.env) {
-        merged.env = { ...merged.env, ...settings.env };
-      }
-
-      if (settings.model) {
-        merged.model = settings.model;
-      }
+    if (this.initPromise) {
+      return this.initPromise;
     }
 
-    this.mergedSettings = merged;
+    this.disposed = false;
+    this.initPromise = this.loadAllSettings().then(() => {
+      if (!this.disposed) {
+        this.setupWatchers();
+        this.initialized = true;
+      }
+      this.initPromise = null;
+    });
+    return this.initPromise;
+  }
+
+  /**
+   * Paths the SDK reads when resolving settings for this cwd. Watching the
+   * containing directories means we pick up file creation as well as edits.
+   */
+  private getWatchedPaths(): string[] {
+    return [
+      path.join(CLAUDE_CONFIG_DIR, "settings.json"),
+      path.join(this.cwd, ".claude", "settings.json"),
+      path.join(this.cwd, ".claude", "settings.local.json"),
+      getManagedSettingsPath(),
+    ];
+  }
+
+  /**
+   * Resolves the effective settings via the SDK and applies the CLI's trust
+   * filter for escalating `permissions.defaultMode` values.
+   */
+  private async loadAllSettings(): Promise<void> {
+    try {
+      const resolved = await resolveSettings({ cwd: this.cwd });
+      this.effective = filterEscalatingDefaultMode(resolved);
+    } catch (error) {
+      this.logger.error("Failed to resolve settings:", error);
+      this.effective = {};
+    }
   }
 
   /**
    * Sets up file watchers for all settings files
    */
   private setupWatchers(): void {
-    const paths = [
-      this.getUserSettingsPath(),
-      this.getProjectSettingsPath(),
-      this.getLocalSettingsPath(),
-      getManagedSettingsPath(),
-    ];
-
-    for (const filePath of paths) {
-      if (!filePath) continue;
-
+    for (const filePath of this.getWatchedPaths()) {
       try {
         const dir = path.dirname(filePath);
         const filename = path.basename(filePath);
@@ -214,9 +150,14 @@ export class SettingsManager {
 
     this.debounceTimer = setTimeout(async () => {
       this.debounceTimer = null;
+      if (this.disposed) {
+        return;
+      }
       try {
         await this.loadAllSettings();
-        this.onChange?.();
+        if (!this.disposed) {
+          this.onChange?.();
+        }
       } catch (error) {
         this.logger.error("Failed to reload settings:", error);
       }
@@ -226,8 +167,8 @@ export class SettingsManager {
   /**
    * Returns the current merged settings
    */
-  getSettings(): ClaudeCodeSettings {
-    return this.mergedSettings;
+  getSettings(): Settings {
+    return this.effective;
   }
 
   /**
@@ -247,7 +188,6 @@ export class SettingsManager {
 
     this.dispose();
     this.cwd = cwd;
-    this.initialized = false;
     await this.initialize();
   }
 
@@ -255,6 +195,10 @@ export class SettingsManager {
    * Disposes of file watchers and cleans up resources
    */
   dispose(): void {
+    this.disposed = true;
+    this.initialized = false;
+    this.initPromise = null;
+
     if (this.debounceTimer) {
       clearTimeout(this.debounceTimer);
       this.debounceTimer = null;
@@ -264,6 +208,5 @@ export class SettingsManager {
       watcher.close();
     }
     this.watchers = [];
-    this.initialized = false;
   }
 }

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

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

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

@@ -0,0 +1,957 @@
+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 { AcpClient, ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
+
+const { querySpy } = vi.hoisted(() => ({
+  querySpy: vi.fn(),
+}));
+
+vi.mock("@anthropic-ai/claude-agent-sdk", async () => {
+  const actual = await vi.importActual<any>("@anthropic-ai/claude-agent-sdk");
+  return {
+    ...actual,
+    query: querySpy,
+  };
+});
+
+describe("ClaudeAcpAgent settings", () => {
+  let tempDir: string;
+  let originalClaudeConfigDir: string | undefined;
+
+  function createMockClient(): AcpClient {
+    return {
+      sessionUpdate: async () => {},
+      requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+      readTextFile: async () => ({ content: "" }),
+      writeTextFile: async () => ({}),
+    } as unknown as AcpClient;
+  }
+
+  function mockQuery() {
+    let capturedOptions: any;
+    const setModelSpy = vi.fn();
+    querySpy.mockImplementation(({ options }: any) => {
+      capturedOptions = options;
+      return {
+        initializationResult: async () => ({
+          models: [
+            {
+              value: "claude-sonnet-4-6",
+              displayName: "Claude Sonnet 4.5",
+              description: "Default",
+            },
+          ],
+        }),
+        setModel: setModelSpy,
+        supportedCommands: async () => [],
+      } as any;
+    });
+    return { getCapturedOptions: () => capturedOptions, setModelSpy };
+  }
+
+  beforeEach(async () => {
+    tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "acp-agent-settings-"));
+    originalClaudeConfigDir = process.env.CLAUDE_CONFIG_DIR;
+    process.env.CLAUDE_CONFIG_DIR = tempDir;
+    querySpy.mockReset();
+    vi.resetModules();
+  });
+
+  afterEach(async () => {
+    if (originalClaudeConfigDir) {
+      process.env.CLAUDE_CONFIG_DIR = originalClaudeConfigDir;
+    } else {
+      delete process.env.CLAUDE_CONFIG_DIR;
+    }
+    await fs.promises.rm(tempDir, { recursive: true, force: true });
+  });
+
+  it("uses permissions.defaultMode for new sessions", async () => {
+    await fs.promises.writeFile(
+      path.join(tempDir, "settings.json"),
+      JSON.stringify({
+        permissions: {
+          defaultMode: "dontAsk",
+        },
+      }),
+    );
+
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(projectDir, { recursive: true });
+
+    const { getCapturedOptions } = mockQuery();
+
+    const { ClaudeAcpAgent } = await import("../acp-agent.js");
+    const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+    const response = await (agent as any).createSession({
+      cwd: projectDir,
+      mcpServers: [],
+      _meta: { disableBuiltInTools: true },
+    });
+
+    expect(getCapturedOptions().permissionMode).toBe("dontAsk");
+    expect(getCapturedOptions().settingSources).toEqual(["user", "project", "local"]);
+    expect(response.modes.currentModeId).toBe("dontAsk");
+  });
+
+  it("supports acceptEdits mode defaults", async () => {
+    await fs.promises.writeFile(
+      path.join(tempDir, "settings.json"),
+      JSON.stringify({
+        permissions: {
+          defaultMode: "acceptEdits",
+        },
+      }),
+    );
+
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(projectDir, { recursive: true });
+
+    const { getCapturedOptions } = mockQuery();
+
+    const { ClaudeAcpAgent } = await import("../acp-agent.js");
+    const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+    const response = await (agent as any).createSession({
+      cwd: projectDir,
+      mcpServers: [],
+      _meta: { disableBuiltInTools: true },
+    });
+
+    expect(getCapturedOptions().permissionMode).toBe("acceptEdits");
+    expect(response.modes.currentModeId).toBe("acceptEdits");
+  });
+
+  it("drops escalating defaultMode when it comes from project-tier settings", async () => {
+    // bypassPermissions in .claude/settings.json (a repo-committed tier) is
+    // filtered by the SDK's trust policy and clamps to 'default'.
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(path.join(projectDir, ".claude"), { recursive: true });
+    await fs.promises.writeFile(
+      path.join(projectDir, ".claude", "settings.json"),
+      JSON.stringify({ permissions: { defaultMode: "bypassPermissions" } }),
+    );
+
+    const { getCapturedOptions } = mockQuery();
+
+    const { ClaudeAcpAgent } = await import("../acp-agent.js");
+    const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+    const response = await (agent as any).createSession({
+      cwd: projectDir,
+      mcpServers: [],
+      _meta: { disableBuiltInTools: true },
+    });
+
+    expect(getCapturedOptions().permissionMode).toBe("default");
+    expect(response.modes.currentModeId).toBe("default");
+  });
+
+  it("defaults to 'default' when no permissions.defaultMode is set", async () => {
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(projectDir, { recursive: true });
+
+    const { getCapturedOptions } = mockQuery();
+
+    const { ClaudeAcpAgent } = await import("../acp-agent.js");
+    const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+    const response = await (agent as any).createSession({
+      cwd: projectDir,
+      mcpServers: [],
+      _meta: { disableBuiltInTools: true },
+    });
+
+    expect(getCapturedOptions().permissionMode).toBe("default");
+    expect(response.modes.currentModeId).toBe("default");
+  });
+
+  it("falls back to 'default' when permissions.defaultMode is invalid", async () => {
+    await fs.promises.writeFile(
+      path.join(tempDir, "settings.json"),
+      JSON.stringify({
+        permissions: {
+          defaultMode: "not-a-real-mode",
+        },
+      }),
+    );
+
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(projectDir, { recursive: true });
+
+    const { getCapturedOptions } = mockQuery();
+
+    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 },
+    });
+
+    // Bad mode is ignored at the usage site; session creation must not throw.
+    expect(getCapturedOptions().permissionMode).toBe("default");
+    expect(response.modes.currentModeId).toBe("default");
+  });
+
+  it("ignores model from settings when it is not a string", async () => {
+    await fs.promises.writeFile(
+      path.join(tempDir, "settings.json"),
+      JSON.stringify({
+        model: 123,
+      }),
+    );
+
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(projectDir, { recursive: true });
+
+    const { setModelSpy } = mockQuery();
+
+    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 },
+    });
+
+    // Bad model is ignored at the usage site; falls back to the first SDK model.
+    // No setModel call is needed because no override was applied — the SDK is
+    // already on its own default.
+    expect(setModelSpy).not.toHaveBeenCalled();
+    expect(response.configOptions?.find((o: any) => o.id === "model")?.currentValue).toBe(
+      "claude-sonnet-4-6",
+    );
+  });
+
+  describe("auto mode availability per model", () => {
+    function mockQueryWithModels(models: any[]): {
+      getCapturedOptions: () => any;
+      setModelSpy: ReturnType<typeof vi.fn>;
+      setPermissionModeSpy: ReturnType<typeof vi.fn>;
+    } {
+      let capturedOptions: any;
+      const setModelSpy = vi.fn();
+      const setPermissionModeSpy = vi.fn();
+      querySpy.mockImplementation(({ options }: any) => {
+        capturedOptions = options;
+        return {
+          initializationResult: async () => ({ models }),
+          setModel: setModelSpy,
+          setPermissionMode: setPermissionModeSpy,
+          supportedCommands: async () => [],
+        } as any;
+      });
+      return {
+        getCapturedOptions: () => capturedOptions,
+        setModelSpy,
+        setPermissionModeSpy,
+      };
+    }
+
+    it("omits `auto` from availableModes when the resolved model lacks supportsAutoMode", async () => {
+      const projectDir = path.join(tempDir, "project");
+      await fs.promises.mkdir(projectDir, { recursive: true });
+
+      mockQueryWithModels([
+        {
+          value: "claude-haiku-4-5",
+          displayName: "Claude Haiku",
+          description: "Fast",
+          // supportsAutoMode intentionally omitted
+        },
+      ]);
+
+      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 modeIds: string[] = response.modes.availableModes.map((m: any) => m.id);
+      expect(modeIds).not.toContain("auto");
+      expect(modeIds).toEqual(
+        expect.arrayContaining(["default", "acceptEdits", "plan", "dontAsk"]),
+      );
+    });
+
+    it("includes `auto` when the resolved model has supportsAutoMode: true", async () => {
+      const projectDir = path.join(tempDir, "project");
+      await fs.promises.mkdir(projectDir, { recursive: true });
+
+      mockQueryWithModels([
+        {
+          value: "claude-opus-4-5",
+          displayName: "Claude Opus",
+          description: "Most capable",
+          supportsAutoMode: true,
+        },
+      ]);
+
+      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 modeIds: string[] = response.modes.availableModes.map((m: any) => m.id);
+      expect(modeIds).toContain("auto");
+    });
+
+    it("clamps permissions.defaultMode='auto' to 'default' on a model that lacks supportsAutoMode", async () => {
+      await fs.promises.writeFile(
+        path.join(tempDir, "settings.json"),
+        JSON.stringify({ permissions: { defaultMode: "auto" } }),
+      );
+
+      const projectDir = path.join(tempDir, "project");
+      await fs.promises.mkdir(projectDir, { recursive: true });
+
+      const { getCapturedOptions, setPermissionModeSpy } = mockQueryWithModels([
+        {
+          value: "claude-haiku-4-5",
+          displayName: "Claude Haiku",
+          description: "Fast",
+          // supportsAutoMode intentionally omitted
+        },
+      ]);
+
+      const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+      try {
+        const { ClaudeAcpAgent } = await import("../acp-agent.js");
+        const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+        const response = await (agent as any).createSession({
+          cwd: projectDir,
+          mcpServers: [],
+          _meta: { disableBuiltInTools: true },
+        });
+
+        // Options.permissionMode is built before init resolves, so it still
+        // carries the user-typed value; the SDK was synced via
+        // setPermissionMode after we discovered the model can't honor it.
+        expect(getCapturedOptions().permissionMode).toBe("auto");
+        expect(setPermissionModeSpy).toHaveBeenCalledWith("default");
+        expect(response.modes.currentModeId).toBe("default");
+        expect(response.modes.availableModes.map((m: any) => m.id)).not.toContain("auto");
+
+        // A descriptive warning was logged so operators see the clamp.
+        const messages = errorSpy.mock.calls.map((c) => c.join(" "));
+        expect(messages.some((m) => m.includes("auto") && m.includes("claude-haiku-4-5"))).toBe(
+          true,
+        );
+      } finally {
+        errorSpy.mockRestore();
+      }
+    });
+
+    it("does not clamp permissions.defaultMode='auto' on a model that supports auto", async () => {
+      await fs.promises.writeFile(
+        path.join(tempDir, "settings.json"),
+        JSON.stringify({ permissions: { defaultMode: "auto" } }),
+      );
+
+      const projectDir = path.join(tempDir, "project");
+      await fs.promises.mkdir(projectDir, { recursive: true });
+
+      const { getCapturedOptions, setPermissionModeSpy } = mockQueryWithModels([
+        {
+          value: "claude-opus-4-5",
+          displayName: "Claude Opus",
+          description: "Most capable",
+          supportsAutoMode: true,
+        },
+      ]);
+
+      const { ClaudeAcpAgent } = await import("../acp-agent.js");
+      const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+      const response = await (agent as any).createSession({
+        cwd: projectDir,
+        mcpServers: [],
+        _meta: { disableBuiltInTools: true },
+      });
+
+      expect(getCapturedOptions().permissionMode).toBe("auto");
+      expect(setPermissionModeSpy).not.toHaveBeenCalled();
+      expect(response.modes.currentModeId).toBe("auto");
+    });
+  });
+
+  describe("availableModels allowlist from settings", () => {
+    function mockQueryWithModels(models: any[]): {
+      setModelSpy: ReturnType<typeof vi.fn>;
+    } {
+      const setModelSpy = vi.fn();
+      querySpy.mockImplementation(() => {
+        return {
+          initializationResult: async () => ({ models }),
+          setModel: setModelSpy,
+          supportedCommands: async () => [],
+        } as any;
+      });
+      return { setModelSpy };
+    }
+
+    it("restricts configOptions to the user's allowlist using their exact IDs", async () => {
+      // Reproduces the scenario from
+      // https://github.com/agentclientprotocol/claude-agent-acp/issues/620:
+      // user lists `claude-haiku-4-5` (no date pin) in availableModels, but
+      // the SDK still surfaces its `haiku` alias which resolves to a
+      // date-pinned variant the user doesn't have access to.
+      await fs.promises.writeFile(
+        path.join(tempDir, "settings.json"),
+        JSON.stringify({
+          availableModels: [
+            "claude-sonnet-4-6[1m]",
+            "claude-opus-4-6[1m]",
+            "claude-haiku-4-5",
+            "claude-opus-4-7[1m]",
+          ],
+        }),
+      );
+
+      const projectDir = path.join(tempDir, "project");
+      await fs.promises.mkdir(projectDir, { recursive: true });
+
+      mockQueryWithModels([
+        { value: "default", displayName: "Default", description: "Default model" },
+        {
+          value: "sonnet[1m]",
+          displayName: "Sonnet (1M context)",
+          description: "Sonnet 4.6 long context",
+        },
+        {
+          value: "opus[1m]",
+          displayName: "Opus (1M context)",
+          description: "Opus 1M context",
+        },
+        { value: "haiku", displayName: "Haiku", description: "Fast" },
+      ]);
+
+      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",
+        "claude-sonnet-4-6[1m]",
+        "claude-opus-4-6[1m]",
+        "claude-haiku-4-5",
+        "claude-opus-4-7[1m]",
+      ]);
+    });
+
+    it("unions availableModels across user and project settings", async () => {
+      // https://code.claude.com/docs/en/model-config#merge-behavior
+      await fs.promises.writeFile(
+        path.join(tempDir, "settings.json"),
+        JSON.stringify({ availableModels: ["claude-haiku-4-5"] }),
+      );
+
+      const projectDir = path.join(tempDir, "project");
+      await fs.promises.mkdir(path.join(projectDir, ".claude"), { recursive: true });
+      await fs.promises.writeFile(
+        path.join(projectDir, ".claude", "settings.json"),
+        JSON.stringify({
+          availableModels: ["claude-haiku-4-5", "claude-opus-4-7[1m]"],
+        }),
+      );
+
+      mockQueryWithModels([
+        { value: "default", displayName: "Default", description: "Default model" },
+        { value: "haiku", displayName: "Haiku", description: "Fast" },
+      ]);
+
+      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");
+      // User and project entries are unioned and deduplicated.
+      expect(modelOption.options.map((o: any) => o.value)).toEqual([
+        "default",
+        "claude-haiku-4-5",
+        "claude-opus-4-7[1m]",
+      ]);
+    });
+
+    it("returns only the default entry when availableModels is an empty array", async () => {
+      await fs.promises.writeFile(
+        path.join(tempDir, "settings.json"),
+        JSON.stringify({ availableModels: [] }),
+      );
+
+      const projectDir = path.join(tempDir, "project");
+      await fs.promises.mkdir(projectDir, { recursive: true });
+
+      mockQueryWithModels([
+        { value: "default", displayName: "Default", description: "Default model" },
+        { value: "haiku", displayName: "Haiku", description: "Fast" },
+      ]);
+
+      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"]);
+    });
+
+    it("does not filter when availableModels is absent from settings", async () => {
+      const projectDir = path.join(tempDir, "project");
+      await fs.promises.mkdir(projectDir, { recursive: true });
+
+      mockQueryWithModels([
+        { value: "default", displayName: "Default", description: "Default model" },
+        { value: "haiku", displayName: "Haiku", description: "Fast" },
+      ]);
+
+      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", "haiku"]);
+    });
+
+    it("passes the user's exact ID to setModel when it matches an SDK alias", async () => {
+      // Without the allowlist, the SDK would resolve `haiku` to a
+      // date-pinned variant. Forcing setModel to receive `claude-haiku-4-5`
+      // is exactly what the issue's workaround
+      // (`ANTHROPIC_DEFAULT_HAIKU_MODEL`) achieves manually.
+      await fs.promises.writeFile(
+        path.join(tempDir, "settings.json"),
+        JSON.stringify({
+          availableModels: ["claude-haiku-4-5"],
+          model: "claude-haiku-4-5",
+        }),
+      );
+
+      const projectDir = path.join(tempDir, "project");
+      await fs.promises.mkdir(projectDir, { recursive: true });
+
+      const { setModelSpy } = mockQueryWithModels([
+        { value: "default", displayName: "Default", description: "Default model" },
+        { value: "haiku", displayName: "Haiku", description: "Fast" },
+      ]);
+
+      const { ClaudeAcpAgent } = await import("../acp-agent.js");
+      const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+      const response = await (agent as any).createSession({
+        cwd: projectDir,
+        mcpServers: [],
+        _meta: { disableBuiltInTools: true },
+      });
+
+      expect(setModelSpy).toHaveBeenCalledWith("claude-haiku-4-5");
+      expect(response.configOptions?.find((o: any) => o.id === "model")?.currentValue).toBe(
+        "claude-haiku-4-5",
+      );
+    });
+
+    it("does not inherit display info across mismatched model versions", async () => {
+      // https://github.com/agentclientprotocol/claude-agent-acp/issues/639:
+      // when the SDK's `opus` alias resolves to Opus 4.7, an allowlist entry
+      // of `claude-opus-4-6` (or `claude-opus-4-6[1m]`) used to substring-match
+      // `opus` and inherit the "Opus 4.7" display info. With version-aware
+      // matching, these entries fall back to showing their literal ID rather
+      // than a misleading newer name.
+      await fs.promises.writeFile(
+        path.join(tempDir, "settings.json"),
+        JSON.stringify({
+          availableModels: [
+            "claude-opus-4-6",
+            "claude-opus-4-6[1m]",
+            "claude-opus-4-7",
+            "claude-opus-4-7[1m]",
+          ],
+        }),
+      );
+
+      const projectDir = path.join(tempDir, "project");
+      await fs.promises.mkdir(projectDir, { recursive: true });
+
+      mockQueryWithModels([
+        { value: "default", displayName: "Default", description: "Default model" },
+        {
+          value: "opus",
+          displayName: "Opus 4.7",
+          description: "Claude Opus 4.7 — complex tasks, higher cost",
+        },
+        {
+          value: "opus[1m]",
+          displayName: "Opus 4.7 (1M context)",
+          description: "Opus 4.7 with 1M context",
+        },
+      ]);
+
+      const { ClaudeAcpAgent } = await import("../acp-agent.js");
+      const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+      const response = await (agent as any).createSession({
+        cwd: projectDir,
+        mcpServers: [],
+        _meta: { disableBuiltInTools: true },
+      });
+
+      const modelOption = response.configOptions.find((o: any) => o.id === "model");
+      const byValue: Record<string, { name: string; description?: string }> = {};
+      for (const opt of modelOption.options) {
+        byValue[opt.value] = { name: opt.name, description: opt.description };
+      }
+
+      // 4-6 entries must NOT inherit the 4.7 SDK alias display info.
+      expect(byValue["claude-opus-4-6"].name).toBe("claude-opus-4-6");
+      expect(byValue["claude-opus-4-6"].description).toBe("");
+      expect(byValue["claude-opus-4-6[1m]"].name).toBe("claude-opus-4-6[1m]");
+      expect(byValue["claude-opus-4-6[1m]"].description).toBe("");
+
+      // 4-7 entries continue to inherit display info from a 4.7 SDK alias.
+      expect(byValue["claude-opus-4-7"].name).toBe("Opus 4.7");
+      expect(byValue["claude-opus-4-7[1m]"].name).toMatch(/Opus 4\.7/);
+    });
+
+    it("does not inherit display info across mismatched model families", async () => {
+      // https://github.com/agentclientprotocol/claude-agent-acp/issues/639:
+      // when the SDK's `opus` alias resolves to Opus 4.8, `claude-opus-4-6[1m]`
+      // fails the version check against `opus` but the tokenized matcher
+      // falls through to `sonnet[1m]` because the `1m` context hint alone
+      // is enough to score a match.
+      await fs.promises.writeFile(
+        path.join(tempDir, "settings.json"),
+        JSON.stringify({
+          availableModels: ["claude-opus-4-6", "claude-opus-4-6[1m]"],
+        }),
+      );
+
+      const projectDir = path.join(tempDir, "project");
+      await fs.promises.mkdir(projectDir, { recursive: true });
+
+      mockQueryWithModels([
+        { value: "default", displayName: "Default", description: "Default model" },
+        {
+          value: "sonnet",
+          displayName: "Sonnet",
+          description: "Sonnet 4.6 · Best for everyday tasks",
+        },
+        {
+          value: "sonnet[1m]",
+          displayName: "Sonnet (1M context)",
+          description: "Sonnet 4.6 for long sessions",
+        },
+        {
+          value: "opus",
+          displayName: "Opus 4.8",
+          description: "Claude Opus 4.8",
+        },
+      ]);
+
+      const { ClaudeAcpAgent } = await import("../acp-agent.js");
+      const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+      const response = await (agent as any).createSession({
+        cwd: projectDir,
+        mcpServers: [],
+        _meta: { disableBuiltInTools: true },
+      });
+
+      const modelOption = response.configOptions.find((o: any) => o.id === "model");
+      const byValue: Record<string, { name: string; description?: string }> = {};
+      for (const opt of modelOption.options) {
+        byValue[opt.value] = { name: opt.name, description: opt.description };
+      }
+
+      expect(byValue["claude-opus-4-6[1m]"].name).toBe("claude-opus-4-6[1m]");
+      expect(byValue["claude-opus-4-6"].name).toBe("claude-opus-4-6");
+    });
+
+    it("preserves ANTHROPIC_CUSTOM_MODEL_OPTION even when absent from the allowlist", async () => {
+      // Per the model-config docs, ANTHROPIC_CUSTOM_MODEL_OPTION adds an entry
+      // "without replacing the built-in aliases" and "appears at the bottom of
+      // the /model picker", so it is exempt from the availableModels allowlist
+      // (the same way the Default option is "not affected by availableModels").
+      // ACP must match: a slim alias allowlist must not hide the custom model
+      // row, and it appears last, after the allowlisted entries.
+      // https://code.claude.com/docs/en/model-config#add-a-custom-model-option
+      const originalEnv = process.env.ANTHROPIC_CUSTOM_MODEL_OPTION;
+      process.env.ANTHROPIC_CUSTOM_MODEL_OPTION = "claude-opus-4-8[1m]";
+      try {
+        await fs.promises.writeFile(
+          path.join(tempDir, "settings.json"),
+          JSON.stringify({
+            availableModels: ["sonnet", "opus", "haiku"],
+          }),
+        );
+
+        const projectDir = path.join(tempDir, "project");
+        await fs.promises.mkdir(projectDir, { recursive: true });
+
+        mockQueryWithModels([
+          { value: "default", displayName: "Default", description: "Default model" },
+          { value: "sonnet", displayName: "Sonnet", description: "Claude Sonnet 4.6" },
+          { value: "opus", displayName: "Opus", description: "Claude Opus 4.6" },
+          { value: "haiku", displayName: "Haiku", description: "Claude Haiku 4.5" },
+          {
+            value: "claude-opus-4-8[1m]",
+            displayName: "Opus 4.8",
+            description: "Claude Opus 4.8",
+          },
+        ]);
+
+        const { ClaudeAcpAgent } = await import("../acp-agent.js");
+        const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+        const response = await (agent as any).createSession({
+          cwd: projectDir,
+          mcpServers: [],
+          _meta: { disableBuiltInTools: true },
+        });
+
+        const modelOption = response.configOptions.find((o: any) => o.id === "model");
+        expect(modelOption.options.map((o: any) => o.value)).toEqual([
+          "default",
+          "sonnet",
+          "opus",
+          "haiku",
+          "claude-opus-4-8[1m]",
+        ]);
+        const custom = modelOption.options.find((o: any) => o.value === "claude-opus-4-8[1m]");
+        expect(custom.name).toBe("Opus 4.8");
+        expect(custom.description).toBe("Claude Opus 4.8");
+      } finally {
+        if (originalEnv === undefined) {
+          delete process.env.ANTHROPIC_CUSTOM_MODEL_OPTION;
+        } else {
+          process.env.ANTHROPIC_CUSTOM_MODEL_OPTION = originalEnv;
+        }
+      }
+    });
+
+    it("does not duplicate the custom model option when also in the allowlist", async () => {
+      // If the user lists the custom model's exact ID in availableModels AND it
+      // is set as ANTHROPIC_CUSTOM_MODEL_OPTION, it must appear exactly once.
+      const originalEnv = process.env.ANTHROPIC_CUSTOM_MODEL_OPTION;
+      process.env.ANTHROPIC_CUSTOM_MODEL_OPTION = "claude-opus-4-8[1m]";
+      try {
+        await fs.promises.writeFile(
+          path.join(tempDir, "settings.json"),
+          JSON.stringify({
+            availableModels: ["sonnet", "claude-opus-4-8[1m]"],
+          }),
+        );
+
+        const projectDir = path.join(tempDir, "project");
+        await fs.promises.mkdir(projectDir, { recursive: true });
+
+        mockQueryWithModels([
+          { value: "default", displayName: "Default", description: "Default model" },
+          { value: "sonnet", displayName: "Sonnet", description: "Claude Sonnet 4.6" },
+          {
+            value: "claude-opus-4-8[1m]",
+            displayName: "Opus 4.8",
+            description: "Claude Opus 4.8",
+          },
+        ]);
+
+        const { ClaudeAcpAgent } = await import("../acp-agent.js");
+        const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+        const response = await (agent as any).createSession({
+          cwd: projectDir,
+          mcpServers: [],
+          _meta: { disableBuiltInTools: true },
+        });
+
+        const modelOption = response.configOptions.find((o: any) => o.id === "model");
+        expect(modelOption.options.map((o: any) => o.value)).toEqual([
+          "default",
+          "sonnet",
+          "claude-opus-4-8[1m]",
+        ]);
+      } finally {
+        if (originalEnv === undefined) {
+          delete process.env.ANTHROPIC_CUSTOM_MODEL_OPTION;
+        } else {
+          process.env.ANTHROPIC_CUSTOM_MODEL_OPTION = originalEnv;
+        }
+      }
+    });
+  });
+
+  it("resolves model aliases like opus[1m] to the correct model", async () => {
+    await fs.promises.writeFile(
+      path.join(tempDir, "settings.json"),
+      JSON.stringify({
+        model: "opus[1m]",
+      }),
+    );
+
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(projectDir, { recursive: true });
+
+    const setModelSpy = vi.fn();
+    querySpy.mockImplementation(({ options: _options }: any) => {
+      return {
+        initializationResult: async () => ({
+          models: [
+            {
+              value: "claude-opus-4-6",
+              displayName: "Claude Opus 4.6",
+              description: "Base",
+            },
+            {
+              value: "claude-opus-4-6-1m",
+              displayName: "Claude Opus 4.6 (1M)",
+              description: "Long context",
+            },
+          ],
+        }),
+        setModel: setModelSpy,
+        supportedCommands: async () => [],
+      } as any;
+    });
+
+    const { ClaudeAcpAgent } = await import("../acp-agent.js");
+    const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+    const response = await (agent as any).createSession({
+      cwd: projectDir,
+      mcpServers: [],
+      _meta: { disableBuiltInTools: true },
+    });
+
+    expect(setModelSpy).toHaveBeenCalledWith("claude-opus-4-6-1m");
+    expect(response.configOptions?.find((o: any) => o.id === "model")?.currentValue).toBe(
+      "claude-opus-4-6-1m",
+    );
+  });
+
+  it("skips the initial setModel when the resolved value matches the SDK's model list verbatim", async () => {
+    // Covers the launcher case from PR #646: the launcher bakes the model into
+    // ANTHROPIC_MODEL, the SDK already starts on that model, and a second
+    // setModel call would be a redundant round-trip (and on some launcher
+    // setups, more fragile than launch-time selection).
+    const originalEnv = process.env.ANTHROPIC_MODEL;
+    process.env.ANTHROPIC_MODEL = "claude-opus-4-6";
+
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(projectDir, { recursive: true });
+
+    const setModelSpy = vi.fn();
+    querySpy.mockImplementation(() => {
+      return {
+        initializationResult: async () => ({
+          models: [
+            { value: "default", displayName: "Default", description: "" },
+            { value: "claude-sonnet-4-6", displayName: "Claude Sonnet 4.6", description: "" },
+            { value: "claude-opus-4-6", displayName: "Claude Opus 4.6", description: "" },
+          ],
+        }),
+        setModel: setModelSpy,
+        supportedCommands: async () => [],
+      } as any;
+    });
+
+    try {
+      const { ClaudeAcpAgent } = await import("../acp-agent.js");
+      const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+      const response = await (agent as any).createSession({
+        cwd: projectDir,
+        mcpServers: [],
+        _meta: { disableBuiltInTools: true },
+      });
+
+      expect(setModelSpy).not.toHaveBeenCalled();
+      expect(response.configOptions?.find((o: any) => o.id === "model")?.currentValue).toBe(
+        "claude-opus-4-6",
+      );
+    } finally {
+      if (originalEnv === undefined) {
+        delete process.env.ANTHROPIC_MODEL;
+      } else {
+        process.env.ANTHROPIC_MODEL = originalEnv;
+      }
+    }
+  });
+
+  it("still calls setModel when the allowlist synthesizes a value the SDK has not surfaced", async () => {
+    // The allowlist may rewrite a model's `value` to the user's literal ID
+    // (e.g., `claude-haiku-4-5`) even when the SDK only exposed an alias
+    // (`haiku`). In that case the SDK has not independently arrived at the
+    // user's preferred ID, so we must sync via setModel.
+    await fs.promises.writeFile(
+      path.join(tempDir, "settings.json"),
+      JSON.stringify({
+        availableModels: ["claude-haiku-4-5"],
+        model: "claude-haiku-4-5",
+      }),
+    );
+
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(projectDir, { recursive: true });
+
+    const setModelSpy = vi.fn();
+    querySpy.mockImplementation(() => {
+      return {
+        initializationResult: async () => ({
+          models: [
+            { value: "default", displayName: "Default", description: "" },
+            { value: "haiku", displayName: "Haiku", description: "Fast" },
+          ],
+        }),
+        setModel: setModelSpy,
+        supportedCommands: async () => [],
+      } as any;
+    });
+
+    const { ClaudeAcpAgent } = await import("../acp-agent.js");
+    const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+    const response = await (agent as any).createSession({
+      cwd: projectDir,
+      mcpServers: [],
+      _meta: { disableBuiltInTools: true },
+    });
+
+    expect(setModelSpy).toHaveBeenCalledWith("claude-haiku-4-5");
+    expect(response.configOptions?.find((o: any) => o.id === "model")?.currentValue).toBe(
+      "claude-haiku-4-5",
+    );
+  });
+});

src/tests/additional-roots.test.ts

@@ -0,0 +1,108 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { SessionNotification } from "@agentclientprotocol/sdk";
+import type { Options } from "@anthropic-ai/claude-agent-sdk";
+import type { AcpClient, ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+let capturedOptions: Options | undefined;
+vi.mock("@anthropic-ai/claude-agent-sdk", async () => ({
+  ...(await vi.importActual<typeof import("@anthropic-ai/claude-agent-sdk")>(
+    "@anthropic-ai/claude-agent-sdk",
+  )),
+  query: ({ options }: { options: Options }) => {
+    capturedOptions = options;
+    return {
+      initializationResult: async () => ({
+        models: [
+          {
+            value: "claude-sonnet-4-6",
+            displayName: "Claude Sonnet",
+            description: "Fast",
+            supportsAutoMode: true,
+          },
+        ],
+      }),
+      setModel: async () => {},
+      setPermissionMode: async () => {},
+      supportedCommands: async () => [],
+      [Symbol.asyncIterator]: async function* () {},
+    };
+  },
+}));
+vi.mock("../tools.js", async () => ({
+  ...(await vi.importActual<typeof import("../tools.js")>("../tools.js")),
+  registerHookCallback: vi.fn(),
+}));
+
+describe("additionalRoots", () => {
+  let agent: ClaudeAcpAgentType;
+  const tempDirs: string[] = [];
+  const newSession = (meta: Record<string, unknown>, cwd = process.cwd()) =>
+    agent.newSession({ cwd, mcpServers: [], _meta: meta });
+
+  beforeEach(async () => {
+    capturedOptions = undefined;
+    tempDirs.length = 0;
+    vi.resetModules();
+    const { ClaudeAcpAgent } = await import("../acp-agent.js");
+    agent = new ClaudeAcpAgent({
+      sessionUpdate: async (_notification: SessionNotification) => {},
+      requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+      readTextFile: async () => ({ content: "" }),
+      writeTextFile: async () => ({}),
+    } as unknown as AcpClient);
+  });
+
+  afterEach(
+    async () =>
+      void (await Promise.all(tempDirs.map((dir) => rm(dir, { recursive: true, force: true })))),
+  );
+
+  it("passes through relative roots as provided", async () => {
+    const projectRoot = await mkdtemp(path.join(os.tmpdir(), "claude-project-"));
+    tempDirs.push(projectRoot);
+    await newSession({ additionalRoots: ["."] }, projectRoot);
+    expect(capturedOptions!.additionalDirectories).toEqual(["."]);
+  });
+
+  it("merges additionalRoots with user additionalDirectories without normalization", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "claude-root-"));
+    tempDirs.push(root);
+    await newSession({
+      additionalRoots: ["", root],
+      claudeCode: { options: { additionalDirectories: ["/workspace/shared"] } },
+    });
+    expect(capturedOptions!.additionalDirectories).toEqual(["/workspace/shared", "", root]);
+  });
+
+  it("prefers the official ACP additionalDirectories field over _meta.additionalRoots", async () => {
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+      additionalDirectories: ["/from/official"],
+      _meta: { additionalRoots: ["/from/meta"] },
+    });
+    expect(capturedOptions!.additionalDirectories).toEqual(["/from/official"]);
+  });
+
+  it("merges official ACP additionalDirectories with claudeCode SDK additionalDirectories", async () => {
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+      additionalDirectories: ["/from/official"],
+      _meta: { claudeCode: { options: { additionalDirectories: ["/from/sdk"] } } },
+    });
+    expect(capturedOptions!.additionalDirectories).toEqual(["/from/sdk", "/from/official"]);
+  });
+
+  it("falls back to _meta.additionalRoots when the official field is omitted", async () => {
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+      _meta: { additionalRoots: ["/from/meta"] },
+    });
+    expect(capturedOptions!.additionalDirectories).toEqual(["/from/meta"]);
+  });
+});

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

@@ -0,0 +1,298 @@
+import { describe, expect, it, Mock, vi, afterEach, beforeEach } from "vitest";
+import { AcpClient, ClaudeAcpAgent } from "../acp-agent.js";
+
+const mockQuery = vi.hoisted(() =>
+  vi.fn(() => ({
+    initializationResult: vi.fn().mockResolvedValue({
+      models: [
+        { value: "id", displayName: "name", description: "description", supportsAutoMode: true },
+      ],
+    }),
+    setModel: vi.fn(),
+    setPermissionMode: vi.fn(),
+    supportedCommands: vi.fn().mockResolvedValue([]),
+  })),
+);
+
+vi.mock("@anthropic-ai/claude-agent-sdk", async () => ({
+  ...(await vi.importActual<typeof import("@anthropic-ai/claude-agent-sdk")>(
+    "@anthropic-ai/claude-agent-sdk",
+  )),
+  query: mockQuery,
+}));
+
+describe("authorization", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    //await all pending events like
+    vi.runAllTimers();
+    vi.useRealTimers();
+
+    vi.unstubAllGlobals();
+    vi.resetAllMocks();
+  });
+
+  async function createAgentMock(): Promise<[ClaudeAcpAgent, Mock]> {
+    const connectionMock = {
+      sessionUpdate: async (_: any) => {},
+    } as AcpClient;
+
+    const agent = new ClaudeAcpAgent(connectionMock);
+
+    return [agent, mockQuery];
+  }
+
+  it("gateway auth not offered without capability", async () => {
+    const [agent] = await createAgentMock();
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {},
+    });
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "gateway" }),
+    );
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "gateway-bedrock" }),
+    );
+  });
+
+  it("gateway auth offered when client advertises auth._meta.gateway capability", async () => {
+    const [agent] = await createAgentMock();
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {
+        auth: { _meta: { gateway: true } },
+      } as any,
+    });
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({
+        id: "gateway",
+        _meta: { gateway: { protocol: "anthropic" } },
+      }),
+    );
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({
+        id: "gateway-bedrock",
+        _meta: { gateway: { protocol: "bedrock" } },
+      }),
+    );
+  });
+
+  it("uses gateway env after anthropic gateway auth", async () => {
+    const [agent, mockQuery] = await createAgentMock();
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {
+        auth: { terminal: true, _meta: { gateway: true } },
+      } as any,
+    });
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "gateway" }),
+    );
+
+    await agent.authenticate({
+      methodId: "gateway",
+      _meta: { gateway: { baseUrl: "https://gateway.example", headers: { "x-api-key": "test" } } },
+    });
+
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+      _meta: {
+        claudeCode: {
+          options: {
+            env: {
+              userEnv: "userEnv",
+            },
+          },
+        },
+      },
+    });
+
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.objectContaining({
+        options: expect.objectContaining({
+          env: expect.objectContaining({
+            ANTHROPIC_AUTH_TOKEN: " ",
+            ANTHROPIC_BASE_URL: "https://gateway.example",
+            ANTHROPIC_CUSTOM_HEADERS: "x-api-key: test",
+            userEnv: "userEnv",
+          }),
+        }),
+      }),
+    );
+  });
+
+  it("uses gateway env after gateway auth", async () => {
+    const [agent, mockQuery] = await createAgentMock();
+
+    await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {
+        auth: { terminal: true, _meta: { gateway: true } },
+      } as any,
+    });
+
+    await agent.authenticate({
+      methodId: "gateway-bedrock",
+      _meta: {
+        gateway: { baseUrl: "https://gateway.example", headers: { "custom-header": "test" } },
+      },
+    });
+
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+    });
+
+    expect(mockQuery).toHaveBeenCalledWith(
+      expect.objectContaining({
+        options: expect.objectContaining({
+          env: expect.objectContaining({
+            CLAUDE_CODE_USE_BEDROCK: "1",
+            AWS_BEARER_TOKEN_BEDROCK: " ",
+            ANTHROPIC_BEDROCK_BASE_URL: "https://gateway.example",
+            ANTHROPIC_CUSTOM_HEADERS: "custom-header: test",
+          }),
+        }),
+      }),
+    );
+  });
+
+  it("hide claude authentication without terminal-auth", async () => {
+    const [agent] = await createAgentMock();
+    vi.stubGlobal("process", { ...process, argv: ["--hide-claude-auth"] });
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {
+        auth: { _meta: { gateway: true } },
+      } as any,
+    });
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "claude-ai-login" }),
+    );
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "console-login" }),
+    );
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "gateway" }),
+    );
+  });
+
+  it("hide claude auth but still show console login when terminal-auth is set", async () => {
+    const [agent] = await createAgentMock();
+    vi.stubGlobal("process", { ...process, argv: ["--hide-claude-auth"] });
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {
+        _meta: { "terminal-auth": true },
+      },
+    });
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "claude-ai-login" }),
+    );
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "console-login" }),
+    );
+  });
+
+  it("hide claude auth but still show console login with terminal capability", async () => {
+    const [agent] = await createAgentMock();
+    vi.stubGlobal("process", { ...process, argv: ["--hide-claude-auth"] });
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: {
+        auth: { terminal: true },
+      },
+    });
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "claude-ai-login" }),
+    );
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "console-login" }),
+    );
+  });
+
+  it("SSH session falls back to single legacy login method", async () => {
+    const [agent] = await createAgentMock();
+    vi.stubGlobal("process", { ...process, env: { ...process.env, SSH_TTY: "/dev/pts/0" } });
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: { auth: { terminal: true } },
+    });
+
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "claude-login" }),
+    );
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "claude-ai-login" }),
+    );
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "console-login" }),
+    );
+  });
+
+  it("CLAUDE_CODE_REMOTE falls back to single legacy login method", async () => {
+    const [agent] = await createAgentMock();
+    vi.stubGlobal("process", { ...process, env: { ...process.env, CLAUDE_CODE_REMOTE: "1" } });
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: { auth: { terminal: true } },
+    });
+
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "claude-login" }),
+    );
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "claude-ai-login" }),
+    );
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "console-login" }),
+    );
+  });
+
+  it("remote environment respects hide-claude-auth", async () => {
+    const [agent] = await createAgentMock();
+    vi.stubGlobal("process", {
+      ...process,
+      argv: ["--hide-claude-auth"],
+      env: { ...process.env, SSH_CONNECTION: "192.168.1.1 12345 192.168.1.2 22" },
+    });
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: { auth: { terminal: true } },
+    });
+
+    expect(initializeResponse.authMethods).not.toContainEqual(
+      expect.objectContaining({ id: "claude-login" }),
+    );
+  });
+
+  it("show claude authentication", async () => {
+    const [agent] = await createAgentMock();
+
+    const initializeResponse = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: { auth: { terminal: true } },
+    });
+
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "claude-ai-login" }),
+    );
+    expect(initializeResponse.authMethods).toContainEqual(
+      expect.objectContaining({ id: "console-login" }),
+    );
+  });
+});

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

@@ -0,0 +1,616 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { RequestError, SessionNotification } from "@agentclientprotocol/sdk";
+import type { Options } from "@anthropic-ai/claude-agent-sdk";
+import type { AcpClient, ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+let capturedOptions: Options | undefined;
+vi.mock("@anthropic-ai/claude-agent-sdk", async () => {
+  const actual = await vi.importActual<typeof import("@anthropic-ai/claude-agent-sdk")>(
+    "@anthropic-ai/claude-agent-sdk",
+  );
+  return {
+    ...actual,
+    query: (args: { prompt: unknown; options: Options }) => {
+      capturedOptions = args.options;
+      return {
+        initializationResult: async () => ({
+          models: [
+            {
+              value: "claude-sonnet-4-6",
+              displayName: "Claude Sonnet",
+              description: "Fast",
+              supportsAutoMode: true,
+            },
+          ],
+        }),
+        setModel: async () => {},
+        setPermissionMode: async () => {},
+        supportedCommands: async () => [],
+        [Symbol.asyncIterator]: async function* () {},
+      };
+    },
+  };
+});
+
+vi.mock("../tools.js", async () => {
+  const actual = await vi.importActual<typeof import("../tools.js")>("../tools.js");
+  return {
+    ...actual,
+    registerHookCallback: vi.fn(),
+  };
+});
+
+describe("createSession options merging", () => {
+  let agent: ClaudeAcpAgentType;
+  let ClaudeAcpAgent: typeof ClaudeAcpAgentType;
+
+  function createMockClient(): AcpClient {
+    return {
+      sessionUpdate: async (_notification: SessionNotification) => {},
+      requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+      readTextFile: async () => ({ content: "" }),
+      writeTextFile: async () => ({}),
+    } as unknown as AcpClient;
+  }
+
+  beforeEach(async () => {
+    capturedOptions = undefined;
+
+    vi.resetModules();
+    const acpAgent = await import("../acp-agent.js");
+    ClaudeAcpAgent = acpAgent.ClaudeAcpAgent;
+
+    agent = new ClaudeAcpAgent(createMockClient());
+  });
+
+  it("merges user-provided disallowedTools with ACP internal list", async () => {
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+      _meta: {
+        claudeCode: {
+          options: {
+            disallowedTools: ["WebSearch", "WebFetch"],
+          },
+        },
+      },
+    });
+
+    // User-provided tools should be present
+    expect(capturedOptions!.disallowedTools).toContain("WebSearch");
+    expect(capturedOptions!.disallowedTools).toContain("WebFetch");
+    // ACP's internal disallowed tool should also be present
+    expect(capturedOptions!.disallowedTools).toContain("AskUserQuestion");
+  });
+
+  it("works when user provides no disallowedTools", async () => {
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+    });
+
+    expect(capturedOptions!.disallowedTools).toContain("AskUserQuestion");
+  });
+
+  it("works when user provides empty disallowedTools", async () => {
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+      _meta: {
+        claudeCode: {
+          options: {
+            disallowedTools: [],
+          },
+        },
+      },
+    });
+
+    expect(capturedOptions!.disallowedTools).toContain("AskUserQuestion");
+  });
+
+  it("sets tools to empty array when disableBuiltInTools is true", async () => {
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+      _meta: {
+        disableBuiltInTools: true,
+        claudeCode: {
+          options: {
+            disallowedTools: ["CustomTool"],
+          },
+        },
+      },
+    });
+
+    // disableBuiltInTools removes all built-in tools from context
+    expect(capturedOptions!.tools).toEqual([]);
+    // User-provided and ACP disallowedTools still apply
+    expect(capturedOptions!.disallowedTools).toContain("CustomTool");
+    expect(capturedOptions!.disallowedTools).toContain("AskUserQuestion");
+  });
+
+  it("merges user-provided hooks with ACP hooks", async () => {
+    const userPreToolUseHook = { hooks: [{ command: "echo pre" }] };
+
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+      _meta: {
+        claudeCode: {
+          options: {
+            hooks: {
+              PreToolUse: [userPreToolUseHook],
+              PostToolUse: [{ hooks: [{ command: "echo user-post" }] }],
+            },
+          },
+        },
+      },
+    });
+
+    // User's PreToolUse hooks should be preserved
+    expect(capturedOptions!.hooks?.PreToolUse).toEqual([userPreToolUseHook]);
+    // PostToolUse should contain both user and ACP hooks
+    expect(capturedOptions!.hooks?.PostToolUse).toHaveLength(2);
+  });
+
+  it("inherits HOME and PATH from process.env when no env is provided", async () => {
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+    });
+
+    expect(capturedOptions?.env?.HOME).toBe(process.env.HOME);
+    expect(capturedOptions?.env?.PATH).toBe(process.env.PATH);
+  });
+
+  it("merges user-provided env vars on top of process.env", async () => {
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+      _meta: {
+        claudeCode: {
+          options: {
+            env: {
+              CUSTOM_VAR: "custom-value",
+            },
+          },
+        },
+      },
+    });
+
+    expect(capturedOptions?.env?.HOME).toBe(process.env.HOME);
+    expect(capturedOptions?.env?.PATH).toBe(process.env.PATH);
+    expect(capturedOptions?.env?.CUSTOM_VAR).toBe("custom-value");
+  });
+
+  it("allows user-provided env vars to override process.env entries", async () => {
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+      _meta: {
+        claudeCode: {
+          options: {
+            env: {
+              HOME: "/custom/home",
+            },
+          },
+        },
+      },
+    });
+
+    expect(capturedOptions?.env?.HOME).toBe("/custom/home");
+  });
+
+  it("defaults tools to claude_code preset when not provided", async () => {
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+    });
+
+    expect(capturedOptions!.tools).toEqual({ type: "preset", preset: "claude_code" });
+  });
+
+  it("passes through user-provided tools string array", async () => {
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+      _meta: {
+        claudeCode: {
+          options: {
+            tools: ["Read", "Glob"],
+          },
+        },
+      },
+    });
+
+    expect(capturedOptions!.tools).toEqual(["Read", "Glob"]);
+  });
+
+  it("explicit tools array takes precedence over disableBuiltInTools", async () => {
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+      _meta: {
+        disableBuiltInTools: true,
+        claudeCode: {
+          options: {
+            tools: ["Read", "Glob"],
+          },
+        },
+      },
+    });
+
+    expect(capturedOptions!.tools).toEqual(["Read", "Glob"]);
+  });
+
+  it("passes through empty tools array to disable all built-in tools", async () => {
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+      _meta: {
+        claudeCode: {
+          options: {
+            tools: [],
+          },
+        },
+      },
+    });
+
+    expect(capturedOptions!.tools).toEqual([]);
+  });
+
+  describe("systemPrompt via _meta", () => {
+    it("defaults to the claude_code preset when not provided", async () => {
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(capturedOptions!.systemPrompt).toEqual({
+        type: "preset",
+        preset: "claude_code",
+      });
+    });
+
+    it("replaces the preset when a string is provided", async () => {
+      await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [],
+        _meta: { systemPrompt: "custom prompt" },
+      });
+
+      expect(capturedOptions!.systemPrompt).toBe("custom prompt");
+    });
+
+    it("forwards append", async () => {
+      await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [],
+        _meta: { systemPrompt: { append: "extra instructions" } },
+      });
+
+      expect(capturedOptions!.systemPrompt).toEqual({
+        type: "preset",
+        preset: "claude_code",
+        append: "extra instructions",
+      });
+    });
+
+    it("forwards excludeDynamicSections", async () => {
+      await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [],
+        _meta: { systemPrompt: { excludeDynamicSections: true } },
+      });
+
+      expect(capturedOptions!.systemPrompt).toEqual({
+        type: "preset",
+        preset: "claude_code",
+        excludeDynamicSections: true,
+      });
+    });
+
+    it("forwards append and excludeDynamicSections together", async () => {
+      await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [],
+        _meta: {
+          systemPrompt: {
+            append: "extra instructions",
+            excludeDynamicSections: true,
+          },
+        },
+      });
+
+      expect(capturedOptions!.systemPrompt).toEqual({
+        type: "preset",
+        preset: "claude_code",
+        append: "extra instructions",
+        excludeDynamicSections: true,
+      });
+    });
+
+    it("ignores caller-provided type/preset overrides", async () => {
+      await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [],
+        _meta: {
+          systemPrompt: {
+            type: "something-else",
+            preset: "other-preset",
+            append: "extra",
+          },
+        },
+      });
+
+      expect(capturedOptions!.systemPrompt).toEqual({
+        type: "preset",
+        preset: "claude_code",
+        append: "extra",
+      });
+    });
+  });
+
+  describe("CLAUDE_MODEL_CONFIG", () => {
+    let originalModelConfig: string | undefined;
+
+    beforeEach(() => {
+      originalModelConfig = process.env.CLAUDE_MODEL_CONFIG;
+      delete process.env.CLAUDE_MODEL_CONFIG;
+    });
+
+    afterEach(() => {
+      if (originalModelConfig !== undefined) {
+        process.env.CLAUDE_MODEL_CONFIG = originalModelConfig;
+      } else {
+        delete process.env.CLAUDE_MODEL_CONFIG;
+      }
+    });
+
+    it("passes modelOverrides as settings", async () => {
+      process.env.CLAUDE_MODEL_CONFIG = JSON.stringify({
+        modelOverrides: { "claude-opus-4-6": "us.anthropic.claude-opus-4-6-v1" },
+      });
+
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(capturedOptions!.settings).toEqual({
+        modelOverrides: { "claude-opus-4-6": "us.anthropic.claude-opus-4-6-v1" },
+      });
+    });
+
+    it("passes availableModels as settings", async () => {
+      process.env.CLAUDE_MODEL_CONFIG = JSON.stringify({
+        availableModels: ["opus", "sonnet"],
+      });
+
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(capturedOptions!.settings).toEqual({
+        availableModels: ["opus", "sonnet"],
+      });
+    });
+
+    it("passes both modelOverrides and availableModels", async () => {
+      process.env.CLAUDE_MODEL_CONFIG = JSON.stringify({
+        modelOverrides: { "claude-opus-4-6": "us.anthropic.claude-opus-4-6-v1" },
+        availableModels: ["opus"],
+      });
+
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(capturedOptions!.settings).toEqual({
+        modelOverrides: { "claude-opus-4-6": "us.anthropic.claude-opus-4-6-v1" },
+        availableModels: ["opus"],
+      });
+    });
+
+    it("does not add settings when env var is not set", async () => {
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(capturedOptions!.settings).toBeUndefined();
+    });
+
+    it("ignores env var when _meta provides settings", async () => {
+      process.env.CLAUDE_MODEL_CONFIG = JSON.stringify({
+        modelOverrides: { "claude-opus-4-6": "us.anthropic.claude-opus-4-6-v1" },
+      });
+
+      await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [],
+        _meta: {
+          claudeCode: {
+            options: {
+              settings: {
+                model: "claude-sonnet-4-6",
+                modelOverrides: { "claude-opus-4-6": "meta-value" },
+              },
+            },
+          },
+        },
+      });
+
+      // _meta settings take precedence; env var is ignored entirely
+      expect(capturedOptions!.settings).toEqual({
+        model: "claude-sonnet-4-6",
+        modelOverrides: { "claude-opus-4-6": "meta-value" },
+      });
+    });
+
+    it("throws on invalid JSON", async () => {
+      process.env.CLAUDE_MODEL_CONFIG = "not-json";
+
+      await expect(agent.newSession({ cwd: process.cwd(), mcpServers: [] })).rejects.toThrow();
+    });
+  });
+
+  it("merges user-provided mcpServers with ACP mcpServers", async () => {
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [
+        {
+          name: "acp-server",
+          command: "node",
+          args: ["acp-server.js"],
+          env: [],
+        },
+      ],
+      _meta: {
+        claudeCode: {
+          options: {
+            mcpServers: {
+              "user-server": {
+                type: "stdio",
+                command: "node",
+                args: ["server.js"],
+              },
+            },
+          },
+        },
+      },
+    });
+
+    // User-provided MCP server should be present
+    expect(capturedOptions!.mcpServers).toHaveProperty("user-server");
+    // ACP-provided MCP server should also be present
+    expect(capturedOptions!.mcpServers).toHaveProperty("acp-server");
+  });
+
+  describe("thinking config from MAX_THINKING_TOKENS", () => {
+    let originalMaxThinking: string | undefined;
+
+    beforeEach(() => {
+      originalMaxThinking = process.env.MAX_THINKING_TOKENS;
+      delete process.env.MAX_THINKING_TOKENS;
+    });
+
+    afterEach(() => {
+      if (originalMaxThinking !== undefined) {
+        process.env.MAX_THINKING_TOKENS = originalMaxThinking;
+      } else {
+        delete process.env.MAX_THINKING_TOKENS;
+      }
+    });
+
+    it("leaves thinking unset (SDK default) when env var is absent", async () => {
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+      expect(capturedOptions!.thinking).toBeUndefined();
+      // The deprecated option must not be set either.
+      expect(capturedOptions!.maxThinkingTokens).toBeUndefined();
+    });
+
+    it("maps 0 to disabled thinking", async () => {
+      process.env.MAX_THINKING_TOKENS = "0";
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+      expect(capturedOptions!.thinking).toEqual({ type: "disabled" });
+    });
+
+    it("maps a positive value to a fixed thinking budget", async () => {
+      process.env.MAX_THINKING_TOKENS = "12000";
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+      expect(capturedOptions!.thinking).toEqual({ type: "enabled", budgetTokens: 12000 });
+    });
+
+    it("ignores a non-numeric value", async () => {
+      process.env.MAX_THINKING_TOKENS = "lots";
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+      expect(capturedOptions!.thinking).toBeUndefined();
+    });
+
+    it("lets a user-provided thinking option override the env default", async () => {
+      process.env.MAX_THINKING_TOKENS = "12000";
+      await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [],
+        _meta: {
+          claudeCode: {
+            options: {
+              thinking: { type: "adaptive" },
+            },
+          },
+        },
+      });
+      expect(capturedOptions!.thinking).toEqual({ type: "adaptive" });
+    });
+  });
+
+  describe("cwd validation", () => {
+    it("rejects a relative cwd with invalidParams", async () => {
+      await expect(
+        agent.newSession({ cwd: "relative/path", mcpServers: [] }),
+      ).rejects.toMatchObject({ code: RequestError.invalidParams().code });
+    });
+
+    it("rejects a non-existent cwd with invalidParams", async () => {
+      const missing = path.join(os.tmpdir(), "claude-acp-does-not-exist-xyz");
+      await expect(agent.newSession({ cwd: missing, mcpServers: [] })).rejects.toMatchObject({
+        code: RequestError.invalidParams().code,
+      });
+    });
+
+    it("rejects a cwd that points at a file with invalidParams", async () => {
+      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(dir, { recursive: true, force: true });
+      }
+    });
+
+    it("accepts an existing absolute directory", async () => {
+      await expect(agent.newSession({ cwd: process.cwd(), mcpServers: [] })).resolves.toBeDefined();
+    });
+  });
+
+  describe("elicitation", () => {
+    it("keeps AskUserQuestion disabled and omits callbacks without elicitation capability", async () => {
+      await agent.initialize({ protocolVersion: 1, clientCapabilities: {} });
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(capturedOptions!.disallowedTools).toContain("AskUserQuestion");
+      expect(capturedOptions!.onElicitation).toBeUndefined();
+    });
+
+    it("enables AskUserQuestion and wires the elicitation callback when form is supported", async () => {
+      await agent.initialize({
+        protocolVersion: 1,
+        clientCapabilities: { elicitation: { form: {} } },
+      });
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(capturedOptions!.disallowedTools).not.toContain("AskUserQuestion");
+      expect(typeof capturedOptions!.onElicitation).toBe("function");
+    });
+
+    it("wires callbacks for url-only elicitation but keeps AskUserQuestion disabled", async () => {
+      await agent.initialize({
+        protocolVersion: 1,
+        clientCapabilities: { elicitation: { url: {} } },
+      });
+      await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+      expect(capturedOptions!.disallowedTools).toContain("AskUserQuestion");
+      expect(typeof capturedOptions!.onElicitation).toBe("function");
+    });
+
+    it("still merges user-provided disallowedTools when AskUserQuestion is enabled", async () => {
+      await agent.initialize({
+        protocolVersion: 1,
+        clientCapabilities: { elicitation: { form: {} } },
+      });
+      await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [],
+        _meta: { claudeCode: { options: { disallowedTools: ["WebSearch"] } } },
+      });
+
+      expect(capturedOptions!.disallowedTools).toContain("WebSearch");
+      expect(capturedOptions!.disallowedTools).not.toContain("AskUserQuestion");
+    });
+  });
+});

src/tests/elicitation.test.ts

@@ -0,0 +1,391 @@
+import { describe, it, expect } from "vitest";
+import type {
+  CreateElicitationRequest,
+  CreateElicitationResponse,
+  EnumOption,
+} from "@agentclientprotocol/sdk";
+import type { ElicitationRequest } from "@anthropic-ai/claude-agent-sdk";
+import {
+  applyAskElicitationResponse,
+  askUserQuestionsToCreateRequest,
+  AskUserQuestion,
+  createElicitationResponseToElicitResult,
+  extractAskUserQuestions,
+  mcpElicitationToCreateRequest,
+} from "../elicitation.js";
+
+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.
+ */
+function mkQuestion(
+  question: string,
+  options: Array<{ label: string; description?: string; preview?: string }>,
+  opts: { header?: string; multiSelect?: boolean } = {},
+): AskUserQuestion {
+  return {
+    question,
+    header: opts.header ?? "",
+    multiSelect: opts.multiSelect ?? false,
+    options: options.map((o) => ({
+      label: o.label,
+      description: o.description ?? "",
+      ...(o.preview ? { preview: o.preview } : {}),
+    })),
+  } as AskUserQuestion;
+}
+
+describe("mcpElicitationToCreateRequest", () => {
+  it("maps a form-mode request, defaulting the schema type to object", () => {
+    const request: ElicitationRequest = {
+      serverName: "server",
+      message: "Need your name",
+      mode: "form",
+      requestedSchema: { properties: { name: { type: "string" } } },
+    };
+
+    const result = mcpElicitationToCreateRequest(request, SESSION_ID);
+
+    expect(result).toEqual({
+      mode: "form",
+      sessionId: SESSION_ID,
+      message: "Need your name",
+      requestedSchema: { type: "object", properties: { name: { type: "string" } } },
+    });
+  });
+
+  it("maps a url-mode request and preserves the elicitation id", () => {
+    const request: ElicitationRequest = {
+      serverName: "server",
+      message: "Authorize",
+      mode: "url",
+      url: "https://example.com/auth",
+      elicitationId: "el-123",
+    };
+
+    expect(mcpElicitationToCreateRequest(request, SESSION_ID)).toEqual({
+      mode: "url",
+      sessionId: SESSION_ID,
+      message: "Authorize",
+      url: "https://example.com/auth",
+      elicitationId: "el-123",
+    });
+  });
+
+  it("generates an elicitation id when a url request omits one", () => {
+    const request: ElicitationRequest = {
+      serverName: "server",
+      message: "Authorize",
+      mode: "url",
+      url: "https://example.com/auth",
+    };
+
+    const result = mcpElicitationToCreateRequest(request, SESSION_ID);
+    expect(result?.mode).toBe("url");
+    expect((result as { elicitationId: string }).elicitationId).toMatch(/.+/);
+  });
+
+  it("returns null for a url request with no url", () => {
+    const request: ElicitationRequest = {
+      serverName: "server",
+      message: "Authorize",
+      mode: "url",
+    };
+
+    expect(mcpElicitationToCreateRequest(request, SESSION_ID)).toBeNull();
+  });
+});
+
+describe("createElicitationResponseToElicitResult", () => {
+  it("maps accept with content", () => {
+    const response = { action: "accept", content: { name: "Ada" } } as CreateElicitationResponse;
+    expect(createElicitationResponseToElicitResult(response)).toEqual({
+      action: "accept",
+      content: { name: "Ada" },
+    });
+  });
+
+  it("defaults accept content to an empty object", () => {
+    const response = { action: "accept" } as CreateElicitationResponse;
+    expect(createElicitationResponseToElicitResult(response)).toEqual({
+      action: "accept",
+      content: {},
+    });
+  });
+
+  it("maps decline and cancel", () => {
+    expect(
+      createElicitationResponseToElicitResult({ action: "decline" } as CreateElicitationResponse),
+    ).toEqual({ action: "decline" });
+    expect(
+      createElicitationResponseToElicitResult({ action: "cancel" } as CreateElicitationResponse),
+    ).toEqual({ action: "cancel" });
+  });
+});
+
+describe("extractAskUserQuestions", () => {
+  const question = mkQuestion("Which?", [{ label: "A" }, { label: "B" }]);
+
+  it("reads questions off the tool input", () => {
+    expect(extractAskUserQuestions({ questions: [question] })).toEqual([question]);
+  });
+
+  it("returns null when there are no questions", () => {
+    expect(extractAskUserQuestions({})).toBeNull();
+    expect(extractAskUserQuestions({ questions: [] })).toBeNull();
+  });
+
+  it("filters out malformed questions (missing options, empty options, bad question)", () => {
+    const input = {
+      questions: [
+        question,
+        { question: "missing options" },
+        { options: [] },
+        { options: [], question: "empty" },
+      ],
+    } as unknown as Record<string, unknown>;
+    expect(extractAskUserQuestions(input)).toEqual([question]);
+  });
+
+  it("returns null when every question is filtered out", () => {
+    const input = {
+      questions: [{ question: "no options" }, { options: [{ label: "A" }] }],
+    } as unknown as Record<string, unknown>;
+    expect(extractAskUserQuestions(input)).toBeNull();
+  });
+});
+
+describe("askUserQuestionsToCreateRequest", () => {
+  it("keys a single-select question by a stable id and carries the prompt in message only", () => {
+    const questions = [
+      mkQuestion(
+        "Which library?",
+        [{ label: "date-fns", description: "Lightweight" }, { label: "luxon" }],
+        {
+          header: "Library",
+        },
+      ),
+    ];
+
+    const result = askUserQuestionsToCreateRequest(questions, SESSION_ID, "tool-1");
+
+    expect(result).toMatchObject({
+      mode: "form",
+      sessionId: SESSION_ID,
+      toolCallId: "tool-1",
+      message: "Which library?",
+    });
+    const schema = (result as Extract<CreateElicitationRequest, { mode: "form" }>).requestedSchema;
+    // Nothing is required; the user can pick, type a custom answer, or skip.
+    expect(schema.required).toBeUndefined();
+    // Single question → no duplicated description (prompt is in `message`).
+    expect(schema.properties?.["question_0"]).toEqual({
+      type: "string",
+      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.
+        { const: "luxon", title: "luxon" },
+      ],
+    });
+    // The full question text is not used as a property key.
+    expect(schema.properties?.["Which library?"]).toBeUndefined();
+  });
+
+  it("forwards option description and preview under _meta for rich clients", () => {
+    const questions = [
+      mkQuestion("Which layout?", [
+        {
+          label: "Grid",
+          description: "Cards in a responsive grid",
+          preview: "```\n[ ] [ ] [ ]\n[ ] [ ] [ ]\n```",
+        },
+        { label: "List", description: "Stacked rows" },
+        { label: "Plain" },
+      ]),
+    ];
+
+    const schema = (
+      askUserQuestionsToCreateRequest(questions, SESSION_ID, undefined) as Extract<
+        CreateElicitationRequest,
+        { mode: "form" }
+      >
+    ).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.
+    expect(oneOf[0]).toEqual({
+      const: "Grid",
+      title: "Grid — 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();
+  });
+
+  it("includes a per-question optional free-text custom-answer field", () => {
+    const questions = [
+      mkQuestion("Which?", [{ label: "A" }, { label: "B" }]),
+      mkQuestion("What else?", [{ label: "C" }, { label: "D" }]),
+    ];
+    const schema = (
+      askUserQuestionsToCreateRequest(questions, SESSION_ID, undefined) as Extract<
+        CreateElicitationRequest,
+        { mode: "form" }
+      >
+    ).requestedSchema;
+
+    // Each question gets its own "Other" box, not one shared form-level field.
+    expect(schema.properties?.["question_0_custom"]).toMatchObject({
+      type: "string",
+      title: "Other",
+    });
+    expect(schema.properties?.["question_1_custom"]).toMatchObject({
+      type: "string",
+      title: "Other",
+    });
+  });
+
+  it("builds an array property for multi-select questions and includes per-field question text", () => {
+    const questions = [
+      mkQuestion("Pick one?", [{ label: "A" }, { label: "B" }]),
+      mkQuestion("Which features?", [{ label: "auth" }, { label: "logging" }], {
+        multiSelect: true,
+      }),
+    ];
+
+    const result = askUserQuestionsToCreateRequest(questions, SESSION_ID, undefined);
+    const schema = (result as Extract<CreateElicitationRequest, { mode: "form" }>).requestedSchema;
+
+    expect(result).not.toHaveProperty("toolCallId");
+    // Multiple questions → generic message, each field carries its own question.
+    expect(result.message).toBe("Please answer the following questions.");
+    expect(schema.properties?.["question_1"]).toEqual({
+      type: "array",
+      title: undefined,
+      description: "Which features?",
+      items: {
+        anyOf: [
+          { const: "auth", title: "auth" },
+          { const: "logging", title: "logging" },
+        ],
+      },
+    });
+  });
+});
+
+describe("applyAskElicitationResponse", () => {
+  const questions = [
+    mkQuestion("Single?", [{ label: "A" }, { label: "B" }]),
+    mkQuestion("Multi?", [{ label: "X" }, { label: "Y" }], { multiSelect: true }),
+  ];
+  const toolInput = { questions, metadata: { source: "test" } };
+
+  it("writes selected labels (keyed by indexed fields) into updatedInput on accept", () => {
+    const response = {
+      action: "accept",
+      content: { question_0: "A", question_1: ["X", "Y"] },
+    } as CreateElicitationResponse;
+
+    expect(applyAskElicitationResponse(response, toolInput, questions)).toEqual({
+      action: "answered",
+      updatedInput: {
+        questions,
+        metadata: { source: "test" },
+        answers: { "Single?": "A", "Multi?": "X, Y" },
+      },
+    });
+  });
+
+  it("folds a per-question custom answer into that question's answer", () => {
+    const response = {
+      action: "accept",
+      content: { question_0: "A", question_1_custom: "something else entirely" },
+    } as CreateElicitationResponse;
+
+    expect(applyAskElicitationResponse(response, toolInput, questions)).toEqual({
+      action: "answered",
+      updatedInput: {
+        questions,
+        metadata: { source: "test" },
+        answers: { "Single?": "A", "Multi?": "something else entirely" },
+      },
+    });
+  });
+
+  it("prefers a question's custom answer over its selection", () => {
+    const response = {
+      action: "accept",
+      content: { question_0: "A", question_0_custom: "  my own take  " },
+    } as CreateElicitationResponse;
+
+    expect(applyAskElicitationResponse(response, toolInput, questions)).toEqual({
+      action: "answered",
+      updatedInput: {
+        questions,
+        metadata: { source: "test" },
+        answers: { "Single?": "my own take" },
+      },
+    });
+  });
+
+  it("ignores empty selections and blank custom answers", () => {
+    const response = {
+      action: "accept",
+      content: { question_1: [], question_0_custom: "   " },
+    } as CreateElicitationResponse;
+
+    expect(applyAskElicitationResponse(response, toolInput, questions)).toEqual({
+      action: "answered",
+      updatedInput: { questions, metadata: { source: "test" }, answers: {} },
+    });
+  });
+
+  it("treats decline as answered with no answers", () => {
+    const response = { action: "decline" } as CreateElicitationResponse;
+    expect(applyAskElicitationResponse(response, toolInput, questions)).toEqual({
+      action: "answered",
+      updatedInput: { questions, metadata: { source: "test" }, answers: {} },
+    });
+  });
+
+  it("returns cancel on cancel", () => {
+    const response = { action: "cancel" } as CreateElicitationResponse;
+    expect(applyAskElicitationResponse(response, toolInput, questions)).toEqual({
+      action: "cancel",
+    });
+  });
+
+  it("omits answers for questions the user left unanswered", () => {
+    const response = {
+      action: "accept",
+      content: { question_0: "B" },
+    } as CreateElicitationResponse;
+
+    const result = applyAskElicitationResponse(response, toolInput, questions);
+    expect(result.action).toBe("answered");
+    expect((result as Extract<typeof result, { action: "answered" }>).updatedInput.answers).toEqual(
+      { "Single?": "B" },
+    );
+  });
+});

src/tests/list-sessions.test.ts

@@ -1,596 +0,0 @@
-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 { AgentSideConnection } from "@agentclientprotocol/sdk";
-import type { ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
-import { encodeProjectPath } from "../utils.js";
-
-describe("unstable_listSessions", () => {
-  let tempDir: string;
-  let originalClaudeConfigDir: string | undefined;
-  let agent: ClaudeAcpAgentType;
-  let ClaudeAcpAgent: typeof ClaudeAcpAgentType;
-
-  // Helper to create a mock AgentSideConnection
-  function createMockClient(): AgentSideConnection {
-    return {
-      sessionUpdate: async () => {},
-      requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
-      readTextFile: async () => ({ content: "" }),
-      writeTextFile: async () => ({}),
-    } as unknown as AgentSideConnection;
-  }
-
-  // Helper to write a session file
-  function writeSessionFile(
-    cwd: string,
-    sessionId: string,
-    options: {
-      userMessage?: string;
-      userMessageArray?: boolean;
-      mtime?: Date;
-      malformed?: boolean;
-      isAgentFile?: boolean;
-      omitCwdFromEntries?: boolean;
-    } = {},
-  ): void {
-    const encodedPath = encodeProjectPath(cwd);
-    const projectDir = path.join(tempDir, "projects", encodedPath);
-    fs.mkdirSync(projectDir, { recursive: true });
-
-    const filename = options.isAgentFile ? `agent-${sessionId}.jsonl` : `${sessionId}.jsonl`;
-    const filePath = path.join(projectDir, filename);
-
-    if (options.malformed) {
-      fs.writeFileSync(filePath, "not valid json\n{also bad");
-      return;
-    }
-
-    const lines: string[] = [];
-
-    // First line with sessionId
-    lines.push(JSON.stringify({ sessionId, type: "init" }));
-
-    // User message if provided
-    if (options.userMessage) {
-      const content = options.userMessageArray
-        ? [{ type: "text", text: options.userMessage }]
-        : options.userMessage;
-      lines.push(
-        JSON.stringify({
-          type: "user",
-          sessionId,
-          ...(options.omitCwdFromEntries ? {} : { cwd }),
-          message: { content },
-        }),
-      );
-    }
-
-    // Assistant response
-    lines.push(
-      JSON.stringify({
-        type: "assistant",
-        sessionId,
-        ...(options.omitCwdFromEntries ? {} : { cwd }),
-        message: { content: "Hello!" },
-      }),
-    );
-
-    fs.writeFileSync(filePath, lines.join("\n"));
-
-    // Set modification time if specified
-    if (options.mtime) {
-      fs.utimesSync(filePath, options.mtime, options.mtime);
-    }
-  }
-
-  beforeEach(async () => {
-    // Create temp directory to isolate tests from real filesystem.
-    // We set process.env.CLAUDE_CONFIG_DIR before importing the module so that
-    // CLAUDE_CONFIG_DIR is evaluated with our temp directory.
-    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "claude-test-"));
-    originalClaudeConfigDir = process.env.CLAUDE_CONFIG_DIR;
-    process.env.CLAUDE_CONFIG_DIR = tempDir;
-
-    // Reset modules to pick up the new CLAUDE_CONFIG_DIR env var
-    vi.resetModules();
-
-    // Dynamic import after setting env var
-    const acpAgent = await import("../acp-agent.js");
-    ClaudeAcpAgent = acpAgent.ClaudeAcpAgent;
-
-    // Create agent instance
-    agent = new ClaudeAcpAgent(createMockClient());
-  });
-
-  afterEach(() => {
-    // Restore env and cleanup
-    if (originalClaudeConfigDir !== undefined) {
-      process.env.CLAUDE_CONFIG_DIR = originalClaudeConfigDir;
-    } else {
-      delete process.env.CLAUDE_CONFIG_DIR;
-    }
-    fs.rmSync(tempDir, { recursive: true, force: true });
-  });
-
-  it("returns empty array when projects directory does not exist", async () => {
-    const result = await agent.unstable_listSessions({});
-    expect(result.sessions).toEqual([]);
-    expect(result.nextCursor).toBeUndefined();
-  });
-
-  it("returns empty array when projects directory is empty", async () => {
-    fs.mkdirSync(path.join(tempDir, "projects"), { recursive: true });
-
-    const result = await agent.unstable_listSessions({});
-    expect(result.sessions).toEqual([]);
-  });
-
-  it("parses session files and returns correct metadata", async () => {
-    const cwd = "/Users/test/myproject";
-    const sessionId = "sess-123";
-    const mtime = new Date("2025-01-15T10:30:00Z");
-
-    writeSessionFile(cwd, sessionId, {
-      userMessage: "Hello, can you help me?",
-      mtime,
-    });
-
-    const result = await agent.unstable_listSessions({});
-
-    expect(result.sessions).toHaveLength(1);
-    expect(result.sessions[0]).toMatchObject({
-      sessionId: "sess-123",
-      cwd: "/Users/test/myproject",
-      title: "Hello, can you help me?",
-    });
-    expect(result.sessions[0]!.updatedAt).toBeDefined();
-  });
-
-  it("extracts title from array-style user message content", async () => {
-    writeSessionFile("/Users/test/project", "sess-456", {
-      userMessage: "Fix the bug in auth",
-      userMessageArray: true,
-    });
-
-    const result = await agent.unstable_listSessions({});
-
-    expect(result.sessions[0]!.title).toBe("Fix the bug in auth");
-  });
-
-  it("truncates long titles to 128 characters with ellipsis", async () => {
-    const longMessage = "A".repeat(150);
-    writeSessionFile("/Users/test/project", "sess-789", {
-      userMessage: longMessage,
-    });
-
-    const result = await agent.unstable_listSessions({});
-
-    expect(result.sessions[0]!.title).toBe("A".repeat(127) + "…");
-  });
-
-  it("replaces newlines with spaces in titles", async () => {
-    const messageWithNewlines = "First line\nSecond line\r\nThird line";
-    writeSessionFile("/Users/test/project", "sess-newlines", {
-      userMessage: messageWithNewlines,
-    });
-
-    const result = await agent.unstable_listSessions({});
-
-    expect(result.sessions[0]!.title).toBe("First line Second line Third line");
-  });
-
-  it("collapses multiple whitespace characters in titles", async () => {
-    const messageWithWhitespace = "Hello    world  \n\n  test";
-    writeSessionFile("/Users/test/project", "sess-whitespace", {
-      userMessage: messageWithWhitespace,
-    });
-
-    const result = await agent.unstable_listSessions({});
-
-    expect(result.sessions[0]!.title).toBe("Hello world test");
-  });
-
-  it("filters sessions by cwd parameter", async () => {
-    writeSessionFile("/Users/test/projectone", "sess-a", { userMessage: "Project A" });
-    writeSessionFile("/Users/test/projecttwo", "sess-b", { userMessage: "Project B" });
-
-    const result = await agent.unstable_listSessions({ cwd: "/Users/test/projectone" });
-
-    expect(result.sessions).toHaveLength(1);
-    expect(result.sessions[0]!.sessionId).toBe("sess-a");
-  });
-
-  it("uses per-entry cwd when filtering even if encoded folder collides", async () => {
-    const encodedPath = encodeProjectPath("/Users/test/a-b");
-    const projectDir = path.join(tempDir, "projects", encodedPath);
-    fs.mkdirSync(projectDir, { recursive: true });
-
-    fs.writeFileSync(
-      path.join(projectDir, "sess-a-b.jsonl"),
-      [
-        JSON.stringify({ sessionId: "sess-a-b", type: "init" }),
-        JSON.stringify({
-          type: "user",
-          sessionId: "sess-a-b",
-          cwd: "/Users/test/a-b",
-          message: { content: "A-B" },
-        }),
-      ].join("\n"),
-    );
-
-    fs.writeFileSync(
-      path.join(projectDir, "sess-a-slash-b.jsonl"),
-      [
-        JSON.stringify({ sessionId: "sess-a-slash-b", type: "init" }),
-        JSON.stringify({
-          type: "user",
-          sessionId: "sess-a-slash-b",
-          cwd: "/Users/test/a/b",
-          message: { content: "A/B" },
-        }),
-      ].join("\n"),
-    );
-
-    const result = await agent.unstable_listSessions({ cwd: "/Users/test/a-b" });
-
-    expect(result.sessions).toHaveLength(1);
-    expect(result.sessions[0]!.sessionId).toBe("sess-a-b");
-    expect(result.sessions[0]!.cwd).toBe("/Users/test/a-b");
-  });
-
-  it("returns the true cwd for paths containing hyphens", async () => {
-    const cwd = "/Users/test/claude-agent-acp";
-    writeSessionFile(cwd, "hyphen-session", { userMessage: "Hyphen test" });
-
-    const result = await agent.unstable_listSessions({});
-
-    expect(result.sessions).toHaveLength(1);
-    expect(result.sessions[0]!.cwd).toBe(cwd);
-    expect(result.sessions[0]!.sessionId).toBe("hyphen-session");
-  });
-
-  it("filters hyphenated paths by cwd correctly", async () => {
-    writeSessionFile("/Users/test/claude-agent-acp", "hyphen-a", { userMessage: "A" });
-    writeSessionFile("/Users/test/other-project", "hyphen-b", { userMessage: "B" });
-
-    const result = await agent.unstable_listSessions({ cwd: "/Users/test/claude-agent-acp" });
-
-    expect(result.sessions).toHaveLength(1);
-    expect(result.sessions[0]!.sessionId).toBe("hyphen-a");
-    expect(result.sessions[0]!.cwd).toBe("/Users/test/claude-agent-acp");
-  });
-
-  it("returns all sessions when cwd is not specified", async () => {
-    writeSessionFile("/Users/test/projectone", "sess-a", { userMessage: "A" });
-    writeSessionFile("/Users/test/projecttwo", "sess-b", { userMessage: "B" });
-
-    const result = await agent.unstable_listSessions({});
-
-    expect(result.sessions).toHaveLength(2);
-  });
-
-  it("sorts sessions by updatedAt descending (most recent first)", async () => {
-    writeSessionFile("/Users/test/project", "old-session", {
-      userMessage: "Old",
-      mtime: new Date("2025-01-01T00:00:00Z"),
-    });
-    writeSessionFile("/Users/test/project", "new-session", {
-      userMessage: "New",
-      mtime: new Date("2025-01-15T00:00:00Z"),
-    });
-
-    const result = await agent.unstable_listSessions({});
-
-    expect(result.sessions[0]!.sessionId).toBe("new-session");
-    expect(result.sessions[1]!.sessionId).toBe("old-session");
-  });
-
-  it("skips files starting with agent-", async () => {
-    writeSessionFile("/Users/test/project", "regular-session", { userMessage: "Regular" });
-    writeSessionFile("/Users/test/project", "hidden-session", {
-      userMessage: "Hidden",
-      isAgentFile: true,
-    });
-
-    const result = await agent.unstable_listSessions({});
-
-    expect(result.sessions).toHaveLength(1);
-    expect(result.sessions[0]!.sessionId).toBe("regular-session");
-  });
-
-  it("skips malformed session files gracefully", async () => {
-    writeSessionFile("/Users/test/project", "good-session", { userMessage: "Good" });
-    writeSessionFile("/Users/test/project", "bad-session", { malformed: true });
-
-    const result = await agent.unstable_listSessions({});
-
-    expect(result.sessions).toHaveLength(1);
-    expect(result.sessions[0]!.sessionId).toBe("good-session");
-  });
-
-  it("uses filename as sessionId when not in file content", async () => {
-    const cwd = "/Users/test/project";
-    const encodedPath = encodeProjectPath(cwd);
-    const projectDir = path.join(tempDir, "projects", encodedPath);
-    fs.mkdirSync(projectDir, { recursive: true });
-
-    // Write file without sessionId in content (uses filename fallback), but with cwd.
-    const filePath = path.join(projectDir, "fallback-id.jsonl");
-    fs.writeFileSync(
-      filePath,
-      [
-        JSON.stringify({ type: "init" }),
-        JSON.stringify({ type: "assistant", cwd, message: { content: "Hi" } }),
-      ].join("\n"),
-    );
-
-    const result = await agent.unstable_listSessions({});
-
-    expect(result.sessions[0]!.sessionId).toBe("fallback-id");
-  });
-
-  it("keeps sessionId stable from filename when later entries have different sessionId", async () => {
-    const cwd = "/Users/test/project";
-    const encodedPath = encodeProjectPath(cwd);
-    const projectDir = path.join(tempDir, "projects", encodedPath);
-    fs.mkdirSync(projectDir, { recursive: true });
-
-    const filePath = path.join(projectDir, "stable-id.jsonl");
-    fs.writeFileSync(
-      filePath,
-      [
-        JSON.stringify({ type: "init", sessionId: "stable-id" }),
-        JSON.stringify({
-          type: "user",
-          sessionId: "stable-id",
-          cwd,
-          message: { content: "Hello" },
-        }),
-        JSON.stringify({
-          type: "assistant",
-          sessionId: "other-id",
-          cwd,
-          message: { content: "Wrong session id from sidechain" },
-        }),
-      ].join("\n"),
-    );
-
-    const result = await agent.unstable_listSessions({});
-
-    expect(result.sessions).toHaveLength(1);
-    expect(result.sessions[0]!.sessionId).toBe("stable-id");
-  });
-
-  it("derives cwd from entries for the filename sessionId only", async () => {
-    const cwd = "/Users/test/project";
-    const encodedPath = encodeProjectPath(cwd);
-    const projectDir = path.join(tempDir, "projects", encodedPath);
-    fs.mkdirSync(projectDir, { recursive: true });
-
-    const filePath = path.join(projectDir, "target-session.jsonl");
-    fs.writeFileSync(
-      filePath,
-      [
-        JSON.stringify({
-          type: "user",
-          sessionId: "target-session",
-          cwd,
-          message: { content: "Correct cwd entry" },
-        }),
-      ].join("\n"),
-    );
-
-    const result = await agent.unstable_listSessions({});
-
-    expect(result.sessions).toHaveLength(1);
-    expect(result.sessions[0]!.sessionId).toBe("target-session");
-    expect(result.sessions[0]!.cwd).toBe(cwd);
-  });
-
-  it("keeps scanning after title to find later cwd in same session", async () => {
-    const cwd = "/Users/test/project";
-    const encodedPath = encodeProjectPath(cwd);
-    const projectDir = path.join(tempDir, "projects", encodedPath);
-    fs.mkdirSync(projectDir, { recursive: true });
-
-    const filePath = path.join(projectDir, "late-cwd.jsonl");
-    fs.writeFileSync(
-      filePath,
-      [
-        JSON.stringify({ type: "init", sessionId: "late-cwd" }),
-        JSON.stringify({
-          type: "user",
-          sessionId: "late-cwd",
-          message: { content: "Title from first user message" },
-        }),
-        JSON.stringify({
-          type: "assistant",
-          sessionId: "late-cwd",
-          cwd,
-          message: { content: "Assistant entry carries cwd" },
-        }),
-      ].join("\n"),
-    );
-
-    const result = await agent.unstable_listSessions({});
-
-    expect(result.sessions).toHaveLength(1);
-    expect(result.sessions[0]!.sessionId).toBe("late-cwd");
-    expect(result.sessions[0]!.cwd).toBe(cwd);
-    expect(result.sessions[0]!.title).toBe("Title from first user message");
-  });
-
-  it("ignores sidechain entries when deriving cwd and title", async () => {
-    const cwd = "/Users/test/project";
-    const encodedPath = encodeProjectPath(cwd);
-    const projectDir = path.join(tempDir, "projects", encodedPath);
-    fs.mkdirSync(projectDir, { recursive: true });
-
-    const filePath = path.join(projectDir, "sidechain-metadata.jsonl");
-    fs.writeFileSync(
-      filePath,
-      [
-        JSON.stringify({ type: "init", sessionId: "sidechain-metadata" }),
-        JSON.stringify({
-          type: "user",
-          sessionId: "sidechain-metadata",
-          isSidechain: true,
-          cwd: "/Users/test/wrong-project",
-          message: { content: "Wrong sidechain title" },
-        }),
-        JSON.stringify({
-          type: "user",
-          sessionId: "sidechain-metadata",
-          cwd,
-          message: { content: "Correct primary title" },
-        }),
-      ].join("\n"),
-    );
-
-    const result = await agent.unstable_listSessions({ cwd });
-
-    expect(result.sessions).toHaveLength(1);
-    expect(result.sessions[0]!.sessionId).toBe("sidechain-metadata");
-    expect(result.sessions[0]!.cwd).toBe(cwd);
-    expect(result.sessions[0]!.title).toBe("Correct primary title");
-  });
-
-  it("skips entries without cwd when cwd filter is not provided", async () => {
-    const cwd = "/Users/test/project";
-    const encodedPath = encodeProjectPath(cwd);
-    const projectDir = path.join(tempDir, "projects", encodedPath);
-    fs.mkdirSync(projectDir, { recursive: true });
-
-    const filePath = path.join(projectDir, "no-cwd.jsonl");
-    fs.writeFileSync(filePath, JSON.stringify({ sessionId: "no-cwd", type: "summary" }) + "\n");
-
-    const result = await agent.unstable_listSessions({});
-
-    expect(result.sessions).toHaveLength(0);
-  });
-
-  it("returns null title when no user message exists", async () => {
-    const cwd = "/Users/test/project";
-    const encodedPath = encodeProjectPath(cwd);
-    const projectDir = path.join(tempDir, "projects", encodedPath);
-    fs.mkdirSync(projectDir, { recursive: true });
-
-    // Write file with only init and assistant message
-    const filePath = path.join(projectDir, "no-user.jsonl");
-    fs.writeFileSync(
-      filePath,
-      [
-        JSON.stringify({ sessionId: "no-user", type: "init" }),
-        JSON.stringify({ type: "assistant", cwd, message: { content: "Hi" } }),
-      ].join("\n"),
-    );
-
-    const result = await agent.unstable_listSessions({});
-
-    expect(result.sessions[0]!.title).toBeNull();
-  });
-
-  describe("pagination", () => {
-    it("returns nextCursor when there are more results", async () => {
-      // Create 60 sessions (more than PAGE_SIZE of 50)
-      for (let i = 0; i < 60; i++) {
-        writeSessionFile("/Users/test/project", `sess-${i.toString().padStart(3, "0")}`, {
-          userMessage: `Session ${i}`,
-          mtime: new Date(Date.now() - i * 1000), // Each older by 1 second
-        });
-      }
-
-      const result = await agent.unstable_listSessions({});
-
-      expect(result.sessions).toHaveLength(50);
-      expect(result.nextCursor).toBeDefined();
-    });
-
-    it("does not return nextCursor when all results fit in one page", async () => {
-      for (let i = 0; i < 10; i++) {
-        writeSessionFile("/Users/test/project", `sess-${i}`, { userMessage: `Session ${i}` });
-      }
-
-      const result = await agent.unstable_listSessions({});
-
-      expect(result.sessions).toHaveLength(10);
-      expect(result.nextCursor).toBeUndefined();
-    });
-
-    it("returns next page when cursor is provided", async () => {
-      // Create 60 sessions
-      for (let i = 0; i < 60; i++) {
-        writeSessionFile("/Users/test/project", `sess-${i.toString().padStart(3, "0")}`, {
-          userMessage: `Session ${i}`,
-          mtime: new Date(Date.now() - i * 1000),
-        });
-      }
-
-      // Get first page
-      const firstPage = await agent.unstable_listSessions({});
-      expect(firstPage.sessions).toHaveLength(50);
-      expect(firstPage.nextCursor).toBeDefined();
-
-      // Get second page
-      const secondPage = await agent.unstable_listSessions({ cursor: firstPage.nextCursor });
-      expect(secondPage.sessions).toHaveLength(10);
-      expect(secondPage.nextCursor).toBeUndefined();
-    });
-
-    it("handles invalid cursor gracefully (starts from beginning)", async () => {
-      writeSessionFile("/Users/test/project", "sess-1", { userMessage: "Test" });
-
-      const result = await agent.unstable_listSessions({ cursor: "invalid-base64!" });
-
-      expect(result.sessions).toHaveLength(1);
-    });
-
-    it("handles malformed cursor JSON gracefully", async () => {
-      writeSessionFile("/Users/test/project", "sess-1", { userMessage: "Test" });
-
-      // Valid base64 but not valid JSON
-      const badCursor = Buffer.from("not json").toString("base64");
-      const result = await agent.unstable_listSessions({ cursor: badCursor });
-
-      expect(result.sessions).toHaveLength(1);
-    });
-  });
-
-  describe("Windows path support", () => {
-    it("decodes Windows-style paths correctly", async () => {
-      // Simulate a Windows path encoded as "C-Users-test-project"
-      const windowsCwd = "C:\\Users\\test\\project";
-      writeSessionFile(windowsCwd, "win-session", { userMessage: "Windows test" });
-
-      const result = await agent.unstable_listSessions({});
-
-      expect(result.sessions).toHaveLength(1);
-      expect(result.sessions[0]!.cwd).toBe("C:\\Users\\test\\project");
-      expect(result.sessions[0]!.sessionId).toBe("win-session");
-    });
-
-    it("filters Windows paths by cwd correctly", async () => {
-      writeSessionFile("C:\\Users\\test\\projectone", "win-a", { userMessage: "A" });
-      writeSessionFile("C:\\Users\\test\\projecttwo", "win-b", { userMessage: "B" });
-
-      const result = await agent.unstable_listSessions({ cwd: "C:\\Users\\test\\projectone" });
-
-      expect(result.sessions).toHaveLength(1);
-      expect(result.sessions[0]!.sessionId).toBe("win-a");
-    });
-
-    it("handles mixed Unix and Windows paths", async () => {
-      writeSessionFile("/Users/test/unixproject", "unix-session", { userMessage: "Unix" });
-      writeSessionFile("C:\\Users\\test\\winproject", "win-session", { userMessage: "Windows" });
-
-      const result = await agent.unstable_listSessions({});
-
-      expect(result.sessions).toHaveLength(2);
-      const cwds = result.sessions.map((s) => s.cwd);
-      expect(cwds).toContain("/Users/test/unixproject");
-      expect(cwds).toContain("C:\\Users\\test\\winproject");
-    });
-  });
-});

src/tests/load-session.test.ts

@@ -1,320 +0,0 @@
-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 { AgentSideConnection, SessionNotification } from "@agentclientprotocol/sdk";
-import type { ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
-import { encodeProjectPath } from "../utils.js";
-
-const { registerHookCallbackSpy } = vi.hoisted(() => ({
-  registerHookCallbackSpy: vi.fn(),
-}));
-
-vi.mock("../tools.js", async () => {
-  const actual = await vi.importActual<typeof import("../tools.js")>("../tools.js");
-  return {
-    ...actual,
-    registerHookCallback: registerHookCallbackSpy,
-  };
-});
-
-describe("loadSession", () => {
-  let tempDir: string;
-  let originalClaudeConfigDir: string | undefined;
-  let agent: ClaudeAcpAgentType;
-  let ClaudeAcpAgent: typeof ClaudeAcpAgentType;
-  let sessionUpdates: SessionNotification[];
-  let createSessionSpy: ReturnType<typeof vi.fn>;
-
-  // Helper to create a mock AgentSideConnection
-  function createMockClient(): AgentSideConnection {
-    return {
-      sessionUpdate: async (notification: SessionNotification) => {
-        sessionUpdates.push(notification);
-      },
-      requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
-      readTextFile: async () => ({ content: "" }),
-      writeTextFile: async () => ({}),
-    } as unknown as AgentSideConnection;
-  }
-
-  function writeSessionFile(
-    cwd: string,
-    sessionId: string,
-    entries: Array<Record<string, unknown> | string>,
-  ): void {
-    const encodedPath = encodeProjectPath(cwd);
-    const projectDir = path.join(tempDir, "projects", encodedPath);
-    fs.mkdirSync(projectDir, { recursive: true });
-
-    const filePath = path.join(projectDir, `${sessionId}.jsonl`);
-    const lines = entries.map((entry) =>
-      typeof entry === "string" ? entry : JSON.stringify(entry),
-    );
-    fs.writeFileSync(filePath, lines.join("\n"));
-  }
-
-  beforeEach(async () => {
-    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "claude-load-session-"));
-    originalClaudeConfigDir = process.env.CLAUDE_CONFIG_DIR;
-    process.env.CLAUDE_CONFIG_DIR = tempDir;
-    sessionUpdates = [];
-    registerHookCallbackSpy.mockClear();
-
-    vi.resetModules();
-
-    const acpAgent = await import("../acp-agent.js");
-    ClaudeAcpAgent = acpAgent.ClaudeAcpAgent;
-
-    agent = new ClaudeAcpAgent(createMockClient());
-    createSessionSpy = vi.fn(async () => ({ modes: null, models: null }));
-    (agent as unknown as { createSession: typeof createSessionSpy }).createSession =
-      createSessionSpy;
-  });
-
-  afterEach(() => {
-    if (originalClaudeConfigDir !== undefined) {
-      process.env.CLAUDE_CONFIG_DIR = originalClaudeConfigDir;
-    } else {
-      delete process.env.CLAUDE_CONFIG_DIR;
-    }
-    fs.rmSync(tempDir, { recursive: true, force: true });
-  });
-
-  it("throws when the session file does not exist", async () => {
-    await expect(
-      agent.loadSession({
-        cwd: "/Users/test/project",
-        sessionId: "missing-session",
-        mcpServers: [],
-      }),
-    ).rejects.toThrow("Session not found");
-
-    expect(createSessionSpy).not.toHaveBeenCalled();
-  });
-
-  it("replays history and returns modes/models from createSession", async () => {
-    const cwd = "/Users/test/project";
-    const sessionId = "session-123";
-
-    writeSessionFile(cwd, sessionId, [
-      { type: "summary", summary: "ignored" },
-      {
-        type: "user",
-        sessionId,
-        message: { role: "user", content: "Hello" },
-      },
-      {
-        type: "assistant",
-        sessionId,
-        message: {
-          role: "assistant",
-          content: [{ type: "thinking", thinking: "Thinking" }],
-        },
-      },
-      {
-        type: "assistant",
-        sessionId,
-        message: {
-          role: "assistant",
-          content: [{ type: "text", text: "Hi" }],
-        },
-      },
-      {
-        type: "assistant",
-        sessionId,
-        message: {
-          role: "assistant",
-          content: [
-            {
-              type: "tool_use",
-              id: "tool-1",
-              name: "Read",
-              input: { file_path: "/tmp/example.txt" },
-            },
-          ],
-        },
-      },
-      {
-        type: "user",
-        sessionId,
-        message: {
-          role: "user",
-          content: [{ type: "tool_result", tool_use_id: "tool-1", content: "ok" }],
-        },
-      },
-    ]);
-
-    const result = await agent.loadSession({ cwd, sessionId, mcpServers: [] });
-
-    expect(result).toEqual({ modes: null, models: null });
-    expect(createSessionSpy).toHaveBeenCalledWith(
-      expect.objectContaining({ cwd, mcpServers: [] }),
-      { resume: sessionId },
-    );
-    expect(registerHookCallbackSpy).not.toHaveBeenCalled();
-
-    expect(sessionUpdates.map((notification) => notification.update.sessionUpdate)).toEqual([
-      "user_message_chunk",
-      "agent_thought_chunk",
-      "agent_message_chunk",
-      "tool_call",
-      "tool_call_update",
-    ]);
-
-    expect(sessionUpdates[0]?.update).toMatchObject({
-      sessionUpdate: "user_message_chunk",
-      content: { type: "text", text: "Hello" },
-    });
-    expect(sessionUpdates[1]?.update).toMatchObject({
-      sessionUpdate: "agent_thought_chunk",
-      content: { type: "text", text: "Thinking" },
-    });
-    expect(sessionUpdates[2]?.update).toMatchObject({
-      sessionUpdate: "agent_message_chunk",
-      content: { type: "text", text: "Hi" },
-    });
-    expect(sessionUpdates[3]?.update).toMatchObject({
-      sessionUpdate: "tool_call",
-      toolCallId: "tool-1",
-      status: "pending",
-    });
-    expect(sessionUpdates[4]?.update).toMatchObject({
-      sessionUpdate: "tool_call_update",
-      toolCallId: "tool-1",
-      status: "completed",
-    });
-  });
-
-  it("skips sidechain, mismatched sessionId, invalid, and unsupported entries", async () => {
-    const cwd = "/Users/test/project";
-    const sessionId = "session-456";
-
-    writeSessionFile(cwd, sessionId, [
-      "{not valid json}",
-      { type: "summary", summary: "ignore" },
-      {
-        type: "user",
-        sessionId,
-        isSidechain: true,
-        message: { role: "user", content: "Sidechain" },
-      },
-      {
-        type: "assistant",
-        sessionId: "other-session",
-        message: { role: "assistant", content: "Wrong session" },
-      },
-      {
-        type: "assistant",
-        sessionId,
-        message: { role: "system", content: "Unsupported role" },
-      },
-      {
-        type: "user",
-        sessionId,
-        message: { role: "user", content: 123 },
-      },
-      {
-        type: "user",
-        sessionId,
-        message: { role: "user", content: "Keep me" },
-      },
-    ]);
-
-    await agent.loadSession({ cwd, sessionId, mcpServers: [] });
-
-    expect(sessionUpdates).toHaveLength(1);
-    expect(sessionUpdates[0]?.update).toMatchObject({
-      sessionUpdate: "user_message_chunk",
-      content: { type: "text", text: "Keep me" },
-    });
-  });
-
-  it("finds session file when cwd differs from the original session cwd", async () => {
-    const originalCwd = "/Users/test/original-project";
-    const differentCwd = "/Users/test/different-project";
-    const sessionId = "cross-cwd-session";
-
-    // Session was created in originalCwd
-    writeSessionFile(originalCwd, sessionId, [
-      {
-        type: "user",
-        sessionId,
-        cwd: originalCwd,
-        message: { role: "user", content: "Hello from original" },
-      },
-    ]);
-
-    // Load with a different cwd
-    await agent.loadSession({ cwd: differentCwd, sessionId, mcpServers: [] });
-
-    expect(sessionUpdates).toHaveLength(1);
-    expect(sessionUpdates[0]?.update).toMatchObject({
-      sessionUpdate: "user_message_chunk",
-      content: { type: "text", text: "Hello from original" },
-    });
-    expect(createSessionSpy).toHaveBeenCalledWith(expect.objectContaining({ cwd: differentCwd }), {
-      resume: sessionId,
-    });
-  });
-
-  it("sends available_commands_update after history replay, not during", async () => {
-    const cwd = "/Users/test/project";
-    const sessionId = "session-commands";
-
-    // Mock createSession to populate the sessions map with a mock query
-    createSessionSpy.mockImplementationOnce(async () => {
-      (agent as unknown as { sessions: Record<string, unknown> }).sessions[sessionId] = {
-        query: {
-          supportedCommands: async () => [{ name: "help", description: "Get help" }],
-        },
-      };
-      return { modes: null, models: null };
-    });
-
-    writeSessionFile(cwd, sessionId, [
-      {
-        type: "user",
-        sessionId,
-        message: { role: "user", content: "Hello" },
-      },
-      {
-        type: "assistant",
-        sessionId,
-        message: { role: "assistant", content: [{ type: "text", text: "Hi" }] },
-      },
-    ]);
-
-    await agent.loadSession({ cwd, sessionId, mcpServers: [] });
-
-    // Flush the setTimeout + async work inside sendAvailableCommandsUpdate
-    await new Promise((resolve) => setTimeout(resolve, 10));
-
-    const updateTypes = sessionUpdates.map((n) => n.update.sessionUpdate);
-
-    // available_commands_update should come AFTER all replay notifications
-    expect(updateTypes).toEqual([
-      "user_message_chunk",
-      "agent_message_chunk",
-      "available_commands_update",
-    ]);
-  });
-
-  it("handles Windows-style paths", async () => {
-    const cwd = "C:\\Users\\test\\project";
-    const sessionId = "win-session";
-
-    writeSessionFile(cwd, sessionId, [
-      {
-        type: "user",
-        sessionId,
-        message: { role: "user", content: "Hello" },
-      },
-    ]);
-
-    await agent.loadSession({ cwd, sessionId, mcpServers: [] });
-
-    expect(sessionUpdates).toHaveLength(1);
-    expect(sessionUpdates[0]?.sessionId).toBe(sessionId);
-  });
-});

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

@@ -0,0 +1,57 @@
+import { describe, it, expect, vi } from "vitest";
+import { resolvePermissionMode, type Logger } from "../acp-agent.js";
+
+function mockLogger() {
+  const error = vi.fn<(...args: any[]) => void>();
+  const log = vi.fn<(...args: any[]) => void>();
+  const logger: Logger = { log, error };
+  return { logger, error, log };
+}
+
+describe("resolvePermissionMode", () => {
+  it("returns 'default' when no mode is provided", () => {
+    expect(resolvePermissionMode()).toBe("default");
+    expect(resolvePermissionMode(undefined)).toBe("default");
+  });
+
+  it("resolves exact canonical modes", () => {
+    expect(resolvePermissionMode("default")).toBe("default");
+    expect(resolvePermissionMode("acceptEdits")).toBe("acceptEdits");
+    expect(resolvePermissionMode("dontAsk")).toBe("dontAsk");
+    expect(resolvePermissionMode("plan")).toBe("plan");
+    expect(resolvePermissionMode("bypassPermissions")).toBe("bypassPermissions");
+  });
+
+  it("resolves case-insensitive aliases", () => {
+    expect(resolvePermissionMode("DontAsk")).toBe("dontAsk");
+    expect(resolvePermissionMode("DONTASK")).toBe("dontAsk");
+    expect(resolvePermissionMode("AcceptEdits")).toBe("acceptEdits");
+    expect(resolvePermissionMode("bypass")).toBe("bypassPermissions");
+  });
+
+  it("trims whitespace", () => {
+    expect(resolvePermissionMode("  dontAsk  ")).toBe("dontAsk");
+  });
+
+  it("falls back to 'default' and logs on non-string values", () => {
+    for (const value of [123, true, {}]) {
+      const { logger, error } = mockLogger();
+      expect(resolvePermissionMode(value, logger)).toBe("default");
+      expect(error).toHaveBeenCalledWith(expect.stringContaining("expected a string"));
+    }
+  });
+
+  it("falls back to 'default' and logs on empty string", () => {
+    for (const value of ["", "  "]) {
+      const { logger, error } = mockLogger();
+      expect(resolvePermissionMode(value, logger)).toBe("default");
+      expect(error).toHaveBeenCalledWith(expect.stringContaining("expected a non-empty string"));
+    }
+  });
+
+  it("falls back to 'default' and logs on unknown mode", () => {
+    const { logger, error } = mockLogger();
+    expect(resolvePermissionMode("yolo", logger)).toBe("default");
+    expect(error).toHaveBeenCalledWith(expect.stringContaining("yolo"));
+  });
+});

src/tests/session-load.test.ts

@@ -0,0 +1,333 @@
+import { describe, it, expect } from "vitest";
+import { randomUUID } from "crypto";
+import { RequestError, SessionNotification } from "@agentclientprotocol/sdk";
+import { query, getSessionMessages } from "@anthropic-ai/claude-agent-sdk";
+import { AcpClient, ClaudeAcpAgent } from "../acp-agent.js";
+import { Pushable } from "../utils.js";
+import type { SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+
+function createMockClient(): AcpClient {
+  return {
+    sessionUpdate: async (_notification: SessionNotification) => {},
+    requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+    readTextFile: async () => ({ content: "" }),
+    writeTextFile: async () => ({}),
+  } as unknown as AcpClient;
+}
+
+describe.skipIf(!process.env.RUN_INTEGRATION_TESTS)("session load/resume lifecycle", () => {
+  it("SDK: session created but never prompted has no messages and is not resumable", async () => {
+    // Create a session via the SDK, initialize it, but never send a prompt
+    const sessionId = randomUUID();
+    const input = new Pushable<SDKUserMessage>();
+
+    const q = query({
+      prompt: input,
+      options: {
+        systemPrompt: { type: "preset", preset: "claude_code" },
+        sessionId,
+        settingSources: ["user", "project", "local"],
+        includePartialMessages: true,
+      },
+    });
+
+    // initializationResult() works without needing a prompt pushed
+    const initResult = await q.initializationResult();
+    expect(initResult).toBeDefined();
+
+    // Close without ever prompting
+    input.end();
+    q.return(undefined);
+
+    // Verify no messages were stored
+    const messages = await getSessionMessages(sessionId);
+    expect(messages).toEqual([]);
+
+    // Verify the session is not resumable
+    const input2 = new Pushable<SDKUserMessage>();
+    const q2 = query({
+      prompt: input2,
+      options: {
+        systemPrompt: { type: "preset", preset: "claude_code" },
+        resume: sessionId,
+        settingSources: ["user", "project", "local"],
+        includePartialMessages: true,
+      },
+    });
+
+    await expect(q2.initializationResult()).rejects.toThrow(
+      /No conversation found with session ID/,
+    );
+
+    input2.end();
+    q2.return(undefined);
+  }, 30000);
+
+  it("ACP: loadSession throws resourceNotFound for a non-existent session", async () => {
+    const agent = new ClaudeAcpAgent(createMockClient());
+    const bogusSessionId = randomUUID();
+
+    try {
+      await expect(
+        agent.loadSession({
+          sessionId: bogusSessionId,
+          cwd: process.cwd(),
+          mcpServers: [],
+        }),
+      ).rejects.toThrow(RequestError);
+    } finally {
+      await agent.dispose();
+    }
+  }, 30000);
+
+  it("ACP: resumeSession throws resourceNotFound for a non-existent session", async () => {
+    const agent = new ClaudeAcpAgent(createMockClient());
+    const bogusSessionId = randomUUID();
+
+    try {
+      await expect(
+        agent.resumeSession({
+          sessionId: bogusSessionId,
+          cwd: process.cwd(),
+          mcpServers: [],
+        }),
+      ).rejects.toThrow(RequestError);
+    } finally {
+      await agent.dispose();
+    }
+  }, 30000);
+
+  it("ACP: newSession without prompt, then loadSession on fresh agent throws resourceNotFound", async () => {
+    // Step 1: Create a real session via ACP, never prompt, dispose
+    const agentA = new ClaudeAcpAgent(createMockClient());
+    const { sessionId } = await agentA.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+    });
+    expect(sessionId).toBeDefined();
+    await agentA.dispose();
+
+    // Step 2: Fresh agent tries to load that session
+    const agentB = new ClaudeAcpAgent(createMockClient());
+
+    try {
+      await expect(
+        agentB.loadSession({
+          sessionId,
+          cwd: process.cwd(),
+          mcpServers: [],
+        }),
+      ).rejects.toThrow(RequestError);
+    } finally {
+      await agentB.dispose();
+    }
+  }, 30000);
+
+  it("ACP: newSession without prompt, then resumeSession on fresh agent throws resourceNotFound", async () => {
+    const agentA = new ClaudeAcpAgent(createMockClient());
+    const { sessionId } = await agentA.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+    });
+    await agentA.dispose();
+
+    const agentB = new ClaudeAcpAgent(createMockClient());
+
+    try {
+      await expect(
+        agentB.resumeSession({
+          sessionId,
+          cwd: process.cwd(),
+          mcpServers: [],
+        }),
+      ).rejects.toThrow(RequestError);
+    } finally {
+      await agentB.dispose();
+    }
+  }, 30000);
+
+  // Regression test for https://github.com/zed-industries/claude-code-acp/issues/579
+  // The client (Zed) renders its own local slash commands — e.g. `/model` —
+  // by injecting user-message prompts whose text is wrapped in
+  // `<command-name>` / `<local-command-stdout>` markers. The Claude SDK
+  // persists those messages verbatim in the session transcript. Without
+  // filtering, `loadSession` replays the markers as user_message_chunks
+  // ahead of the real prompt, leaking CLI internals into the transcript.
+  it("ACP: loadSession does not replay local-command metadata user messages", async () => {
+    const recordedUserChunks: string[] = [];
+    const client = {
+      sessionUpdate: async (notification: SessionNotification) => {
+        if (notification.update.sessionUpdate === "user_message_chunk") {
+          const content = notification.update.content;
+          if (content.type === "text") recordedUserChunks.push(content.text);
+        }
+      },
+      requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+      readTextFile: async () => ({ content: "" }),
+      writeTextFile: async () => ({}),
+    } as unknown as AcpClient;
+
+    const commandName =
+      "<command-name>/model</command-name>\n            <command-message>model</command-message>\n            <command-args>opus</command-args>";
+    const commandStdout =
+      "<local-command-stdout>Set model to opus (claude-opus-4-7)</local-command-stdout>";
+
+    // Step 1: create a session via the SDK, push the marker user messages
+    // followed by a real "hi" prompt. We bypass the ACP agent's prompt loop
+    // so we're only testing what the loadSession replay path does, not how
+    // prompts get routed.
+    const sessionId = randomUUID();
+    const input = new Pushable<SDKUserMessage>();
+    const q = query({
+      prompt: input,
+      options: {
+        systemPrompt: { type: "preset", preset: "claude_code" },
+        sessionId,
+        settingSources: ["user", "project", "local"],
+        includePartialMessages: true,
+      },
+    });
+    await q.initializationResult();
+
+    // Zed renders its local slash commands by mixing the marker blocks into
+    // the user's prompt content array alongside the real text. The Claude
+    // SDK persists the message verbatim — including the marker blocks —
+    // which is what loadSession must filter when it replays.
+    input.push({
+      type: "user",
+      message: {
+        role: "user",
+        content: [
+          { type: "text", text: commandName },
+          { type: "text", text: commandStdout },
+          { type: "text", text: "hi" },
+        ],
+      },
+      session_id: sessionId,
+      parent_tool_use_id: null,
+    });
+
+    for await (const msg of q) {
+      if (msg.type === "result") break;
+    }
+    input.end();
+    q.return(undefined);
+
+    // Sanity check: the SDK transcript contains the metadata we're filtering.
+    const sdkMessages = await getSessionMessages(sessionId);
+    const sdkTexts = sdkMessages
+      .map((m) => {
+        const c = (m as { message?: { content?: unknown } }).message?.content;
+        if (typeof c === "string") return c;
+        if (Array.isArray(c))
+          return c
+            .map((b) =>
+              b && typeof b === "object" && "text" in b
+                ? String((b as { text: unknown }).text)
+                : "",
+            )
+            .join("");
+        return "";
+      })
+      .join("\n");
+    expect(sdkTexts).toContain("<command-name>");
+    expect(sdkTexts).toContain("<local-command-stdout>");
+    expect(sdkTexts).toContain("hi");
+
+    // Step 2: load the session through the ACP agent and confirm the markers
+    // never reach the client as user_message_chunks, while the real "hi"
+    // prompt does.
+    const agent = new ClaudeAcpAgent(client);
+    try {
+      await agent.loadSession({
+        sessionId,
+        cwd: process.cwd(),
+        mcpServers: [],
+      });
+    } finally {
+      await agent.dispose();
+    }
+
+    for (const chunk of recordedUserChunks) {
+      expect(chunk).not.toContain("<command-name>");
+      expect(chunk).not.toContain("<command-message>");
+      expect(chunk).not.toContain("<command-args>");
+      expect(chunk).not.toContain("<local-command-stdout>");
+      expect(chunk).not.toContain("<local-command-stderr>");
+    }
+    expect(recordedUserChunks.some((c) => c.includes("hi"))).toBe(true);
+  }, 60000);
+
+  // Second regression: the original issue showed the markers and the real
+  // "hi" prompt all concatenated into a single string ending with "hi".
+  // loadSession must strip the marker tags in-place rather than dropping the
+  // whole message.
+  it("ACP: loadSession strips marker tags from a concatenated single-string prompt", async () => {
+    const recordedUserChunks: string[] = [];
+    const client = {
+      sessionUpdate: async (notification: SessionNotification) => {
+        if (notification.update.sessionUpdate === "user_message_chunk") {
+          const content = notification.update.content;
+          if (content.type === "text") recordedUserChunks.push(content.text);
+        }
+      },
+      requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+      readTextFile: async () => ({ content: "" }),
+      writeTextFile: async () => ({}),
+    } as unknown as AcpClient;
+
+    // Exact shape from https://github.com/zed-industries/claude-code-acp/issues/579.
+    const concatenated =
+      "<command-name>/model</command-name>\n            <command-message>model</command-message>\n            <command-args>opus</command-args>" +
+      "<local-command-stdout>Set model to opus (claude-opus-4-7)</local-command-stdout>\n" +
+      "<command-name>/model</command-name>\n            <command-message>model</command-message>\n            <command-args>opus[1m]</command-args>" +
+      "<local-command-stdout>Set model to opus[1m] (claude-opus-4-7[1m])</local-command-stdout>" +
+      "hi";
+
+    const sessionId = randomUUID();
+    const input = new Pushable<SDKUserMessage>();
+    const q = query({
+      prompt: input,
+      options: {
+        systemPrompt: { type: "preset", preset: "claude_code" },
+        sessionId,
+        settingSources: ["user", "project", "local"],
+        includePartialMessages: true,
+      },
+    });
+    await q.initializationResult();
+
+    input.push({
+      type: "user",
+      message: { role: "user", content: concatenated },
+      session_id: sessionId,
+      parent_tool_use_id: null,
+    });
+    for await (const msg of q) {
+      if (msg.type === "result") break;
+    }
+    input.end();
+    q.return(undefined);
+
+    const agent = new ClaudeAcpAgent(client);
+    try {
+      await agent.loadSession({
+        sessionId,
+        cwd: process.cwd(),
+        mcpServers: [],
+      });
+    } finally {
+      await agent.dispose();
+    }
+
+    expect(recordedUserChunks.length).toBeGreaterThan(0);
+    for (const chunk of recordedUserChunks) {
+      expect(chunk).not.toContain("<command-name>");
+      expect(chunk).not.toContain("<command-message>");
+      expect(chunk).not.toContain("<command-args>");
+      expect(chunk).not.toContain("<local-command-stdout>");
+      expect(chunk).not.toContain("<local-command-stderr>");
+    }
+    expect(recordedUserChunks.some((c) => c.includes("hi"))).toBe(true);
+  }, 60000);
+});

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 });
   });
 
@@ -52,5 +65,155 @@ describe("SettingsManager", () => {
       settings = settingsManager.getSettings();
       expect(settings.model).toBe("claude-3-5-haiku");
     });
+
+    it("should expose availableModels from settings", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          availableModels: ["claude-haiku-4-5", "claude-opus-4-7[1m]"],
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      const settings = settingsManager.getSettings();
+      expect(settings.availableModels).toEqual(["claude-haiku-4-5", "claude-opus-4-7[1m]"]);
+    });
+
+    it("should union and dedupe availableModels across sources", async () => {
+      // Per Claude Code docs: "When `availableModels` is set at multiple
+      // levels, such as user settings and project settings, arrays are
+      // merged and deduplicated."
+      // https://code.claude.com/docs/en/model-config#merge-behavior
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          availableModels: ["claude-haiku-4-5", "claude-opus-4-7[1m]"],
+        }),
+      );
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.local.json"),
+        JSON.stringify({
+          // claude-opus-4-7[1m] overlaps with project; should be deduped.
+          availableModels: ["claude-opus-4-7[1m]", "claude-sonnet-4-6[1m]"],
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      const settings = settingsManager.getSettings();
+      expect(settings.availableModels).toEqual([
+        "claude-haiku-4-5",
+        "claude-opus-4-7[1m]",
+        "claude-sonnet-4-6[1m]",
+      ]);
+    });
+
+    it("should merge permissions.defaultMode with later sources taking precedence", async () => {
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.json"),
+        JSON.stringify({
+          permissions: {
+            defaultMode: "dontAsk",
+          },
+        }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      let settings = settingsManager.getSettings();
+      expect(settings.permissions?.defaultMode).toBe("dontAsk");
+
+      // Local settings override the mode
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.local.json"),
+        JSON.stringify({
+          permissions: {
+            defaultMode: "plan",
+          },
+        }),
+      );
+
+      settingsManager.dispose();
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      settings = settingsManager.getSettings();
+      expect(settings.permissions?.defaultMode).toBe("plan");
+    });
+  });
+
+  describe("escalating defaultMode trust filter", () => {
+    // The SDK's filterEscalatingDefaultMode drops escalating values
+    // (bypassPermissions / auto / acceptEdits) that came from a repo-committed
+    // tier (.claude/settings.json), preventing a checked-in file from
+    // silently escalating permissions. Local (.claude/settings.local.json)
+    // and user-tier sources are not committed by convention, so escalating
+    // values from those tiers are preserved.
+
+    it.each(["bypassPermissions", "auto", "acceptEdits"] as const)(
+      "drops %s when set in project-tier settings",
+      async (mode) => {
+        const claudeDir = path.join(tempDir, ".claude");
+        await fs.promises.mkdir(claudeDir, { recursive: true });
+
+        await fs.promises.writeFile(
+          path.join(claudeDir, "settings.json"),
+          JSON.stringify({ permissions: { defaultMode: mode } }),
+        );
+
+        settingsManager = new SettingsManager(tempDir);
+        await settingsManager.initialize();
+
+        expect(settingsManager.getSettings().permissions?.defaultMode).toBeUndefined();
+      },
+    );
+
+    it.each(["plan", "dontAsk"] as const)(
+      "preserves non-escalating %s from project-tier settings",
+      async (mode) => {
+        const claudeDir = path.join(tempDir, ".claude");
+        await fs.promises.mkdir(claudeDir, { recursive: true });
+
+        await fs.promises.writeFile(
+          path.join(claudeDir, "settings.json"),
+          JSON.stringify({ permissions: { defaultMode: mode } }),
+        );
+
+        settingsManager = new SettingsManager(tempDir);
+        await settingsManager.initialize();
+
+        expect(settingsManager.getSettings().permissions?.defaultMode).toBe(mode);
+      },
+    );
+
+    it("preserves escalating defaultMode when it comes from local-tier settings", async () => {
+      // settings.local.json is git-ignored by convention, so the trust
+      // filter does not apply.
+      const claudeDir = path.join(tempDir, ".claude");
+      await fs.promises.mkdir(claudeDir, { recursive: true });
+
+      await fs.promises.writeFile(
+        path.join(claudeDir, "settings.local.json"),
+        JSON.stringify({ permissions: { defaultMode: "acceptEdits" } }),
+      );
+
+      settingsManager = new SettingsManager(tempDir);
+      await settingsManager.initialize();
+
+      expect(settingsManager.getSettings().permissions?.defaultMode).toBe("acceptEdits");
+    });
   });
 });

src/tools.ts

@@ -5,6 +5,23 @@ import {
   ToolCallLocation,
   ToolKind,
 } from "@agentclientprotocol/sdk";
+import { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+import {
+  AgentInput,
+  AskUserQuestionInput,
+  BashInput,
+  FileEditInput,
+  FileReadInput,
+  FileWriteInput,
+  GlobInput,
+  GrepInput,
+  TaskCreateInput,
+  TaskCreateOutput,
+  TaskUpdateInput,
+  TodoWriteInput,
+  WebFetchInput,
+  WebSearchInput,
+} from "@anthropic-ai/claude-agent-sdk/sdk-tools.js";
 import {
   ImageBlockParam,
   TextBlockParam,
@@ -14,29 +31,31 @@ import {
   WebSearchToolResultError,
 } from "@anthropic-ai/sdk/resources";
 import {
-  BetaBashCodeExecutionToolResultBlockParam,
   BetaBashCodeExecutionResultBlock,
+  BetaBashCodeExecutionToolResultBlockParam,
   BetaBashCodeExecutionToolResultError,
-  BetaCodeExecutionToolResultBlockParam,
   BetaCodeExecutionResultBlock,
+  BetaCodeExecutionToolResultBlockParam,
   BetaCodeExecutionToolResultError,
+  BetaImageBlockParam,
   BetaRequestMCPToolResultBlockParam,
-  BetaTextEditorCodeExecutionToolResultBlockParam,
-  BetaTextEditorCodeExecutionViewResultBlock,
   BetaTextEditorCodeExecutionCreateResultBlock,
   BetaTextEditorCodeExecutionStrReplaceResultBlock,
+  BetaTextEditorCodeExecutionToolResultBlockParam,
   BetaTextEditorCodeExecutionToolResultError,
+  BetaTextEditorCodeExecutionViewResultBlock,
+  BetaToolReferenceBlock,
   BetaToolResultBlockParam,
   BetaToolSearchToolResultBlockParam,
-  BetaToolReferenceBlock,
-  BetaToolSearchToolSearchResultBlock,
   BetaToolSearchToolResultError,
-  BetaWebFetchToolResultBlockParam,
+  BetaToolSearchToolSearchResultBlock,
   BetaWebFetchBlock,
+  BetaWebFetchToolResultBlockParam,
   BetaWebFetchToolResultErrorBlock,
   BetaWebSearchToolResultBlockParam,
-  BetaImageBlockParam,
 } from "@anthropic-ai/sdk/resources/beta.mjs";
+import path from "node:path";
+import { Logger } from "./acp-agent.js";
 
 /**
  * Union of all possible content types that can appear in tool results from the Anthropic SDK.
@@ -61,20 +80,6 @@ type ToolResultContent =
   | BetaTextEditorCodeExecutionCreateResultBlock
   | BetaTextEditorCodeExecutionStrReplaceResultBlock
   | BetaTextEditorCodeExecutionToolResultError;
-import { HookCallback } from "@anthropic-ai/claude-agent-sdk";
-import { Logger } from "./acp-agent.js";
-import {
-  AgentInput,
-  BashInput,
-  FileEditInput,
-  FileReadInput,
-  FileWriteInput,
-  GlobInput,
-  GrepInput,
-  TodoWriteInput,
-  WebFetchInput,
-  WebSearchInput,
-} from "@anthropic-ai/claude-agent-sdk/sdk-tools.js";
 
 interface ToolInfo {
   title: string;
@@ -103,15 +108,31 @@ interface ToolUpdate {
   };
 }
 
+/**
+ * Convert an absolute file path to a project-relative path for display.
+ * Returns the original path if it's outside the project directory or if no cwd is provided.
+ */
+export function toDisplayPath(filePath: string, cwd?: string): string {
+  if (!cwd) return filePath;
+  const resolvedCwd = path.resolve(cwd);
+  const resolvedFile = path.resolve(filePath);
+  if (resolvedFile.startsWith(resolvedCwd + path.sep) || resolvedFile === resolvedCwd) {
+    return path.relative(resolvedCwd, resolvedFile);
+  }
+  return filePath;
+}
+
 export function toolInfoFromToolUse(
   toolUse: any,
   supportsTerminalOutput: boolean = false,
+  cwd?: string,
 ): ToolInfo {
   const name = toolUse.name;
 
   switch (name) {
+    case "Agent":
     case "Task": {
-      const input = toolUse.input as AgentInput | BashInput;
+      const input = toolUse.input as AgentInput | BashInput | undefined;
       return {
         title: input?.description ? input.description : "Task",
         kind: "think",
@@ -128,7 +149,7 @@ export function toolInfoFromToolUse(
     }
 
     case "Bash": {
-      const input = toolUse.input as BashInput;
+      const input = toolUse.input as BashInput | undefined;
       return {
         title: input?.command ? input.command : "Terminal",
         kind: "execute",
@@ -146,17 +167,18 @@ export function toolInfoFromToolUse(
     }
 
     case "Read": {
-      const input = toolUse.input as FileReadInput;
+      const input = toolUse.input as FileReadInput | undefined;
       let limit = "";
-      if (input.limit && input.limit > 0) {
+      if (input?.limit && input.limit > 0) {
         limit = " (" + (input.offset ?? 1) + " - " + ((input.offset ?? 1) + input.limit - 1) + ")";
-      } else if (input.offset) {
+      } else if (input?.offset) {
         limit = " (from line " + input.offset + ")";
       }
+      const displayPath = input?.file_path ? toDisplayPath(input.file_path, cwd) : "File";
       return {
-        title: "Read " + (input.file_path ?? "File") + limit,
+        title: "Read " + displayPath + limit,
         kind: "read",
-        locations: input.file_path
+        locations: input?.file_path
           ? [
               {
                 path: input.file_path,
@@ -169,7 +191,7 @@ export function toolInfoFromToolUse(
     }
 
     case "Write": {
-      const input = toolUse.input as FileWriteInput;
+      const input = toolUse.input as FileWriteInput | undefined;
       let content: ToolCallContent[] = [];
       if (input && input.file_path) {
         content = [
@@ -188,8 +210,9 @@ export function toolInfoFromToolUse(
           },
         ];
       }
+      const displayPath = input?.file_path ? toDisplayPath(input.file_path, cwd) : undefined;
       return {
-        title: input?.file_path ? `Write ${input.file_path}` : "Write",
+        title: displayPath ? `Write ${displayPath}` : "Write",
         kind: "edit",
         content,
         locations: input?.file_path ? [{ path: input.file_path }] : [],
@@ -197,7 +220,7 @@ export function toolInfoFromToolUse(
     }
 
     case "Edit": {
-      const input = toolUse.input as FileEditInput;
+      const input = toolUse.input as FileEditInput | undefined;
       let content: ToolCallContent[] = [];
       if (input && input.file_path && (input.old_string || input.new_string)) {
         content = [
@@ -209,8 +232,9 @@ export function toolInfoFromToolUse(
           },
         ];
       }
+      const displayPath = input?.file_path ? toDisplayPath(input.file_path, cwd) : undefined;
       return {
-        title: input?.file_path ? `Edit ${input.file_path}` : "Edit",
+        title: displayPath ? `Edit ${displayPath}` : "Edit",
         kind: "edit",
         content,
         locations: input?.file_path ? [{ path: input.file_path }] : [],
@@ -218,44 +242,44 @@ export function toolInfoFromToolUse(
     }
 
     case "Glob": {
-      const input = toolUse.input as GlobInput;
+      const input = toolUse.input as GlobInput | undefined;
       let label = "Find";
-      if (input.path) {
+      if (input?.path) {
         label += ` \`${input.path}\``;
       }
-      if (input.pattern) {
+      if (input?.pattern) {
         label += ` \`${input.pattern}\``;
       }
       return {
         title: label,
         kind: "search",
         content: [],
-        locations: input.path ? [{ path: input.path }] : [],
+        locations: input?.path ? [{ path: input.path }] : [],
       };
     }
 
     case "Grep": {
-      const input = toolUse.input as GrepInput;
+      const input = toolUse.input as GrepInput | undefined;
       let label = "grep";
 
-      if (input["-i"]) {
+      if (input?.["-i"]) {
         label += " -i";
       }
-      if (input["-n"]) {
+      if (input?.["-n"]) {
         label += " -n";
       }
 
-      if (input["-A"] !== undefined) {
+      if (input?.["-A"] !== undefined) {
         label += ` -A ${input["-A"]}`;
       }
-      if (input["-B"] !== undefined) {
+      if (input?.["-B"] !== undefined) {
         label += ` -B ${input["-B"]}`;
       }
-      if (input["-C"] !== undefined) {
+      if (input?.["-C"] !== undefined) {
         label += ` -C ${input["-C"]}`;
       }
 
-      if (input.output_mode) {
+      if (input?.output_mode) {
         switch (input.output_mode) {
           case "files_with_matches":
             label += " -l";
@@ -269,27 +293,27 @@ export function toolInfoFromToolUse(
         }
       }
 
-      if (input.head_limit !== undefined) {
+      if (input?.head_limit !== undefined) {
         label += ` | head -${input.head_limit}`;
       }
 
-      if (input.glob) {
+      if (input?.glob) {
         label += ` --include="${input.glob}"`;
       }
 
-      if (input.type) {
+      if (input?.type) {
         label += ` --type=${input.type}`;
       }
 
-      if (input.multiline) {
+      if (input?.multiline) {
         label += " -P";
       }
 
-      if (input.pattern) {
+      if (input?.pattern) {
         label += ` "${input.pattern}"`;
       }
 
-      if (input.path) {
+      if (input?.path) {
         label += ` ${input.path}`;
       }
 
@@ -318,14 +342,14 @@ export function toolInfoFromToolUse(
     }
 
     case "WebSearch": {
-      const input = toolUse.input as WebSearchInput;
-      let label = `"${input.query}"`;
+      const input = toolUse.input as WebSearchInput | undefined;
+      let label = input?.query ? `"${input.query}"` : "Web search";
 
-      if (input.allowed_domains && input.allowed_domains.length > 0) {
+      if (input?.allowed_domains && input.allowed_domains.length > 0) {
         label += ` (allowed: ${input.allowed_domains.join(", ")})`;
       }
 
-      if (input.blocked_domains && input.blocked_domains.length > 0) {
+      if (input?.blocked_domains && input.blocked_domains.length > 0) {
         label += ` (blocked: ${input.blocked_domains.join(", ")})`;
       }
 
@@ -337,7 +361,7 @@ export function toolInfoFromToolUse(
     }
 
     case "TodoWrite": {
-      const input = toolUse.input as TodoWriteInput;
+      const input = toolUse.input as TodoWriteInput | undefined;
       return {
         title: Array.isArray(input?.todos)
           ? `Update TODOs: ${input.todos.map((todo: any) => todo.content).join(", ")}`
@@ -347,11 +371,66 @@ export function toolInfoFromToolUse(
       };
     }
 
+    case "TaskCreate": {
+      const input = toolUse.input as TaskCreateInput | undefined;
+      return {
+        title: input?.subject ? `Create task: ${input.subject}` : "Create task",
+        kind: "think",
+        content: [],
+      };
+    }
+
+    case "TaskUpdate": {
+      const input = toolUse.input as TaskUpdateInput | undefined;
+      return {
+        title: input?.subject ? `Update task: ${input.subject}` : "Update task",
+        kind: "think",
+        content: [],
+      };
+    }
+
+    case "TaskList": {
+      return {
+        title: "List tasks",
+        kind: "think",
+        content: [],
+      };
+    }
+
+    case "TaskGet": {
+      return {
+        title: "Get task",
+        kind: "think",
+        content: [],
+      };
+    }
+
     case "ExitPlanMode": {
+      const planInput = toolUse.input as { plan?: string } | undefined;
       return {
         title: "Ready to code?",
         kind: "switch_mode",
-        content: [],
+        content: planInput?.plan
+          ? [{ type: "content" as const, content: { type: "text" as const, text: planInput.plan } }]
+          : [],
+      };
+    }
+
+    case "AskUserQuestion": {
+      const input = toolUse.input as Partial<AskUserQuestionInput> | undefined;
+      const questions = Array.isArray(input?.questions) ? input.questions : [];
+      return {
+        title:
+          questions.length === 1 && questions[0]?.question
+            ? questions[0].question
+            : "Asking for your input",
+        kind: "other",
+        content: questions
+          .filter((q) => typeof q?.question === "string")
+          .map((q) => ({
+            type: "content" as const,
+            content: { type: "text" as const, text: q.question },
+          })),
       };
     }
 
@@ -406,7 +485,8 @@ export function toolUpdateFromToolResult(
     "is_error" in toolResult &&
     toolResult.is_error &&
     toolResult.content &&
-    toolResult.content.length > 0
+    toolResult.content.length > 0 &&
+    !(toolUse?.name === "Bash" && supportsTerminalOutput)
   ) {
     // Only return errors
     return toAcpContentUpdate(toolResult.content, true);
@@ -450,7 +530,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;
 
@@ -461,17 +543,24 @@ export function toolUpdateFromToolResult(
         result.type === "bash_code_execution_result"
       ) {
         const bashResult = result as BetaBashCodeExecutionResultBlock;
-        output = bashResult.stdout || bashResult.stderr || "";
+        output = [bashResult.stdout, bashResult.stderr].filter(Boolean).join("\n");
         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) {
@@ -638,10 +727,107 @@ export type ClaudePlanEntry = {
   activeForm: string;
 };
 
-export function planEntries(input: { todos: ClaudePlanEntry[] }): PlanEntry[] {
-  return input.todos.map((input) => ({
-    content: input.content,
-    status: input.status,
+export function planEntries(input: { todos: ClaudePlanEntry[] } | undefined): PlanEntry[] {
+  return (input?.todos ?? []).map((todo) => ({
+    content: todo.content,
+    status: todo.status,
+    priority: "medium",
+  }));
+}
+
+/**
+ * Per-session task list accumulated from Task* tool calls (TaskCreate /
+ * TaskUpdate). The headless/SDK session emits these as incremental tool
+ * calls keyed by task ID, replacing the snapshot-style TodoWrite tool.
+ * Iteration order is insertion order (Map semantics), matching the order
+ * tasks are created.
+ */
+export type TaskEntry = {
+  subject: string;
+  status: "pending" | "in_progress" | "completed";
+  activeForm?: string;
+  description?: string;
+};
+export type TaskState = Map<string, TaskEntry>;
+
+/**
+ * Best-effort parse of a TaskCreate tool_result content into the structured
+ * TaskCreateOutput. The SDK delivers tool outputs either as a string or as
+ * an array of TextBlockParam-like blocks containing JSON text; try both.
+ */
+export function parseTaskCreateOutput(content: unknown): TaskCreateOutput | undefined {
+  const tryParse = (text: string): TaskCreateOutput | undefined => {
+    try {
+      const parsed = JSON.parse(text);
+      if (
+        parsed &&
+        typeof parsed === "object" &&
+        parsed.task &&
+        typeof parsed.task.id === "string"
+      ) {
+        return parsed as TaskCreateOutput;
+      }
+    } catch {
+      // ignore
+    }
+    return undefined;
+  };
+
+  if (typeof content === "string") {
+    return tryParse(content);
+  }
+  if (Array.isArray(content)) {
+    for (const block of content) {
+      if (block && typeof block === "object" && "type" in block && block.type === "text") {
+        const text = (block as { text?: unknown }).text;
+        if (typeof text === "string") {
+          const parsed = tryParse(text);
+          if (parsed) return parsed;
+        }
+      }
+    }
+  }
+  return undefined;
+}
+
+export function applyTaskCreate(
+  state: TaskState,
+  input: TaskCreateInput | undefined,
+  output: TaskCreateOutput | undefined,
+): void {
+  const taskId = output?.task?.id;
+  if (!taskId || !input) return;
+  state.set(taskId, {
+    subject: input.subject,
+    status: "pending",
+    activeForm: input.activeForm,
+    description: input.description,
+  });
+}
+
+export function applyTaskUpdate(state: TaskState, input: TaskUpdateInput | undefined): void {
+  if (!input?.taskId) return;
+  if (input.status === "deleted") {
+    state.delete(input.taskId);
+    return;
+  }
+  const existing = state.get(input.taskId);
+  // Without a subject from either the existing entry or the update payload,
+  // we'd produce a plan entry with empty `content` — drop the update.
+  const subject = input.subject ?? existing?.subject;
+  if (!subject) return;
+  state.set(input.taskId, {
+    subject,
+    status: input.status ?? existing?.status ?? "pending",
+    activeForm: input.activeForm ?? existing?.activeForm,
+    description: input.description ?? existing?.description,
+  });
+}
+
+export function taskStateToPlanEntries(state: TaskState): PlanEntry[] {
+  return Array.from(state.values()).map((task) => ({
+    content: task.subject,
+    status: task.status,
     priority: "medium",
   }));
 }
@@ -656,7 +842,7 @@ export function markdownEscape(text: string): string {
   return escape + "\n" + text + (text.endsWith("\n") ? "" : "\n") + escape;
 }
 
-interface EditToolResponseHunk {
+interface DiffToolResponseHunk {
   oldStart: number;
   oldLines: number;
   newStart: number;
@@ -664,23 +850,24 @@ interface EditToolResponseHunk {
   lines: string[];
 }
 
-interface EditToolResponse {
+interface DiffToolResponse {
   filePath?: string;
-  structuredPatch?: EditToolResponseHunk[];
+  structuredPatch?: DiffToolResponseHunk[];
 }
 
 /**
- * Builds diff ToolUpdate content from the structured Edit toolResponse provided
- * by the PostToolUse hook. Unlike parsing the plain unified diff string, this uses
- * the pre-parsed structuredPatch which supports multiple replacement sites (replaceAll)
- * and always includes context lines for better readability.
+ * Builds diff ToolUpdate content from the structured toolResponse provided by
+ * the PostToolUse hook for diff-producing tools (Edit, Write). Unlike parsing
+ * the plain unified diff string, this uses the pre-parsed structuredPatch
+ * which supports multiple replacement sites (replaceAll) and always includes
+ * context lines for better readability.
  */
-export function toolUpdateFromEditToolResponse(toolResponse: unknown): {
+export function toolUpdateFromDiffToolResponse(toolResponse: unknown): {
   content?: ToolCallContent[];
   locations?: ToolCallLocation[];
 } {
   if (!toolResponse || typeof toolResponse !== "object") return {};
-  const response = toolResponse as EditToolResponse;
+  const response = toolResponse as DiffToolResponse;
   if (!response.filePath || !Array.isArray(response.structuredPatch)) return {};
 
   const content: ToolCallContent[] = [];
@@ -773,3 +960,38 @@ export const createPostToolUseHook =
     }
     return { continue: true };
   };
+
+/**
+ * Hook callback for `TaskCreated` / `TaskCompleted` events. The SDK fires
+ * these for both user-facing TaskCreate tool calls and subagent task
+ * creation, giving us `task_id` + `task_subject` without having to parse
+ * tool_result payloads.
+ *
+ * Populating `taskState` from the hook means a later `TaskUpdate` (which
+ * typically only carries `taskId` + `status`) finds an existing entry with
+ * a real subject, instead of synthesizing a placeholder with empty content.
+ */
+export const createTaskHook =
+  (options: { taskState: TaskState; onChange?: () => Promise<void> }): HookCallback =>
+  async (input): Promise<{ continue: boolean }> => {
+    const taskId =
+      "task_id" in input && typeof input.task_id === "string" ? input.task_id : undefined;
+    if (!taskId) return { continue: true };
+
+    if (input.hook_event_name === "TaskCreated") {
+      if (!input.task_subject) return { continue: true };
+      if (options.taskState.has(taskId)) return { continue: true };
+      options.taskState.set(taskId, {
+        subject: input.task_subject,
+        status: "pending",
+        description: input.task_description,
+      });
+      if (options.onChange) await options.onChange();
+    } else if (input.hook_event_name === "TaskCompleted") {
+      const existing = options.taskState.get(taskId);
+      if (!existing || existing.status === "completed") return { continue: true };
+      options.taskState.set(taskId, { ...existing, status: "completed" });
+      if (options.onChange) await options.onChange();
+    }
+    return { continue: true };
+  };

src/utils.ts

@@ -2,9 +2,7 @@
 
 import { Readable, Writable } from "node:stream";
 import { WritableStream, ReadableStream } from "node:stream/web";
-import { readFileSync } from "node:fs";
 import { Logger } from "./acp-agent.js";
-import { ClaudeCodeSettings, getManagedSettingsPath } from "./settings.js";
 
 // Useful for bridging push-based and async-iterator-based code.
 export class Pushable<T> implements AsyncIterable<T> {
@@ -89,26 +87,3 @@ export function unreachable(value: never, logger: Logger = console) {
 export function sleep(time: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, time));
 }
-
-export function loadManagedSettings(): ClaudeCodeSettings | null {
-  try {
-    return JSON.parse(readFileSync(getManagedSettingsPath(), "utf8")) as ClaudeCodeSettings;
-  } catch {
-    return null;
-  }
-}
-
-export function applyEnvironmentSettings(settings: ClaudeCodeSettings): void {
-  if (settings.env) {
-    for (const [key, value] of Object.entries(settings.env)) {
-      process.env[key] = value;
-    }
-  }
-}
-
-// Helper to encode a path like Claude does:
-// - Unix: "/Users/test" -> "-Users-test"
-// - Windows: "C:\Users\test" -> "C--Users-test"
-export function encodeProjectPath(cwd: string): string {
-  return cwd.replace(/[^a-zA-Z0-9]/g, "-");
-}

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,