chore(main): release 0.31.1 (#600 )

🤖 I have created a release *beep* *boop* --- ## [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](f0801d50b2)) --- 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>
fix: detect glibc and use correct binary (#599 )
2026-11-04 16:31:56 +00:00 · 2026-04-27 12:02:31 +02:00 · 2026-04-27 10:01:08 +00:00 · 2026-04-27 11:54:12 +02:00 · 2026-04-24 17:14:31 +02:00 · 2026-04-24 15:13:02 +00:00
19 changed files with 3269 additions and 870 deletions
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -8,7 +8,7 @@ updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
-      interval: "weekly"
+      interval: "daily"
    allow:
      - dependency-type: "all"
    groups:
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -24,7 +24,7 @@ jobs:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd

      - name: Use Node.js
-        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
        with:
          node-version: "lts/*"
          cache: "npm"
--- a/.github/workflows/publish.yml
+++ b/.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@1b10c78c7865c340bc4f6099eb2f838309f1e8c3
        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,77 +34,6 @@ 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]
-    # TODO: Re-enable once Bun SDK compatibility is fixed
-    if: false
-    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
@@ -117,7 +46,7 @@ jobs:
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
      # 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"
@@ -126,31 +55,3 @@ jobs:
      - run: npm ci
      - run: npm run build
      - run: npm publish
-
-  release:
-    name: Create Release
-    runs-on: ubuntu-latest
-    needs: [publish-npm, release-please]
-    # TODO: Re-enable once Bun SDK compatibility is fixed
-    if: false
-    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
--- a/.release-please-manifest.json
+++ b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "0.26.0"
+  ".": "0.31.1"
 }
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,83 @@
 # Changelog

+## [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)


--- a/docs/model-configuration.md
+++ b/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.
--- a/package-lock.json
+++ b/package-lock.json
--- a/package.json
+++ b/package.json
@@ -3,7 +3,7 @@
  "publishConfig": {
    "access": "public"
  },
-  "version": "0.26.0",
+  "version": "0.31.1",
  "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.1",
-    "@anthropic-ai/claude-agent-sdk": "0.2.96",
+    "@agentclientprotocol/sdk": "0.20.0",
+    "@anthropic-ai/claude-agent-sdk": "0.2.119",
    "zod": "^3.25.0 || ^4.0.0"
  },
  "devDependencies": {
-    "@anthropic-ai/sdk": "0.85.0",
+    "@anthropic-ai/sdk": "0.89.0",
    "@eslint/js": "10.0.1",
-    "@types/node": "25.5.2",
-    "@typescript-eslint/eslint-plugin": "8.58.1",
-    "@typescript-eslint/parser": "8.58.1",
-    "eslint": "10.2.0",
+    "@types/node": "25.6.0",
+    "@typescript-eslint/eslint-plugin": "8.59.0",
+    "@typescript-eslint/parser": "8.59.0",
+    "eslint": "10.2.1",
    "eslint-config-prettier": "10.1.8",
-    "globals": "17.4.0",
-    "prettier": "3.8.1",
+    "globals": "17.5.0",
+    "prettier": "3.8.3",
    "ts-node": "10.9.2",
-    "typescript": "6.0.2",
-    "vitest": "4.1.3"
+    "typescript": "6.0.3",
+    "vitest": "4.1.5"
  }
 }
--- a/src/acp-agent.ts
+++ b/src/acp-agent.ts
@@ -51,17 +51,18 @@ import {
  ModelUsage,
  Options,
  PermissionMode,
+  PermissionUpdate,
  Query,
  query,
+  Settings,
+  SDKAssistantMessageError,
  SDKPartialAssistantMessage,
-  SDKResultMessage,
  SDKUserMessage,
  SlashCommand,
 } from "@anthropic-ai/claude-agent-sdk";
 import { ContentBlockParam } from "@anthropic-ai/sdk/resources";
 import { BetaContentBlock, BetaRawContentBlockDelta } from "@anthropic-ai/sdk/resources/beta.mjs";
 import { randomUUID } from "node:crypto";
-import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import packageJson from "../package.json" with { type: "json" };
@@ -109,6 +110,22 @@ type AccumulatedUsage = {
  cachedWriteTokens: number;
 };

+type UsageSnapshot = {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_input_tokens: number;
+  cache_creation_input_tokens: number;
+};
+
+const ZERO_USAGE = Object.freeze({
+  input_tokens: 0,
+  output_tokens: 0,
+  cache_read_input_tokens: 0,
+  cache_creation_input_tokens: 0,
+});
+
+const DEFAULT_CONTEXT_WINDOW = 200000;
+
 type Session = {
  query: Query;
  input: Pushable<SDKUserMessage>;
@@ -121,11 +138,19 @@ type Session = {
  accumulatedUsage: AccumulatedUsage;
  modes: SessionModeState;
  models: SessionModelState;
+  modelInfos: ModelInfo[];
  configOptions: SessionConfigOption[];
  promptRunning: boolean;
  pendingMessages: Map<string, { resolve: (cancelled: boolean) => void; order: number }>;
  nextPendingOrder: number;
  abortController: AbortController;
+  emitRawSDKMessages: boolean | SDKMessageFilter[];
+  /** Context window size of the last top-level assistant model, carried across
+   *  prompts so mid-stream usage_update notifications report a correct `size`
+   *  before the turn's first result message arrives. Defaults to
+   *  DEFAULT_CONTEXT_WINDOW, refreshed from each result's modelUsage, and
+   *  invalidated when the user switches the session's model. */
+  contextWindowSize: number;
 };

 /** Compute a stable fingerprint of the session-defining params so we can
@@ -151,6 +176,11 @@ type BackgroundTerminal =
      pendingOutput: TerminalOutputResponse;
    };

+export type SDKMessageFilter = {
+  type: string;
+  subtype?: string;
+};
+
 /**
 * Extra metadata that can be given when creating a new session.
 */
@@ -172,6 +202,14 @@ export type NewSessionMeta = {
     *   - tools (passed through; defaults to claude_code preset if not provided)
     */
    options?: Options;
+    /**
+     * When set, raw SDK messages are emitted as extNotification("_claude/sdkMessage", message)
+     * in addition to normal processing.
+     * - true: emit all messages
+     * - false/undefined: emit nothing (default)
+     * - SDKMessageFilter[]: emit only messages matching at least one filter
+     */
+    emitRawSDKMessages?: boolean | SDKMessageFilter[];
  };
  additionalRoots?: string[];
 };
@@ -226,14 +264,53 @@ export type ToolUseCache = {
  };
 };

-function isStaticBinary(): boolean {
-  return process.env.CLAUDE_AGENT_ACP_IS_SINGLE_FILE_BUN !== undefined;
+export async function claudeCliPath(): Promise<string> {
+  if (process.env.CLAUDE_CODE_EXECUTABLE) {
+    return process.env.CLAUDE_CODE_EXECUTABLE;
+  }
+  // The SDK's CLI is a native binary shipped as a platform-specific optional
+  // dependency of @anthropic-ai/claude-agent-sdk. Resolve via a require bound
+  // to the SDK so nested installs are found even when npm doesn't hoist.
+  const { createRequire } = await import("node:module");
+  const req = createRequire(import.meta.resolve("@anthropic-ai/claude-agent-sdk"));
+  const ext = process.platform === "win32" ? ".exe" : "";
+  // On linux, both glibc and musl variants may be installed side-by-side
+  // (e.g. bunx hydrates every optional dep), so picking one by trial is
+  // unreliable: the wrong binary segfaults at runtime instead of failing to
+  // spawn. Detect the runtime libc and prefer the matching variant, falling
+  // back to the other only if the preferred one isn't installed.
+  const candidates =
+    process.platform === "linux"
+      ? isMuslLibc()
+        ? [
+            `@anthropic-ai/claude-agent-sdk-linux-${process.arch}-musl/claude${ext}`,
+            `@anthropic-ai/claude-agent-sdk-linux-${process.arch}/claude${ext}`,
+          ]
+        : [
+            `@anthropic-ai/claude-agent-sdk-linux-${process.arch}/claude${ext}`,
+            `@anthropic-ai/claude-agent-sdk-linux-${process.arch}-musl/claude${ext}`,
+          ]
+      : [`@anthropic-ai/claude-agent-sdk-${process.platform}-${process.arch}/claude${ext}`];
+  for (const candidate of candidates) {
+    try {
+      return req.resolve(candidate);
+    } catch {
+      // try next candidate
+    }
+  }
+  throw new Error(
+    `Claude native binary not found for ${process.platform}-${process.arch}. ` +
+      `Reinstall @anthropic-ai/claude-agent-sdk without --omit=optional, or set CLAUDE_CODE_EXECUTABLE.`,
+  );
 }

-export async function claudeCliPath(): Promise<string> {
-  return isStaticBinary()
-    ? (await import("@anthropic-ai/claude-agent-sdk/embed")).default
-    : import.meta.resolve("@anthropic-ai/claude-agent-sdk").replace("sdk.mjs", "cli.js");
+function isMuslLibc(): boolean {
+  // process.report.getReport().header.glibcVersionRuntime is populated when
+  // Node is dynamically linked against glibc, and absent on musl.
+  const report = process.report?.getReport() as
+    | { header?: { glibcVersionRuntime?: string } }
+    | undefined;
+  return !report?.header?.glibcVersionRuntime;
 }

 function shouldHideClaudeAuth(): boolean {
@@ -248,6 +325,56 @@ const ALLOW_BYPASS = !IS_ROOT || !!process.env.IS_SANDBOX;
 // message and without invoking the model.
 const LOCAL_ONLY_COMMANDS = new Set(["/context", "/heapdump", "/extra-usage"]);

+// The Claude SDK persists local slash command invocations (e.g. `/model`) and
+// their output as user messages in the session transcript, wrapping the
+// payload in these XML-like markers that the CLI uses for its own display.
+// The live prompt loop drops them; replay must strip them too or they leak
+// into the UI on session/load.
+const LOCAL_COMMAND_TAG_PATTERN =
+  /<(command-name|command-message|command-args|local-command-stdout|local-command-stderr)>[\s\S]*?<\/\1>/g;
+
+function stripMarkerTags(text: string): string {
+  return text.replace(LOCAL_COMMAND_TAG_PATTERN, "");
+}
+
+/**
+ * Return user-message content with local-command marker tags removed, or
+ * `null` if nothing meaningful remains (caller should skip the message).
+ * Preserves real prose that's mixed in alongside the markers — e.g. a
+ * message like `<command-name>…</command-name>hi` becomes `hi`.
+ */
+export function stripLocalCommandMetadata(content: unknown): unknown | null {
+  if (typeof content === "string") {
+    const stripped = stripMarkerTags(content);
+    return stripped.trim() === "" ? null : stripped;
+  }
+  if (!Array.isArray(content)) return content;
+
+  const kept: unknown[] = [];
+  for (const block of content) {
+    if (
+      block &&
+      typeof block === "object" &&
+      "type" in block &&
+      (block as { type: unknown }).type === "text" &&
+      "text" in block &&
+      typeof (block as { text: unknown }).text === "string"
+    ) {
+      const stripped = stripMarkerTags((block as { text: string }).text);
+      if (stripped.trim() === "") continue;
+      kept.push({ ...(block as object), text: stripped });
+    } else {
+      kept.push(block);
+    }
+  }
+  if (kept.length === 0) return null;
+  return kept;
+}
+
+export function isLocalCommandMetadata(content: unknown): boolean {
+  return stripLocalCommandMetadata(content) === null;
+}
+
 const PERMISSION_MODE_ALIASES: Record<string, PermissionMode> = {
  auto: "auto",
  default: "default",
@@ -286,6 +413,50 @@ export function resolvePermissionMode(defaultMode?: unknown): PermissionMode {
  return mapped;
 }

+/**
+ * Builds the label for the "Always Allow" permission option so the user can see
+ * the exact scope they are committing to. Uses the SDK-provided suggestions
+ * when available (e.g. `Bash(npm test:*)`) and falls back to naming the whole
+ * tool so "Always Allow" is never a blank check without disclosure.
+ */
+export function describeAlwaysAllow(
+  suggestions: PermissionUpdate[] | undefined,
+  toolName: string,
+): string {
+  if (!suggestions || suggestions.length === 0) {
+    return `Always Allow all ${toolName}`;
+  }
+
+  const ruleLabels: string[] = [];
+  const directories: string[] = [];
+
+  for (const update of suggestions) {
+    if (update.type === "addRules" && update.behavior === "allow") {
+      for (const rule of update.rules) {
+        ruleLabels.push(
+          rule.ruleContent ? `${rule.toolName}(${rule.ruleContent})` : `all ${rule.toolName}`,
+        );
+      }
+    } else if (update.type === "addDirectories") {
+      directories.push(...update.directories);
+    }
+  }
+
+  const parts: string[] = [];
+  if (ruleLabels.length > 0) {
+    parts.push(ruleLabels.join(", "));
+  }
+  if (directories.length > 0) {
+    parts.push(`access to ${directories.join(", ")}`);
+  }
+
+  if (parts.length === 0) {
+    return `Always Allow all ${toolName}`;
+  }
+
+  return `Always Allow ${parts.join(" and ")}`;
+}
+
 // Implement the ACP Agent interface
 export class ClaudeAcpAgent implements Agent {
  sessions: {
@@ -325,13 +496,21 @@ export class ClaudeAcpAgent implements Agent {

    const supportsTerminalAuth = request.clientCapabilities?.auth?.terminal === true;
    const supportsMetaTerminalAuth = request.clientCapabilities?._meta?.["terminal-auth"] === true;
-    const noBrowser = !!process.env.NO_BROWSER;

-    // When NO_BROWSER is set (e.g. remote environments), fall back to the single
-    // terminal-only login that doesn't try to open a browser.
+    // Detect remote environments where the OAuth browser redirect to localhost
+    // won't work. This matches the SDK's internal isRemote check. In these cases,
+    // the `auth login` subcommand would fall back to a device-code-like manual
+    // flow, which doesn't work well over ACP, so we offer the TUI login instead.
+    const isRemote = !!(
+      process.env.NO_BROWSER ||
+      process.env.SSH_CONNECTION ||
+      process.env.SSH_CLIENT ||
+      process.env.SSH_TTY ||
+      process.env.CLAUDE_CODE_REMOTE
+    );
    const terminalAuthMethods: AuthMethod[] = [];

-    if (noBrowser) {
+    if (isRemote) {
      const remoteLoginMethod: AuthMethod = {
        description: "Run `claude /login` in the terminal",
        name: "Log in with Claude",
@@ -430,14 +609,6 @@ export class ClaudeAcpAgent implements Agent {
  }

  async newSession(params: NewSessionRequest): Promise<NewSessionResponse> {
-    if (
-      !this.gatewayAuthMeta &&
-      fs.existsSync(path.resolve(os.homedir(), ".claude.json.backup")) &&
-      !fs.existsSync(path.resolve(os.homedir(), ".claude.json"))
-    ) {
-      throw RequestError.authRequired();
-    }
-
    const response = await this.createSession(params, {
      // Revisit these meta values once we support resume
      resume: (params._meta as NewSessionMeta | undefined)?.claudeCode?.options?.resume,
@@ -468,7 +639,7 @@ export class ClaudeAcpAgent implements Agent {
    return response;
  }

-  async unstable_resumeSession(params: ResumeSessionRequest): Promise<ResumeSessionResponse> {
+  async resumeSession(params: ResumeSessionRequest): Promise<ResumeSessionResponse> {
    const result = await this.getOrCreateSession(params);

    // Needs to happen after we return the session
@@ -532,8 +703,15 @@ export class ClaudeAcpAgent implements Agent {
    };

    let lastAssistantTotalUsage: number | null = null;
+    let lastAssistantUsage: UsageSnapshot | null = null;
    let lastAssistantModel: string | null = null;
-    let lastContextWindowSize: number = 200000;
+    // When the Claude SDK classifies a turn as failed (e.g. rate limit, auth
+    // problem, billing), it sets a categorical `error` field on the
+    // `SDKAssistantMessage` that precedes the final `result` message. We
+    // capture it here so the subsequent `RequestError.internalError` can
+    // forward it to clients as structured `data`, sparing them from
+    // pattern-matching on the human-readable message text.
+    let lastAssistantError: SDKAssistantMessageError | undefined;

    const userMessage = promptToClaude(params);

@@ -575,6 +753,16 @@ export class ClaudeAcpAgent implements Agent {
          break;
        }

+        if (
+          session.emitRawSDKMessages &&
+          shouldEmitRawMessage(session.emitRawSDKMessages, message)
+        ) {
+          await this.client.extNotification("_claude/sdkMessage", {
+            sessionId: params.sessionId,
+            message: message as Record<string, unknown>,
+          });
+        }
+
        switch (message.type) {
          case "system":
            switch (message.subtype) {
@@ -605,12 +793,13 @@ export class ClaudeAcpAgent implements Agent {
                // "944k/1m" right after the user sees "Compacting completed",
                // which is confusing and wrong.
                lastAssistantTotalUsage = 0;
+                lastAssistantUsage = null;
                await this.client.sessionUpdate({
                  sessionId: message.session_id,
                  update: {
                    sessionUpdate: "usage_update",
                    used: 0,
-                    size: lastContextWindowSize,
+                    size: session.contextWindowSize,
                  },
                });
                await this.client.sessionUpdate({
@@ -645,8 +834,13 @@ export class ClaudeAcpAgent implements Agent {
              case "task_started":
              case "task_notification":
              case "task_progress":
+              case "task_updated":
              case "elicitation_complete":
+              case "plugin_install":
+              case "memory_recall":
+              case "notification":
              case "api_retry":
+              case "mirror_error":
                // Todo: process via status api: https://docs.claude.com/en/docs/claude-code/hooks#hook-output
                break;
              default:
@@ -664,8 +858,13 @@ export class ClaudeAcpAgent implements Agent {
            const matchingModelUsage = lastAssistantModel
              ? getMatchingModelUsage(message.modelUsage, lastAssistantModel)
              : null;
-            const contextWindowSize = matchingModelUsage?.contextWindow ?? 200000;
-            lastContextWindowSize = contextWindowSize;
+            // Only overwrite when we have an authoritative value — a miss
+            // (e.g. a turn with no top-level assistant message) would
+            // otherwise discard the window learned on a prior turn and
+            // leave the next prompt's mid-stream updates reporting 200k.
+            if (matchingModelUsage) {
+              session.contextWindowSize = matchingModelUsage.contextWindow;
+            }

            // Send usage_update notification
            if (lastAssistantTotalUsage !== null) {
@@ -674,7 +873,7 @@ export class ClaudeAcpAgent implements Agent {
                update: {
                  sessionUpdate: "usage_update",
                  used: lastAssistantTotalUsage,
-                  size: contextWindowSize,
+                  size: session.contextWindowSize,
                  cost: {
                    amount: message.total_cost_usd,
                    currency: "USD",
@@ -698,7 +897,10 @@ export class ClaudeAcpAgent implements Agent {
                  break;
                }
                if (message.is_error) {
-                  throw RequestError.internalError(undefined, message.result);
+                  throw RequestError.internalError(
+                    errorKindData(lastAssistantError),
+                    message.result,
+                  );
                }
                // For local-only commands (no model invocation), the result
                // text is the command output — forward it to the client.
@@ -723,7 +925,7 @@ export class ClaudeAcpAgent implements Agent {
                }
                if (message.is_error) {
                  throw RequestError.internalError(
-                    undefined,
+                    errorKindData(lastAssistantError),
                    message.errors.join(", ") || message.subtype,
                  );
                }
@@ -735,7 +937,7 @@ export class ClaudeAcpAgent implements Agent {
              case "error_max_structured_output_retries":
                if (message.is_error) {
                  throw RequestError.internalError(
-                    undefined,
+                    errorKindData(lastAssistantError),
                    message.errors.join(", ") || message.subtype,
                  );
                }
@@ -748,6 +950,57 @@ export class ClaudeAcpAgent implements Agent {
            break;
          }
          case "stream_event": {
+            if (
+              message.parent_tool_use_id === null &&
+              (message.event.type === "message_start" || message.event.type === "message_delta")
+            ) {
+              if (message.event.type === "message_start") {
+                lastAssistantUsage = snapshotFromUsage(message.event.message.usage);
+                const model = message.event.message.model;
+                if (model && model !== "<synthetic>") {
+                  lastAssistantModel = model;
+                  // Only upgrade from the default — once a `result` has given
+                  // us an authoritative window, trust it over the heuristic.
+                  // Model switches invalidate the cached window via
+                  // `syncSessionConfigState`, which resets us back to the
+                  // default so this branch runs again for the new model.
+                  if (session.contextWindowSize === DEFAULT_CONTEXT_WINDOW) {
+                    const inferred = inferContextWindowFromModel(model);
+                    if (inferred !== null) {
+                      session.contextWindowSize = inferred;
+                    }
+                  }
+                }
+              } else {
+                const usage = message.event.usage;
+                const prev: Readonly<UsageSnapshot> = lastAssistantUsage ?? ZERO_USAGE;
+                // Per Anthropic API, message_delta usage fields are *cumulative*;
+                // nullable fields (input_tokens and the cache fields) fall back
+                // to the prior snapshot when the server omits them from this
+                // delta. Only output_tokens is guaranteed non-null.
+                lastAssistantUsage = {
+                  input_tokens: usage.input_tokens ?? prev.input_tokens,
+                  output_tokens: usage.output_tokens,
+                  cache_read_input_tokens:
+                    usage.cache_read_input_tokens ?? prev.cache_read_input_tokens,
+                  cache_creation_input_tokens:
+                    usage.cache_creation_input_tokens ?? prev.cache_creation_input_tokens,
+                };
+              }
+
+              const nextUsage = totalTokens(lastAssistantUsage);
+              if (nextUsage !== lastAssistantTotalUsage) {
+                lastAssistantTotalUsage = nextUsage;
+                await this.client.sessionUpdate({
+                  sessionId: params.sessionId,
+                  update: {
+                    sessionUpdate: "usage_update",
+                    used: nextUsage,
+                    size: session.contextWindowSize,
+                  },
+                });
+              }
+            }
            for (const notification of streamEventToAcpNotifications(
              message,
              params.sessionId,
@@ -790,29 +1043,19 @@ export class ClaudeAcpAgent implements Agent {
              }
            }

-            // Store latest assistant usage (excluding subagents)
-            // Sum all token types as a proxy for post-turn context occupancy:
-            // current turn's output will become next turn's input.
-            // Note: per the Anthropic API, input_tokens excludes cache tokens —
-            // cache_read and cache_creation are reported separately, so summing
-            // all four fields is not double-counting.
-            if ((message.message as any).usage && message.parent_tool_use_id === null) {
-              const messageWithUsage = message.message as unknown as SDKResultMessage;
-              lastAssistantTotalUsage =
-                messageWithUsage.usage.input_tokens +
-                messageWithUsage.usage.output_tokens +
-                messageWithUsage.usage.cache_read_input_tokens +
-                messageWithUsage.usage.cache_creation_input_tokens;
-            }
-            // Track the current top-level model for context window size lookup
-            // (exclude subagent messages to stay in sync with lastAssistantTotalUsage)
-            if (
-              message.type === "assistant" &&
-              message.parent_tool_use_id === null &&
-              message.message.model &&
-              message.message.model !== "<synthetic>"
-            ) {
-              lastAssistantModel = message.message.model;
+            // Snapshot the latest top-level assistant usage and model so the
+            // next `result` can emit a usage_update tied to the right context
+            // window. Subagent messages are excluded to keep the snapshot
+            // aligned with what the user's current selection is producing.
+            if (message.type === "assistant" && message.parent_tool_use_id === null) {
+              lastAssistantUsage = snapshotFromUsage(message.message.usage);
+              lastAssistantTotalUsage = totalTokens(lastAssistantUsage);
+              if (message.message.model && message.message.model !== "<synthetic>") {
+                lastAssistantModel = message.message.model;
+              }
+              if (message.error) {
+                lastAssistantError = message.error;
+              }
            }

            // Slash commands like /compact can generate invalid output... doesn't match
@@ -935,7 +1178,7 @@ export class ClaudeAcpAgent implements Agent {
  async cancel(params: CancelNotification): Promise<void> {
    const session = this.sessions[params.sessionId];
    if (!session) {
-      throw new Error("Session not found");
+      return;
    }
    session.cancelled = true;
    for (const [, pending] of session.pendingMessages) {
@@ -955,10 +1198,16 @@ export class ClaudeAcpAgent implements Agent {
    await this.cancel({ sessionId });
    session.settingsManager.dispose();
    session.abortController.abort();
+    session.query.close();
    delete this.sessions[sessionId];
  }

-  async unstable_closeSession(params: CloseSessionRequest): Promise<CloseSessionResponse> {
+  /** Tear down all active sessions. Called when the ACP connection closes. */
+  async dispose(): Promise<void> {
+    await Promise.all(Object.keys(this.sessions).map((id) => this.teardownSession(id)));
+  }
+
+  async closeSession(params: CloseSessionRequest): Promise<CloseSessionResponse> {
    if (!this.sessions[params.sessionId]) {
      throw new Error("Session not found");
    }
@@ -969,11 +1218,17 @@ export class ClaudeAcpAgent implements Agent {
  async unstable_setSessionModel(
    params: SetSessionModelRequest,
  ): Promise<SetSessionModelResponse | void> {
-    if (!this.sessions[params.sessionId]) {
+    const session = this.sessions[params.sessionId];
+    if (!session) {
      throw new Error("Session not found");
    }
-    await this.sessions[params.sessionId].query.setModel(params.modelId);
-    await this.updateConfigOption(params.sessionId, "model", params.modelId);
+    // Resolve aliases (e.g. "opus", "opus[1m]") to canonical model IDs so
+    // downstream lookups in modelInfos succeed and the effort option isn't
+    // silently dropped.
+    const resolved = resolveModelPreference(session.modelInfos, params.modelId);
+    const modelId = resolved?.value ?? params.modelId;
+    await session.query.setModel(modelId);
+    await this.updateConfigOption(params.sessionId, "model", modelId);
  }

  async setSessionMode(params: SetSessionModeRequest): Promise<SetSessionModeResponse> {
@@ -1043,14 +1298,11 @@ export class ClaudeAcpAgent implements Agent {
    } else if (params.configId === "model") {
      await this.sessions[params.sessionId].query.setModel(resolvedValue);
    }
+    // Effort SDK sync is handled inside applyConfigOptionValue so that direct
+    // effort changes and effort changes induced by a model switch go through
+    // the same path.

-    this.syncSessionConfigState(session, params.configId, params.value);
-
-    session.configOptions = session.configOptions.map((o) =>
-      o.id === params.configId && typeof o.currentValue === "string"
-        ? { ...o, currentValue: resolvedValue }
-        : o,
-    );
+    await this.applyConfigOptionValue(session, params.configId, resolvedValue);

    return { configOptions: session.configOptions };
  }
@@ -1087,9 +1339,17 @@ export class ClaudeAcpAgent implements Agent {
    const messages = await getSessionMessages(sessionId);

    for (const message of messages) {
+      // @ts-expect-error - untyped in SDK but we handle all of these
+      let content: unknown = message.message.content;
+      // @ts-expect-error - untyped in SDK but we handle all of these
+      if (message.message.role === "user") {
+        content = stripLocalCommandMetadata(content);
+        if (content === null) continue;
+      }
+
      for (const notification of toAcpNotifications(
        // @ts-expect-error - untyped in SDK but we handle all of these
-        message.message.content,
+        content,
        // @ts-expect-error - untyped in SDK but we handle all of these
        message.message.role,
        sessionId,
@@ -1119,6 +1379,7 @@ export class ClaudeAcpAgent implements Agent {

  canUseTool(sessionId: string): CanUseTool {
    return async (toolName, toolInput, { signal, suggestions, toolUseID }) => {
+      const alwaysAllowLabel = describeAlwaysAllow(suggestions, toolName);
      const supportsTerminalOutput = this.clientCapabilities?._meta?.["terminal_output"] === true;
      const session = this.sessions[sessionId];
      if (!session) {
@@ -1130,6 +1391,7 @@ export class ClaudeAcpAgent implements Agent {

      if (toolName === "ExitPlanMode") {
        const options = [
+          { kind: "allow_always", name: 'Yes, and use "auto" mode', optionId: "auto" },
          {
            kind: "allow_always",
            name: "Yes, and auto-accept edits",
@@ -1167,6 +1429,7 @@ export class ClaudeAcpAgent implements Agent {
          response.outcome?.outcome === "selected" &&
          (response.outcome.optionId === "default" ||
            response.outcome.optionId === "acceptEdits" ||
+            response.outcome.optionId === "auto" ||
            response.outcome.optionId === "bypassPermissions")
        ) {
          await this.client.sessionUpdate({
@@ -1207,7 +1470,7 @@ export class ClaudeAcpAgent implements Agent {
        options: [
          {
            kind: "allow_always",
-            name: "Always Allow",
+            name: alwaysAllowLabel,
            optionId: "allow_always",
          },
          { kind: "allow_once", name: "Allow", optionId: "allow" },
@@ -1280,11 +1543,7 @@ export class ClaudeAcpAgent implements Agent {
    const session = this.sessions[sessionId];
    if (!session) return;

-    this.syncSessionConfigState(session, configId, value);
-
-    session.configOptions = session.configOptions.map((o) =>
-      o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o,
-    );
+    await this.applyConfigOptionValue(session, configId, value);

    await this.client.sessionUpdate({
      sessionId,
@@ -1295,12 +1554,57 @@ export class ClaudeAcpAgent implements Agent {
    });
  }

-  private syncSessionConfigState(session: Session, configId: string, value: string): void {
+  private async applyConfigOptionValue(
+    session: Session,
+    configId: string,
+    value: string,
+  ): Promise<void> {
+    // Sync top-level session state
    if (configId === "mode") {
      session.modes = { ...session.modes, currentModeId: value };
    } else if (configId === "model") {
+      if (session.models.currentModelId !== value) {
+        // The cached context window was learned for the previous model; reset
+        // to the new model's heuristic so mid-stream updates between now and
+        // the next `result` reflect the user's selection instead of the old
+        // model's window.
+        session.contextWindowSize = inferContextWindowFromModel(value) ?? DEFAULT_CONTEXT_WINDOW;
+      }
      session.models = { ...session.models, currentModelId: value };
    }
+
+    // Update configOptions
+    if (configId === "model") {
+      // Rebuild config options since effort levels depend on the selected model
+      const effortOpt = session.configOptions.find((o) => o.id === "effort");
+      const currentEffort =
+        typeof effortOpt?.currentValue === "string" ? effortOpt.currentValue : undefined;
+      session.configOptions = buildConfigOptions(
+        session.modes,
+        session.models,
+        session.modelInfos,
+        currentEffort,
+      );
+
+      // Sync effort with the SDK if it changed after the model switch
+      const newEffortOpt = session.configOptions.find((o) => o.id === "effort");
+      const newEffort =
+        typeof newEffortOpt?.currentValue === "string" ? newEffortOpt.currentValue : undefined;
+      if (newEffort !== currentEffort) {
+        await session.query.applyFlagSettings({
+          effortLevel: newEffort as Settings["effortLevel"],
+        });
+      }
+    } else {
+      session.configOptions = session.configOptions.map((o) =>
+        o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o,
+      );
+      if (configId === "effort") {
+        await session.query.applyFlagSettings({
+          effortLevel: value as Settings["effortLevel"],
+        });
+      }
+    }
  }

  private async getOrCreateSession(params: {
@@ -1401,10 +1705,16 @@ export class ClaudeAcpAgent implements Agent {
        systemPrompt = customPrompt;
      } else if (
        typeof customPrompt === "object" &&
-        "append" in customPrompt &&
-        typeof customPrompt.append === "string"
+        customPrompt !== null &&
+        !Array.isArray(customPrompt)
      ) {
-        systemPrompt.append = customPrompt.append;
+        // Forward all preset options (append, excludeDynamicSections, and
+        // anything the SDK adds later) while locking type/preset.
+        systemPrompt = {
+          ...(customPrompt as object),
+          type: "preset",
+          preset: "claude_code",
+        } as Options["systemPrompt"];
      }
    }

@@ -1421,6 +1731,9 @@ export class ClaudeAcpAgent implements Agent {
      ? parseInt(process.env.MAX_THINKING_TOKENS, 10)
      : undefined;

+    // Parse model configuration from environment (e.g. Bedrock model overrides)
+    const modelConfig = parseModelConfig(process.env.CLAUDE_MODEL_CONFIG);
+
    // Disable this for now, not a great way to expose this over ACP at the moment (in progress work so we can revisit)
    const disallowedTools = ["AskUserQuestion"];

@@ -1439,6 +1752,17 @@ export class ClaudeAcpAgent implements Agent {
      settingSources: ["user", "project", "local"],
      ...(maxThinkingTokens !== undefined && { maxThinkingTokens }),
      ...userProvidedOptions,
+      // CLAUDE_MODEL_CONFIG env var is a fallback for model
+      // configuration (e.g. Bedrock model ID overrides). When the caller
+      // provides settings via _meta, we intentionally ignore the env var —
+      // the caller is assumed to have full control over model configuration.
+      ...(!userProvidedOptions?.settings &&
+        modelConfig && {
+          settings: {
+            ...(modelConfig.modelOverrides && { modelOverrides: modelConfig.modelOverrides }),
+            ...(modelConfig.availableModels && { availableModels: modelConfig.availableModels }),
+          },
+        }),
      env: {
        ...process.env,
        ...userProvidedOptions?.env,
@@ -1455,14 +1779,7 @@ export class ClaudeAcpAgent implements Agent {
      allowDangerouslySkipPermissions: ALLOW_BYPASS,
      permissionMode,
      canUseTool: this.canUseTool(sessionId),
-      // note: although not documented by the types, passing an absolute path
-      // here works to find zed's managed node version.
-      executable: isStaticBinary() ? undefined : (process.execPath as any),
-      ...(process.env.CLAUDE_CODE_EXECUTABLE
-        ? { pathToClaudeCodeExecutable: process.env.CLAUDE_CODE_EXECUTABLE }
-        : isStaticBinary()
-          ? { pathToClaudeCodeExecutable: await claudeCliPath() }
-          : {}),
+      pathToClaudeCodeExecutable: process.env.CLAUDE_CODE_EXECUTABLE ?? (await claudeCliPath()),
      extraArgs: {
        ...userProvidedOptions?.extraArgs,
        "replay-user-messages": "",
@@ -1522,7 +1839,8 @@ export class ClaudeAcpAgent implements Agent {
      if (
        creationOpts.resume &&
        error instanceof Error &&
-        error.message === "Query closed before response received"
+        (error.message === "Query closed before response received" ||
+          error.message.includes("No conversation found with session ID"))
      ) {
        throw RequestError.resourceNotFound(sessionId);
      }
@@ -1546,7 +1864,7 @@ export class ClaudeAcpAgent implements Agent {
      {
        id: "auto",
        name: "Auto",
-        decription: "Use a model classifier to approve/deny permission prompts.",
+        description: "Use a model classifier to approve/deny permission prompts",
      },
      {
        id: "default",
@@ -1583,7 +1901,20 @@ export class ClaudeAcpAgent implements Agent {
      availableModes,
    };

-    const configOptions = buildConfigOptions(modes, models);
+    const configOptions = buildConfigOptions(
+      modes,
+      models,
+      initializationResult.models,
+      settingsManager.getSettings().effortLevel,
+    );
+
+    // Apply the initial effort level to the SDK so it matches the UI default
+    const initialEffort = configOptions.find((o) => o.id === "effort");
+    if (initialEffort && typeof initialEffort.currentValue === "string") {
+      await q.applyFlagSettings({
+        effortLevel: initialEffort.currentValue as Settings["effortLevel"],
+      });
+    }

    this.sessions[sessionId] = {
      query: q,
@@ -1600,11 +1931,15 @@ export class ClaudeAcpAgent implements Agent {
      },
      modes,
      models,
+      modelInfos: initializationResult.models,
      configOptions,
      promptRunning: false,
      pendingMessages: new Map(),
      nextPendingOrder: 0,
      abortController,
+      emitRawSDKMessages: sessionMeta?.claudeCode?.emitRawSDKMessages ?? false,
+      contextWindowSize:
+        inferContextWindowFromModel(models.currentModelId) ?? DEFAULT_CONTEXT_WINDOW,
    };

    return {
@@ -1616,6 +1951,17 @@ export class ClaudeAcpAgent implements Agent {
  }
 }

+function shouldEmitRawMessage(
+  config: boolean | SDKMessageFilter[],
+  message: { type: string; subtype?: string },
+): boolean {
+  if (config === true) return true;
+  if (config === false) return false;
+  return config.some(
+    (f) => f.type === message.type && (f.subtype === undefined || f.subtype === message.subtype),
+  );
+}
+
 function sessionUsage(session: Session) {
  return {
    inputTokens: session.accumulatedUsage.inputTokens,
@@ -1630,6 +1976,57 @@ function sessionUsage(session: Session) {
  };
 }

+/** Sum all four fields as a proxy for post-turn context occupancy: the current
+ *  turn's output becomes next turn's input. Per the Anthropic API, input_tokens
+ *  excludes cache tokens — cache_read and cache_creation are reported
+ *  separately — so summing all four is not double-counting. */
+function totalTokens(usage: UsageSnapshot): number {
+  return (
+    usage.input_tokens +
+    usage.output_tokens +
+    usage.cache_read_input_tokens +
+    usage.cache_creation_input_tokens
+  );
+}
+
+/**
+ * Build the `data` payload attached to a `RequestError.internalError` when we
+ * have a categorical error from the Claude SDK. Returns `undefined` when no
+ * categorical error is available, matching the previous behavior of passing
+ * `undefined` to `RequestError.internalError`.
+ *
+ * The `errorKind` field is a convention for ACP clients to dispatch on
+ * without having to pattern-match the human-readable message text. Clients
+ * that don't understand it fall back to the existing message-based rendering.
+ */
+function errorKindData(
+  errorKind: SDKAssistantMessageError | undefined,
+): { errorKind: SDKAssistantMessageError } | undefined {
+  return errorKind ? { errorKind } : undefined;
+}
+
+/** Project a nullable API usage object into our non-null snapshot shape.
+ *  Both SDK message_start and assistant message `usage` have `number | null`
+ *  cache fields; we coerce absent values to 0 so `totalTokens` never hits
+ *  NaN. `input_tokens`/`output_tokens` are typed `number` by the SDK but
+ *  synthetic or third-party-backend stream events have been observed emitting
+ *  them as null/undefined — coerce those too so a malformed upstream event
+ *  can't leak NaN into the wire `used` field. Delta events have different
+ *  semantics (cumulative + prev fallback) and are handled inline. */
+function snapshotFromUsage(usage: {
+  input_tokens?: number | null;
+  output_tokens?: number | null;
+  cache_read_input_tokens?: number | null;
+  cache_creation_input_tokens?: number | null;
+}): UsageSnapshot {
+  return {
+    input_tokens: usage.input_tokens ?? 0,
+    output_tokens: usage.output_tokens ?? 0,
+    cache_read_input_tokens: usage.cache_read_input_tokens ?? 0,
+    cache_creation_input_tokens: usage.cache_creation_input_tokens ?? 0,
+  };
+}
+
 function createEnvForGateway(gatewayMeta?: GatewayAuthMeta) {
  if (!gatewayMeta) {
    return {};
@@ -1646,8 +2043,10 @@ function createEnvForGateway(gatewayMeta?: GatewayAuthMeta) {
 function buildConfigOptions(
  modes: SessionModeState,
  models: SessionModelState,
+  modelInfos: ModelInfo[],
+  currentEffortLevel?: string,
 ): SessionConfigOption[] {
-  return [
+  const options: SessionConfigOption[] = [
    {
      id: "mode",
      name: "Mode",
@@ -1675,6 +2074,46 @@ function buildConfigOptions(
      })),
    },
  ];
+
+  // Add effort level option based on the currently selected model
+  const currentModelInfo = modelInfos.find((m) => m.value === models.currentModelId);
+  const supportedLevels = currentModelInfo?.supportsEffort
+    ? (currentModelInfo.supportedEffortLevels ?? [])
+    : [];
+
+  if (supportedLevels.length > 0) {
+    const effortOptions = supportedLevels.map((level) => ({
+      value: level,
+      name: level
+        .split(/[_-]/)
+        .map((part) => (part ? part.charAt(0).toUpperCase() + part.slice(1) : part))
+        .join(" "),
+    }));
+
+    // Keep the current level if valid, otherwise prefer xhigh (Claude Code's
+    // recommended default for capable models), then high (the API default).
+    const includes = (l: string) => (supportedLevels as string[]).includes(l);
+    const validEffort =
+      currentEffortLevel && includes(currentEffortLevel)
+        ? currentEffortLevel
+        : includes("xhigh")
+          ? "xhigh"
+          : includes("high")
+            ? "high"
+            : supportedLevels[0];
+
+    options.push({
+      id: "effort",
+      name: "Effort",
+      description: "Available effort levels for this model",
+      category: "effort",
+      type: "select",
+      currentValue: validEffort,
+      options: effortOptions,
+    });
+  }
+
+  return options;
 }

 // Claude Code CLI persists display strings like "opus[1m]" in settings,
@@ -2000,8 +2439,8 @@ export function toAcpNotifications(
        const alreadyCached = chunk.id in toolUseCache;
        toolUseCache[chunk.id] = chunk;
        if (chunk.name === "TodoWrite") {
-          // @ts-expect-error - sometimes input is empty object
-          if (Array.isArray(chunk.input.todos)) {
+          // @ts-expect-error - sometimes input is empty object or undefined
+          if (Array.isArray(chunk.input?.todos)) {
            update = {
              sessionUpdate: "plan",
              entries: planEntries(chunk.input as { todos: ClaudePlanEntry[] }),
@@ -2155,6 +2594,7 @@ export function toAcpNotifications(
      case "container_upload":
      case "compaction":
      case "compaction_delta":
+      case "advisor_tool_result":
        break;

      default:
@@ -2237,7 +2677,12 @@ export function runAcp() {
  const output = nodeToWebReadable(process.stdin);

  const stream = ndJsonStream(input, output);
-  new AgentSideConnection((client) => new ClaudeAcpAgent(client), stream);
+  let agent!: ClaudeAcpAgent;
+  const connection = new AgentSideConnection((client) => {
+    agent = new ClaudeAcpAgent(client);
+    return agent;
+  }, stream);
+  return { connection, agent };
 }

 function commonPrefixLength(a: string, b: string) {
@@ -2248,6 +2693,30 @@ function commonPrefixLength(a: string, b: string) {
  return i;
 }

+/** Best-effort first guess of a model's context window from its ID, used only
+ *  until a `result` message arrives with the authoritative `modelUsage` value.
+ *  Anthropic 1M-context variants encode "1m" as a distinct token in the SDK
+ *  model ID (e.g., "claude-opus-4-6-1m"), which `\b1m\b` catches without also
+ *  matching things like "10m" or embedded substrings. */
+function inferContextWindowFromModel(model: string): number | null {
+  if (/\b1m\b/i.test(model)) return 1_000_000;
+  return null;
+}
+
+function parseModelConfig(
+  raw: string | undefined,
+): { modelOverrides?: Record<string, string>; availableModels?: string[] } | undefined {
+  if (!raw) return undefined;
+  const parsed = JSON.parse(raw);
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new Error("CLAUDE_MODEL_CONFIG must be a JSON object");
+  }
+  const result: { modelOverrides?: Record<string, string>; availableModels?: string[] } = {};
+  if (parsed.modelOverrides !== undefined) result.modelOverrides = parsed.modelOverrides;
+  if (parsed.availableModels !== undefined) result.availableModels = parsed.availableModels;
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
 function getMatchingModelUsage(modelUsage: Record<string, ModelUsage>, currentModel: string) {
  let bestKey: string | null = null;
  let bestLen = 0;
--- a/src/index.ts
+++ b/src/index.ts
@@ -5,8 +5,35 @@ import { loadManagedSettings, applyEnvironmentSettings } from "./utils.js";
 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) {
@@ -24,8 +51,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();
 }
--- a/src/lib.ts
+++ b/src/lib.ts
@@ -1,11 +1,14 @@
 // 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,
--- a/src/settings.ts
+++ b/src/settings.ts
@@ -22,6 +22,7 @@ export interface ClaudeCodeSettings {
  permissions?: PermissionSettings;
  env?: Record<string, string>;
  model?: string;
+  effortLevel?: string;
 }

 /**
@@ -188,6 +189,10 @@ export class SettingsManager {
        merged.model = settings.model;
      }

+      if (settings.effortLevel !== undefined) {
+        merged.effortLevel = settings.effortLevel;
+      }
+
      if (settings.permissions?.defaultMode !== undefined) {
        merged.permissions = {
          ...merged.permissions,
--- a/src/tests/acp-agent.test.ts
+++ b/src/tests/acp-agent.test.ts
--- a/src/tests/authorization.test.ts
+++ b/src/tests/authorization.test.ts
@@ -169,9 +169,9 @@ describe("authorization", () => {
    );
  });

-  it("NO_BROWSER falls back to single legacy login method", async () => {
+  it("SSH session falls back to single legacy login method", async () => {
    const [agent] = await createAgentMock();
-    vi.stubGlobal("process", { ...process, env: { ...process.env, NO_BROWSER: "1" } });
+    vi.stubGlobal("process", { ...process, env: { ...process.env, SSH_TTY: "/dev/pts/0" } });

    const initializeResponse = await agent.initialize({
      protocolVersion: 1,
@@ -189,12 +189,32 @@ describe("authorization", () => {
    );
  });

-  it("NO_BROWSER respects hide-claude-auth", async () => {
+  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, NO_BROWSER: "1" },
+      env: { ...process.env, SSH_CONNECTION: "192.168.1.1 12345 192.168.1.2 22" },
    });

    const initializeResponse = await agent.initialize({
--- a/src/tests/create-session-options.test.ts
+++ b/src/tests/create-session-options.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, vi } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import { AgentSideConnection, SessionNotification } from "@agentclientprotocol/sdk";
 import type { Options } from "@anthropic-ai/claude-agent-sdk";
 import type { ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
@@ -253,6 +253,189 @@ 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: "/test", mcpServers: [] });
+
+      expect(capturedOptions!.systemPrompt).toEqual({
+        type: "preset",
+        preset: "claude_code",
+      });
+    });
+
+    it("replaces the preset when a string is provided", async () => {
+      await agent.newSession({
+        cwd: "/test",
+        mcpServers: [],
+        _meta: { systemPrompt: "custom prompt" },
+      });
+
+      expect(capturedOptions!.systemPrompt).toBe("custom prompt");
+    });
+
+    it("forwards append", async () => {
+      await agent.newSession({
+        cwd: "/test",
+        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: "/test",
+        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: "/test",
+        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: "/test",
+        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: "/test", 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: "/test", 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: "/test", 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: "/test", 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: "/test",
+        mcpServers: [],
+        _meta: {
+          claudeCode: {
+            options: {
+              settings: {
+                model: "claude-sonnet-4-5",
+                modelOverrides: { "claude-opus-4-6": "meta-value" },
+              },
+            },
+          },
+        },
+      });
+
+      // _meta settings take precedence; env var is ignored entirely
+      expect(capturedOptions!.settings).toEqual({
+        model: "claude-sonnet-4-5",
+        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: "/test", mcpServers: [] })).rejects.toThrow();
+    });
+  });
+
  it("merges user-provided mcpServers with ACP mcpServers", async () => {
    await agent.newSession({
      cwd: "/test",
--- a/src/tests/session-config-options.test.ts
+++ b/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(() => ({
@@ -58,6 +59,19 @@ const MOCK_CONFIG_OPTIONS = [
      description: m.description,
    })),
  },
+  {
+    id: "effort",
+    name: "Effort",
+    description: "Available effort levels for this model",
+    type: "select",
+    category: "effort",
+    currentValue: "high",
+    options: [
+      { value: "low", name: "Low" },
+      { value: "medium", name: "Medium" },
+      { value: "high", name: "High" },
+    ],
+  },
 ];

 describe("session config options", () => {
@@ -67,6 +81,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 +97,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,
    };
  }

@@ -384,6 +413,101 @@ describe("session config options", () => {
      const modelOption = session.configOptions.find((o) => o.id === "model");
      expect(modelOption?.currentValue).toBe("claude-sonnet-4-5");
    });
+
+    it("includes updated effort in config_option_update 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-5",
+          displayName: "Claude Sonnet",
+          description: "Balanced",
+          supportsEffort: false,
+        },
+      ];
+
+      await agent.unstable_setSessionModel({
+        sessionId: SESSION_ID,
+        modelId: "claude-sonnet-4-5",
+      });
+
+      const configUpdate = sessionUpdates.find(
+        (n) => n.update.sessionUpdate === "config_option_update",
+      );
+      expect(configUpdate).toBeDefined();
+      const effortOption = (configUpdate?.update as any).configOptions.find(
+        (o: any) => o.id === "effort",
+      );
+      expect(effortOption).toBeUndefined();
+      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: undefined });
+    });
+
+    it("clamps effort in config_option_update 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-5",
+          displayName: "Claude Sonnet",
+          description: "Balanced",
+          supportsEffort: true,
+          supportedEffortLevels: ["low", "medium", "high"],
+        },
+      ];
+
+      await agent.unstable_setSessionModel({
+        sessionId: SESSION_ID,
+        modelId: "claude-sonnet-4-5",
+      });
+
+      const configUpdate = sessionUpdates.find(
+        (n) => n.update.sessionUpdate === "config_option_update",
+      );
+      const effortOption = (configUpdate?.update as any).configOptions.find(
+        (o: any) => o.id === "effort",
+      );
+      expect(effortOption).toBeDefined();
+      expect(effortOption.currentValue).toBe("high");
+      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: "high" });
+    });
+
+    it("preserves effort in config_option_update when new model supports same level", async () => {
+      // Set effort to "low" first
+      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
+      const effortOpt = session.configOptions.find((o: any) => o.id === "effort");
+      if (effortOpt) effortOpt.currentValue = "low";
+
+      await agent.unstable_setSessionModel({
+        sessionId: SESSION_ID,
+        modelId: "claude-sonnet-4-5",
+      });
+
+      const configUpdate = sessionUpdates.find(
+        (n) => n.update.sessionUpdate === "config_option_update",
+      );
+      const effortOption = (configUpdate?.update as any).configOptions.find(
+        (o: any) => o.id === "effort",
+      );
+      expect(effortOption?.currentValue).toBe("low");
+      // Effort didn't change, so applyFlagSettings should NOT be called
+      expect(applyFlagSettingsSpy).not.toHaveBeenCalled();
+    });
  });

  describe("no config_option_update notification when using setSessionConfigOption", () => {
@@ -418,6 +542,223 @@ 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("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-5",
+          displayName: "Claude Sonnet",
+          description: "Balanced",
+          supportsEffort: false,
+        },
+      ];
+
+      const response = await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-4-5",
+      });
+
+      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-5",
+          displayName: "Claude Sonnet",
+          description: "Balanced",
+          supportsEffort: false,
+        },
+      ];
+
+      await agent.setSessionConfigOption({
+        sessionId: SESSION_ID,
+        configId: "model",
+        value: "claude-sonnet-4-5",
+      });
+
+      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: undefined });
+    });
+
+    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-5" };
+      session.modelInfos = [
+        {
+          value: "claude-opus-4-5",
+          displayName: "Claude Opus",
+          description: "Most capable",
+          supportsEffort: true,
+          supportedEffortLevels: ["low", "medium", "high"],
+        },
+        {
+          value: "claude-sonnet-4-5",
+          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 "high" (the API default)
+      expect(effortOption?.currentValue).toBe("high");
+    });
+
+    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-5",
+          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-5",
+      });
+
+      const effortOption = response.configOptions.find((o) => o.id === "effort");
+      expect(effortOption).toBeDefined();
+      // "max" is not in sonnet's levels, so should fall back to "high" (the API default)
+      expect(effortOption?.currentValue).toBe("high");
+      // SDK should be told about the clamped value
+      expect(applyFlagSettingsSpy).toHaveBeenCalledWith({ effortLevel: "high" });
+    });
+
+    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-5",
+      });
+
+      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();
--- a/src/tests/session-load.test.ts
+++ b/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);
+});
--- a/src/tests/tools.test.ts
+++ b/src/tests/tools.test.ts
@@ -11,7 +11,12 @@ 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,
+  toolInfoFromToolUse,
+  planEntries,
+} from "../tools.js";

 describe("rawOutput in tool call updates", () => {
  const mockClient = {} as AgentSideConnection;
@@ -1271,3 +1276,112 @@ 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);
+  });
+});
--- a/src/tools.ts
+++ b/src/tools.ts
@@ -128,7 +128,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 +145,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 +163,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 +187,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 +216,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 +238,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 +289,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 +338,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 +357,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(", ")}`
@@ -368,7 +368,7 @@ export function toolInfoFromToolUse(
    }

    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",
@@ -661,10 +661,10 @@ 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",
  }));
 }