chore(main): release 0.44.0 (#759)

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


##
[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](7a701623df))
* **deps:** update to @anthropic-ai/claude-agent-sdk 0.3.170
([#761](https://github.com/agentclientprotocol/claude-agent-acp/issues/761))
([d8af943](d8af943a1e))

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

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

.github/dependabot.yml

@@ -8,7 +8,7 @@ updates:
   - package-ecosystem: "npm"
     directory: "/"
     schedule:
-      interval: "weekly"
+      interval: "daily"
     allow:
       - dependency-type: "all"
     groups:

.github/workflows/ci.yml

@@ -21,10 +21,10 @@ jobs:
     timeout-minutes: 5
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10
 
       - name: Use Node.js
-        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
         with:
           node-version: "lts/*"
           cache: "npm"

.github/workflows/publish.yml

@@ -16,14 +16,14 @@ jobs:
       # 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@f8d387b68d61c58ab83c6c016672934102569859
+        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@16a9c90856f42705d54a6fda1823352bdc62cf38
+      - uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7
         id: release
         with:
           token: ${{ steps.generate-token.outputs.token }}
@@ -34,89 +34,19 @@ jobs:
       release_created: ${{ steps.release.outputs.release_created }}
       tag_name: ${{ steps.release.outputs.tag_name }}
 
-  build-binaries:
-    name: Build (${{ matrix.target }})
-    runs-on: ubuntu-latest
-    needs: [release-please]
-    if: ${{ needs.release-please.outputs.release_created }}
-    permissions:
-      contents: read
-    timeout-minutes: 15
-
-    strategy:
-      fail-fast: true
-      matrix:
-        include:
-          - target: bun-linux-x64
-            artifact: claude-agent-acp
-            archive: claude-agent-acp-linux-x64.tar.gz
-          - target: bun-linux-arm64
-            artifact: claude-agent-acp
-            archive: claude-agent-acp-linux-arm64.tar.gz
-          - target: bun-linux-x64-musl
-            artifact: claude-agent-acp
-            archive: claude-agent-acp-linux-x64-musl.tar.gz
-          - target: bun-linux-arm64-musl
-            artifact: claude-agent-acp
-            archive: claude-agent-acp-linux-arm64-musl.tar.gz
-          - target: bun-darwin-x64
-            artifact: claude-agent-acp
-            archive: claude-agent-acp-darwin-x64.zip
-          - target: bun-darwin-arm64
-            artifact: claude-agent-acp
-            archive: claude-agent-acp-darwin-arm64.zip
-          - target: bun-windows-x64
-            artifact: claude-agent-acp.exe
-            archive: claude-agent-acp-windows-x64.zip
-          - target: bun-windows-arm64
-            artifact: claude-agent-acp.exe
-            archive: claude-agent-acp-windows-arm64.zip
-
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
-
-      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6
-        with:
-          bun-version: latest
-
-      - name: Install dependencies
-        run: bun install
-
-      - name: Build binary
-        run: |
-          bun build src/index.ts \
-            --compile \
-            --target ${{ matrix.target }} \
-            --define 'process.env.CLAUDE_AGENT_ACP_IS_SINGLE_FILE_BUN="true"' \
-            --outfile ${{ matrix.artifact }}
-
-      - name: Compress binary
-        run: |
-          if [[ "${{ matrix.archive }}" == *.zip ]]; then
-            zip ${{ matrix.archive }} ${{ matrix.artifact }}
-          else
-            tar czf ${{ matrix.archive }} ${{ matrix.artifact }}
-          fi
-
-      - name: Upload artifact
-        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f
-        with:
-          name: ${{ matrix.archive }}
-          path: ${{ matrix.archive }}
-
   publish-npm:
     name: Publish to npm
     runs-on: ubuntu-latest
-    needs: [build-binaries, release-please]
+    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@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10
       # Setup .npmrc file to publish to npm
-      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
         with:
           node-version: "lts/*"
           registry-url: "https://registry.npmjs.org"
@@ -125,30 +55,3 @@ jobs:
       - run: npm ci
       - run: npm run build
       - run: npm publish
-
-  release:
-    name: Create Release
-    runs-on: ubuntu-latest
-    needs: [build-binaries, publish-npm, release-please]
-    if: ${{ needs.release-please.outputs.release_created }}
-    permissions:
-      contents: write
-
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
-
-      - name: Download all artifacts
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c
-        with:
-          path: artifacts
-          merge-multiple: true
-
-      - name: Upload artifacts
-        shell: bash
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          gh release upload \
-            "${{ needs.release-please.outputs.tag_name }}" \
-            artifacts/* \
-            --clobber

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.25.0"
+  ".": "0.44.0"
 }

CHANGELOG.md

@@ -1,5 +1,323 @@
 # Changelog
 
+## [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)
 
 

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.

package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.25.0",
+  "version": "0.44.0",
   "description": "An ACP-compatible coding agent powered by the Claude Agent SDK (TypeScript)",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
@@ -60,22 +60,22 @@
   "author": "Zed Industries",
   "license": "Apache-2.0",
   "dependencies": {
-    "@agentclientprotocol/sdk": "0.18.0",
-    "@anthropic-ai/claude-agent-sdk": "0.2.91",
+    "@agentclientprotocol/sdk": "0.25.0",
+    "@anthropic-ai/claude-agent-sdk": "0.3.170",
     "zod": "^3.25.0 || ^4.0.0"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "0.82.0",
+    "@anthropic-ai/sdk": "0.103.0",
     "@eslint/js": "10.0.1",
-    "@types/node": "25.5.1",
-    "@typescript-eslint/eslint-plugin": "8.58.0",
-    "@typescript-eslint/parser": "8.58.0",
-    "eslint": "10.1.0",
+    "@types/node": "25.9.2",
+    "@typescript-eslint/eslint-plugin": "8.61.0",
+    "@typescript-eslint/parser": "8.61.0",
+    "eslint": "10.4.1",
     "eslint-config-prettier": "10.1.8",
-    "globals": "17.4.0",
-    "prettier": "3.8.1",
+    "globals": "17.6.0",
+    "prettier": "3.8.4",
     "ts-node": "10.9.2",
-    "typescript": "6.0.2",
-    "vitest": "4.1.2"
+    "typescript": "6.0.3",
+    "vitest": "4.1.8"
   }
 }

src/elicitation.ts

@@ -0,0 +1,249 @@
+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 optional free-text "custom answer" field. */
+const CUSTOM_ANSWER_FIELD = "customAnswer";
+
+/**
+ * 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.
+ *
+ * A trailing optional free-text field mirrors the CLI's custom-answer box: the
+ * user can type their own answer instead of (or as well as) picking an option.
+ * 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: option.label,
+      title: option.description ? `${option.label} — ${option.description}` : option.label,
+    }));
+
+    // 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[CUSTOM_ANSWER_FIELD] = {
+    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. Free text from the custom-
+ * answer field becomes the tool's top-level `response`. 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) => {
+    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;
+  });
+
+  const updatedInput: Record<string, unknown> = { ...toolInput, answers };
+  const custom = content[CUSTOM_ANSWER_FIELD];
+  if (typeof custom === "string" && custom.trim() !== "") {
+    const response: AskUserQuestionOutput["response"] = custom;
+    updatedInput.response = response;
+  }
+
+  return { action: "answered", updatedInput };
+}
+
+/**
+ * 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,16 +1,46 @@
 #!/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";
 
 if (process.argv.includes("--cli")) {
-  process.argv = process.argv.filter((arg) => arg !== "--cli");
-  await import(await claudeCliPath());
+  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 {
-  const managedSettings = loadManagedSettings();
-  if (managedSettings) {
-    applyEnvironmentSettings(managedSettings);
+  // 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
@@ -24,8 +54,23 @@ if (process.argv.includes("--cli")) {
     console.error("Unhandled Rejection at:", promise, "reason:", reason);
   });
 
-  runAcp();
+  const { connection, agent } = runAcp();
 
-  // Keep process alive
+  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();
 }

src/lib.ts

@@ -1,31 +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 {
-  loadManagedSettings,
-  applyEnvironmentSettings,
-  nodeToWebReadable,
-  nodeToWebWritable,
-  Pushable,
-  unreachable,
-} from "./utils.js";
+export { nodeToWebReadable, nodeToWebWritable, Pushable, unreachable } from "./utils.js";
 export {
   toolInfoFromToolUse,
   toDisplayPath,
   planEntries,
   toolUpdateFromToolResult,
 } from "./tools.js";
-export {
-  SettingsManager,
-  type ClaudeCodeSettings,
-  type SettingsManagerOptions,
-} from "./settings.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,50 +21,10 @@ import { CLAUDE_CONFIG_DIR } from "./acp-agent.js";
  * Docs: https://code.claude.com/docs/en/iam#tool-specific-permission-rules
  */
 
-export interface PermissionSettings {
-  defaultMode?: string;
-}
-
-export interface ClaudeCodeSettings {
-  permissions?: PermissionSettings;
-  env?: Record<string, string>;
-  model?: string;
-}
-
-/**
- * Reads and parses a JSON settings file, returning an empty object if not found or invalid.
- * Silently ignores missing files (ENOENT) but logs warnings for other errors
- * (malformed JSON, permission errors, etc.) to aid debugging.
- */
-async function loadSettingsFile(
-  filePath: string | null,
-  logger?: { error: (...args: any[]) => void },
-): Promise<ClaudeCodeSettings> {
-  if (!filePath) {
-    return {};
-  }
-
-  try {
-    const content = await fs.promises.readFile(filePath, "utf-8");
-    return JSON.parse(content) as ClaudeCodeSettings;
-  } catch (error) {
-    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-      return {};
-    }
-    logger?.error(`Failed to load settings from ${filePath}:`, error);
-    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:
@@ -71,23 +38,17 @@ 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 };
@@ -125,94 +86,37 @@ export class SettingsManager {
   }
 
   /**
-   * Returns the path to the user settings file
+   * 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 getUserSettingsPath(): string {
-    return path.join(CLAUDE_CONFIG_DIR, "settings.json");
+  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(),
+    ];
   }
 
   /**
-   * 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
+   * Resolves the effective settings via the SDK and applies the CLI's trust
+   * filter for escalating `permissions.defaultMode` values.
    */
   private async loadAllSettings(): Promise<void> {
-    const [userSettings, projectSettings, localSettings, enterpriseSettings] = await Promise.all([
-      loadSettingsFile(this.getUserSettingsPath(), this.logger),
-      loadSettingsFile(this.getProjectSettingsPath(), this.logger),
-      loadSettingsFile(this.getLocalSettingsPath(), this.logger),
-      loadSettingsFile(getManagedSettingsPath(), this.logger),
-    ]);
-
-    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 (settings.permissions?.defaultMode !== undefined) {
-        merged.permissions = {
-          ...merged.permissions,
-          defaultMode: settings.permissions.defaultMode,
-        };
-      }
+    try {
+      const resolved = await resolveSettings({ cwd: this.cwd });
+      this.effective = filterEscalatingDefaultMode(resolved);
+    } catch (error) {
+      this.logger.error("Failed to resolve settings:", error);
+      this.effective = {};
     }
-
-    this.mergedSettings = merged;
   }
 
   /**
    * 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);
@@ -263,8 +167,8 @@ export class SettingsManager {
   /**
    * Returns the current merged settings
    */
-  getSettings(): ClaudeCodeSettings {
-    return this.mergedSettings;
+  getSettings(): Settings {
+    return this.effective;
   }
 
   /**

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

@@ -39,7 +39,7 @@ describe("ClaudeAcpAgent settings", () => {
         initializationResult: async () => ({
           models: [
             {
-              value: "claude-sonnet-4-5",
+              value: "claude-sonnet-4-6",
               displayName: "Claude Sonnet 4.5",
               description: "Default",
             },
@@ -126,6 +126,31 @@ describe("ClaudeAcpAgent settings", () => {
     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 });
@@ -145,12 +170,12 @@ describe("ClaudeAcpAgent settings", () => {
     expect(response.modes.currentModeId).toBe("default");
   });
 
-  it("throws when permissions.defaultMode is not a string", async () => {
+  it("falls back to 'default' when permissions.defaultMode is invalid", async () => {
     await fs.promises.writeFile(
       path.join(tempDir, "settings.json"),
       JSON.stringify({
         permissions: {
-          defaultMode: 123,
+          defaultMode: "not-a-real-mode",
         },
       }),
     );
@@ -158,18 +183,523 @@ describe("ClaudeAcpAgent settings", () => {
     const projectDir = path.join(tempDir, "project");
     await fs.promises.mkdir(projectDir, { recursive: true });
 
-    mockQuery();
+    const { getCapturedOptions } = mockQuery();
 
     const { ClaudeAcpAgent } = await import("../acp-agent.js");
     const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
 
-    await expect(
-      (agent as any).createSession({
+    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 },
-      }),
-    ).rejects.toThrow("Invalid permissions.defaultMode");
+      });
+
+      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("resolves model aliases like opus[1m] to the correct model", async () => {
@@ -215,6 +745,102 @@ describe("ClaudeAcpAgent settings", () => {
     });
 
     expect(setModelSpy).toHaveBeenCalledWith("claude-opus-4-6-1m");
-    expect(response.models.currentModelId).toBe("claude-opus-4-6-1m");
+    expect(response.configOptions?.find((o: any) => o.id === "model")?.currentValue).toBe(
+      "claude-opus-4-6-1m",
+    );
+  });
+
+  it("skips the initial setModel when the resolved value matches the SDK's model list verbatim", async () => {
+    // Covers the launcher case from PR #646: the launcher bakes the model into
+    // ANTHROPIC_MODEL, the SDK already starts on that model, and a second
+    // setModel call would be a redundant round-trip (and on some launcher
+    // setups, more fragile than launch-time selection).
+    const originalEnv = process.env.ANTHROPIC_MODEL;
+    process.env.ANTHROPIC_MODEL = "claude-opus-4-6";
+
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(projectDir, { recursive: true });
+
+    const setModelSpy = vi.fn();
+    querySpy.mockImplementation(() => {
+      return {
+        initializationResult: async () => ({
+          models: [
+            { value: "default", displayName: "Default", description: "" },
+            { value: "claude-sonnet-4-6", displayName: "Claude Sonnet 4.6", description: "" },
+            { value: "claude-opus-4-6", displayName: "Claude Opus 4.6", description: "" },
+          ],
+        }),
+        setModel: setModelSpy,
+        supportedCommands: async () => [],
+      } as any;
+    });
+
+    try {
+      const { ClaudeAcpAgent } = await import("../acp-agent.js");
+      const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+      const response = await (agent as any).createSession({
+        cwd: projectDir,
+        mcpServers: [],
+        _meta: { disableBuiltInTools: true },
+      });
+
+      expect(setModelSpy).not.toHaveBeenCalled();
+      expect(response.configOptions?.find((o: any) => o.id === "model")?.currentValue).toBe(
+        "claude-opus-4-6",
+      );
+    } finally {
+      if (originalEnv === undefined) {
+        delete process.env.ANTHROPIC_MODEL;
+      } else {
+        process.env.ANTHROPIC_MODEL = originalEnv;
+      }
+    }
+  });
+
+  it("still calls setModel when the allowlist synthesizes a value the SDK has not surfaced", async () => {
+    // The allowlist may rewrite a model's `value` to the user's literal ID
+    // (e.g., `claude-haiku-4-5`) even when the SDK only exposed an alias
+    // (`haiku`). In that case the SDK has not independently arrived at the
+    // user's preferred ID, so we must sync via setModel.
+    await fs.promises.writeFile(
+      path.join(tempDir, "settings.json"),
+      JSON.stringify({
+        availableModels: ["claude-haiku-4-5"],
+        model: "claude-haiku-4-5",
+      }),
+    );
+
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(projectDir, { recursive: true });
+
+    const setModelSpy = vi.fn();
+    querySpy.mockImplementation(() => {
+      return {
+        initializationResult: async () => ({
+          models: [
+            { value: "default", displayName: "Default", description: "" },
+            { value: "haiku", displayName: "Haiku", description: "Fast" },
+          ],
+        }),
+        setModel: setModelSpy,
+        supportedCommands: async () => [],
+      } as any;
+    });
+
+    const { ClaudeAcpAgent } = await import("../acp-agent.js");
+    const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+    const response = await (agent as any).createSession({
+      cwd: projectDir,
+      mcpServers: [],
+      _meta: { disableBuiltInTools: true },
+    });
+
+    expect(setModelSpy).toHaveBeenCalledWith("claude-haiku-4-5");
+    expect(response.configOptions?.find((o: any) => o.id === "model")?.currentValue).toBe(
+      "claude-haiku-4-5",
+    );
   });
 });

src/tests/additional-roots.test.ts

@@ -15,9 +15,17 @@ vi.mock("@anthropic-ai/claude-agent-sdk", async () => ({
     capturedOptions = options;
     return {
       initializationResult: async () => ({
-        models: [{ value: "claude-sonnet-4-5", displayName: "Claude Sonnet", description: "Fast" }],
+        models: [
+          {
+            value: "claude-sonnet-4-6",
+            displayName: "Claude Sonnet",
+            description: "Fast",
+            supportsAutoMode: true,
+          },
+        ],
       }),
       setModel: async () => {},
+      setPermissionMode: async () => {},
       supportedCommands: async () => [],
       [Symbol.asyncIterator]: async function* () {},
     };
@@ -31,7 +39,7 @@ vi.mock("../tools.js", async () => ({
 describe("additionalRoots", () => {
   let agent: ClaudeAcpAgentType;
   const tempDirs: string[] = [];
-  const newSession = (meta: Record<string, unknown>, cwd = "/test") =>
+  const newSession = (meta: Record<string, unknown>, cwd = process.cwd()) =>
     agent.newSession({ cwd, mcpServers: [], _meta: meta });
 
   beforeEach(async () => {
@@ -68,4 +76,33 @@ describe("additionalRoots", () => {
     });
     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/authorization.test.ts

@@ -5,14 +5,20 @@ import { AgentSideConnection } from "@agentclientprotocol/sdk";
 const mockQuery = vi.hoisted(() =>
   vi.fn(() => ({
     initializationResult: vi.fn().mockResolvedValue({
-      models: [{ value: "id", displayName: "name", description: "description" }],
+      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", () => ({
+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,
 }));
 
@@ -50,6 +56,9 @@ describe("authorization", () => {
     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 () => {
@@ -62,11 +71,20 @@ describe("authorization", () => {
       } as any,
     });
     expect(initializeResponse.authMethods).toContainEqual(
-      expect.objectContaining({ id: "gateway" }),
+      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 gateway auth", async () => {
+  it("uses gateway env after anthropic gateway auth", async () => {
     const [agent, mockQuery] = await createAgentMock();
 
     const initializeResponse = await agent.initialize({
@@ -85,7 +103,7 @@ describe("authorization", () => {
     });
 
     await agent.newSession({
-      cwd: "testRoot",
+      cwd: process.cwd(),
       mcpServers: [],
       _meta: {
         claudeCode: {
@@ -102,7 +120,7 @@ describe("authorization", () => {
       expect.objectContaining({
         options: expect.objectContaining({
           env: expect.objectContaining({
-            ANTHROPIC_AUTH_TOKEN: "",
+            ANTHROPIC_AUTH_TOKEN: " ",
             ANTHROPIC_BASE_URL: "https://gateway.example",
             ANTHROPIC_CUSTOM_HEADERS: "x-api-key: test",
             userEnv: "userEnv",
@@ -112,6 +130,42 @@ describe("authorization", () => {
     );
   });
 
+  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"] });
@@ -169,6 +223,64 @@ describe("authorization", () => {
     );
   });
 
+  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();
 

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

@@ -1,7 +1,10 @@
-import { describe, it, expect, beforeEach, vi } from "vitest";
-import { AgentSideConnection, SessionNotification } from "@agentclientprotocol/sdk";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { AgentSideConnection, RequestError, SessionNotification } from "@agentclientprotocol/sdk";
 import type { Options } from "@anthropic-ai/claude-agent-sdk";
 import type { 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 () => {
@@ -15,10 +18,16 @@ vi.mock("@anthropic-ai/claude-agent-sdk", async () => {
       return {
         initializationResult: async () => ({
           models: [
-            { value: "claude-sonnet-4-5", displayName: "Claude Sonnet", description: "Fast" },
+            {
+              value: "claude-sonnet-4-6",
+              displayName: "Claude Sonnet",
+              description: "Fast",
+              supportsAutoMode: true,
+            },
           ],
         }),
         setModel: async () => {},
+        setPermissionMode: async () => {},
         supportedCommands: async () => [],
         [Symbol.asyncIterator]: async function* () {},
       };
@@ -59,7 +68,7 @@ describe("createSession options merging", () => {
 
   it("merges user-provided disallowedTools with ACP internal list", async () => {
     await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
       mcpServers: [],
       _meta: {
         claudeCode: {
@@ -79,7 +88,7 @@ describe("createSession options merging", () => {
 
   it("works when user provides no disallowedTools", async () => {
     await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
       mcpServers: [],
     });
 
@@ -88,7 +97,7 @@ describe("createSession options merging", () => {
 
   it("works when user provides empty disallowedTools", async () => {
     await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
       mcpServers: [],
       _meta: {
         claudeCode: {
@@ -104,7 +113,7 @@ describe("createSession options merging", () => {
 
   it("sets tools to empty array when disableBuiltInTools is true", async () => {
     await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
       mcpServers: [],
       _meta: {
         disableBuiltInTools: true,
@@ -127,7 +136,7 @@ describe("createSession options merging", () => {
     const userPreToolUseHook = { hooks: [{ command: "echo pre" }] };
 
     await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
       mcpServers: [],
       _meta: {
         claudeCode: {
@@ -149,7 +158,7 @@ describe("createSession options merging", () => {
 
   it("inherits HOME and PATH from process.env when no env is provided", async () => {
     await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
       mcpServers: [],
     });
 
@@ -159,7 +168,7 @@ describe("createSession options merging", () => {
 
   it("merges user-provided env vars on top of process.env", async () => {
     await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
       mcpServers: [],
       _meta: {
         claudeCode: {
@@ -179,7 +188,7 @@ describe("createSession options merging", () => {
 
   it("allows user-provided env vars to override process.env entries", async () => {
     await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
       mcpServers: [],
       _meta: {
         claudeCode: {
@@ -197,7 +206,7 @@ describe("createSession options merging", () => {
 
   it("defaults tools to claude_code preset when not provided", async () => {
     await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
       mcpServers: [],
     });
 
@@ -206,7 +215,7 @@ describe("createSession options merging", () => {
 
   it("passes through user-provided tools string array", async () => {
     await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
       mcpServers: [],
       _meta: {
         claudeCode: {
@@ -222,7 +231,7 @@ describe("createSession options merging", () => {
 
   it("explicit tools array takes precedence over disableBuiltInTools", async () => {
     await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
       mcpServers: [],
       _meta: {
         disableBuiltInTools: true,
@@ -239,7 +248,7 @@ describe("createSession options merging", () => {
 
   it("passes through empty tools array to disable all built-in tools", async () => {
     await agent.newSession({
-      cwd: "/test",
+      cwd: process.cwd(),
       mcpServers: [],
       _meta: {
         claudeCode: {
@@ -253,9 +262,192 @@ describe("createSession options merging", () => {
     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: "/test",
+      cwd: process.cwd(),
       mcpServers: [
         {
           name: "acp-server",
@@ -284,4 +476,140 @@ describe("createSession options merging", () => {
     // ACP-provided MCP server should also be present
     expect(capturedOptions!.mcpServers).toHaveProperty("acp-server");
   });
+
+  describe("thinking config from MAX_THINKING_TOKENS", () => {
+    let originalMaxThinking: string | undefined;
+
+    beforeEach(() => {
+      originalMaxThinking = process.env.MAX_THINKING_TOKENS;
+      delete process.env.MAX_THINKING_TOKENS;
+    });
+
+    afterEach(() => {
+      if (originalMaxThinking !== undefined) {
+        process.env.MAX_THINKING_TOKENS = originalMaxThinking;
+      } else {
+        delete process.env.MAX_THINKING_TOKENS;
+      }
+    });
+
+    it("leaves thinking unset (SDK default) when env var is absent", async () => {
+      await agent.newSession({ cwd: 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 file = path.join(os.tmpdir(), "claude-acp-cwd-is-a-file.txt");
+      fs.writeFileSync(file, "not a directory");
+      try {
+        await expect(agent.newSession({ cwd: file, mcpServers: [] })).rejects.toMatchObject({
+          code: RequestError.invalidParams().code,
+        });
+      } finally {
+        fs.rmSync(file, { force: true });
+      }
+    });
+
+    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,309 @@
+import { describe, it, expect } from "vitest";
+import type { CreateElicitationRequest, CreateElicitationResponse } 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 }>,
+  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 ?? "" })),
+  } 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" },
+        { const: "luxon", title: "luxon" },
+      ],
+    });
+    // The full question text is not used as a property key.
+    expect(schema.properties?.["Which library?"]).toBeUndefined();
+  });
+
+  it("includes an optional free-text custom-answer field", () => {
+    const questions = [mkQuestion("Which?", [{ label: "A" }, { label: "B" }])];
+    const schema = (
+      askUserQuestionsToCreateRequest(questions, SESSION_ID, undefined) as Extract<
+        CreateElicitationRequest,
+        { mode: "form" }
+      >
+    ).requestedSchema;
+
+    expect(schema.properties?.["customAnswer"]).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("maps the free-text custom-answer field to the tool's response", () => {
+    const response = {
+      action: "accept",
+      content: { question_0: "A", customAnswer: "something else entirely" },
+    } as CreateElicitationResponse;
+
+    expect(applyAskElicitationResponse(response, toolInput, questions)).toEqual({
+      action: "answered",
+      updatedInput: {
+        questions,
+        metadata: { source: "test" },
+        answers: { "Single?": "A" },
+        response: "something else entirely",
+      },
+    });
+  });
+
+  it("ignores empty selections and blank custom answers", () => {
+    const response = {
+      action: "accept",
+      content: { question_1: [], customAnswer: "   " },
+    } 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/resolve-permission-mode.test.ts

@@ -1,5 +1,12 @@
-import { describe, it, expect } from "vitest";
-import { resolvePermissionMode } from "../acp-agent.js";
+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", () => {
@@ -26,18 +33,25 @@ describe("resolvePermissionMode", () => {
     expect(resolvePermissionMode("  dontAsk  ")).toBe("dontAsk");
   });
 
-  it("throws on non-string values", () => {
-    expect(() => resolvePermissionMode(123)).toThrow("expected a string");
-    expect(() => resolvePermissionMode(true)).toThrow("expected a string");
-    expect(() => resolvePermissionMode({})).toThrow("expected a string");
+  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("throws on empty string", () => {
-    expect(() => resolvePermissionMode("")).toThrow("expected a non-empty string");
-    expect(() => resolvePermissionMode("  ")).toThrow("expected a non-empty 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("throws on unknown mode", () => {
-    expect(() => resolvePermissionMode("yolo")).toThrow("Invalid permissions.defaultMode: yolo");
+  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-config-options.test.ts

@@ -1,5 +1,6 @@
 import { describe, it, expect, beforeEach, vi } from "vitest";
 import { AgentSideConnection, SessionNotification } from "@agentclientprotocol/sdk";
+import type { ModelInfo } from "@anthropic-ai/claude-agent-sdk";
 import type { ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
 
 const { registerHookCallbackSpy } = vi.hoisted(() => ({
@@ -29,7 +30,7 @@ const MOCK_MODELS = {
   currentModelId: "claude-opus-4-5",
   availableModels: [
     { modelId: "claude-opus-4-5", name: "Claude Opus", description: "Most capable" },
-    { modelId: "claude-sonnet-4-5", name: "Claude Sonnet", description: "Balanced" },
+    { modelId: "claude-sonnet-4-6", name: "Claude Sonnet", description: "Balanced" },
   ],
 };
 
@@ -58,6 +59,20 @@ const MOCK_CONFIG_OPTIONS = [
       description: m.description,
     })),
   },
+  {
+    id: "effort",
+    name: "Effort",
+    description: "Available effort levels for this model",
+    type: "select",
+    category: "effort",
+    currentValue: "default",
+    options: [
+      { value: "default", name: "Default" },
+      { value: "low", name: "Low" },
+      { value: "medium", name: "Medium" },
+      { value: "high", name: "High" },
+    ],
+  },
 ];
 
 describe("session config options", () => {
@@ -67,6 +82,7 @@ describe("session config options", () => {
   let createSessionSpy: ReturnType<typeof vi.fn>;
   let setPermissionModeSpy: ReturnType<typeof vi.fn>;
   let setModelSpy: ReturnType<typeof vi.fn>;
+  let applyFlagSettingsSpy: ReturnType<typeof vi.fn>;
 
   function createMockClient(): AgentSideConnection {
     return {
@@ -82,18 +98,32 @@ describe("session config options", () => {
   function populateSession() {
     setPermissionModeSpy = vi.fn();
     setModelSpy = vi.fn();
+    applyFlagSettingsSpy = vi.fn();
 
     (agent as unknown as { sessions: Record<string, unknown> }).sessions[SESSION_ID] = {
       query: {
         setPermissionMode: setPermissionModeSpy,
         setModel: setModelSpy,
+        applyFlagSettings: applyFlagSettingsSpy,
         supportedCommands: async () => [],
       },
       input: null,
       cancelled: false,
       permissionMode: "default",
       settingsManager: {},
+      modes: structuredClone(MOCK_MODES),
+      models: structuredClone(MOCK_MODELS),
+      modelInfos: MOCK_MODELS.availableModels.map(
+        (m): ModelInfo => ({
+          value: m.modelId,
+          displayName: m.name,
+          description: m.description,
+          supportsEffort: true,
+          supportedEffortLevels: ["low", "medium", "high"],
+        }),
+      ),
       configOptions: structuredClone(MOCK_CONFIG_OPTIONS),
+      contextWindowSize: 200000,
     };
   }
 
@@ -118,13 +148,13 @@ describe("session config options", () => {
 
   describe("newSession returns configOptions", () => {
     it("includes configOptions in the response", async () => {
-      const response = await agent.newSession({ cwd: "/test", mcpServers: [] });
+      const response = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
       expect(response.configOptions).toBeDefined();
       expect(response.configOptions).toEqual(MOCK_CONFIG_OPTIONS);
     });
 
     it("includes mode and model config options", async () => {
-      const response = await agent.newSession({ cwd: "/test", mcpServers: [] });
+      const response = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
       const modeOption = response.configOptions?.find((o) => o.id === "mode");
       const modelOption = response.configOptions?.find((o) => o.id === "model");
       expect(modeOption).toBeDefined();
@@ -143,7 +173,7 @@ describe("session config options", () => {
       (agent as unknown as { loadSession: typeof loadSessionSpy }).loadSession = loadSessionSpy;
 
       const response = await agent.loadSession({
-        cwd: "/test",
+        cwd: process.cwd(),
         sessionId: SESSION_ID,
         mcpServers: [],
       });
@@ -213,10 +243,10 @@ describe("session config options", () => {
       await agent.setSessionConfigOption({
         sessionId: SESSION_ID,
         configId: "model",
-        value: "claude-sonnet-4-5",
+        value: "claude-sonnet-4-6",
       });
 
-      expect(setModelSpy).toHaveBeenCalledWith("claude-sonnet-4-5");
+      expect(setModelSpy).toHaveBeenCalledWith("claude-sonnet-4-6");
 
       const configUpdate = sessionUpdates.find(
         (n) => n.update.sessionUpdate === "config_option_update",
@@ -244,7 +274,7 @@ describe("session config options", () => {
         value: "sonnet",
       });
 
-      expect(setModelSpy).toHaveBeenCalledWith("claude-sonnet-4-5");
+      expect(setModelSpy).toHaveBeenCalledWith("claude-sonnet-4-6");
     });
 
     it("resolves display name to model ID", async () => {
@@ -254,19 +284,19 @@ describe("session config options", () => {
         value: "Claude Sonnet",
       });
 
-      expect(setModelSpy).toHaveBeenCalledWith("claude-sonnet-4-5");
+      expect(setModelSpy).toHaveBeenCalledWith("claude-sonnet-4-6");
     });
 
     it("still works with exact model ID", async () => {
       const response = await agent.setSessionConfigOption({
         sessionId: SESSION_ID,
         configId: "model",
-        value: "claude-sonnet-4-5",
+        value: "claude-sonnet-4-6",
       });
 
-      expect(setModelSpy).toHaveBeenCalledWith("claude-sonnet-4-5");
+      expect(setModelSpy).toHaveBeenCalledWith("claude-sonnet-4-6");
       const modelOption = response.configOptions.find((o) => o.id === "model");
-      expect(modelOption?.currentValue).toBe("claude-sonnet-4-5");
+      expect(modelOption?.currentValue).toBe("claude-sonnet-4-6");
     });
 
     it("throws for completely invalid model value", async () => {
@@ -347,33 +377,30 @@ describe("session config options", () => {
     });
   });
 
-  describe("unstable_setSessionModel sends config_option_update", () => {
+  describe("setSessionConfigOption(model) returns updated configOptions", () => {
     beforeEach(() => {
       populateSession();
     });
 
-    it("sends config_option_update when model is changed via setSessionModel", async () => {
-      await agent.unstable_setSessionModel({
+    it("returns configOptions with the new model when changed", async () => {
+      const response = await agent.setSessionConfigOption({
         sessionId: SESSION_ID,
-        modelId: "claude-sonnet-4-5",
+        configId: "model",
+        value: "claude-sonnet-4-6",
       });
 
-      const configUpdate = sessionUpdates.find(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      expect(configUpdate).toBeDefined();
-      expect(configUpdate?.update).toMatchObject({
-        sessionUpdate: "config_option_update",
-        configOptions: expect.arrayContaining([
-          expect.objectContaining({ id: "model", currentValue: "claude-sonnet-4-5" }),
+      expect(response.configOptions).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ id: "model", currentValue: "claude-sonnet-4-6" }),
         ]),
-      });
+      );
     });
 
     it("updates stored configOptions currentValue when model changes", async () => {
-      await agent.unstable_setSessionModel({
+      await agent.setSessionConfigOption({
         sessionId: SESSION_ID,
-        modelId: "claude-sonnet-4-5",
+        configId: "model",
+        value: "claude-sonnet-4-6",
       });
 
       const session = (
@@ -382,7 +409,89 @@ describe("session config options", () => {
         }
       ).sessions[SESSION_ID];
       const modelOption = session.configOptions.find((o) => o.id === "model");
-      expect(modelOption?.currentValue).toBe("claude-sonnet-4-5");
+      expect(modelOption?.currentValue).toBe("claude-sonnet-4-6");
+    });
+
+    it("drops effort from returned configOptions when model drops effort support", async () => {
+      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
+      session.modelInfos = [
+        {
+          value: "claude-opus-4-5",
+          displayName: "Claude Opus",
+          description: "Most capable",
+          supportsEffort: true,
+          supportedEffortLevels: ["low", "medium", "high"],
+        },
+        {
+          value: "claude-sonnet-4-6",
+          displayName: "Claude Sonnet",
+          description: "Balanced",
+          supportsEffort: false,
+        },
+      ];
+
+      const response = await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-4-6",
+      });
+
+      const effortOption = response.configOptions.find((o) => o.id === "effort");
+      expect(effortOption).toBeUndefined();
+      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: null });
+    });
+
+    it("clamps effort in returned configOptions when new model has different supported levels", async () => {
+      // Set current effort to "max" which the new model won't support
+      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
+      const effortOpt = session.configOptions.find((o: any) => o.id === "effort");
+      if (effortOpt) effortOpt.currentValue = "max";
+
+      session.modelInfos = [
+        {
+          value: "claude-opus-4-5",
+          displayName: "Claude Opus",
+          description: "Most capable",
+          supportsEffort: true,
+          supportedEffortLevels: ["low", "medium", "high", "max"],
+        },
+        {
+          value: "claude-sonnet-4-6",
+          displayName: "Claude Sonnet",
+          description: "Balanced",
+          supportsEffort: true,
+          supportedEffortLevels: ["low", "medium", "high"],
+        },
+      ];
+
+      const response = await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-4-6",
+      });
+
+      const effortOption = response.configOptions.find((o) => o.id === "effort");
+      expect(effortOption).toBeDefined();
+      expect(effortOption?.currentValue).toBe("default");
+      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: null });
+    });
+
+    it("preserves effort in returned configOptions when new model supports same level", async () => {
+      // Set effort to "low" first
+      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
+      const effortOpt = session.configOptions.find((o: any) => o.id === "effort");
+      if (effortOpt) effortOpt.currentValue = "low";
+
+      const response = await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-4-6",
+      });
+
+      const effortOption = response.configOptions.find((o) => o.id === "effort");
+      expect(effortOption?.currentValue).toBe("low");
+      // Effort didn't change, so applyFlagSettings should NOT be called
+      expect(applyFlagSettingsSpy).not.toHaveBeenCalled();
     });
   });
 
@@ -408,7 +517,7 @@ describe("session config options", () => {
       await agent.setSessionConfigOption({
         sessionId: SESSION_ID,
         configId: "model",
-        value: "claude-sonnet-4-5",
+        value: "claude-sonnet-4-6",
       });
 
       const configUpdates = sessionUpdates.filter(
@@ -418,6 +527,248 @@ describe("session config options", () => {
     });
   });
 
+  describe("setSessionConfigOption for effort", () => {
+    beforeEach(() => {
+      populateSession();
+    });
+
+    it("calls applyFlagSettings with effortLevel", async () => {
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "effort",
+        value: "low",
+      });
+
+      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: "low" });
+    });
+
+    it("calls applyFlagSettings with null effortLevel for 'default'", async () => {
+      // Set effort to a non-default value first
+      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
+      const effortOpt = session.configOptions.find((o: any) => o.id === "effort");
+      if (effortOpt) effortOpt.currentValue = "high";
+
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "effort",
+        value: "default",
+      });
+
+      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: null });
+
+      // The SDK's applyFlagSettings travels over a JSON pipe and only clears a
+      // flag-layer key when an explicit `null` is sent — `undefined` is
+      // dropped during JSON.stringify, which would leave the previous effort
+      // override in place. Round-trip the call args through JSON to make sure
+      // the key actually reaches the SDK.
+      const calls = applyFlagSettingsSpy.mock.calls;
+      const lastCallArgs = calls[calls.length - 1]?.[0];
+      const serialized = JSON.parse(JSON.stringify(lastCallArgs));
+      expect(serialized).toHaveProperty("effortLevel", null);
+    });
+
+    it("updates effort currentValue in returned configOptions", async () => {
+      const response = await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "effort",
+        value: "medium",
+      });
+
+      const effortOption = response.configOptions.find((o) => o.id === "effort");
+      expect(effortOption?.currentValue).toBe("medium");
+    });
+
+    it("throws for invalid effort value", async () => {
+      await expect(
+        agent.setSessionConfigOption({
+          sessionId: SESSION_ID,
+          configId: "effort",
+          value: "turbo",
+        }),
+      ).rejects.toThrow("Invalid value for config option effort: turbo");
+    });
+
+    it("does not send config_option_update notification", async () => {
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "effort",
+        value: "low",
+      });
+
+      const configUpdates = sessionUpdates.filter(
+        (n) => n.update.sessionUpdate === "config_option_update",
+      );
+      expect(configUpdates).toHaveLength(0);
+    });
+
+    it("other options are unchanged when effort is updated", async () => {
+      const response = await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "effort",
+        value: "low",
+      });
+
+      const modeOption = response.configOptions.find((o) => o.id === "mode");
+      expect(modeOption?.currentValue).toBe("default");
+      const modelOption = response.configOptions.find((o) => o.id === "model");
+      expect(modelOption?.currentValue).toBe("claude-opus-4-5");
+    });
+  });
+
+  describe("effort level and model switch interactions", () => {
+    beforeEach(() => {
+      populateSession();
+    });
+
+    it("drops effort option when switching to a model without effort support", async () => {
+      // Make sonnet not support effort
+      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
+      session.modelInfos = [
+        {
+          value: "claude-opus-4-5",
+          displayName: "Claude Opus",
+          description: "Most capable",
+          supportsEffort: true,
+          supportedEffortLevels: ["low", "medium", "high"],
+        },
+        {
+          value: "claude-sonnet-4-6",
+          displayName: "Claude Sonnet",
+          description: "Balanced",
+          supportsEffort: false,
+        },
+      ];
+
+      const response = await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-4-6",
+      });
+
+      const effortOption = response.configOptions.find((o) => o.id === "effort");
+      expect(effortOption).toBeUndefined();
+    });
+
+    it("clears effort via applyFlagSettings when switching to a model without effort", async () => {
+      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
+      session.modelInfos = [
+        {
+          value: "claude-opus-4-5",
+          displayName: "Claude Opus",
+          description: "Most capable",
+          supportsEffort: true,
+          supportedEffortLevels: ["low", "medium", "high"],
+        },
+        {
+          value: "claude-sonnet-4-6",
+          displayName: "Claude Sonnet",
+          description: "Balanced",
+          supportsEffort: false,
+        },
+      ];
+
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-4-6",
+      });
+
+      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: null });
+    });
+
+    it("adds effort option when switching to a model that supports effort", async () => {
+      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
+      // Start with sonnet (no effort) as current
+      session.models = { ...session.models, currentModelId: "claude-sonnet-4-6" };
+      session.modelInfos = [
+        {
+          value: "claude-opus-4-5",
+          displayName: "Claude Opus",
+          description: "Most capable",
+          supportsEffort: true,
+          supportedEffortLevels: ["low", "medium", "high"],
+        },
+        {
+          value: "claude-sonnet-4-6",
+          displayName: "Claude Sonnet",
+          description: "Balanced",
+          supportsEffort: false,
+        },
+      ];
+      // Remove effort from current config options
+      session.configOptions = session.configOptions.filter((o: any) => o.id !== "effort");
+
+      const response = await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-opus-4-5",
+      });
+
+      const effortOption = response.configOptions.find((o) => o.id === "effort");
+      expect(effortOption).toBeDefined();
+      // No previous effort, so defaults to "default" (no effort override)
+      expect(effortOption?.currentValue).toBe("default");
+    });
+
+    it("clamps effort to valid value when new model has different supported levels", async () => {
+      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
+      // Set current effort to "max" (not supported by sonnet in our mock)
+      const effortOpt = session.configOptions.find((o: any) => o.id === "effort");
+      if (effortOpt) effortOpt.currentValue = "max";
+
+      session.modelInfos = [
+        {
+          value: "claude-opus-4-5",
+          displayName: "Claude Opus",
+          description: "Most capable",
+          supportsEffort: true,
+          supportedEffortLevels: ["low", "medium", "high", "max"],
+        },
+        {
+          value: "claude-sonnet-4-6",
+          displayName: "Claude Sonnet",
+          description: "Balanced",
+          supportsEffort: true,
+          supportedEffortLevels: ["low", "medium", "high"],
+        },
+      ];
+
+      const response = await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-4-6",
+      });
+
+      const effortOption = response.configOptions.find((o) => o.id === "effort");
+      expect(effortOption).toBeDefined();
+      // "max" is not in sonnet's levels, so should fall back to "default" (no effort override)
+      expect(effortOption?.currentValue).toBe("default");
+      // SDK should be told to clear the effort override
+      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: null });
+    });
+
+    it("preserves effort value when new model supports the same level", async () => {
+      // Set effort to "low"
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "effort",
+        value: "low",
+      });
+
+      // Switch model — both support "low"
+      const response = await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-4-6",
+      });
+
+      const effortOption = response.configOptions.find((o) => o.id === "effort");
+      expect(effortOption?.currentValue).toBe("low");
+      // applyFlagSettings was called once for the effort change, but not again for the model switch
+      expect(applyFlagSettingsSpy).toHaveBeenCalledTimes(1);
+    });
+  });
+
   describe("bidirectional consistency", () => {
     beforeEach(() => {
       populateSession();
@@ -437,10 +788,10 @@ describe("session config options", () => {
       await agent.setSessionConfigOption({
         sessionId: SESSION_ID,
         configId: "model",
-        value: "claude-sonnet-4-5",
+        value: "claude-sonnet-4-6",
       });
 
-      expect(setModelSpy).toHaveBeenCalledWith("claude-sonnet-4-5");
+      expect(setModelSpy).toHaveBeenCalledWith("claude-sonnet-4-6");
     });
 
     it("setSessionMode also syncs configOptions", async () => {
@@ -454,10 +805,11 @@ describe("session config options", () => {
       expect(session.configOptions.find((o) => o.id === "mode")?.currentValue).toBe("plan");
     });
 
-    it("setSessionModel also syncs configOptions", async () => {
-      await agent.unstable_setSessionModel({
+    it("setSessionConfigOption(model) also syncs configOptions", async () => {
+      await agent.setSessionConfigOption({
         sessionId: SESSION_ID,
-        modelId: "claude-sonnet-4-5",
+        configId: "model",
+        value: "claude-sonnet-4-6",
       });
 
       const session = (
@@ -466,8 +818,350 @@ describe("session config options", () => {
         }
       ).sessions[SESSION_ID];
       expect(session.configOptions.find((o) => o.id === "model")?.currentValue).toBe(
-        "claude-sonnet-4-5",
+        "claude-sonnet-4-6",
       );
     });
   });
+
+  describe("auto mode availability per model", () => {
+    /**
+     * Augment the session populated by `populateSession()` with a Haiku entry
+     * (no `supportsAutoMode`), Opus + Sonnet entries with `supportsAutoMode:
+     * true`, and seed `availableModes` so it currently includes `auto`. This
+     * exercises the per-model recomputation done by `applyConfigOptionValue`
+     * on a model switch.
+     */
+    function setupHaikuOpusSession(currentModeId: string = "default") {
+      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
+      session.modelInfos = [
+        {
+          value: "claude-opus-4-5",
+          displayName: "Claude Opus",
+          description: "Most capable",
+          supportsEffort: true,
+          supportedEffortLevels: ["low", "medium", "high"],
+          supportsAutoMode: true,
+        },
+        {
+          value: "claude-sonnet-4-6",
+          displayName: "Claude Sonnet",
+          description: "Balanced",
+          supportsEffort: true,
+          supportedEffortLevels: ["low", "medium", "high"],
+          supportsAutoMode: true,
+        },
+        {
+          value: "claude-haiku-4-5",
+          displayName: "Claude Haiku",
+          description: "Fast",
+          supportsEffort: true,
+          supportedEffortLevels: ["low", "medium", "high"],
+          // supportsAutoMode intentionally omitted
+        },
+      ];
+      session.models = {
+        currentModelId: "claude-opus-4-5",
+        availableModels: [
+          { modelId: "claude-opus-4-5", name: "Claude Opus", description: "Most capable" },
+          { modelId: "claude-sonnet-4-6", name: "Claude Sonnet", description: "Balanced" },
+          { modelId: "claude-haiku-4-5", name: "Claude Haiku", description: "Fast" },
+        ],
+      };
+      session.modes = {
+        currentModeId,
+        availableModes: [
+          {
+            id: "auto",
+            name: "Auto",
+            description: "Use a model classifier to approve/deny permission prompts",
+          },
+          {
+            id: "default",
+            name: "Default",
+            description: "Standard behavior, prompts for dangerous operations",
+          },
+          {
+            id: "acceptEdits",
+            name: "Accept Edits",
+            description: "Auto-accept file edit operations",
+          },
+          { id: "plan", name: "Plan Mode", description: "Planning mode" },
+          {
+            id: "dontAsk",
+            name: "Don't Ask",
+            description: "Don't prompt for permissions, deny if not pre-approved",
+          },
+        ],
+      };
+      // Reflect the seeded availableModes/availableModels in configOptions so
+      // the pre-state matches what `createSession` would have produced for
+      // Opus, and `setSessionConfigOption` validation can accept the seeded
+      // model ids (notably the new Haiku entry).
+      session.configOptions = session.configOptions.map((o: any) => {
+        if (o.id === "mode") {
+          return {
+            ...o,
+            currentValue: currentModeId,
+            options: session.modes.availableModes.map((m: any) => ({
+              value: m.id,
+              name: m.name,
+              description: m.description,
+            })),
+          };
+        }
+        if (o.id === "model") {
+          return {
+            ...o,
+            currentValue: session.models.currentModelId,
+            options: session.models.availableModels.map((m: any) => ({
+              value: m.modelId,
+              name: m.name,
+              description: m.description,
+            })),
+          };
+        }
+        return o;
+      });
+      return session;
+    }
+
+    beforeEach(() => {
+      populateSession();
+    });
+
+    it("drops `auto` from available modes when switching to Haiku", async () => {
+      setupHaikuOpusSession("default");
+
+      const response = await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-haiku-4-5",
+      });
+
+      const modeOption = response.configOptions.find((o) => o.id === "mode");
+      expect(modeOption).toBeDefined();
+      const modeValues = (modeOption as any).options.map((o: any) => o.value);
+      expect(modeValues).not.toContain("auto");
+      expect(modeValues).toEqual(
+        expect.arrayContaining(["default", "acceptEdits", "plan", "dontAsk"]),
+      );
+    });
+
+    it("re-adds `auto` when switching from Haiku back to Opus", async () => {
+      const session = setupHaikuOpusSession("default");
+      // Pretend Haiku is the current model with no `auto`.
+      session.models.currentModelId = "claude-haiku-4-5";
+      session.modes.availableModes = session.modes.availableModes.filter(
+        (m: any) => m.id !== "auto",
+      );
+      const modeOpt = session.configOptions.find((o: any) => o.id === "mode");
+      modeOpt.options = session.modes.availableModes.map((m: any) => ({
+        value: m.id,
+        name: m.name,
+        description: m.description,
+      }));
+
+      const response = await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-opus-4-5",
+      });
+
+      const modeOption = response.configOptions.find((o) => o.id === "mode");
+      expect(modeOption).toBeDefined();
+      const modeValues = (modeOption as any).options.map((o: any) => o.value);
+      expect(modeValues).toContain("auto");
+
+      // The current mode ("default") is still valid on Opus, so no
+      // current_mode_update should have been emitted by the model switch.
+      const modeUpdates = sessionUpdates.filter(
+        (n) => n.update.sessionUpdate === "current_mode_update",
+      );
+      expect(modeUpdates).toHaveLength(0);
+    });
+
+    it("preserves the current mode when it remains valid after a model switch", async () => {
+      setupHaikuOpusSession("plan");
+
+      const response = await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-haiku-4-5",
+      });
+
+      // `plan` is in availableModes for both Opus and Haiku, so no clamp.
+      expect(setPermissionModeSpy).not.toHaveBeenCalledWith("default");
+
+      const modeUpdates = sessionUpdates.filter(
+        (n) => n.update.sessionUpdate === "current_mode_update",
+      );
+      expect(modeUpdates).toHaveLength(0);
+
+      const modeOption = response.configOptions.find((o) => o.id === "mode");
+      expect((modeOption as any).currentValue).toBe("plan");
+    });
+
+    it("clamps mode and emits current_mode_update via setSessionConfigOption(model)", async () => {
+      // Switching Opus(auto) → Haiku clamps the mode to "default". The
+      // `current_mode_update` side effect must fire so clients learn about the
+      // clamp even though the request/response API returns the new
+      // configOptions rather than emitting a config_option_update.
+      setupHaikuOpusSession("auto");
+
+      const response = await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-haiku-4-5",
+      });
+
+      expect(setPermissionModeSpy).toHaveBeenCalledWith("default");
+
+      const modeUpdates = sessionUpdates.filter(
+        (n) => n.update.sessionUpdate === "current_mode_update",
+      );
+      expect(modeUpdates).toHaveLength(1);
+      expect((modeUpdates[0].update as any).currentModeId).toBe("default");
+
+      // setSessionConfigOption is a request/response API: it returns the new
+      // configOptions in the response rather than emitting a
+      // config_option_update notification.
+      const configUpdates = sessionUpdates.filter(
+        (n) => n.update.sessionUpdate === "config_option_update",
+      );
+      expect(configUpdates).toHaveLength(0);
+
+      const modeOption = response.configOptions.find((o: any) => o.id === "mode");
+      expect(modeOption).toBeDefined();
+      expect((modeOption as any).currentValue).toBe("default");
+      expect((modeOption as any).options.map((o: any) => o.value)).not.toContain("auto");
+    });
+
+    it("rejects direct setSessionMode to `auto` when the active model does not offer it", async () => {
+      const session = setupHaikuOpusSession("default");
+      session.models.currentModelId = "claude-haiku-4-5";
+      session.modes.availableModes = session.modes.availableModes.filter(
+        (mode: any) => mode.id !== "auto",
+      );
+
+      await expect(agent.setSessionMode({ sessionId: SESSION_ID, modeId: "auto" })).rejects.toThrow(
+        "Mode auto is not available in this session",
+      );
+
+      expect(setPermissionModeSpy).not.toHaveBeenCalledWith("auto");
+      expect(sessionUpdates).toHaveLength(0);
+    });
+  });
+
+  describe("ExitPlanMode permission options filtered by availableModes", () => {
+    let capturedPermissionRequest: any;
+    let permissionResponse: any;
+
+    beforeEach(() => {
+      capturedPermissionRequest = null;
+      permissionResponse = { outcome: { outcome: "cancelled" } };
+      // Replace the default mock client with one that captures the
+      // requestPermission call so we can assert on the offered options.
+      (agent as any).client = {
+        sessionUpdate: async (notification: SessionNotification) => {
+          sessionUpdates.push(notification);
+        },
+        requestPermission: async (params: any) => {
+          capturedPermissionRequest = params;
+          return permissionResponse;
+        },
+        readTextFile: async () => ({ content: "" }),
+        writeTextFile: async () => ({}),
+      };
+      populateSession();
+    });
+
+    it("omits the `auto` option on a model without supportsAutoMode", async () => {
+      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
+      // Haiku-shaped session: availableModes does NOT include `auto`.
+      session.modes = {
+        currentModeId: "plan",
+        availableModes: [
+          { id: "default", name: "Default", description: "Standard" },
+          { id: "acceptEdits", name: "Accept Edits", description: "Auto-accept edits" },
+          { id: "plan", name: "Plan Mode", description: "Planning mode" },
+          { id: "dontAsk", name: "Don't Ask", description: "Deny if not pre-approved" },
+        ],
+      };
+
+      const canUseTool = (agent as any).canUseTool(SESSION_ID);
+      const signal = new AbortController().signal;
+      try {
+        await canUseTool(
+          "ExitPlanMode",
+          { plan: "do stuff" },
+          { signal, suggestions: undefined, toolUseID: "toolu_1" },
+        );
+      } catch {
+        // The mock client returns `cancelled`, which makes canUseTool throw.
+        // We only care about the captured requestPermission options.
+      }
+
+      expect(capturedPermissionRequest).not.toBeNull();
+      const optionIds = capturedPermissionRequest.options.map((o: any) => o.optionId);
+      expect(optionIds).not.toContain("auto");
+      expect(optionIds).toEqual(expect.arrayContaining(["default", "acceptEdits", "plan"]));
+    });
+
+    it("denies a selected `auto` option if the client did not receive that option", async () => {
+      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
+      session.modes = {
+        currentModeId: "plan",
+        availableModes: [
+          { id: "default", name: "Default", description: "Standard" },
+          { id: "acceptEdits", name: "Accept Edits", description: "Auto-accept edits" },
+          { id: "plan", name: "Plan Mode", description: "Planning mode" },
+          { id: "dontAsk", name: "Don't Ask", description: "Deny if not pre-approved" },
+        ],
+      };
+      permissionResponse = { outcome: { outcome: "selected", optionId: "auto" } };
+
+      const canUseTool = (agent as any).canUseTool(SESSION_ID);
+      const result = await canUseTool(
+        "ExitPlanMode",
+        { plan: "do stuff" },
+        { signal: new AbortController().signal, suggestions: undefined, toolUseID: "toolu_2" },
+      );
+
+      expect(capturedPermissionRequest).not.toBeNull();
+      const optionIds = capturedPermissionRequest.options.map((o: any) => o.optionId);
+      expect(optionIds).not.toContain("auto");
+      expect(result.behavior).toBe("deny");
+      expect(sessionUpdates).toHaveLength(0);
+    });
+
+    it("includes the `auto` option on a model with supportsAutoMode", async () => {
+      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
+      session.modes = {
+        currentModeId: "plan",
+        availableModes: [
+          { id: "auto", name: "Auto", description: "Use a model classifier" },
+          { id: "default", name: "Default", description: "Standard" },
+          { id: "acceptEdits", name: "Accept Edits", description: "Auto-accept edits" },
+          { id: "plan", name: "Plan Mode", description: "Planning mode" },
+          { id: "dontAsk", name: "Don't Ask", description: "Deny if not pre-approved" },
+        ],
+      };
+
+      const canUseTool = (agent as any).canUseTool(SESSION_ID);
+      const signal = new AbortController().signal;
+      try {
+        await canUseTool(
+          "ExitPlanMode",
+          { plan: "do stuff" },
+          { signal, suggestions: undefined, toolUseID: "toolu_3" },
+        );
+      } catch {
+        // mock returns cancelled
+      }
+
+      expect(capturedPermissionRequest).not.toBeNull();
+      const optionIds = capturedPermissionRequest.options.map((o: any) => o.optionId);
+      expect(optionIds).toContain("auto");
+    });
+  });
 });

src/tests/session-load.test.ts

@@ -0,0 +1,333 @@
+import { describe, it, expect } from "vitest";
+import { randomUUID } from "crypto";
+import { AgentSideConnection, RequestError, SessionNotification } from "@agentclientprotocol/sdk";
+import { query, getSessionMessages } from "@anthropic-ai/claude-agent-sdk";
+import { ClaudeAcpAgent } from "../acp-agent.js";
+import { Pushable } from "../utils.js";
+import type { SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+
+function createMockClient(): AgentSideConnection {
+  return {
+    sessionUpdate: async (_notification: SessionNotification) => {},
+    requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+    readTextFile: async () => ({ content: "" }),
+    writeTextFile: async () => ({}),
+  } as unknown as AgentSideConnection;
+}
+
+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 AgentSideConnection;
+
+    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 AgentSideConnection;
+
+    // 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

@@ -53,6 +53,57 @@ describe("SettingsManager", () => {
       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 });
@@ -90,4 +141,66 @@ describe("SettingsManager", () => {
       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/tests/tools.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, beforeEach } from "vitest";
 import { AgentSideConnection, ClientCapabilities } from "@agentclientprotocol/sdk";
 import { ImageBlockParam, ToolResultBlockParam } from "@anthropic-ai/sdk/resources";
 import {
@@ -11,7 +11,18 @@ import {
   BetaBashCodeExecutionToolResultBlockParam,
 } from "@anthropic-ai/sdk/resources/beta.mjs";
 import { toAcpNotifications, ToolUseCache, Logger } from "../acp-agent.js";
-import { toolUpdateFromToolResult, createPostToolUseHook, toolInfoFromToolUse } from "../tools.js";
+import {
+  toolUpdateFromToolResult,
+  createPostToolUseHook,
+  createTaskHook,
+  toolInfoFromToolUse,
+  planEntries,
+  applyTaskCreate,
+  applyTaskUpdate,
+  parseTaskCreateOutput,
+  taskStateToPlanEntries,
+  TaskState,
+} from "../tools.js";
 
 describe("rawOutput in tool call updates", () => {
   const mockClient = {} as AgentSideConnection;
@@ -662,14 +673,19 @@ describe("Bash terminal output", () => {
   });
 
   describe("toAcpNotifications with clientCapabilities", () => {
-    const toolUseCache: ToolUseCache = {
-      toolu_bash: {
-        type: "tool_use",
-        id: "toolu_bash",
-        name: "Bash",
-        input: { command: "ls -la" },
-      },
-    };
+    // Reset before each test: toAcpNotifications prunes the cache entry once it
+    // maps the tool_result, so a shared object would be empty by the 2nd test.
+    let toolUseCache: ToolUseCache;
+    beforeEach(() => {
+      toolUseCache = {
+        toolu_bash: {
+          type: "tool_use",
+          id: "toolu_bash",
+          name: "Bash",
+          input: { command: "ls -la" },
+        },
+      };
+    });
 
     const bashResult: BetaBashCodeExecutionResultBlock = {
       type: "bash_code_execution_result",
@@ -781,11 +797,21 @@ describe("Bash terminal output", () => {
         { clientCapabilities: { _meta: { terminal_output: true } } },
       );
 
+      // Fresh cache: the withSupport call above already consumed the entry,
+      // since toAcpNotifications prunes the tool_use once it maps the result.
+      const toolUseCacheWithoutSupport: ToolUseCache = {
+        toolu_bash: {
+          type: "tool_use",
+          id: "toolu_bash",
+          name: "Bash",
+          input: { command: "ls -la" },
+        },
+      };
       const withoutSupport = toAcpNotifications(
         [toolResult],
         "assistant",
         "test-session",
-        toolUseCache,
+        toolUseCacheWithoutSupport,
         mockClient,
         mockLogger,
       );
@@ -837,6 +863,31 @@ describe("Bash terminal output", () => {
     });
   });
 
+  describe("toolUseCache pruning", () => {
+    it("retains the tool_use entry until its result, then prunes it", () => {
+      const toolUseCache: ToolUseCache = {};
+      const toolUse = {
+        type: "tool_use" as const,
+        id: "toolu_read",
+        name: "Read",
+        input: { file_path: "/tmp/x.txt" },
+      };
+
+      // tool_use is cached and kept (the matching result hasn't arrived yet).
+      toAcpNotifications([toolUse], "assistant", "s", toolUseCache, mockClient, mockLogger);
+      expect(toolUseCache.toolu_read).toBeDefined();
+
+      // tool_result resolves it, so the entry is pruned to bound memory.
+      const toolResult: ToolResultBlockParam = {
+        type: "tool_result",
+        tool_use_id: "toolu_read",
+        content: [{ type: "text", text: "hello" }],
+      };
+      toAcpNotifications([toolResult], "assistant", "s", toolUseCache, mockClient, mockLogger);
+      expect(toolUseCache.toolu_read).toBeUndefined();
+    });
+  });
+
   describe("post-tool-use hook sends diff content for Edit tool", () => {
     it("should include content and locations from structuredPatch in hook update", async () => {
       const toolUseCache: ToolUseCache = {};
@@ -1051,6 +1102,162 @@ describe("Bash terminal output", () => {
     });
   });
 
+  describe("post-tool-use hook sends diff content for Write tool", () => {
+    // Regression: previously the dispatch only invoked
+    // toolUpdateFromDiffToolResponse for `Edit`, so a Write that
+    // overwrote an existing file (FileWriteOutput.type === "update")
+    // showed a "creation" diff (oldText: null, full new content) at
+    // tool_use time and was never corrected after the tool ran.
+    it("should emit a real diff for Write of an existing file (type: update)", async () => {
+      const toolUseCache: ToolUseCache = {};
+      const hookUpdates: any[] = [];
+      const mockClientWithUpdate = {
+        sessionUpdate: async (notification: any) => {
+          hookUpdates.push(notification);
+        },
+      } as unknown as AgentSideConnection;
+
+      toAcpNotifications(
+        [
+          {
+            type: "tool_use" as const,
+            id: "toolu_write_update",
+            name: "Write",
+            input: {
+              file_path: "/Users/test/project/file.ts",
+              content: "line1\nNEW line2\nline3",
+            },
+          },
+        ],
+        "assistant",
+        "test-session",
+        toolUseCache,
+        mockClientWithUpdate,
+        mockLogger,
+      );
+
+      const hook = createPostToolUseHook(mockLogger);
+      await hook(
+        {
+          hook_event_name: "PostToolUse",
+          tool_name: "Write",
+          tool_input: {
+            file_path: "/Users/test/project/file.ts",
+            content: "line1\nNEW line2\nline3",
+          },
+          tool_response: {
+            type: "update",
+            filePath: "/Users/test/project/file.ts",
+            content: "line1\nNEW line2\nline3",
+            originalFile: "line1\nold line2\nline3",
+            structuredPatch: [
+              {
+                oldStart: 1,
+                oldLines: 3,
+                newStart: 1,
+                newLines: 3,
+                lines: [" line1", "-old line2", "+NEW line2", " line3"],
+              },
+            ],
+            userModified: false,
+          },
+          tool_use_id: "toolu_write_update",
+          session_id: "test-session",
+          transcript_path: "/tmp/test",
+          cwd: "/tmp",
+        },
+        "toolu_write_update",
+        { signal: AbortSignal.abort() },
+      );
+
+      expect(hookUpdates).toHaveLength(1);
+      const hookUpdate = hookUpdates[0].update;
+      expect(hookUpdate._meta.claudeCode.toolName).toBe("Write");
+      expect(hookUpdate.content).toEqual([
+        {
+          type: "diff",
+          path: "/Users/test/project/file.ts",
+          oldText: "line1\nold line2\nline3",
+          newText: "line1\nNEW line2\nline3",
+        },
+      ]);
+      expect(hookUpdate.locations).toEqual([{ path: "/Users/test/project/file.ts", line: 1 }]);
+    });
+
+    it("should still emit a sensible diff for Write of a brand-new file (type: create)", async () => {
+      const toolUseCache: ToolUseCache = {};
+      const hookUpdates: any[] = [];
+      const mockClientWithUpdate = {
+        sessionUpdate: async (notification: any) => {
+          hookUpdates.push(notification);
+        },
+      } as unknown as AgentSideConnection;
+
+      toAcpNotifications(
+        [
+          {
+            type: "tool_use" as const,
+            id: "toolu_write_create",
+            name: "Write",
+            input: {
+              file_path: "/Users/test/project/new.ts",
+              content: "first\nsecond",
+            },
+          },
+        ],
+        "assistant",
+        "test-session",
+        toolUseCache,
+        mockClientWithUpdate,
+        mockLogger,
+      );
+
+      const hook = createPostToolUseHook(mockLogger);
+      await hook(
+        {
+          hook_event_name: "PostToolUse",
+          tool_name: "Write",
+          tool_input: {
+            file_path: "/Users/test/project/new.ts",
+            content: "first\nsecond",
+          },
+          tool_response: {
+            type: "create",
+            filePath: "/Users/test/project/new.ts",
+            content: "first\nsecond",
+            originalFile: null,
+            structuredPatch: [
+              {
+                oldStart: 0,
+                oldLines: 0,
+                newStart: 1,
+                newLines: 2,
+                lines: ["+first", "+second"],
+              },
+            ],
+          },
+          tool_use_id: "toolu_write_create",
+          session_id: "test-session",
+          transcript_path: "/tmp/test",
+          cwd: "/tmp",
+        },
+        "toolu_write_create",
+        { signal: AbortSignal.abort() },
+      );
+
+      expect(hookUpdates).toHaveLength(1);
+      const hookUpdate = hookUpdates[0].update;
+      expect(hookUpdate.content).toEqual([
+        {
+          type: "diff",
+          path: "/Users/test/project/new.ts",
+          oldText: null,
+          newText: "first\nsecond",
+        },
+      ]);
+    });
+  });
+
   describe("post-tool-use hook preserves terminal _meta", () => {
     it("should send terminal_output and terminal_exit as separate notifications, and hook should only have claudeCode", async () => {
       const clientCapabilities: ClientCapabilities = {
@@ -1271,3 +1478,513 @@ describe("toolInfoFromToolUse - ExitPlanMode", () => {
     expect(info.content).toEqual([]);
   });
 });
+
+describe("toolInfoFromToolUse - undefined input regression", () => {
+  it("Read with undefined input should not throw", () => {
+    const toolUse = { name: "Read", id: "toolu_read_undef", input: undefined };
+    const info = toolInfoFromToolUse(toolUse, false);
+    expect(info.title).toBe("Read File");
+    expect(info.locations).toEqual([]);
+  });
+
+  it("Grep with undefined input should not throw", () => {
+    const toolUse = { name: "Grep", id: "toolu_grep_undef", input: undefined };
+    const info = toolInfoFromToolUse(toolUse, false);
+    expect(info.title).toBe("grep");
+  });
+
+  it("Glob with undefined input should not throw", () => {
+    const toolUse = { name: "Glob", id: "toolu_glob_undef", input: undefined };
+    const info = toolInfoFromToolUse(toolUse, false);
+    expect(info.title).toBe("Find");
+    expect(info.locations).toEqual([]);
+  });
+
+  it("WebSearch with undefined input should not throw", () => {
+    const toolUse = { name: "WebSearch", id: "toolu_ws_undef", input: undefined };
+    const info = toolInfoFromToolUse(toolUse, false);
+    expect(info.title).toBe("Web search");
+  });
+
+  it("TodoWrite with undefined input should not throw", () => {
+    const toolUse = { name: "TodoWrite", id: "toolu_todo_undef", input: undefined };
+    const info = toolInfoFromToolUse(toolUse, false);
+    expect(info.title).toBe("Update TODOs");
+  });
+});
+
+describe("planEntries - undefined input regression", () => {
+  it("should return empty array when input is undefined", () => {
+    expect(planEntries(undefined)).toEqual([]);
+  });
+
+  it("should return empty array when input has no todos", () => {
+    expect(planEntries({} as any)).toEqual([]);
+  });
+
+  it("should still map valid todos correctly", () => {
+    const result = planEntries({
+      todos: [
+        { content: "Task 1", status: "pending", activeForm: "" },
+        { content: "Task 2", status: "completed", activeForm: "" },
+      ],
+    });
+    expect(result).toEqual([
+      { content: "Task 1", status: "pending", priority: "medium" },
+      { content: "Task 2", status: "completed", priority: "medium" },
+    ]);
+  });
+});
+
+describe("toAcpNotifications - TodoWrite with undefined input regression", () => {
+  const mockClient = {} as AgentSideConnection;
+  const mockLogger: Logger = { log: () => {}, error: () => {} };
+
+  it("should not throw when TodoWrite tool_use has undefined input", () => {
+    const toolUseCache: ToolUseCache = {};
+
+    const notifications = toAcpNotifications(
+      [
+        {
+          type: "tool_use" as const,
+          id: "toolu_todo_undef",
+          name: "TodoWrite",
+          input: undefined as any,
+        },
+      ],
+      "assistant",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+    );
+
+    // TodoWrite with undefined input should not crash, and should not emit plan update
+    const planUpdates = notifications.filter((n) => (n.update as any).sessionUpdate === "plan");
+    expect(planUpdates).toHaveLength(0);
+  });
+
+  it("should still emit plan update when TodoWrite has valid input", () => {
+    const toolUseCache: ToolUseCache = {};
+
+    const notifications = toAcpNotifications(
+      [
+        {
+          type: "tool_use" as const,
+          id: "toolu_todo_valid",
+          name: "TodoWrite",
+          input: { todos: [{ content: "Do X", status: "pending" }] },
+        },
+      ],
+      "assistant",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+    );
+
+    const planUpdates = notifications.filter((n) => (n.update as any).sessionUpdate === "plan");
+    expect(planUpdates).toHaveLength(1);
+  });
+});
+
+describe("parseTaskCreateOutput", () => {
+  it("parses JSON-string content", () => {
+    const parsed = parseTaskCreateOutput(JSON.stringify({ task: { id: "1", subject: "X" } }));
+    expect(parsed).toEqual({ task: { id: "1", subject: "X" } });
+  });
+
+  it("parses array-of-text-block content", () => {
+    const parsed = parseTaskCreateOutput([
+      { type: "text", text: JSON.stringify({ task: { id: "2", subject: "Y" } }) },
+    ]);
+    expect(parsed).toEqual({ task: { id: "2", subject: "Y" } });
+  });
+
+  it("returns undefined for non-JSON content", () => {
+    expect(parseTaskCreateOutput("not json")).toBeUndefined();
+    expect(parseTaskCreateOutput([{ type: "text", text: "not json" }])).toBeUndefined();
+  });
+
+  it("returns undefined when task.id is missing", () => {
+    expect(parseTaskCreateOutput(JSON.stringify({ task: { subject: "X" } }))).toBeUndefined();
+  });
+});
+
+describe("applyTaskCreate / applyTaskUpdate", () => {
+  it("creates an entry on TaskCreate when both input and output are present", () => {
+    const state: TaskState = new Map();
+    applyTaskCreate(
+      state,
+      { subject: "Write tests", description: "Cover Task* flow", activeForm: "Writing tests" },
+      { task: { id: "1", subject: "Write tests" } },
+    );
+    expect(state.get("1")).toEqual({
+      subject: "Write tests",
+      status: "pending",
+      activeForm: "Writing tests",
+      description: "Cover Task* flow",
+    });
+  });
+
+  it("is a no-op when the output has no task ID", () => {
+    const state: TaskState = new Map();
+    applyTaskCreate(state, { subject: "X", description: "Y" }, undefined);
+    expect(state.size).toBe(0);
+  });
+
+  it("updates fields by task ID and keeps insertion order in plan entries", () => {
+    const state: TaskState = new Map();
+    applyTaskCreate(state, { subject: "A", description: "" }, { task: { id: "1", subject: "A" } });
+    applyTaskCreate(state, { subject: "B", description: "" }, { task: { id: "2", subject: "B" } });
+    applyTaskUpdate(state, { taskId: "1", status: "in_progress" });
+    expect(taskStateToPlanEntries(state)).toEqual([
+      { content: "A", status: "in_progress", priority: "medium" },
+      { content: "B", status: "pending", priority: "medium" },
+    ]);
+  });
+
+  it("removes entries when status is 'deleted'", () => {
+    const state: TaskState = new Map();
+    applyTaskCreate(state, { subject: "A", description: "" }, { task: { id: "1", subject: "A" } });
+    applyTaskUpdate(state, { taskId: "1", status: "deleted" });
+    expect(state.size).toBe(0);
+  });
+
+  it("creates a placeholder entry when TaskUpdate carries a subject for an unseen task", () => {
+    const state: TaskState = new Map();
+    applyTaskUpdate(state, { taskId: "5", subject: "Late arrival", status: "in_progress" });
+    expect(state.get("5")).toEqual({
+      subject: "Late arrival",
+      status: "in_progress",
+      activeForm: undefined,
+      description: undefined,
+    });
+  });
+
+  it("skips TaskUpdate for an unseen task when no subject is available", () => {
+    const state: TaskState = new Map();
+    applyTaskUpdate(state, { taskId: "5", status: "in_progress" });
+    // Without a subject we'd render an empty-content plan entry, so the
+    // update is dropped instead of synthesizing a blank placeholder.
+    expect(state.has("5")).toBe(false);
+  });
+});
+
+describe("toAcpNotifications - Task* tools", () => {
+  const mockClient = {} as AgentSideConnection;
+  const mockLogger: Logger = { log: () => {}, error: () => {} };
+
+  it("suppresses tool_call for TaskCreate/TaskUpdate/TaskList/TaskGet on tool_use", () => {
+    const toolUseCache: ToolUseCache = {};
+    const taskState: TaskState = new Map();
+
+    const notifications = toAcpNotifications(
+      [
+        { type: "tool_use", id: "1", name: "TaskCreate", input: { subject: "A", description: "" } },
+        {
+          type: "tool_use",
+          id: "2",
+          name: "TaskUpdate",
+          input: { taskId: "1", status: "in_progress" },
+        },
+        { type: "tool_use", id: "3", name: "TaskList", input: {} },
+        { type: "tool_use", id: "4", name: "TaskGet", input: { taskId: "1" } },
+      ] as any,
+      "assistant",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+      { taskState },
+    );
+
+    expect(notifications).toHaveLength(0);
+    expect(taskState.size).toBe(0);
+  });
+
+  it("emits a plan snapshot after a TaskCreate tool_result and accumulates state", () => {
+    const toolUseCache: ToolUseCache = {};
+    const taskState: TaskState = new Map();
+
+    toAcpNotifications(
+      [
+        {
+          type: "tool_use",
+          id: "1",
+          name: "TaskCreate",
+          input: { subject: "First", description: "" },
+        },
+      ] as any,
+      "assistant",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+      { taskState },
+    );
+
+    const created = toAcpNotifications(
+      [
+        {
+          type: "tool_result",
+          tool_use_id: "1",
+          content: JSON.stringify({ task: { id: "1", subject: "First" } }),
+          is_error: false,
+        },
+      ] as any,
+      "user",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+      { taskState },
+    );
+
+    expect(created).toHaveLength(1);
+    expect(created[0].update).toMatchObject({
+      sessionUpdate: "plan",
+      entries: [{ content: "First", status: "pending", priority: "medium" }],
+    });
+
+    // A second TaskCreate accumulates rather than replacing.
+    toAcpNotifications(
+      [
+        {
+          type: "tool_use",
+          id: "2",
+          name: "TaskCreate",
+          input: { subject: "Second", description: "" },
+        },
+      ] as any,
+      "assistant",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+      { taskState },
+    );
+
+    const second = toAcpNotifications(
+      [
+        {
+          type: "tool_result",
+          tool_use_id: "2",
+          content: JSON.stringify({ task: { id: "2", subject: "Second" } }),
+          is_error: false,
+        },
+      ] as any,
+      "user",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+      { taskState },
+    );
+
+    expect(second[0].update).toMatchObject({
+      sessionUpdate: "plan",
+      entries: [
+        { content: "First", status: "pending", priority: "medium" },
+        { content: "Second", status: "pending", priority: "medium" },
+      ],
+    });
+  });
+
+  it("emits a plan snapshot reflecting status changes after a TaskUpdate tool_result", () => {
+    const toolUseCache: ToolUseCache = {};
+    const taskState: TaskState = new Map([["1", { subject: "First", status: "pending" as const }]]);
+    toolUseCache["update-1"] = {
+      type: "tool_use",
+      id: "update-1",
+      name: "TaskUpdate",
+      input: { taskId: "1", status: "completed" },
+    };
+
+    const notifications = toAcpNotifications(
+      [
+        {
+          type: "tool_result",
+          tool_use_id: "update-1",
+          content: JSON.stringify({
+            success: true,
+            taskId: "1",
+            updatedFields: ["status"],
+          }),
+          is_error: false,
+        },
+      ] as any,
+      "user",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+      { taskState },
+    );
+
+    expect(notifications).toHaveLength(1);
+    expect(notifications[0].update).toMatchObject({
+      sessionUpdate: "plan",
+      entries: [{ content: "First", status: "completed", priority: "medium" }],
+    });
+  });
+
+  it("suppresses TaskList and TaskGet tool_result without touching task state", () => {
+    const toolUseCache: ToolUseCache = {
+      "list-1": { type: "tool_use", id: "list-1", name: "TaskList", input: {} },
+      "get-1": { type: "tool_use", id: "get-1", name: "TaskGet", input: { taskId: "1" } },
+    };
+    const taskState: TaskState = new Map([
+      ["1", { subject: "Existing", status: "in_progress" as const }],
+    ]);
+
+    const notifications = toAcpNotifications(
+      [
+        { type: "tool_result", tool_use_id: "list-1", content: "...", is_error: false },
+        { type: "tool_result", tool_use_id: "get-1", content: "...", is_error: false },
+      ] as any,
+      "user",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+      { taskState },
+    );
+
+    expect(notifications).toHaveLength(0);
+    expect(taskState.get("1")).toEqual({ subject: "Existing", status: "in_progress" });
+  });
+
+  it("does not apply TaskCreate/TaskUpdate when the tool_result reports an error", () => {
+    const toolUseCache: ToolUseCache = {
+      "create-1": {
+        type: "tool_use",
+        id: "create-1",
+        name: "TaskCreate",
+        input: { subject: "A", description: "" },
+      },
+    };
+    const taskState: TaskState = new Map();
+
+    const notifications = toAcpNotifications(
+      [
+        {
+          type: "tool_result",
+          tool_use_id: "create-1",
+          content: "task creation failed",
+          is_error: true,
+        },
+      ] as any,
+      "user",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+      { taskState },
+    );
+
+    expect(notifications).toHaveLength(0);
+    expect(taskState.size).toBe(0);
+  });
+});
+
+describe("createTaskHook", () => {
+  it("registers a task on TaskCreated and fires onChange", async () => {
+    const taskState: TaskState = new Map();
+    let changes = 0;
+    const hook = createTaskHook({
+      taskState,
+      onChange: async () => {
+        changes++;
+      },
+    });
+
+    await hook(
+      {
+        hook_event_name: "TaskCreated",
+        task_id: "t-1",
+        task_subject: "Investigate flaky test",
+        task_description: "Repro and fix",
+      } as any,
+      undefined,
+      { signal: new AbortController().signal },
+    );
+
+    expect(taskState.get("t-1")).toEqual({
+      subject: "Investigate flaky test",
+      status: "pending",
+      description: "Repro and fix",
+    });
+    expect(changes).toBe(1);
+  });
+
+  it("does not clobber an existing entry on TaskCreated", async () => {
+    const taskState: TaskState = new Map([
+      ["t-1", { subject: "Investigate flaky test", status: "in_progress" as const }],
+    ]);
+    let changes = 0;
+    const hook = createTaskHook({
+      taskState,
+      onChange: async () => {
+        changes++;
+      },
+    });
+
+    await hook(
+      {
+        hook_event_name: "TaskCreated",
+        task_id: "t-1",
+        task_subject: "Investigate flaky test",
+      } as any,
+      undefined,
+      { signal: new AbortController().signal },
+    );
+
+    expect(taskState.get("t-1")?.status).toBe("in_progress");
+    expect(changes).toBe(0);
+  });
+
+  it("marks a task completed on TaskCompleted", async () => {
+    const taskState: TaskState = new Map([
+      ["t-1", { subject: "Investigate flaky test", status: "in_progress" as const }],
+    ]);
+    let changes = 0;
+    const hook = createTaskHook({
+      taskState,
+      onChange: async () => {
+        changes++;
+      },
+    });
+
+    await hook(
+      {
+        hook_event_name: "TaskCompleted",
+        task_id: "t-1",
+        task_subject: "Investigate flaky test",
+      } as any,
+      undefined,
+      { signal: new AbortController().signal },
+    );
+
+    expect(taskState.get("t-1")?.status).toBe("completed");
+    expect(changes).toBe(1);
+  });
+
+  it("is a no-op for unrelated hook events", async () => {
+    const taskState: TaskState = new Map();
+    let changes = 0;
+    const hook = createTaskHook({
+      taskState,
+      onChange: async () => {
+        changes++;
+      },
+    });
+
+    await hook({ hook_event_name: "PostToolUse", tool_name: "Read" } as any, undefined, {
+      signal: new AbortController().signal,
+    });
+
+    expect(taskState.size).toBe(0);
+    expect(changes).toBe(0);
+  });
+});

src/tools.ts

@@ -8,12 +8,16 @@ import {
 import { HookCallback } from "@anthropic-ai/claude-agent-sdk";
 import {
   AgentInput,
+  AskUserQuestionInput,
   BashInput,
   FileEditInput,
   FileReadInput,
   FileWriteInput,
   GlobInput,
   GrepInput,
+  TaskCreateInput,
+  TaskCreateOutput,
+  TaskUpdateInput,
   TodoWriteInput,
   WebFetchInput,
   WebSearchInput,
@@ -128,7 +132,7 @@ export function toolInfoFromToolUse(
   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",
@@ -145,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",
@@ -163,18 +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";
+      const displayPath = input?.file_path ? toDisplayPath(input.file_path, cwd) : "File";
       return {
         title: "Read " + displayPath + limit,
         kind: "read",
-        locations: input.file_path
+        locations: input?.file_path
           ? [
               {
                 path: input.file_path,
@@ -187,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 = [
@@ -216,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 = [
@@ -238,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";
@@ -289,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}`;
       }
 
@@ -338,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(", ")})`;
       }
 
@@ -357,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(", ")}`
@@ -367,8 +371,42 @@ 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 };
+      const planInput = toolUse.input as { plan?: string } | undefined;
       return {
         title: "Ready to code?",
         kind: "switch_mode",
@@ -378,6 +416,24 @@ export function toolInfoFromToolUse(
       };
     }
 
+    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 },
+          })),
+      };
+    }
+
     case "Other": {
       const input = toolUse.input;
       let output;
@@ -661,10 +717,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",
   }));
 }
@@ -679,7 +832,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;
@@ -687,23 +840,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[] = [];
@@ -796,3 +950,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,19 +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;
-    }
-  }
-}