refactor: move AcpClient and Logger out of acp-agent.ts

Updates the Claude Agent SDK from 0.3.318 to 0.3.319, which bundles
Claude Code 2.1.319. Also updates `@anthropic-ai/sdk` (1.4.0 → 1.6.0)
and the transitive dependencies in the lockfile (`@babel/runtime`,
`@eslint-community/regexpp`, `@rolldown/pluginutils`, `hono`, `jose`,
`vite`).

## Reviewed, no change needed

- **`mcp_task` background tasks:** SDK sessions get these only with
`CLAUDE_AUTO_BACKGROUND_TASKS=1` and streaming input. The adapter does
not set that variable, so they don't occur by default. If a user sets
it, the Async Tasks panel shows the raw `mcp_task` type, and the
`resource_links` on the task notification are not forwarded. Left as a
possible follow-up.
- **`deleteSession()` rejects with `ENOTEMPTY`** when the session folder
is only partly removed. `session/delete` already rethrows any error
other than "not found".
- **`session_writes_lost`** is now sent only when the CLI exits 0. The
adapter only logs it.
- **`permissions.denyInsteadOfPrompting`:** with it set, the CLI denies
instead of calling `canUseTool`. That is the setting's intent.
- **`mcp_call.check_permissions`, `set_has_subscribers`,
`disableWindowsBashCommandSplit`:** the adapter does not use these.
- The comments on the `getSettings` and `unanswered` type workarounds
now name 0.3.319; both are still missing from the SDK's types.

## Not updated

TypeScript stays on 6.0.3: typescript-eslint 8.72.1 requires `typescript
<6.1.0`, so 7.0.2 has to wait for a typescript-eslint release that
supports it.

## Testing

`npm run build`, `npm run check` and `npm run test:run` pass. `npm run
test:integration` was not run.

.github/workflows/binaries.yml

@@ -0,0 +1,125 @@
+# Builds the standalone executables (scripts/build-binary.mjs) and smoke-tests
+# each one on a runner of its own platform. Each archive holds
+# `claude-agent-acp` and the Claude CLI (`claude`) it runs from its directory.
+# CI calls this to check that every target still builds and starts; the
+# release calls it with `upload: true` and attaches the archives to the GitHub
+# release.
+name: Binaries
+
+on:
+  workflow_call:
+    inputs:
+      upload:
+        description: Upload each archive as a workflow artifact for the release job.
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Binary (${{ matrix.target }})
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: bun-linux-x64
+            runner: ubuntu-latest
+            archive: claude-agent-acp-linux-x64.tar.gz
+          - target: bun-linux-arm64
+            runner: ubuntu-24.04-arm
+            archive: claude-agent-acp-linux-arm64.tar.gz
+          # npm skips the musl package on a glibc host, so these are
+          # cross-built and smoke-tested in an Alpine container.
+          - target: bun-linux-x64-musl
+            runner: ubuntu-latest
+            archive: claude-agent-acp-linux-x64-musl.tar.gz
+            musl: true
+          - target: bun-linux-arm64-musl
+            runner: ubuntu-24.04-arm
+            archive: claude-agent-acp-linux-arm64-musl.tar.gz
+            musl: true
+          - target: bun-darwin-x64
+            runner: macos-15-intel
+            archive: claude-agent-acp-darwin-x64.zip
+          - target: bun-darwin-arm64
+            runner: macos-latest
+            archive: claude-agent-acp-darwin-arm64.zip
+          - target: bun-windows-x64
+            runner: windows-latest
+            archive: claude-agent-acp-windows-x64.zip
+          - target: bun-windows-arm64
+            runner: windows-11-arm
+            archive: claude-agent-acp-windows-arm64.zip
+
+    defaults:
+      run:
+        shell: bash
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1
+        with:
+          node-version: "lts/*"
+          check-latest: true
+          cache: "npm"
+
+      # Unpinned: each build is smoke-tested on its platform before it uploads,
+      # so a Bun release that breaks the executable fails here instead of
+      # shipping. Pin a version if one ever regresses past the smoke test.
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: latest
+
+      - run: npm ci
+
+      - name: Install the musl Claude CLI package
+        if: ${{ matrix.musl }}
+        run: |
+          version="$(node -p "require('./node_modules/@anthropic-ai/claude-agent-sdk/package.json').version")"
+          npm install --no-save --force "@anthropic-ai/claude-agent-sdk-linux-${RUNNER_ARCH,,}-musl@$version"
+
+      - name: Build
+        run: |
+          echo "Built \`${{ matrix.target }}\` with Bun $(bun --version)" >> "$GITHUB_STEP_SUMMARY"
+          node scripts/build-binary.mjs --target ${{ matrix.target }}
+
+      - name: Smoke test
+        if: ${{ !matrix.musl }}
+        run: node scripts/smoke-binary.mjs
+
+      # Claude Code's Alpine requirements: libgcc and libstdc++.
+      - name: Smoke test (Alpine)
+        if: ${{ matrix.musl }}
+        run: |
+          docker run --rm -v "$PWD:/work" -w /work node:lts-alpine \
+            sh -c 'apk add --no-cache libgcc libstdc++ >/dev/null && node scripts/smoke-binary.mjs'
+
+      - name: Archive
+        if: ${{ inputs.upload }}
+        env:
+          ARCHIVE: ${{ matrix.archive }}
+        run: |
+          cd dist-bin
+          if [[ "$ARCHIVE" == *.zip ]]; then
+            if [[ "$RUNNER_OS" == "Windows" ]]; then
+              pwsh -Command "Compress-Archive -Path claude-agent-acp.exe,claude.exe -DestinationPath ../$ARCHIVE"
+            else
+              zip "../$ARCHIVE" claude-agent-acp claude
+            fi
+          else
+            tar czf "../$ARCHIVE" claude-agent-acp claude
+          fi
+
+      - name: Upload
+        if: ${{ inputs.upload }}
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: ${{ matrix.archive }}
+          path: ${{ matrix.archive }}
+          retention-days: 7
+          if-no-files-found: error

.github/workflows/ci.yml

@@ -27,6 +27,7 @@ jobs:
         uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1
         with:
           node-version: "lts/*"
+          check-latest: true
           cache: "npm"
 
       - name: Install dependencies
@@ -43,3 +44,7 @@ jobs:
 
       - name: Run tests
         run: npm run test:run
+
+  binaries:
+    name: Binaries
+    uses: ./.github/workflows/binaries.yml

.github/workflows/publish.yml

@@ -36,7 +36,7 @@ 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@bcd2ba49218906704ab6c1aa796996da409d3eb1
+        uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510
         id: generate-token
         with:
           # GitHub App ID secret name
@@ -77,6 +77,7 @@ jobs:
       - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1
         with:
           node-version: "lts/*"
+          check-latest: true
           registry-url: "https://registry.npmjs.org"
       - run: npm ci
       - run: npm run build
@@ -87,6 +88,38 @@ jobs:
           npm publish
           echo "version=$version" >> "$GITHUB_OUTPUT"
 
+  # Standalone executables for the GitHub release, stable releases only. They
+  # don't gate the npm publish: a failed build leaves the release without
+  # binaries, and re-running the failed jobs attaches them.
+  build-binaries:
+    name: Build binaries
+    needs: [release-please]
+    if: ${{ needs.release-please.outputs.release_created == 'true' }}
+    # The called workflow only reads the repository; upload-binaries does the write.
+    permissions:
+      contents: read
+    uses: ./.github/workflows/binaries.yml
+    with:
+      upload: true
+
+  upload-binaries:
+    name: Attach binaries to the release
+    runs-on: ubuntu-latest
+    needs: [release-please, build-binaries]
+    permissions:
+      contents: write
+    timeout-minutes: 15
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          path: artifacts
+          merge-multiple: true
+      - name: Upload to the release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ needs.release-please.outputs.tag_name }}
+        run: gh release upload "$TAG" artifacts/* --clobber --repo "$GITHUB_REPOSITORY"
+
   # Same shape as publish-npm. Tagging is a separate job, so nothing here needs
   # write access to the repository.
   publish-npm-preview:
@@ -132,6 +165,7 @@ jobs:
       - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1
         with:
           node-version: "lts/*"
+          check-latest: true
           registry-url: "https://registry.npmjs.org"
       # Ahead of the version bump, so this still validates the committed lockfile.
       - run: npm ci
@@ -197,7 +231,11 @@ jobs:
           echo "Tagged \`v$VERSION\` at \`$SHA\`" >> "$GITHUB_STEP_SUMMARY"
 
   trigger-registry-update:
-    needs: [publish-npm, publish-npm-preview]
+    # upload-binaries too, so a stable release's archives are attached before the
+    # registry reads the release: it takes each archive's sha256 from the release
+    # assets when it bumps the version. It only waits; a failed or skipped upload
+    # (every preview) doesn't stop the dispatch.
+    needs: [publish-npm, publish-npm-preview, upload-binaries]
     # Both channels dispatch this: the registry has its own handling for preview
     # versions. The two never fire together — a release merge publishes stable and
     # skips the preview, and every other push does the reverse — so the registry sees
@@ -254,7 +292,7 @@ jobs:
           exit 1
 
       - name: Generate token scoped to the registry repo
-        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1
+        uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510
         id: registry-token
         with:
           app-id: ${{ secrets.REGISTRY_UPDATER_APP_ID }}

.gitignore

@@ -3,4 +3,5 @@ dist
 .DS_Store
 .claude/*.local.*
 CLAUDE.local.md
-.idea/
+.idea/
+dist-bin

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.93.0"
+  ".": "0.101.0"
 }

AGENTS.md

@@ -16,13 +16,85 @@ npm run format        # prettier --write
 CI runs `format:check`, `lint`, `build` and `test:run`. Run `npm run check` before
 opening a PR.
 
-## Code comments
+## Coding guidelines
 
-Keep comments straightforward, concise, and concrete. Say what the code does and
-why, in plain terms: name the actual state, call, or failure involved instead of
-alluding to it. Prefer a short concrete example over an abstract description.
-Don't use vague phrases like "keeps it honest" or "the residual case" that make
-the reader reconstruct the meaning.
+- Keep edits consistent with the surrounding code's formatting, naming and idioms.
+- Keep comments concise and concrete. Name the actual state, call or failure
+  instead of alluding to it, prefer a short example over an abstract
+  description, and avoid vague phrases like "keeps it honest". A comment or doc
+  must be true on every code path it describes, and a doc that lists what a
+  result omits or rejects must name the actual cases.
+- When a request can't be served, throw a `RequestError` whose message says what
+  happened and what to do (e.g. "Try again when the turn ends"). Don't drop the
+  request silently.
+- Don't report success for work you start without awaiting it. If the detached
+  call can still refuse and its `.catch` only logs, check the refusal condition
+  first or report the failure to the client.
+- A result must not depend on what an earlier call happened to cache. A request
+  right after a restart, with cold caches, must return the same thing as one
+  after a warm-up.
+- If code relies on an ordering or call sequence that nothing enforces (e.g. an
+  echo arriving before the result), say so in a short comment.
+
+## Architecture and design fit
+
+- Before coding, read the code the change plugs into and find the module that
+  owns the state or concept. Build on that module, not beside it.
+- Don't add new features or components to `acp-agent.ts`. If no existing module fits the new
+  code cleanly, create a dedicated one that owns the feature's state and logic,
+  and keep the change in `acp-agent.ts` to the calls that wire it in.
+- Prefer extending an existing mechanism over adding a new one, even if it takes
+  a small refactor (moving a helper, generalizing a function). Add a parallel
+  path, special case or flag only when the existing structure can't support the
+  change.
+- Before writing new logic, check whether it already exists in a sibling handler
+  of the same flow or in a helper that works with the same data, and reuse it.
+  Paths that handle the same input must apply the same rules through the same
+  code: the live stream and the `session/load` replay, the command list and
+  command dispatch, `prompt` and `steer`. Two copies of one check drift apart.
+- Put guards, filters and cleanup in the module that owns the state, so every
+  caller gets them. If guards, flags or fallbacks pile up in one place,
+  restructure instead of adding another.
+- If a result is meant to match another request's output, reuse that request's
+  logic.
+- The adapter serves ACP v1 and v2. A change that is not meant for one protocol
+  version only must work correctly in both. `src/v2/` converts v2 requests to v1
+  and reuses the v1 logic; keep v2-only differences in the conversion.
+- A session runs one turn at a time. "Claude is working" means `startTurn`'s
+  check (an unsettled turn in `turnQueue`, or `foregroundWork` for the session);
+  don't write a narrower one. Anything that sends `session/update` must go
+  through the turn queue or be refused while the session is busy, or its output
+  lands inside another turn. Keep the session marked busy across awaited network
+  calls.
+- Don't branch on a local copy of state that Claude Code or a remote service
+  owns: it goes stale when the other side changes. Have a command set the state
+  the user asks for instead of toggling it.
+- A command or name the adapter adds must not shadow one that Claude Code or the
+  user's own commands and skills already provide.
+- New optional request fields and `_meta` keys must not reject requests that
+  were valid before.
+- If a workaround or new path is unavoidable (e.g. a Claude Code or SDK
+  limitation), say why in a short code comment and in the PR description.
+
+## Testing guidelines
+
+- Before adding a test, search `src/tests/` for existing tests of the same API
+  and scenario, and add to their file and `describe` block. Use the helpers in
+  `helpers.ts` and `session-doubles.ts` instead of copying setup.
+- Don't add cases that take the same code path. Tests that differ only in input
+  and expected output belong in one `it.each`. Don't repeat another test's
+  assertions; assert only what this test is about.
+- Reach a state the shortest way (e.g. set `session.tornDown = true`) instead of
+  driving a full flow with extra mocks, unless the flow is what you test.
+- Build test doubles from what the bundled Claude Code CLI really sends,
+  including fields like `origin` it echoes back and fields it omits. A double
+  simpler than the real message hides bugs. If unsure, check against the real
+  CLI (`npm run test:integration`).
+- Cover both ACP v1 and v2 when a change affects what a client receives
+  (updates, responses, replay). A change to internal logic only does not need
+  its tests duplicated per version.
+- For each behavior the docs or comments promise, including what is omitted or
+  rejected, have a test that would fail if it broke.
 
 ## Pull requests
 

CHANGELOG.md

@@ -1,5 +1,164 @@
 # Changelog
 
+## [0.101.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.100.0...v0.101.0) (2026-11-05)
+
+
+### Features
+
+* compact idle sessions before the prompt cache expires ([#1522](https://github.com/agentclientprotocol/claude-agent-acp/issues/1522)) ([a79d073](https://github.com/agentclientprotocol/claude-agent-acp/commit/a79d07324dc15808c94a889a3b60615cca5a9fbd)), closes [#1454](https://github.com/agentclientprotocol/claude-agent-acp/issues/1454) [#1518](https://github.com/agentclientprotocol/claude-agent-acp/issues/1518)
+* ship single-file executables built with bun ([#1524](https://github.com/agentclientprotocol/claude-agent-acp/issues/1524)) ([e3f0b6c](https://github.com/agentclientprotocol/claude-agent-acp/commit/e3f0b6c89c783939e6ca8c19c220c21b58263f46))
+* start sessions in Auto mode by default ([#1533](https://github.com/agentclientprotocol/claude-agent-acp/issues/1533)) ([7ea9eec](https://github.com/agentclientprotocol/claude-agent-acp/commit/7ea9eec8392a43191b25a5c3636c181cc7eb42f3))
+* stream the output of v2 background commands ([#1512](https://github.com/agentclientprotocol/claude-agent-acp/issues/1512)) ([53e3eec](https://github.com/agentclientprotocol/claude-agent-acp/commit/53e3eec0134209654f53c46f319aaac851b8fff0))
+
+
+### Bug Fixes
+
+* honor configured fallback for unavailable restored modes ([#1520](https://github.com/agentclientprotocol/claude-agent-acp/issues/1520)) ([8bbdea6](https://github.com/agentclientprotocol/claude-agent-acp/commit/8bbdea6cc62a7ae080cb73ff476ed28ad7574018))
+* update to @anthropic-ai/claude-agent-sdk 0.3.318 ([#1525](https://github.com/agentclientprotocol/claude-agent-acp/issues/1525)) ([1d4418f](https://github.com/agentclientprotocol/claude-agent-acp/commit/1d4418f80daf14c29cecc5b23286f52c7f0402ec))
+
+## [0.100.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.99.1...v0.100.0) (2026-11-02)
+
+
+### Features
+
+* list v2 background tool calls ([#1511](https://github.com/agentclientprotocol/claude-agent-acp/issues/1511)) ([4d79b9f](https://github.com/agentclientprotocol/claude-agent-acp/commit/4d79b9ffbce95c23928a5dd771d6c87476d37160))
+* report subagent working directories ([#1496](https://github.com/agentclientprotocol/claude-agent-acp/issues/1496)) ([eb78afa](https://github.com/agentclientprotocol/claude-agent-acp/commit/eb78afa8556b8fc4082495e48e3fd1762fb6a50f))
+* report v2 background work ([#1510](https://github.com/agentclientprotocol/claude-agent-acp/issues/1510)) ([5565259](https://github.com/agentclientprotocol/claude-agent-acp/commit/5565259771cb74e3a9bdbacfcbce43e061d81422))
+* report why Claude Code could not start a session ([#1508](https://github.com/agentclientprotocol/claude-agent-acp/issues/1508)) ([38cf656](https://github.com/agentclientprotocol/claude-agent-acp/commit/38cf656fc9d80fec2d1a16c472779803e2c802d2))
+
+
+### Bug Fixes
+
+* align session/cancel, session/close, and v2 setup with the ACP v2 spec ([#1494](https://github.com/agentclientprotocol/claude-agent-acp/issues/1494)) ([f50598a](https://github.com/agentclientprotocol/claude-agent-acp/commit/f50598a39c5dc3908d4b98a7213e01d63ea867d5))
+* forward v2 elicitation values and read dismissed v2 permission prompts as a refusal ([#1493](https://github.com/agentclientprotocol/claude-agent-acp/issues/1493)) ([3bc6711](https://github.com/agentclientprotocol/claude-agent-acp/commit/3bc671193c6456516fe05a0eaa53c17bdfb6a190))
+* keep native Windows paths in v2 git patches ([#1492](https://github.com/agentclientprotocol/claude-agent-acp/issues/1492)) ([c3428de](https://github.com/agentclientprotocol/claude-agent-acp/commit/c3428de1bf411c513b0703ddd56bb6c5fdff583c))
+* preserve live session settings across provider refreshes ([#1474](https://github.com/agentclientprotocol/claude-agent-acp/issues/1474)) ([e01a288](https://github.com/agentclientprotocol/claude-agent-acp/commit/e01a28838499dd6dd7c31e35708090b938e852c6))
+* reject unreadable skill manifests ([#1482](https://github.com/agentclientprotocol/claude-agent-acp/issues/1482)) ([99a6e76](https://github.com/agentclientprotocol/claude-agent-acp/commit/99a6e76158b9164e51bd62e3b89113beadea5ce2))
+* report the fresh context's usage when ExitPlanMode clears context ([#1484](https://github.com/agentclientprotocol/claude-agent-acp/issues/1484)) ([2fd46c8](https://github.com/agentclientprotocol/claude-agent-acp/commit/2fd46c866d4ff2939fe1b1245b15a536d6de7c0b))
+* update to @agentclientprotocol/sdk 2.2.0 ([#1491](https://github.com/agentclientprotocol/claude-agent-acp/issues/1491)) ([1d2b92f](https://github.com/agentclientprotocol/claude-agent-acp/commit/1d2b92feae5eeccde3ac738edca1f1d71250762e))
+* update to @agentclientprotocol/sdk 2.4.0 ([#1509](https://github.com/agentclientprotocol/claude-agent-acp/issues/1509)) ([720bbb3](https://github.com/agentclientprotocol/claude-agent-acp/commit/720bbb3e4c65874775a0bb9418799baf4b6e3680))
+* update to Claude Agent SDK 0.3.316 (Claude Code 2.1.316) ([#1507](https://github.com/agentclientprotocol/claude-agent-acp/issues/1507)) ([1d03064](https://github.com/agentclientprotocol/claude-agent-acp/commit/1d0306468b632c6a56b4fb076ad7a19f23d9e7b5))
+* validate session, prompt, config, and auth requests per the latest ACP spec ([#1495](https://github.com/agentclientprotocol/claude-agent-acp/issues/1495)) ([d2ef490](https://github.com/agentclientprotocol/claude-agent-acp/commit/d2ef490a318033049af00cb9164a39ac2dd1eb95))
+
+## [0.99.1](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.99.0...v0.99.1) (2026-10-29)
+
+
+### Bug Fixes
+
+* add approval id to plan ([#1469](https://github.com/agentclientprotocol/claude-agent-acp/issues/1469)) ([4b4b2c4](https://github.com/agentclientprotocol/claude-agent-acp/commit/4b4b2c4de7c492070f6260cacea5680b2e045a5a))
+* allow forking sessions into a different directory ([#1483](https://github.com/agentclientprotocol/claude-agent-acp/issues/1483)) ([8bd0bc9](https://github.com/agentclientprotocol/claude-agent-acp/commit/8bd0bc9b03fb4a30e0b1755128baad12a214a58d))
+* detect "Run /login" login-expired messages as authRequired ([#1481](https://github.com/agentclientprotocol/claude-agent-acp/issues/1481)) ([fccaebc](https://github.com/agentclientprotocol/claude-agent-acp/commit/fccaebcf87e8f37144ec1a64920c0c53997edabe))
+* mark plugin, bundled and nested Claude skills as skills for AIR ([#1473](https://github.com/agentclientprotocol/claude-agent-acp/issues/1473)) ([52c241e](https://github.com/agentclientprotocol/claude-agent-acp/commit/52c241e71512ec19c4dd79c95c51ce67f04d7aac))
+* title subagent sessions by their task ([#1479](https://github.com/agentclientprotocol/claude-agent-acp/issues/1479)) ([7dcb629](https://github.com/agentclientprotocol/claude-agent-acp/commit/7dcb62923d38ac24e386b0626fe123334341c445))
+
+## [0.99.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.98.0...v0.99.0) (2026-10-28)
+
+
+### Features
+
+* Add thinking display configuration ([#1081](https://github.com/agentclientprotocol/claude-agent-acp/issues/1081)) ([2f1f4d1](https://github.com/agentclientprotocol/claude-agent-acp/commit/2f1f4d144196c7518a7c072f9ae0e70ac9b91a44))
+* send embedded blob resources in prompts to Claude ([#1460](https://github.com/agentclientprotocol/claude-agent-acp/issues/1460)) ([d0ee308](https://github.com/agentclientprotocol/claude-agent-acp/commit/d0ee30813fbc79dbe122f7455c8e1746e09be458))
+* tell the client when an MCP server fails to start ([#1464](https://github.com/agentclientprotocol/claude-agent-acp/issues/1464)) ([54b35ee](https://github.com/agentclientprotocol/claude-agent-acp/commit/54b35ee0f4d765efc5bc39107a524891266c42ac))
+* update to Claude Agent SDK 0.3.312 ([#1471](https://github.com/agentclientprotocol/claude-agent-acp/issues/1471)) ([4cb8906](https://github.com/agentclientprotocol/claude-agent-acp/commit/4cb8906d32a618011cfeba3260e4eb1db2fd829f))
+* **v2:** send the current session info on session/resume ([#1462](https://github.com/agentclientprotocol/claude-agent-acp/issues/1462)) ([f6ed4a4](https://github.com/agentclientprotocol/claude-agent-acp/commit/f6ed4a4f7d9dd5b5e7ed4e9973d9661becb9f583))
+
+
+### Bug Fixes
+
+* deny a background permission request that the client cancels ([#1466](https://github.com/agentclientprotocol/claude-agent-acp/issues/1466)) ([f646c82](https://github.com/agentclientprotocol/claude-agent-acp/commit/f646c821f1b05df471aac8f1018ea08e2a793f6e))
+* don't report decline when the client can't render an MCP elicitation ([#1465](https://github.com/agentclientprotocol/claude-agent-acp/issues/1465)) ([54b869c](https://github.com/agentclientprotocol/claude-agent-acp/commit/54b869c990ad3efa25c976e8eb3ff5a37808a6a3))
+* list the current model among the model config option's values ([#1463](https://github.com/agentclientprotocol/claude-agent-acp/issues/1463)) ([8e6fe92](https://github.com/agentclientprotocol/claude-agent-acp/commit/8e6fe92a98dab8cec868a8a782e0ded55c94e571))
+* report EnterPlanMode tool calls with the switch_mode kind ([#1467](https://github.com/agentclientprotocol/claude-agent-acp/issues/1467)) ([93c1f43](https://github.com/agentclientprotocol/claude-agent-acp/commit/93c1f43519a6a542dc55a39985d0abd12195129d))
+* return ACP error codes for unknown sessions and invalid config values ([#1458](https://github.com/agentclientprotocol/claude-agent-acp/issues/1458)) ([c2e85cb](https://github.com/agentclientprotocol/claude-agent-acp/commit/c2e85cb58067d9b00e6609ce9e90d4ec3a5d0feb))
+* update ACP SDK to 2.1.0 (schema v1.27.0 / v2.0.0-alpha.10) ([9f9aebf](https://github.com/agentclientprotocol/claude-agent-acp/commit/9f9aebf44bdecab887b03871fee8a2885ceac19a))
+* **v2:** keep clients in sync with config changes and replayed tool calls ([#1461](https://github.com/agentclientprotocol/claude-agent-acp/issues/1461)) ([2a0c188](https://github.com/agentclientprotocol/claude-agent-acp/commit/2a0c188a0aebd0ea03fb449f72dfa53f98c7622d))
+* **v2:** reject MCP transports and prompt content the agent doesn't advertise ([#1459](https://github.com/agentclientprotocol/claude-agent-acp/issues/1459)) ([2480888](https://github.com/agentclientprotocol/claude-agent-acp/commit/2480888b90498158054266bdb3bd7f22822e1b73))
+
+## [0.98.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.97.0...v0.98.0) (2026-10-27)
+
+
+### Features
+
+* add batch session metadata lookup ([#1408](https://github.com/agentclientprotocol/claude-agent-acp/issues/1408)) ([0ce42f2](https://github.com/agentclientprotocol/claude-agent-acp/commit/0ce42f2c312d190f78024d8b4b1ae5f00d9e5939))
+
+
+### Bug Fixes
+
+* publish Monitor async tasks as monitors ([#1452](https://github.com/agentclientprotocol/claude-agent-acp/issues/1452)) ([4324dce](https://github.com/agentclientprotocol/claude-agent-acp/commit/4324dce4be877c55385b3389cebac1c63d08f456))
+* settle the tool call of a SandboxNetworkAccess permission request ([#1448](https://github.com/agentclientprotocol/claude-agent-acp/issues/1448)) ([8f43ac8](https://github.com/agentclientprotocol/claude-agent-acp/commit/8f43ac808931a3f14719bbed37b9b153c9933139))
+* **v2:** leave the tool call status out of permission subjects ([#1447](https://github.com/agentclientprotocol/claude-agent-acp/issues/1447)) ([c7c80f7](https://github.com/agentclientprotocol/claude-agent-acp/commit/c7c80f7b26f8d90f7f1c828036db64bc46dddddf))
+
+## [0.97.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.96.0...v0.97.0) (2026-10-26)
+
+
+### Features
+
+* add ultracode session config option ([#1438](https://github.com/agentclientprotocol/claude-agent-acp/issues/1438)) ([de96cef](https://github.com/agentclientprotocol/claude-agent-acp/commit/de96cef382d8daf27301f1f90ae4b5e7f665f73a))
+
+
+### Bug Fixes
+
+* bump body-parser from 2.3.0 to 2.4.0 ([#1436](https://github.com/agentclientprotocol/claude-agent-acp/issues/1436)) ([c26e640](https://github.com/agentclientprotocol/claude-agent-acp/commit/c26e640915739dc7a3cd0664f8f5879098e0fd83))
+* distinguish model options with duplicate labels ([#1286](https://github.com/agentclientprotocol/claude-agent-acp/issues/1286)) ([434be13](https://github.com/agentclientprotocol/claude-agent-acp/commit/434be13a33141af8655c6f7c30f574841bf2279c))
+* keep the usage-limit error when it arrives after compaction ([#1377](https://github.com/agentclientprotocol/claude-agent-acp/issues/1377)) ([2a1525e](https://github.com/agentclientprotocol/claude-agent-acp/commit/2a1525e57cd89246d1a50993fd6ba335c4e634ca))
+* pass --settings before the auth status subcommand ([#1392](https://github.com/agentclientprotocol/claude-agent-acp/issues/1392)) ([6a33ded](https://github.com/agentclientprotocol/claude-agent-acp/commit/6a33dedcbb90e7bf9db91207f0edbf19ca6d705e))
+* preserve foreground fork reports until launch completes ([#1431](https://github.com/agentclientprotocol/claude-agent-acp/issues/1431)) ([e369479](https://github.com/agentclientprotocol/claude-agent-acp/commit/e369479f93b34f84a11103323d097c44df42e02e))
+* settle advisor tool results before completing turns ([#1247](https://github.com/agentclientprotocol/claude-agent-acp/issues/1247)) ([bed795d](https://github.com/agentclientprotocol/claude-agent-acp/commit/bed795d261620e6d5113e427a7196d94e66e7034))
+* settle live steers folded into autonomous cycles ([#1185](https://github.com/agentclientprotocol/claude-agent-acp/issues/1185)) ([a4957d1](https://github.com/agentclientprotocol/claude-agent-acp/commit/a4957d17c1e1a925ba3b72b29c5dcde4faabbe17))
+
+## [0.96.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.95.0...v0.96.0) (2026-10-26)
+
+
+### Features
+
+* report SendMessage delegations as linked session messages ([#1424](https://github.com/agentclientprotocol/claude-agent-acp/issues/1424)) ([739dde3](https://github.com/agentclientprotocol/claude-agent-acp/commit/739dde3ae5bb848bdb90e2c9150e2cc4687d480c))
+* report the model of each native subagent ([#1432](https://github.com/agentclientprotocol/claude-agent-acp/issues/1432)) ([c319e5e](https://github.com/agentclientprotocol/claude-agent-acp/commit/c319e5e542aabe353bb2c5e177e4c5853392b8c4))
+
+
+### Bug Fixes
+
+* do not hold an AIR load replay until the CLI starts ([#1433](https://github.com/agentclientprotocol/claude-agent-acp/issues/1433)) ([eb9d63e](https://github.com/agentclientprotocol/claude-agent-acp/commit/eb9d63e5fde9b8fd8fe692dfb3280faba6626a42))
+* refine RFD child models after a load, and retry a failed model update ([#1434](https://github.com/agentclientprotocol/claude-agent-acp/issues/1434)) ([9a8bf71](https://github.com/agentclientprotocol/claude-agent-acp/commit/9a8bf71d454fa85d03f55d4101a77e3ea7a149d0))
+* send subagents' current state after a load response ([#1423](https://github.com/agentclientprotocol/claude-agent-acp/issues/1423)) ([17a967b](https://github.com/agentclientprotocol/claude-agent-acp/commit/17a967b4dab78bbb9cf9fedae60e6821578dc5cb))
+* update to Claude Code 2.1.310 ([#1435](https://github.com/agentclientprotocol/claude-agent-acp/issues/1435)) ([2f3c6bb](https://github.com/agentclientprotocol/claude-agent-acp/commit/2f3c6bb7b3451a00cd77d7bb31c09e690ca220b3))
+
+## [0.95.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.94.0...v0.95.0) (2026-10-23)
+
+
+### Features
+
+* end a turn at its result for AIR clients with backgroundSubagents ([#1262](https://github.com/agentclientprotocol/claude-agent-acp/issues/1262)) ([9b3a5c8](https://github.com/agentclientprotocol/claude-agent-acp/commit/9b3a5c891c75e78b985adb31f4e4b59a16ad2ebc))
+* report read-only subagent configuration ([#1417](https://github.com/agentclientprotocol/claude-agent-acp/issues/1417)) ([6ab670b](https://github.com/agentclientprotocol/claude-agent-acp/commit/6ab670baaefb30aaac2606d8ee6524e08243e5b5))
+* report RFD delegations as linked session messages ([#1405](https://github.com/agentclientprotocol/claude-agent-acp/issues/1405)) ([59e292e](https://github.com/agentclientprotocol/claude-agent-acp/commit/59e292e29f773cc6f03c0999993cbe8a2d97a7e3))
+* serve experimental ACP v2 ([#1400](https://github.com/agentclientprotocol/claude-agent-acp/issues/1400)) ([4d378f9](https://github.com/agentclientprotocol/claude-agent-acp/commit/4d378f93f36d37ba5ef64af87b617706dd9c6e82))
+* show messages typed in other Remote Control clients ([#1371](https://github.com/agentclientprotocol/claude-agent-acp/issues/1371)) ([5b11f47](https://github.com/agentclientprotocol/claude-agent-acp/commit/5b11f470b1c05b114c876b3b6e5b4df9441b1087))
+* update to Claude Code 2.1.309 ([#1413](https://github.com/agentclientprotocol/claude-agent-acp/issues/1413)) ([a1521b6](https://github.com/agentclientprotocol/claude-agent-acp/commit/a1521b6196c58dbc5065f9c19fc9694273d3d435))
+
+
+### Bug Fixes
+
+* bump fast-uri from 3.1.8 to 3.1.9 ([#1410](https://github.com/agentclientprotocol/claude-agent-acp/issues/1410)) ([0fe22ae](https://github.com/agentclientprotocol/claude-agent-acp/commit/0fe22ae5a172b228a574665bb7136b900746041d))
+* bump postcss from 8.5.30 to 8.5.31 in the minor group ([#1403](https://github.com/agentclientprotocol/claude-agent-acp/issues/1403)) ([ecaa2c9](https://github.com/agentclientprotocol/claude-agent-acp/commit/ecaa2c935b9f2b63c1846ca17c6c3398390fb0ef))
+* bump the minor group across 1 directory with 2 updates ([#1416](https://github.com/agentclientprotocol/claude-agent-acp/issues/1416)) ([f7d6030](https://github.com/agentclientprotocol/claude-agent-acp/commit/f7d6030c04af23171058772480d55f6d2aee5298))
+* IJAI-3744 keep a session running while its background tasks are open ([#1399](https://github.com/agentclientprotocol/claude-agent-acp/issues/1399)) ([e9f986b](https://github.com/agentclientprotocol/claude-agent-acp/commit/e9f986b8a941f5c1789078a39e474f247bd0db60))
+* publish the session title as soon as the CLI has it ([#1406](https://github.com/agentclientprotocol/claude-agent-acp/issues/1406)) ([50cd76e](https://github.com/agentclientprotocol/claude-agent-acp/commit/50cd76e78dd9bb1ab0e4850a8d95431175ab5947))
+* publish turns that Claude Code starts after end_turn as an async task in v1 ([#1390](https://github.com/agentclientprotocol/claude-agent-acp/issues/1390)) ([a1d0eee](https://github.com/agentclientprotocol/claude-agent-acp/commit/a1d0eeeaad3d67a0765f4b89e3d81c1af6ca0dbb))
+
+## [0.94.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.93.0...v0.94.0) (2026-10-19)
+
+
+### Features
+
+* send one end event after the session/load history replay for AIR ([#1361](https://github.com/agentclientprotocol/claude-agent-acp/issues/1361)) ([1420994](https://github.com/agentclientprotocol/claude-agent-acp/commit/1420994ced20919aad127a8bd0294de022449e35))
+
+
+### Bug Fixes
+
+* match OpenRouter model ids in the gateway model listing ([#1365](https://github.com/agentclientprotocol/claude-agent-acp/issues/1365)) ([bcf74c2](https://github.com/agentclientprotocol/claude-agent-acp/commit/bcf74c2fe8e32bd24714d45122529dcf2f99a279))
+* resolve a skill's SKILL.md by its declared name, not by its directory name ([#1372](https://github.com/agentclientprotocol/claude-agent-acp/issues/1372)) ([424db87](https://github.com/agentclientprotocol/claude-agent-acp/commit/424db8753581bfaf4c5bf278f8df8c089eec35da))
+* update to ACP SDK 2.0.0 ([#1386](https://github.com/agentclientprotocol/claude-agent-acp/issues/1386)) ([ff01e06](https://github.com/agentclientprotocol/claude-agent-acp/commit/ff01e06579225e00643914692994cd60da4d6225))
+* update to Claude Code 2.1.303 ([#1384](https://github.com/agentclientprotocol/claude-agent-acp/issues/1384)) ([2dab922](https://github.com/agentclientprotocol/claude-agent-acp/commit/2dab92264414d133fd6774f7a90241ea5192ba32))
+
 ## [0.93.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.92.0...v0.93.0) (2026-10-16)
 
 

README.md

@@ -17,6 +17,7 @@ This tool implements an ACP agent by using the official [Claude Agent SDK](https
 - Interactive (and background) terminals
 - Custom [Slash commands](https://docs.anthropic.com/en/docs/claude-code/slash-commands)
 - Client MCP servers
+- An Ultracode session config option, which turns on Claude Code's dynamic workflows for every task. It appears when dynamic workflows are enabled and the model supports ultracode (any model with `xhigh` effort)
 - `/mcp` in the chat: the MCP server status as a list. The adapter runs `/mcp reconnect`, `/mcp enable`, and `/mcp disable` through the SDK control API, because Claude Code refuses them in SDK mode. A reconnect of an ACP server that needs authentication starts MCP OAuth through URL elicitation
 - Session-scoped long-running goals for AIR through the [goal extension](docs/air-extensions.md#goal) under `_meta.jetbrains.air.goal`
 - Structured errors, recovery, and warnings through the opt-in [session failure extension](docs/air-extensions.md#session-failure)
@@ -35,6 +36,23 @@ To try changes that have landed on `main` but are not released yet, install from
 npm install @agentclientprotocol/claude-agent-acp@preview
 ```
 
+### Standalone executables
+
+Each release attaches archives for Linux (glibc and musl), macOS and Windows, on
+x64 and arm64, to its [GitHub release](https://github.com/agentclientprotocol/claude-agent-acp/releases).
+They need no Node.js install. Each holds two files: `claude-agent-acp`, and the
+Claude CLI (`claude`) it runs. Keep them in the same directory; a symlink to
+`claude-agent-acp` elsewhere works. To use a Claude CLI you already have
+instead, set `CLAUDE_CODE_EXECUTABLE`. On Alpine, install `libgcc` and
+`libstdc++` first.
+
+To build one for your machine (needs [Bun](https://bun.sh)) and check it:
+
+```sh
+npm run build:binary
+npm run smoke:binary            # add `-- --full` to drive a real session; needs a Claude login
+```
+
 ### Subagent sessions
 
 A client that declares `clientCapabilities.subagents`, other than JetBrains AIR, gets each Agent or
@@ -47,9 +65,26 @@ Task subagent as its own child session, following the [subagents RFD](https://gi
   `end_turn` or `cancelled` when the SDK gives the reason. A failure is `idle` with the `error`
   stop reason and the SDK's error text as its `error`. The child keeps its session for every
   delegation to it.
-- The prompt of the Agent or Task call that launches the child, and the message of each
-  SendMessage call that resumes it, is a `session_message` in the child's transcript. The tool
-  call stays a tool call of the session that made it.
+- A child that runs outside its parent's working directory, such as an Agent call with
+  `isolation: "worktree"`, gets its `cwd` on `subagent_update` before its first tool call. The
+  adapter takes it from the `cwd` of the child's own hooks: its SubagentStart hook runs before its
+  first model request. It sends `cwd: null` when the child is back in its parent's directory. A
+  child in its parent's directory gets no `cwd`, and no child gets `additionalDirectories`: Claude
+  Code gives a subagent the session's additional directories, so it inherits them. A replay
+  announces a child with the `cwd` that its transcript recorded, and clears it after the response
+  when that directory no longer exists.
+- Session messages replace the Agent or Task call that launches the child, which its parent is
+  not shown:
+  - The launch's prompt is a `session_message` in both transcripts: the parent's outgoing view and
+    the child's incoming one. Both use the launch's tool use id, and each names the other with the
+    draft RFD's `recipientMessageId` and `senderMessageId`.
+  - A foreground child's answer, from the launch's result, is the child's `session_message` to
+    the parent. In Claude Code's hand-back mode, the child's `SubagentHandback` call is its
+    message to the parent instead, in both transcripts and linked the same way.
+  - A launch whose child is never exposed is shown as a tool call after all, with its final
+    status.
+- The message of a SendMessage call that resumes the child is a `session_message` in the child's
+  transcript. The SendMessage call stays a tool call of the session that made it.
 - `session/cancel` on the parent interrupts Claude Code, which stops the foreground children that
   the turn waits on. Background children keep running, as the RFD prefers; a client stops one with
   its own `cancel`. Each stopped child reports `idle` with `cancelled` from Claude Code's own
@@ -65,8 +100,8 @@ Task subagent as its own child session, following the [subagents RFD](https://gi
   exits is `idle` with no stop reason.
 - A child whose parent is not yet known when it ends is not exposed, since the RFD forbids
   guessing its parent.
-- A replay restores each child under its live session id, from its own transcript: its prompt and
-  each SendMessage message are `session_message`s, and its end is an `idle` before the response.
+- A replay restores each child under its live session id, from its own transcript, with the same
+  session messages as live, and its end is an `idle` before the response.
   A launch without Claude Code's metadata file for the child stays an ordinary tool call of the
   parent, and a notice, for a client that takes notices, says that subagent history is missing.
 - After a load or resume, with or without replay, a SendMessage that resumes an agent from before
@@ -95,10 +130,13 @@ root session. Clients that use the historical `_meta["subagent-transcript"]` cap
 
 ### Experimental ACP v2
 
-Started with `CLAUDE_AGENT_ACP_EXPERIMENTAL_V2=1`, the adapter also serves the
-[draft ACP v2](https://agentclientprotocol.com/protocol/v2/overview): a client that asks for
-protocol version 2 or later in `initialize` gets v2, and every other client gets v1, as before.
-The draft can still change, and this surface changes with it.
+The adapter also serves the [draft ACP v2](https://agentclientprotocol.com/protocol/v2/overview):
+a client that asks for protocol version 2 or later in `initialize` gets v2, and every other client
+gets v1. The draft can still change, and this surface changes with it.
+
+`CLAUDE_AGENT_ACP_PROTOCOL` limits the adapter to one version. With `v1`, a client that asks
+for v2 is negotiated down to v1. With `v2`, the adapter rejects the `initialize` of a v1 client.
+`auto`, the default, serves both.
 
 On v2 the adapter serves the session baseline (`session/new`, `session/list`, `session/resume`
 with replay, `session/close`, `session/prompt`, `session/cancel`), `session/delete`,

docs/RELEASES.md

@@ -7,7 +7,9 @@ keeps a single release PR open, titled `chore(main): release X.Y.Z` and labelled
 `autorelease: pending`.
 
 Merging that PR is what releases. It tags `vX.Y.Z`, creates the GitHub release,
-publishes to npm, and dispatches a version update to the agent registry.
+publishes to npm, dispatches a version update to the agent registry, and
+attaches the [standalone executables](../README.md#standalone-executables) to
+the GitHub release. Previews get no executables.
 
 There is no manual release button, and versions are never typed in by hand: the
 version is an output of the commit history, not an input.
@@ -45,6 +47,9 @@ gh release view "v<version>"
 npm view "@agentclientprotocol/claude-agent-acp@<version>"
 ```
 
+The release should list 8 `claude-agent-acp-*` archives. They are attached a
+few minutes after the release is created, once every platform has built.
+
 ## Preview releases
 
 Every push to `main` that is not a release merge publishes a preview from the
@@ -203,6 +208,13 @@ npm versions are immutable. If the package already published and only the
 registry update failed, pass `-f publish_npm=false` so the run skips publishing
 and only re-dispatches the registry update.
 
+### The release has no executables
+
+`build-binaries` and `upload-binaries` don't gate npm, so a failed build only
+leaves the release without archives. Re-run the failed jobs of that publish run
+(`gh run rerun <run-id> --failed`); the upload uses `--clobber`, so archives
+already attached are replaced rather than duplicated.
+
 ### A preview published but the commit was not tagged
 
 Only the publish is irreversible, so re-run just the tag job:

docs/air-extensions.md

@@ -27,8 +27,10 @@ It describes only this adapter.
 - [Session failure](#session-failure)
 - [Native subagent sessions](#native-subagent-sessions)
 - [Session index](#session-index)
+- [Background subagents](#background-subagents)
 - [Context compaction](#context-compaction)
 - [Question custom answers](#question-custom-answers)
+- [Load replay end](#load-replay-end)
 - [Session fork point](#session-fork-point)
 - [Presentation hints](#presentation-hints)
 - [Removed keys](#removed-keys)
@@ -124,7 +126,8 @@ The `initialize` response of an AIR client carries the agent side of the extensi
           "asyncTasks",
           "recommendedValue",
           "diffPatch",
-          "planFile"
+          "planFile",
+          "backgroundSubagents"
         ],
         "goal": {
           "version": 1,
@@ -138,8 +141,8 @@ The `initialize` response of an AIR client carries the agent side of the extensi
 }
 ```
 
-The agent list does not depend on the capabilities that AIR declares, except `sessionIndex`: the agent lists it, together with `sessionArchive`, `sessionRename`, `sessionListSubscribe` and `sessionWorktrees`, only for a client that declared `sessionIndex`.
-An extension is active only when the client declared its capability. The client does not declare `sessionArchive`, `sessionRename`, `sessionListSubscribe` and `sessionWorktrees`.
+The agent list does not depend on the capabilities that AIR declares, except `sessionIndex`: the agent lists it, together with `sessionBatchGet`, `sessionArchive`, `sessionRename`, `sessionListSubscribe` and `sessionWorktrees`, only for a client that declared `sessionIndex`.
+An extension is active only when the client declared its capability. The client does not declare `sessionBatchGet`, `sessionArchive`, `sessionRename`, `sessionListSubscribe` and `sessionWorktrees`.
 The response to a client that is not AIR has no `_meta.jetbrains` key.
 
 ### Capabilities
@@ -153,11 +156,14 @@ The response to a client that is not AIR has no `_meta.jetbrains` key.
 | `agentFileChangeReport`  | yes                 | Accepts a report request on `session/prompt` and sends the changed file list.                                   | [Agent file-change report](#agent-file-change-report)   |
 | `nativeSubagentSessions` | yes                 | Reports an Agent or Task subagent as a native ACP child session.                                                | [Native subagent sessions](#native-subagent-sessions)   |
 | `planFile`               | yes                 | Sends the path of the plan file in place of the plan text of an ExitPlanMode.                                   | [Plan file](#plan-file)                                 |
+| `backgroundSubagents`    | yes                 | Ends a prompt turn at its result while background subagents still run.                                          | [Background subagents](#background-subagents)           |
 | `sessionIndex`           | on request          | Pages, orders and annotates `session/list`; adds rename, archive and a list subscription.                       | [Session index](#session-index)                         |
+| `sessionBatchGet`        | with `sessionIndex` | Supports `_session/batch_get` for metadata of known session IDs.                                                | [Batch get](#batch-get)                                 |
 | `sessionArchive`         | with `sessionIndex` | Nothing on its own: the agent lists it to tell that it supports `_session/archive` and `_session/unarchive`.    | [Archive](#archive)                                     |
 | `sessionRename`          | with `sessionIndex` | Nothing on its own: the agent lists it to tell that it supports `_session/rename`.                              | [Rename](#rename)                                       |
 | `sessionListSubscribe`   | with `sessionIndex` | Nothing on its own: the agent lists it to tell that it supports `_session/list/subscribe`.                      | [List subscription](#list-subscription)                 |
 | `sessionWorktrees`       | with `sessionIndex` | Nothing on its own: the agent lists it to tell that rows carry `agentWorktree` for a worktree Claude Code made. | [List response](#list-response)                         |
+| `loadReplayEnd`          | no                  | Sends one `session_info_update` after the whole history replay of a loaded session.                             | [Load replay end](#load-replay-end)                     |
 | `rawInputRendering`      | no                  | Sends no display copy of readable input in `content`. The client renders `rawInput`.                            | [Tool call contract](#tool-call-contract)               |
 
 The adapter ignores `planContentDelta`.
@@ -193,6 +199,7 @@ The adapter sends these keys only to an AIR client. "AIR" in the Gate column mea
 | `kind`                         | session mode `_meta.jetbrains.air` and mode config option value `_meta.jetbrains.air` | `standard`, `plan`, `auto_review`, or `full_access`                    | AIR                                                                                    |
 | `kind`                         | available command `_meta.jetbrains.air` of a skill                                    | `skill`                                                                | AIR, when the skill's `SKILL.md` is found; not for a built-in command or an MCP prompt |
 | `skillPath`                    | available command `_meta.jetbrains.air` of a skill                                    | absolute path of the skill's `SKILL.md`                                | AIR, together with `kind: "skill"`                                                     |
+| `loadReplayEnd`                | `session_info_update._meta.jetbrains.air`                                             | `true`                                                                 | `loadReplayEnd`                                                                        |
 | `fork`                         | `session/fork` request `_meta.jetbrains.air` (client to agent)                        | `{version: 1, messageId, messageFingerprint?, messageOccurrence?}`     | none                                                                                   |
 
 ## JetBrains shared keys
@@ -508,6 +515,17 @@ While the adapter does not know the path, a report carries no `planFilePath` key
 The adapter never sends a blank path, because AIR reads a present non-file value as a retraction.
 Without `rawInputRendering`, a `planFile` client gets no copy of the plan in `content` either.
 
+### Approved plan identity
+
+For an AIR client with plan operations, the approved plan ID is `plan-mode:<tool-call ID>`.
+Claude uses the SDK tool-call ID of ExitPlanMode.
+Each review keeps its own plan. Repeated updates of that review keep the same plan ID.
+AIR joins the plan to its review by ID, even when the text includes user edits.
+This link needs no extra metadata.
+The live result, history replay, and clear-context approval use the same identity.
+The identity does not depend on `planFile`: it also applies when the request carries inline plan text.
+Other clients keep the `plan-mode` ID.
+
 ### Fallback
 
 The plan text goes out as before in these cases:
@@ -701,7 +719,7 @@ A non-empty plan also gets one clear-context choice with the same priority.
 After that choice, the adapter stops the old private Claude query and hides that internal rejection.
 It starts a new private query under the same ACP session.
 It continues the turn with `Implement the following plan:` and the complete plan.
-The mode, model, agent, effort, Fast mode, and turn usage stay the same.
+The mode, model, agent, effort, Fast mode, ultracode, and turn usage stay the same.
 The SDK cannot apply `allowedPrompts` again, so those hints do not survive the handoff.
 
 The adapter does not allow a callback only because the session mode is `bypassPermissions`.
@@ -991,6 +1009,20 @@ When an announced task leaves that list, the adapter reports `stopped`.
 A later terminal event can correct that state to `completed` or `failed`.
 At shutdown, the adapter finishes each open task as `failed` or `stopped`.
 
+### Autonomous turn
+
+Claude Code can start a turn of its own after the prompt ended, for example to answer the notification of a finished background task.
+ACP v1 has no session state, so the adapter publishes such a turn as an async task.
+The task has the id `autonomous-turn-<uuid>`, the name `Claude is working`, `taskType: "turn"`, and `showInTranscript: false`.
+Its description is the summary of the last task notification, when there is one.
+The task starts at the SDK `running` state while no prompt is active or queued.
+When the state stays `running`, as it does while background agents run, it starts at the first root output with no prompt open.
+It ends `completed` at the result of the turn or at the SDK `idle` state, and `failed` at an error result.
+A coalesced placeholder result (`num_turns: 0`) does not end it.
+A prompt that the turn takes in ends the task, because that prompt owns the turn now.
+A stop request interrupts the turn instead of stopping an SDK task.
+It returns `{ "stopped": false }` while a prompt waits for its turn, because the interrupt would drop that prompt.
+
 ### Stop request
 
 The client sends `_session/async_task/stop`:
@@ -1262,8 +1294,8 @@ The session index makes `session/list` a bounded, ordered page with row metadata
 
 AIR declares `sessionIndex` in `_meta.jetbrains.air.capabilities`.
 Unlike the other capabilities, the agent advertises `sessionIndex` only to a client that declared it, and never under ACP v2.
-Exactly when it advertises `sessionIndex`, the agent also advertises `sessionArchive` (it supports `_session/archive` and `_session/unarchive`), `sessionRename` (it supports `_session/rename`), `sessionListSubscribe` (it supports `_session/list/subscribe` and `_session/list/unsubscribe`) and `sessionWorktrees` (rows carry `agentWorktree`, see [List response](#list-response)).
-The client does not declare these four; declaring them without `sessionIndex` enables nothing.
+Exactly when it advertises `sessionIndex`, the agent also advertises `sessionBatchGet` (it supports `_session/batch_get`), `sessionArchive` (it supports `_session/archive` and `_session/unarchive`), `sessionRename` (it supports `_session/rename`), `sessionListSubscribe` (it supports `_session/list/subscribe` and `_session/list/unsubscribe`) and `sessionWorktrees` (rows carry `agentWorktree`, see [List response](#list-response)).
+The client does not declare these five; declaring them without `sessionIndex` enables nothing.
 Everything in this section applies only to such a client, except where [Delete and close](#delete-and-close) says otherwise.
 A client without the capability gets the `session/list` of before: the SDK `listSessions` call, pages of 1000 by file mtime, `offset:N` cursors, and no row `_meta`.
 It gets no new notification, and the adapter starts no watcher for it.
@@ -1353,6 +1385,7 @@ Each row carries `_meta.jetbrains.air` with flat row fields of the RFDs. `archiv
   - a session this connection runs: the SDK `session_state_changed` state; `error` instead of `idle` when its last turn failed (an error result, `is_error` or an `error_*` subtype, that was not a cancel). A session whose query failed here (not a cancel) is reported as any other session, but `error` until its transcript shows a prompt or a turn end after the failure, unless a busy or waiting interactive CLI holds it;
   - a session no live Claude Code process holds: `idle`, or `error` when its last turn ended with an API error (an assistant record with `isApiErrorMessage: true`, also when the CLI's turn-end records follow it, with no prompt after it);
   - a session that an interactive CLI holds (not an `sdk-*` entrypoint) whose registry status is newer than the transcript: `busy` and `shell` are `running`, `waiting` is `requires_action`, `idle` is `idle`, or `error` after such an API error;
+  - any other held session whose last turn ended with an open background task: `running`, also after 10 minutes, until the registry status is `idle`. Claude Code wakes the session again when the task ends, so the session gets one `idle` at the last turn end, not one for each task. A background shell command (`toolUseResult.backgroundTaskId`) or an async sub-agent (`isAsync` with an `agentId`) opens a task. Its `<task-notification>` with a `<status>`, as a user record or a `queue-operation` `remove`, or the result of a `TaskStop` call closes it. A notification without a `<status>`, such as the check-in of a quiet shell or a `Monitor` event, keeps it open. Sidechain records open no task. The tail gives the tasks on top of those of an earlier scan when the file only grew within the tail; else the whole transcript is read, and only for such a held session. A background task that a sub-agent starts is not seen: it is only in the transcript of the sub-agent;
   - any other held session: `idle` after a finished turn (an assistant `end_turn`, a user interrupt, or the CLI turn-end records), `error` after a turn that ended with an API error, `running` for an unfinished turn written in the last 10 minutes, and no state otherwise.
 - The live processes come from `<config>/sessions/<pid>.json`, with the liveness rules of Claude Desktop: `kill(pid, 0)` (or `EPERM`), a matching `procStart`, no foreign `pidDomain`, and records older than 24 hours only with a matching `procStart`.
   The adapter never reads the `.key` files there and never changes the directory.
@@ -1421,6 +1454,71 @@ In all of the session index methods and in `session/delete`, a session id matche
 Loading an archived session does not unarchive it.
 The CLI cleanup still deletes old transcripts (`cleanupPeriodDays`), archived or not.
 
+### Batch get
+
+`_session/batch_get` refreshes metadata for retained session IDs, such as pinned
+sessions and folder members outside the recent list page. Check for
+`sessionBatchGet` in `initialize.result._meta.jetbrains.air.capabilities` before
+calling it.
+
+The params object must contain only `sessionIds`: an array of distinct,
+non-blank strings. IDs match exactly, without trimming or case normalization.
+Malformed params, duplicates or extra fields return `Invalid params` (`-32602`).
+The agent sets no limit on the number of IDs; the client chooses the batch size
+for the latency it accepts. Archived sessions and sessions in other projects
+or worktrees are eligible.
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 7,
+  "method": "_session/batch_get",
+  "params": { "sessionIds": ["oldA", "oldB", "oldC"] }
+}
+```
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 7,
+  "result": {
+    "sessions": [
+      {
+        "sessionId": "oldA",
+        "cwd": "/project",
+        "title": "Fix the build",
+        "updatedAt": "2026-01-01T00:00:00.000Z",
+        "_meta": { "jetbrains": { "air": { "version": 1, "archived": false } } }
+      }
+    ]
+  }
+}
+```
+
+The example IDs are placeholders for stored Claude session UUIDs. `sessions`
+contains the same full rows as `session/list` without a project filter, including
+archived sessions and `_meta.jetbrains.air`. Copies use the same
+newest-readable-copy selection as the list. Returned sessions preserve their
+relative request order. Non-UUID IDs and IDs without a listable transcript are
+omitted: absent, empty, unreadable or malformed transcripts, sidechains, sessions
+whose continuation has history, and transcripts whose cwd cannot be recovered.
+A sidecar alone does not supply a row.
+
+`{ "sessionIds": [] }` returns `{ "sessions": [] }` without reading the store.
+A store-wide failure, such as an unreadable projects root, rejects the request.
+Individual results reflect the store as each ID is read.
+
+Lookup normally addresses only the requested transcript filenames in each project
+and reads their metadata. A transcript without a cwd can use a sibling's cwd,
+as the list does. This fallback enumerates and stats sibling transcripts only
+in the directories of rows still missing a cwd, then reads at most 64 siblings
+per directory, newest mtime first. A failed recovery is cached for 60 seconds
+unless the directory mtime changes. Other project histories are not enumerated.
+The agent looks up 100 IDs at a time; the client may request any number of IDs.
+Merge returned rows with the recent page by `sessionId`. A batch read does not
+expand an existing list subscription's scope; refresh retained IDs outside that
+scope explicitly.
+
 ### List subscription
 
 `_session/list/subscribe { "cwd": "…" }` returns `{ "subscriptionId": "…" }`.
@@ -1444,6 +1542,7 @@ From then on the agent sends `_session/list/changes` notifications for the sessi
 
 - `cwd` is required and must be an absolute path; a missing, non-string or relative `cwd` is `-32602`. Other parameters are ignored.
 - The scope is the sessions of `cwd` and of the same subdirectory in every existing linked worktree of its repository, as a list with `includeWorktrees: true` resolves it, in any archive state. Sidechain and subagent transcripts are left out, as in the list.
+- There is no page or recent-session limit: changes to older pinned or folder sessions within that scope are reported even outside the page AIR loaded. Pinned IDs outside the subscribed project and worktrees are not tracked; `_session/batch_get` does not add them to the subscription. AIR must subscribe to their project scope or refresh them explicitly.
 - `sessions` holds the full current row of each session in scope that appeared, or whose `title`, `lastPromptAt`, `state`, `lastTurnEndedAt`, `cost`, `model`, `forkedFrom`, `agentWorktree` or `archived` changed since the last row sent for it on this subscription. A row is exactly the row of `session/list`, `_meta.jetbrains.air` included.
 - After subscribe, the first change of each session sends its row in full, even when only `updatedAt` changed. From then on, a change of `updatedAt` alone sends nothing; the new `updatedAt` comes with the next change.
 - `removed` holds the ids of sessions that left the scope: deleted (the transcript is gone), or moved to a path outside it. It may name a session the client does not list (one it never listed, one the list hides, such as a session continued in another one when that one changes); the client ignores such an id.
@@ -1470,7 +1569,7 @@ It is idempotent, and an unknown id also returns `{}`.
 `session/delete`:
 
 - a `sessionIndex` client: deletes every transcript of the session (empty ones too) and every `<sessionId>/` directory, also one left without a transcript by an earlier failed delete. Anything left behind fails the request. A session that runs here is closed first. As with the CLI, the session is deleted also when another Claude Code process has it open. An unknown session is `-32002`.
-- an AIR client without `sessionIndex`: archives the session instead of deleting it (the title records of [Archive](#archive)), because AIR uses delete for "Done" and can reopen the session. A session that runs here is closed first. The list hides archived sessions from such a client too: those whose custom title, as the SDK list reports it, is archived. A session without a transcript fails with the error of the SDK delete, as before.
+- an AIR client without `sessionIndex`: archives the session instead of deleting it (the title records of [Archive](#archive)), because AIR uses delete for "Done" and can reopen the session. A session that runs here is closed first. The list hides archived sessions from such a client too: those whose custom title, as the SDK list reports it, is archived. A session without a transcript has nothing to archive, so the delete succeeds, as ACP asks of a session that does not exist.
   A `sessionIndex` client sees such a session as archived (`archived: true`), as AIR's native Claude path does.
 - any other client: the SDK delete. A session without a transcript (unknown, deleted before, or
   never prompted) succeeds, as ACP asks.
@@ -1496,6 +1595,7 @@ Names and semantics follow them; the transport differs, and so do the `archived`
 | capability `sessionIndex` (`_meta.jetbrains.air`)                                                 | `sessionCapabilities.list.limit`                                                                                                                                                                                |
 | capability `sessionArchive` (`_meta.jetbrains.air`)                                               | `sessionCapabilities.archive` (#2161)                                                                                                                                                                           |
 | capability `sessionRename` (`_meta.jetbrains.air`)                                                | `sessionCapabilities.setTitle` (#1987)                                                                                                                                                                          |
+| capability `sessionBatchGet`, `_session/batch_get`                                                | none                                                                                                                                                                                                            |
 | `_meta.jetbrains.air.list.limit`                                                                  | `session/list` `limit`                                                                                                                                                                                          |
 | `_meta.jetbrains.air.list.includeWorktrees`                                                       | `session/list` `includeWorktrees`                                                                                                                                                                               |
 | `_meta.jetbrains.air.list.archived` (`"unarchived"`, `"archived"`, `"all"`)                       | `session/list` `archived` (#2161), a boolean there                                                                                                                                                              |
@@ -1521,6 +1621,45 @@ It differs in transport, until the RFD lands in the SDK, in the list filter, and
 - the list parameter is `_meta.jetbrains.air.list.archived`, and the state is `_meta.jetbrains.air.archived` on rows and in `session_info_update`, not the `archived` fields;
 - an AIR client without `sessionIndex` still archives with `session/delete` (see [Delete and close](#delete-and-close)), which the RFD asks clients not to do.
 
+## Background subagents
+
+A prompt turn can start a background Agent or Task subagent.
+A SendMessage tool call can also resume a subagent that ended.
+Claude Code sends the result of the turn when the main agent stops, also while such a subagent still runs.
+
+### Hold without the capability
+
+A client that does not declare `backgroundSubagents` gets the hold of issues #864 and #866.
+The adapter keeps the `session/prompt` request open while a subagent that the turn started or resumed runs.
+The subagent output, its permission requests and the followup summary of the model then go out inside the turn.
+The turn ends at the followup result, at an `idle` with no live subagent, at `session/cancel`, or when the next prompt starts.
+The hold protects a client that stops listening at the prompt response.
+
+### Behavior with the capability
+
+AIR declares `backgroundSubagents` in `initialize.clientCapabilities._meta.jetbrains.air.capabilities`.
+The capability applies to ACP v1 only. ACP v2 keeps the hold, and the agent does not advertise the capability to ACP v2.
+
+- The turn ends at its result with the stop reason of the result, usually `end_turn`.
+- The subagent updates, permission requests and elicitations go out after the prompt response.
+- The routing does not change: the native child session, else the root session with the parent tool call in `_meta.claudeCode.parentToolUseId`.
+- The followup cycle after a subagent ends is an autonomous cycle. Its updates go out of a turn. Its result does not end a turn.
+- A steer with no turn in flight starts a new turn, or returns `promptRequired` when the client asks for it.
+- `session/cancel` with no turn works as before: the adapter interrupts the SDK query and reports each native subagent session as cancelled.
+- The tool call of a running subagent does not fail the incomplete tool call check of the turn.
+- The [agent file-change report](#agent-file-change-report) of the turn does not include an edit that a subagent makes after the result.
+- An open permission request of a subagent counts as an open request for the next turn and for the steer priority.
+
+### Plan approval out of a turn
+
+The followup cycle can call ExitPlanMode. AIR then gets the permission request out of a turn.
+The request has no clear-context option, because the fresh query must continue an ACP turn.
+"No, keep planning" stops only the followup cycle. There is no turn to end.
+
+A prompt turn owns the request when the turn is active, or when Claude Code asks before the echo of its prompt.
+Then the request has the clear-context option.
+A turn that took over a followup cycle also owns the request of that cycle, and the accepted plan continues in that turn.
+
 ## Context compaction
 
 The adapter implements the ACP session compaction RFD for a client that declares `clientCapabilities.session.compaction`.
@@ -1540,14 +1679,14 @@ For AIR, both forms carry `_meta.jetbrains.air.contextCompaction`:
 }
 ```
 
-| Field        | Meaning                                                               |
-| ------------ | --------------------------------------------------------------------- |
-| `version`    | Must equal `1`.                                                       |
-| `trigger`    | `manual` or `automatic`.                                              |
-| `preTokens`  | The context size before the compaction.                               |
-| `postTokens` | The context size after the compaction.                                |
-| `durationMs` | The duration of the compaction.                                       |
-| `error`      | The error of a failed compaction. Only the tool call form carries it. |
+| Field        | Meaning                                                                                                  |
+| ------------ | -------------------------------------------------------------------------------------------------------- |
+| `version`    | Must equal `1`.                                                                                          |
+| `trigger`    | `manual`, `automatic`, or `idle`: the adapter compacted an idle session before its prompt cache expired. |
+| `preTokens`  | The context size before the compaction.                                                                  |
+| `postTokens` | The context size after the compaction.                                                                   |
+| `durationMs` | The duration of the compaction.                                                                          |
+| `error`      | The error of a failed compaction. Only the tool call form carries it.                                    |
 
 The standard `toolCallId` or `compactionId` and the `status` own the identity and the phase.
 The `compaction_update` form puts the error in the standard `error` field.
@@ -1576,6 +1715,32 @@ For AIR, the companion field also carries the same value under the root key `_me
 Released AIR versions read only that key.
 A client that is not AIR gets neither key.
 
+## Load replay end
+
+ACP has no signal that the history replay of `session/load` is over, other than the response.
+The adapter replays the transcript while the Claude Code CLI starts, so the history can arrive long before the response.
+
+The client declares `loadReplayEnd` in its capabilities. The agent does not advertise it.
+After the history replay of the loaded session, the agent then sends one more update for that session:
+
+```json
+{
+  "sessionId": "<loaded session>",
+  "update": {
+    "sessionUpdate": "session_info_update",
+    "_meta": { "jetbrains": { "air": { "version": 1, "loadReplayEnd": true } } }
+  }
+}
+```
+
+- The update has no `title` and no `updatedAt`. A `null` there would clear the value.
+- It comes after every replayed update, the subagent history that the replay sends to the child sessions included, and before the `session/load` response.
+- It comes also for an empty history.
+- It comes for `session/load` of a new or an already live session, and for the ACP v2 `session/resume` with `replayFrom: {type: "start"}`.
+- It does not come when the replay stops or fails. The replay stops when the CLI start fails during the replay.
+- It does not come for a live update, and it does not come to a client without the capability.
+- The `session/load` can still fail after it, for example when the CLI start fails after the replay. The event means that the recorded history arrived whole. The client decides what to do with the failed load.
+
 ## Session fork point
 
 AIR can fork a session at one agent message.

examples/simple-client.ts

@@ -82,10 +82,10 @@ import {
   client as acpClient,
   methods,
   ndJsonStream,
-} from "@agentclientprotocol/sdk";
+} from "@agentclientprotocol/sdk/unstable";
 // Type-only: Node's type stripping does not elide value imports, and these two
 // exist only in the .d.ts — importing them normally is a runtime SyntaxError.
-import type { AnyMessage, Stream } from "@agentclientprotocol/sdk";
+import type { AnyMessage, Stream } from "@agentclientprotocol/sdk/unstable";
 
 // ---------------------------------------------------------------- steering
 

examples/steering.ts

@@ -46,7 +46,7 @@ import {
   ndJsonStream,
   type PromptRequest,
   type PromptResponse,
-} from "@agentclientprotocol/sdk";
+} from "@agentclientprotocol/sdk/unstable";
 
 /** The steering extension method, per the ACP steering wire protocol. */
 const STEERING_METHOD = "_session/steering";

package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.93.0",
+  "version": "0.101.0",
   "description": "An ACP-compatible coding agent powered by the Claude Agent SDK (TypeScript)",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",
@@ -21,12 +21,15 @@
   "files": [
     "dist/",
     "!dist/tests/",
+    "!dist/binary-entry.*",
     "README.md",
     "LICENSE",
     "package.json"
   ],
   "scripts": {
     "build": "tsc",
+    "build:binary": "node scripts/build-binary.mjs",
+    "smoke:binary": "node scripts/smoke-binary.mjs",
     "start": "node dist/index.js",
     "dev": "npm run build && npm run start",
     "example:simple-client": "node --experimental-strip-types --disable-warning=ExperimentalWarning examples/simple-client.ts",
@@ -65,26 +68,25 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@agentclientprotocol/sdk": "1.9.0",
-    "@anthropic-ai/claude-agent-sdk": "0.3.300",
+    "@agentclientprotocol/sdk": "2.4.0",
+    "@anthropic-ai/claude-agent-sdk": "0.3.319",
     "diff": "9.0.0",
     "zod": "4.6.7"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "0.134.0",
+    "@anthropic-ai/sdk": "1.6.0",
     "@eslint/js": "10.0.1",
     "@tsconfig/node22": "22.0.6",
-    "@types/node": "26.6.5",
-    "@typescript-eslint/eslint-plugin": "8.71.2",
-    "@typescript-eslint/parser": "8.71.2",
+    "@types/node": "26.6.6",
+    "@typescript-eslint/eslint-plugin": "8.72.1",
+    "@typescript-eslint/parser": "8.72.1",
     "ajv": "8.20.0",
     "ajv-formats": "3.0.1",
-    "eslint": "10.12.0",
+    "eslint": "10.14.0",
     "eslint-config-prettier": "10.1.8",
-    "globals": "17.13.0",
+    "globals": "17.14.0",
     "prettier": "3.9.10",
-    "ts-node": "10.9.2",
     "typescript": "6.0.3",
-    "vitest": "5.0.4"
+    "vitest": "5.1.0"
   }
 }

scripts/build-binary.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+// Builds an executable of the agent with `bun build --compile` and copies the
+// target platform's Claude CLI next to it. Both files go in the release
+// archive: the executable runs the CLI from its own directory.
+//
+//   node scripts/build-binary.mjs [--target bun-linux-x64-musl] [--outfile path]
+//
+// --target defaults to the host. Cross-compiling needs the target's SDK
+// platform package installed; the script prints the install command when it
+// is missing.
+
+import { spawnSync } from "node:child_process";
+import { chmodSync, copyFileSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function hostTarget() {
+  const os = process.platform === "win32" ? "windows" : process.platform;
+  // Node linked against glibc reports its version; musl builds don't.
+  const musl =
+    process.platform === "linux" && !process.report.getReport().header.glibcVersionRuntime;
+  return `bun-${os}-${process.arch}${musl ? "-musl" : ""}`;
+}
+
+const { values } = parseArgs({
+  options: {
+    target: { type: "string", default: hostTarget() },
+    outfile: { type: "string" },
+  },
+});
+const target = values.target;
+
+// Bun targets look like `bun-<os>-<arch>` with optional `-musl`, `-baseline` or
+// `-modern` suffixes; the SDK names its packages `<platform>-<arch>[-musl]`.
+const match = /^bun-(linux|darwin|windows)-(x64|arm64|aarch64)(?:-.+)?$/.exec(target);
+if (!match) {
+  console.error(
+    `Unsupported target "${target}". Expected e.g. bun-linux-x64, bun-darwin-arm64, bun-windows-x64.`,
+  );
+  process.exit(1);
+}
+const [, os, rawArch] = match;
+const platform = os === "windows" ? "win32" : os;
+const arch = rawArch === "aarch64" ? "arm64" : rawArch;
+const musl = target.split("-").includes("musl");
+const exe = os === "windows" ? ".exe" : "";
+const cliPackage = `@anthropic-ai/claude-agent-sdk-${platform}-${arch}${musl ? "-musl" : ""}`;
+const cliSpecifier = `${cliPackage}/claude${exe}`;
+const outfile = resolve(values.outfile ?? join(repoRoot, "dist-bin", `claude-agent-acp${exe}`));
+
+// Resolve from the SDK, the way claudeCliPath() does at runtime, so a nested
+// install is checked rather than only a hoisted one.
+const sdkRequire = createRequire(
+  createRequire(join(repoRoot, "package.json")).resolve("@anthropic-ai/claude-agent-sdk"),
+);
+let cliPath;
+try {
+  cliPath = sdkRequire.resolve(cliSpecifier);
+} catch {
+  const sdkVersion = JSON.parse(
+    readFileSync(
+      join(dirname(sdkRequire.resolve("@anthropic-ai/claude-agent-sdk")), "package.json"),
+      "utf8",
+    ),
+  ).version;
+  console.error(
+    `${cliSpecifier} is not installed. npm only installs the host's platform package; for ${target} run:\n\n` +
+      `  npm install --no-save --force ${cliPackage}@${sdkVersion}\n`,
+  );
+  process.exit(1);
+}
+
+const bun = spawnSync(
+  "bun",
+  ["build", "src/binary-entry.ts", "--compile", "--target", target, "--outfile", outfile],
+  { cwd: repoRoot, stdio: "inherit", shell: process.platform === "win32" },
+);
+if (bun.error) {
+  console.error(`Could not run bun: ${bun.error.message}. Install it from https://bun.sh.`);
+  process.exit(1);
+}
+if (bun.status !== 0) process.exit(bun.status ?? 1);
+
+// The executable runs the CLI from its own directory (src/binary-entry.ts).
+const cliOutfile = join(dirname(outfile), `claude${exe}`);
+copyFileSync(cliPath, cliOutfile);
+chmodSync(cliOutfile, 0o755);
+console.log(`Copied ${cliSpecifier} to ${cliOutfile}`);

scripts/smoke-binary.mjs

@@ -0,0 +1,470 @@
+#!/usr/bin/env node
+// Smoke-tests a built agent over ACP. Defaults to the executable from
+// scripts/build-binary.mjs, with `claude` next to it. Pass another command
+// after `--` to compare, e.g.
+// `node scripts/smoke-binary.mjs --full -- node "$PWD/dist/index.js"` (the full
+// run starts the agent in a scratch directory, so paths must be absolute).
+//
+//   node scripts/smoke-binary.mjs            # no login needed
+//   node scripts/smoke-binary.mjs --full     # talks to the model; needs a logged-in Claude
+//
+// SMOKE_DEBUG=1 prints every tool call the full run saw.
+//
+// The basic run checks `--version`, `--cli --version`, `initialize` (v1 and
+// v2) and the `terminal-auth` login command. The
+// full run also has Claude use Bash, Read (text and image), Edit and a
+// subagent in a scratch directory, then cancels a turn, lists the session,
+// loads it in a fresh agent process, and forks and deletes it.
+//
+// Claude Code's native builds have no Grep or Glob tool: its Bash shell wraps
+// `grep` and `find` in functions that run the ugrep and bfs built into the
+// Claude binary at `$CLAUDE_CODE_EXECPATH`. The full run checks that those
+// run, since they are the helpers a packaged build could fail to reach.
+
+import { spawn, spawnSync } from "node:child_process";
+import {
+  copyFileSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import readline from "node:readline";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { deflateSync } from "node:zlib";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const { values, positionals } = parseArgs({
+  options: { full: { type: "boolean", default: false } },
+  allowPositionals: true,
+});
+const exe = process.platform === "win32" ? ".exe" : "";
+const [command, ...commandArgs] =
+  positionals.length > 0 ? positionals : [join(repoRoot, "dist-bin", `claude-agent-acp${exe}`)];
+
+let failures = 0;
+function check(ok, label, detail) {
+  console.log(
+    `${ok ? "ok  " : "FAIL"} ${label}${!ok && detail !== undefined ? `: ${detail}` : ""}`,
+  );
+  if (!ok) failures++;
+  return ok;
+}
+
+// ---------------------------------------------------------------- basic
+
+function runSync(args, [cmd, ...cmdArgs] = [command, ...commandArgs]) {
+  const result = spawnSync(cmd, [...cmdArgs, ...args], {
+    encoding: "utf8",
+    timeout: 60_000,
+  });
+  return { stdout: (result.stdout ?? "").trim(), error: result.error ?? result.stderr };
+}
+
+const version = JSON.parse(readFileSync(join(repoRoot, "package.json"), "utf8")).version;
+const own = runSync(["--version"]);
+check(own.stdout === version, `--version prints ${version}`, own.stdout || own.error);
+const cli = runSync(["--cli", "--version"]);
+check(
+  /\(Claude Code\)$/.test(cli.stdout),
+  "--cli --version runs the bundled Claude CLI",
+  cli.stdout || cli.error,
+);
+
+// The release archive's layout: the executable finds `claude` in the directory
+// of its real path. Only for the default executable; a `--` command has no
+// such layout.
+if (positionals.length === 0) {
+  const scratch = mkdtempSync(join(tmpdir(), "acp-layout-"));
+  try {
+    if (process.platform !== "win32") {
+      const link = join(scratch, "claude-agent-acp");
+      symlinkSync(command, link);
+      const linked = runSync(["--cli", "--version"], [link]);
+      check(
+        /\(Claude Code\)$/.test(linked.stdout),
+        "a symlink to the executable finds the bundled CLI",
+        linked.stdout || linked.error,
+      );
+      rmSync(link);
+    }
+    const alone = join(scratch, `claude-agent-acp${exe}`);
+    copyFileSync(command, alone);
+    const missing = runSync(["--cli", "--version"], [alone]);
+    check(
+      String(missing.error).includes("The Claude CLI is missing"),
+      "without claude next to it, says the CLI is missing",
+      missing.stdout || missing.error,
+    );
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+/** Starts the agent and speaks newline-delimited JSON-RPC to it. */
+function startAgent(cwd, onNotification) {
+  const child = spawn(command, commandArgs, { cwd, stdio: ["pipe", "pipe", "pipe"] });
+  const stderr = [];
+  child.stderr.on("data", (chunk) => stderr.push(chunk));
+  let nextId = 0;
+  const pending = new Map();
+  const write = (message) =>
+    child.stdin.write(JSON.stringify({ jsonrpc: "2.0", ...message }) + "\n");
+  readline.createInterface({ input: child.stdout }).on("line", (line) => {
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      check(false, "stdout carries only JSON-RPC", line.slice(0, 200));
+      return;
+    }
+    if (message.method === undefined && pending.has(message.id)) {
+      pending.get(message.id)(message);
+      pending.delete(message.id);
+    } else if (message.method === "session/request_permission") {
+      const allow =
+        message.params.options.find((o) => o.kind === "allow_once") ?? message.params.options[0];
+      write({
+        id: message.id,
+        result: { outcome: { outcome: "selected", optionId: allow.optionId } },
+      });
+    } else if (message.id !== undefined && message.method !== undefined) {
+      write({
+        id: message.id,
+        error: { code: -32601, message: `smoke client does not handle ${message.method}` },
+      });
+    } else {
+      onNotification?.(message);
+    }
+  });
+  const exited = new Promise((resolve) => child.on("exit", resolve));
+  // Answer anything still pending if the agent dies, instead of hanging.
+  let exitError;
+  exited.then((code) => {
+    exitError = { message: `agent exited with ${code}: ${Buffer.concat(stderr)}` };
+    for (const resolve of pending.values()) resolve({ error: exitError });
+    pending.clear();
+  });
+  return {
+    request(method, params) {
+      const id = ++nextId;
+      return new Promise((resolve) => {
+        if (exitError) return resolve({ error: exitError });
+        pending.set(id, resolve);
+        write({ id, method, params });
+      });
+    },
+    notify: (method, params) => write({ method, params }),
+    async stop() {
+      child.stdin.end();
+      const code = await Promise.race([
+        exited,
+        new Promise((r) => setTimeout(() => r("timeout"), 10_000)),
+      ]);
+      if (code === "timeout") child.kill();
+      return { code, stderr: Buffer.concat(stderr).toString() };
+    },
+  };
+}
+
+const initializeParams = { protocolVersion: 1, clientCapabilities: {} };
+{
+  const agent = startAgent(process.cwd());
+  const init = await agent.request("initialize", initializeParams);
+  check(
+    init.result?.agentInfo?.version === version,
+    "initialize answers",
+    JSON.stringify(init.error),
+  );
+  const { code } = await agent.stop();
+  check(code === 0, "exits 0 when stdin closes", code);
+}
+{
+  // The `terminal-auth` login command reruns the agent; run it with
+  // `--version` in place of `auth login --console` instead of logging in.
+  // `--version` wins over a stray argument, so also check that no path inside
+  // a compiled executable leaked into the arguments.
+  const agent = startAgent(process.cwd());
+  const init = await agent.request("initialize", {
+    protocolVersion: 1,
+    clientCapabilities: { _meta: { "terminal-auth": true } },
+  });
+  await agent.stop();
+  const login = init.result?.authMethods?.find((m) => m.id === "console-login")?._meta?.[
+    "terminal-auth"
+  ];
+  const cliArgs = login?.args?.slice(0, login.args.indexOf("--cli") + 1);
+  const rerun = login
+    ? runSync([...cliArgs, "--version"], [login.command])
+    : { stdout: "", error: "no terminal-auth console-login method" };
+  check(
+    /\(Claude Code\)$/.test(rerun.stdout) &&
+      !login.args.some((arg) => arg.includes("$bunfs") || arg.includes("~BUN")),
+    "the terminal-auth login command reruns the agent",
+    `${JSON.stringify(login)} -> ${rerun.stdout || rerun.error}`,
+  );
+}
+{
+  const agent = startAgent(process.cwd());
+  const init = await agent.request("initialize", {
+    protocolVersion: 2,
+    info: { name: "smoke-binary", version },
+    capabilities: {},
+  });
+  check(
+    init.result?.protocolVersion === 2,
+    "initialize answers ACP v2",
+    JSON.stringify(init.error),
+  );
+  await agent.stop();
+}
+
+// ---------------------------------------------------------------- full
+
+if (values.full) {
+  const work = mkdtempSync(join(tmpdir(), "acp-smoke-"));
+  try {
+    await fullSmoke(work);
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/** A solid red 16x16 PNG, so the model has something to name. */
+function redPng() {
+  const crcTable = Array.from({ length: 256 }, (_, n) => {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    return c >>> 0;
+  });
+  const crc = (buf) => {
+    let c = 0xffffffff;
+    for (const byte of buf) c = crcTable[(c ^ byte) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+  };
+  const chunk = (type, data) => {
+    const body = Buffer.concat([Buffer.from(type), data]);
+    const out = Buffer.alloc(body.length + 8);
+    out.writeUInt32BE(data.length, 0);
+    body.copy(out, 4);
+    out.writeUInt32BE(crc(body), body.length + 4);
+    return out;
+  };
+  const size = 16;
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(size, 0);
+  header.writeUInt32BE(size, 4);
+  header[8] = 8; // bit depth
+  header[9] = 2; // RGB
+  const row = Buffer.concat([Buffer.from([0]), Buffer.alloc(size * 3, Buffer.from([255, 0, 0]))]);
+  return Buffer.concat([
+    Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
+    chunk("IHDR", header),
+    chunk("IDAT", deflateSync(Buffer.concat(Array(size).fill(row)))),
+    chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+/** Writes its results to files so the checks don't depend on the model's reply. */
+function searchCommand(token) {
+  return [
+    `grep -rl "${token}" . > grep.out`,
+    'find . -name "*.md" > find.out',
+    '{ echo "$CLAUDE_CODE_EXECPATH"; grep --version | head -1; find --version | head -1; } > tools.out',
+  ].join("; ");
+}
+
+function searchResults(work) {
+  const read = (name) => {
+    try {
+      return readFileSync(join(work, name), "utf8");
+    } catch (error) {
+      return String(error);
+    }
+  };
+  const [execPath = "", grepVersion = "", findVersion = ""] = read("tools.out").split("\n");
+  return { grep: read("grep.out"), find: read("find.out"), execPath, grepVersion, findVersion };
+}
+
+async function fullSmoke(work) {
+  const token = `SMOKE_TOKEN_${process.pid}`;
+  mkdirSync(join(work, "notes"));
+  mkdirSync(join(work, "src"));
+  writeFileSync(join(work, "notes", "alpha.md"), `# Alpha\n\nThe token is ${token}.\n`);
+  writeFileSync(join(work, "notes", "beta.md"), "# Beta\n\nNothing here.\n");
+  writeFileSync(join(work, "src", "gamma.ts"), `export const value = "${token}";\n`);
+  writeFileSync(join(work, "pixel.png"), redPng());
+
+  const toolCalls = new Map();
+  let text = "";
+  const onNotification = (message) => {
+    if (message.method !== "session/update") return;
+    const update = message.params.update;
+    if (update.sessionUpdate === "agent_message_chunk" && update.content.type === "text") {
+      text += update.content.text;
+    } else if (
+      update.sessionUpdate === "tool_call" ||
+      update.sessionUpdate === "tool_call_update"
+    ) {
+      const call = toolCalls.get(update.toolCallId) ?? {};
+      toolCalls.set(update.toolCallId, {
+        ...call,
+        name: update._meta?.claudeCode?.toolName ?? call.name,
+        status: update.status ?? call.status,
+        title: update.title ?? call.title,
+      });
+    }
+  };
+
+  const agent = startAgent(work, onNotification);
+  await agent.request("initialize", initializeParams);
+  const created = await agent.request("session/new", { cwd: work, mcpServers: [] });
+  if (!check(created.result?.sessionId, "session/new", JSON.stringify(created.error))) {
+    console.error((await agent.stop()).stderr);
+    return;
+  }
+  const sessionId = created.result.sessionId;
+
+  const started = Date.now();
+  const prompt = await agent.request("session/prompt", {
+    sessionId,
+    prompt: [
+      {
+        type: "text",
+        text: [
+          "This is an automated smoke test of your tools. Do each step with the named tool, in order, one tool call per step:",
+          `1. Bash: run exactly \`${searchCommand(token)}\``,
+          "2. Read: read notes/alpha.md.",
+          "3. Read: read pixel.png and note its color.",
+          `4. Edit: in notes/alpha.md replace "${token}" with "EDITED".`,
+          "5. Bash: run `cat notes/alpha.md`.",
+          '6. Agent: launch a subagent (subagent_type "Explore") that counts the .ts files under src/ and reports the number.',
+          "Then reply with one line: SMOKE-DONE color=<the color of pixel.png> tsfiles=<the subagent's count>.",
+        ].join("\n"),
+      },
+    ],
+  });
+  check(
+    prompt.result?.stopReason === "end_turn",
+    "prompt ends with end_turn",
+    JSON.stringify(prompt.result ?? prompt.error),
+  );
+  console.log(`     (turn took ${Math.round((Date.now() - started) / 1000)}s)`);
+
+  const calls = [...toolCalls.values()];
+  if (process.env.SMOKE_DEBUG) console.log(JSON.stringify(calls, null, 1));
+  const searched = searchResults(work);
+  check(
+    searched.grep.includes("alpha.md") && searched.grep.includes("gamma.ts"),
+    "grep found the token",
+    searched.grep,
+  );
+  check(
+    searched.find.includes("alpha.md") && searched.find.includes("beta.md"),
+    "find listed the .md files",
+    searched.find,
+  );
+  check(
+    /^ugrep /.test(searched.grepVersion),
+    "grep ran Claude's embedded ugrep",
+    searched.grepVersion,
+  );
+  check(/^bfs /.test(searched.findVersion), "find ran Claude's embedded bfs", searched.findVersion);
+  console.log(`     (CLAUDE_CODE_EXECPATH=${searched.execPath})`);
+  for (const name of ["Read", "Edit", "Bash"]) {
+    const used = calls.filter((c) => c.name === name);
+    check(
+      used.length > 0 && used.every((c) => c.status === "completed"),
+      `${name} ran and completed`,
+      JSON.stringify(used),
+    );
+  }
+  const subagent = calls.filter((c) => c.name === "Agent" || c.name === "Task");
+  check(
+    subagent.some((c) => c.status === "completed"),
+    "subagent ran and completed",
+    JSON.stringify(subagent),
+  );
+  const failed = calls.filter((c) => c.status === "failed");
+  check(failed.length === 0, "no tool call failed", JSON.stringify(failed));
+  check(
+    readFileSync(join(work, "notes", "alpha.md"), "utf8").includes("EDITED"),
+    "Edit changed the file on disk",
+  );
+  check(
+    /SMOKE-DONE/.test(text) && /color=\W*red/i.test(text),
+    "image read as red",
+    text.slice(-300),
+  );
+  check(/tsfiles=\W*1\b/.test(text), "subagent counted 1 .ts file", text.slice(-300));
+
+  // A cancel interrupts a running Bash command and ends the turn as cancelled.
+  const cancelled = agent.request("session/prompt", {
+    sessionId,
+    prompt: [
+      { type: "text", text: "Use the Bash tool to run `sleep 60`. Do not run anything else." },
+    ],
+  });
+  const deadline = Date.now() + 60_000;
+  const bashRunning = () =>
+    [...toolCalls.values()].some((c) => c.name === "Bash" && c.status !== "completed");
+  while (!bashRunning() && Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  agent.notify("session/cancel", { sessionId });
+  const cancelResult = await cancelled;
+  check(
+    cancelResult.result?.stopReason === "cancelled",
+    "session/cancel ends the turn as cancelled",
+    JSON.stringify(cancelResult.result ?? cancelResult.error),
+  );
+
+  const listed = await agent.request("session/list", { cwd: work });
+  check(
+    listed.result?.sessions?.some((s) => s.sessionId === sessionId),
+    "session/list finds the session",
+    JSON.stringify(listed.result ?? listed.error),
+  );
+  const { code, stderr } = await agent.stop();
+  check(code === 0, "exits 0 when stdin closes", code);
+  if (failures > 0) console.error(stderr);
+
+  // A fresh process, so the replay comes from the transcript on disk.
+  let replayed = "";
+  const reloaded = startAgent(work, (message) => {
+    const update = message.params?.update;
+    if (update?.sessionUpdate === "user_message_chunk" && update.content.type === "text")
+      replayed += update.content.text;
+  });
+  await reloaded.request("initialize", initializeParams);
+  const loaded = await reloaded.request("session/load", { sessionId, cwd: work, mcpServers: [] });
+  check(!loaded.error, "session/load in a new process", JSON.stringify(loaded.error));
+  check(replayed.includes(token), "session/load replays the first prompt", replayed.slice(0, 200));
+
+  // Fork and delete go through the SDK's transcript helpers, not the CLI.
+  const forked = await reloaded.request("session/fork", { sessionId, cwd: work, mcpServers: [] });
+  const forkId = forked.result?.sessionId;
+  check(
+    forkId && forkId !== sessionId,
+    "session/fork",
+    JSON.stringify(forked.result ?? forked.error),
+  );
+  if (forkId) {
+    const deleted = await reloaded.request("session/delete", { sessionId: forkId });
+    const after = await reloaded.request("session/list", { cwd: work });
+    check(
+      !deleted.error && !after.result?.sessions?.some((s) => s.sessionId === forkId),
+      "session/delete removes the fork",
+      JSON.stringify(deleted.error ?? after.result),
+    );
+  }
+  await reloaded.stop();
+}
+
+console.log(failures === 0 ? "\nsmoke test passed" : `\n${failures} check(s) failed`);
+process.exit(failures === 0 ? 0 : 1);

src/acp-client.ts

@@ -0,0 +1,158 @@
+import {
+  AgentContext,
+  CompleteElicitationNotification,
+  CreateElicitationRequest,
+  CreateElicitationResponse,
+  methods,
+  ReadTextFileRequest,
+  ReadTextFileResponse,
+  RequestPermissionRequest,
+  RequestPermissionResponse,
+  SessionNotification,
+  WriteTextFileRequest,
+  WriteTextFileResponse,
+} from "@agentclientprotocol/sdk/unstable";
+import { AcpSessionNotification, asSdkSessionNotification } from "./acp-subagents.js";
+import { type AcpPermissionRequest } from "./permissions/presentation.js";
+import { ChangedMetaFilter } from "./tool-calls/changed-meta-filter.js";
+
+/**
+ * Logger interface for customizing logging output
+ */
+export interface Logger {
+  log: (...args: any[]) => void;
+  error: (...args: any[]) => void;
+  /** Optional: a caller that supplies no `warn` gets its warnings on `error`. */
+  warn?: (...args: any[]) => void;
+}
+
+/**
+ * Client-facing surface the agent calls back into. This is the subset of ACP
+ * client methods the agent actually uses, expressed as a narrow interface so
+ * tests can supply lightweight mocks. In production it is backed by
+ * {@link ClientConnection} over the SDK's typed `AgentContext`.
+ */
+export interface AcpClient {
+  sessionUpdate(params: AcpSessionNotification): Promise<void>;
+  /** `signal`, when aborted, sends `$/cancel_request` for the in-flight
+   *  permission request so the client can dismiss its prompt, and rejects the
+   *  call at once: a client that ignores the cancel never answers. */
+  requestPermission(
+    params: AcpPermissionRequest,
+    signal?: AbortSignal,
+  ): Promise<RequestPermissionResponse>;
+  readTextFile(params: ReadTextFileRequest): Promise<ReadTextFileResponse>;
+  writeTextFile(params: WriteTextFileRequest): Promise<WriteTextFileResponse>;
+  /** `signal`, when aborted, sends `$/cancel_request` for the in-flight
+   *  elicitation so the client can dismiss its prompt, and rejects the call
+   *  at once, as {@link requestPermission} does. */
+  createElicitation(
+    params: CreateElicitationRequest,
+    signal?: AbortSignal,
+  ): Promise<CreateElicitationResponse>;
+  completeElicitation(params: CompleteElicitationNotification): Promise<void>;
+  /** Send a custom (extension) notification, e.g. `_claude/sdkMessage`. */
+  extNotification(method: string, params: Record<string, unknown>): Promise<void>;
+}
+
+/**
+ * Bridges {@link AcpClient} to the connection-scoped {@link AgentContext}
+ * exposed by `AgentApp.connect(...)` as `connection.client`. The peer handle is
+ * valid for the entire connection lifetime, so it is captured once at
+ * construction.
+ */
+export class ClientConnection implements AcpClient {
+  constructor(private readonly ctx: AgentContext) {}
+
+  sessionUpdate(params: AcpSessionNotification): Promise<void> {
+    return this.ctx.notify(methods.client.session.update, asSdkSessionNotification(params));
+  }
+
+  requestPermission(
+    params: RequestPermissionRequest,
+    signal?: AbortSignal,
+  ): Promise<RequestPermissionResponse> {
+    return this.ctx.request(methods.client.session.requestPermission, params, {
+      cancellationSignal: signal,
+      stopWaitingOnCancel: true,
+    });
+  }
+
+  readTextFile(params: ReadTextFileRequest): Promise<ReadTextFileResponse> {
+    return this.ctx.request(methods.client.fs.readTextFile, params);
+  }
+
+  writeTextFile(params: WriteTextFileRequest): Promise<WriteTextFileResponse> {
+    return this.ctx.request(methods.client.fs.writeTextFile, params);
+  }
+
+  createElicitation(
+    params: CreateElicitationRequest,
+    signal?: AbortSignal,
+  ): Promise<CreateElicitationResponse> {
+    return this.ctx.request(methods.client.elicitation.create, params, {
+      cancellationSignal: signal,
+      stopWaitingOnCancel: true,
+    });
+  }
+
+  completeElicitation(params: CompleteElicitationNotification): Promise<void> {
+    return this.ctx.notify(methods.client.elicitation.complete, params);
+  }
+
+  extNotification(method: string, params: Record<string, unknown>): Promise<void> {
+    return this.ctx.notify(method, params);
+  }
+}
+
+/**
+ * The client that the agent talks to. For an AIR client, every session update
+ * passes the {@link ChangedMetaFilter} last, after the native subagent routing,
+ * so a `tool_call_update` carries only the `_meta` keys that changed. ACP
+ * merges only the top-level tool call fields, not the `_meta` keys. So another
+ * client gets the full `_meta` on each update.
+ */
+export class ChangedMetaClient implements AcpClient {
+  private readonly filter = new ChangedMetaFilter();
+
+  constructor(
+    private readonly inner: AcpClient,
+    private readonly airClient: () => boolean,
+  ) {}
+
+  async sessionUpdate(params: AcpSessionNotification): Promise<void> {
+    if (!this.airClient()) return this.inner.sessionUpdate(params);
+    const update = this.filter.apply(params.update as SessionNotification["update"]);
+    if (update) await this.inner.sessionUpdate({ ...params, update } as AcpSessionNotification);
+  }
+
+  requestPermission(
+    params: AcpPermissionRequest,
+    signal?: AbortSignal,
+  ): Promise<RequestPermissionResponse> {
+    return this.inner.requestPermission(params, signal);
+  }
+
+  readTextFile(params: ReadTextFileRequest): Promise<ReadTextFileResponse> {
+    return this.inner.readTextFile(params);
+  }
+
+  writeTextFile(params: WriteTextFileRequest): Promise<WriteTextFileResponse> {
+    return this.inner.writeTextFile(params);
+  }
+
+  createElicitation(
+    params: CreateElicitationRequest,
+    signal?: AbortSignal,
+  ): Promise<CreateElicitationResponse> {
+    return this.inner.createElicitation(params, signal);
+  }
+
+  completeElicitation(params: CompleteElicitationNotification): Promise<void> {
+    return this.inner.completeElicitation(params);
+  }
+
+  extNotification(method: string, params: Record<string, unknown>): Promise<void> {
+    return this.inner.extNotification(method, params);
+  }
+}

src/acp-subagents.ts

@@ -2,7 +2,7 @@ import type {
   ClientCapabilities,
   SessionCapabilities,
   SessionNotification,
-} from "@agentclientprotocol/sdk";
+} from "@agentclientprotocol/sdk/unstable";
 import {
   AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY,
   clientSupportsAirCapability,
@@ -17,7 +17,8 @@ export { AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY } from "./air-extension.js";
  * - `rfd`: the subagents RFD (agentclientprotocol/agent-client-protocol#1992,
  *   as revised): `subagent_update` and `session_message`, which the SDK types.
  *   A client that declares `clientCapabilities.subagents` and is not AIR gets
- *   it. (ACP v2 clients do not get subagents yet.)
+ *   it. (An ACP v2 client gets it without declaring anything, since subagents
+ *   are part of v2's baseline.)
  * - `air`: the earlier draft of that RFD, which AIR implements:
  *   `subagent_spawned` and `subagent_state_update`, typed below. AIR gets it,
  *   whichever capability it declares (`docs/air-extensions.md`).

src/agent-command.ts

@@ -0,0 +1,19 @@
+/**
+ * The command that starts this agent again with the flags it was started with,
+ * for a client to run in a terminal (e.g. `terminal-auth` login).
+ *
+ * Under Node, `process.argv` is `[node, script, ...flags]`, so the command is
+ * `node script ...flags`. In a `bun build --compile` executable it is
+ * `["bun", "/$bunfs/root/<name>", ...flags]` (`B:\~BUN\root\<name>` on
+ * Windows): `process.execPath` is the executable itself and `argv[1]` names a
+ * file inside it, which must not be passed back as an argument.
+ */
+export function agentCommand(argv: readonly string[] = process.argv): {
+  command: string;
+  args: string[];
+} {
+  const [, script, ...flags] = argv;
+  if (script === undefined) return { command: process.execPath, args: [] };
+  const compiled = script.includes("$bunfs") || script.includes("~BUN");
+  return { command: process.execPath, args: compiled ? flags : [script, ...flags] };
+}

src/air-extension.ts

@@ -1,5 +1,10 @@
 export const AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY = "nativeSubagentSessions";
 export const AIR_ASYNC_TASKS_CAPABILITY = "asyncTasks";
+/**
+ * A prompt turn ends at its result also while its background subagents run.
+ * The subagent updates and requests then go out after the prompt response.
+ */
+export const AIR_BACKGROUND_SUBAGENTS_CAPABILITY = "backgroundSubagents";
 export const AIR_SESSION_FAILURE_CAPABILITY = "sessionFailure";
 export const AIR_RECOMMENDED_CONFIG_VALUE_CAPABILITY = "recommendedValue";
 export const AIR_CUSTOM_INSTRUCTIONS_CAPABILITY = "customInstructions";
@@ -17,6 +22,9 @@ export const AIR_PLAN_FILE_CAPABILITY = "planFile";
  * subscription. Advertised only to a client that declares it.
  */
 export const AIR_SESSION_INDEX_CAPABILITY = "sessionIndex";
+/** Metadata lookup of known ids with `_session/batch_get`. Advertised
+ *  exactly when {@link AIR_SESSION_INDEX_CAPABILITY} is negotiated. */
+export const AIR_SESSION_BATCH_GET_CAPABILITY = "sessionBatchGet";
 /**
  * The agent supports `_session/archive` and `_session/unarchive`. Advertised
  * exactly when {@link AIR_SESSION_INDEX_CAPABILITY} is; the client does not
@@ -40,6 +48,14 @@ export const AIR_SESSION_LIST_SUBSCRIBE_CAPABILITY = "sessionListSubscribe";
  * {@link AIR_SESSION_INDEX_CAPABILITY} is; the client does not declare it.
  */
 export const AIR_SESSION_WORKTREES_CAPABILITY = "sessionWorktrees";
+/**
+ * The client wants to know when the history replay of a loaded session is
+ * whole. After the last replayed update, the agent sends one
+ * `session_info_update` with `_meta.jetbrains.air.loadReplayEnd: true` (see
+ * {@link AIR_LOAD_REPLAY_END_KEY}). The client declares it; the agent does not
+ * advertise it.
+ */
+export const AIR_LOAD_REPLAY_END_CAPABILITY = "loadReplayEnd";
 
 /** The `_meta.jetbrains.air` keys that the ACP tool call contract defines. */
 export const AIR_COMMAND_TITLE_KEY = "commandTitle";
@@ -53,6 +69,8 @@ export const AIR_KIND_KEY = "kind";
 export const AIR_SKILL_PATH_KEY = "skillPath";
 export const AIR_PERMISSION_KEY = "permission";
 export const AIR_CUSTOM_ANSWER_KEY = "customAnswer";
+/** The `_meta.jetbrains.air` key of the update that ends a whole history replay. */
+export const AIR_LOAD_REPLAY_END_KEY = "loadReplayEnd";
 /**
  * The root `_meta` spelling of {@link AIR_CUSTOM_ANSWER_KEY} that released
  * AIR versions read. Remove it when the ACP registry no longer serves AIR

src/async-tasks.ts

@@ -1,4 +1,5 @@
-import type { ClientCapabilities } from "@agentclientprotocol/sdk";
+import { randomUUID } from "node:crypto";
+import type { ClientCapabilities } from "@agentclientprotocol/sdk/unstable";
 import type { AcpSessionNotification, AsyncTaskState } from "./acp-subagents.js";
 import { AIR_ASYNC_TASKS_CAPABILITY, clientSupportsAirCapability } from "./air-extension.js";
 import { noticeOrTranscriptUpdate } from "./session-notices.js";
@@ -14,6 +15,8 @@ type AsyncTask = {
   taskType: string;
   description: string;
   showInTranscript: boolean;
+  /** A Monitor tool call or an SDK `local_monitor` task: published as a monitor the client cannot stop. */
+  monitor: boolean;
   outputFilePath?: string;
   toolCallId?: string;
   /**
@@ -39,6 +42,12 @@ type AsyncTask = {
   terminalSource?: TerminalSource;
   /** The optional fields that the client holds now, as JSON. */
   published: Map<string, string>;
+  /**
+   * Whether the task stands for a model turn that Claude Code started on its
+   * own, see {@link AsyncTaskRuntime.autonomousTurnStarted}. The SDK knows no
+   * such task, so its background task list never ends it.
+   */
+  autonomousTurn: boolean;
 };
 
 type TaskIdentity = { taskId?: unknown; task_id?: unknown };
@@ -121,6 +130,10 @@ export class AsyncTaskRuntime {
    * The oldest entries are dropped.
    */
   private readonly outputPathsByToolCall = new Map<string, string[]>();
+  /** The task of the autonomous turn that runs now. */
+  private autonomousTurn?: AsyncTask;
+  /** The summary of the last task notification, which usually starts the next autonomous turn. */
+  private lastNotificationSummary?: string;
 
   constructor(
     readonly enabled: boolean,
@@ -131,7 +144,8 @@ export class AsyncTaskRuntime {
      *  the tasks that a tool call in another session started, for example in
      *  a native subagent session. `toolNameOf`: the name of the tool of a tool
      *  call, or `undefined` when the tool call is unknown. A task that a
-     *  `Monitor` tool call started is ignored. */
+     *  `Monitor` tool call started is published as a monitor: the SDK reports
+     *  it as `local_bash`, so the adapter names it a monitor. */
     private readonly options: {
       notices?: boolean;
       routeOf?: (toolCallId: string) => Route | undefined;
@@ -144,7 +158,7 @@ export class AsyncTaskRuntime {
     const taskId = taskIdOf(message);
     if (!taskId) return;
     const task = this.task(taskId);
-    if (isSubagentTask(message) || isMonitorTask(message)) {
+    if (isSubagentTask(message)) {
       this.ignore(task);
       return;
     }
@@ -175,7 +189,7 @@ export class AsyncTaskRuntime {
     const taskId = taskIdOf(message);
     if (!taskId) return;
     const task = this.task(taskId);
-    if (isSubagentTask(message) || isMonitorTask(message)) {
+    if (isSubagentTask(message)) {
       this.ignore(task);
       return;
     }
@@ -300,6 +314,7 @@ export class AsyncTaskRuntime {
     const state = taskState(message.status);
     if (!taskId || !state || state === "running" || state === "paused") return;
 
+    this.lastNotificationSummary = nonBlankString(message.summary) ?? this.lastNotificationSummary;
     const task = this.task(taskId);
     const wasTerminal = isTerminal(task.state);
     const correctsLevelState = wasTerminal && task.terminalSource === "level";
@@ -343,7 +358,7 @@ export class AsyncTaskRuntime {
       const task = this.task(taskId);
       if (task.ignored || isTerminal(task.state)) continue;
       const levelTaskType = field(item, "taskType", "task_type");
-      if (levelTaskType === "local_agent" || levelTaskType === "local_monitor") {
+      if (levelTaskType === "local_agent") {
         this.ignore(task);
         continue;
       }
@@ -363,6 +378,7 @@ export class AsyncTaskRuntime {
       if (
         (task.announced || task.held) &&
         !task.ignored &&
+        !task.autonomousTurn &&
         !isTerminal(task.state) &&
         !live.has(task.id)
       ) {
@@ -378,6 +394,7 @@ export class AsyncTaskRuntime {
   }
 
   async finishAll(state: Extract<AsyncTaskState, "failed" | "stopped">): Promise<void> {
+    this.autonomousTurn = undefined;
     const errors: unknown[] = [];
     for (const task of this.tasks.values()) {
       if ((task.announced || task.held) && !task.ignored && !isTerminal(task.state)) {
@@ -394,7 +411,13 @@ export class AsyncTaskRuntime {
 
   canStop(taskId: string): boolean {
     const task = this.tasks.get(taskId);
-    return task?.announced === true && !task.ignored && !task.stopping && !isTerminal(task.state);
+    return (
+      task?.announced === true &&
+      !task.monitor &&
+      !task.ignored &&
+      !task.stopping &&
+      !isTerminal(task.state)
+    );
   }
 
   claimStop(taskId: string): boolean {
@@ -412,6 +435,7 @@ export class AsyncTaskRuntime {
     const task = this.tasks.get(taskId);
     if (!task || !task.announced || task.ignored || task.stopAnnounced) return;
     task.stopAnnounced = true;
+    if (this.autonomousTurn === task) this.autonomousTurn = undefined;
     // No terminal summary: a stopped task leaves the Async Tasks panel at once,
     // so anything said there is said to nobody.
     await this.finish(task, "stopped", undefined, "event");
@@ -438,6 +462,54 @@ export class AsyncTaskRuntime {
     );
   }
 
+  /**
+   * Publishes a model turn that Claude Code started with no prompt open, for
+   * example to answer a task notification. ACP v1 has no session state, and
+   * the client already got the stop reason of its last prompt, so this task is
+   * the only sign that the agent works. The tool calls of the turn are in the
+   * transcript already, so the task is not shown there.
+   *
+   * [cause] names what started the turn when Claude Code says so, for example
+   * "A scheduled wakeup fired." It replaces the description of a task that is
+   * already open; without it, an open task is left as it is.
+   */
+  async autonomousTurnStarted(cause?: string): Promise<void> {
+    if (!this.enabled) return;
+    if (this.autonomousTurn) {
+      if (cause) await this.publishProgress(this.autonomousTurn, { description: cause });
+      return;
+    }
+    const task = this.task(`autonomous-turn-${randomUUID()}`);
+    task.autonomousTurn = true;
+    task.startedObserved = true;
+    task.name = "Claude is working";
+    task.taskType = "turn";
+    task.description =
+      cause ?? this.lastNotificationSummary ?? "Claude Code started a turn without a prompt.";
+    task.showInTranscript = false;
+    this.lastNotificationSummary = undefined;
+    this.autonomousTurn = task;
+    await this.announce(task, { withoutToolCall: true });
+  }
+
+  /** Whether the task of an autonomous turn is open. */
+  get autonomousTurnOpen(): boolean {
+    return this.autonomousTurn !== undefined;
+  }
+
+  /** Ends the task of the autonomous turn that runs now, if there is one. */
+  async autonomousTurnEnded(state: "completed" | "failed"): Promise<void> {
+    const task = this.autonomousTurn;
+    if (!task) return;
+    this.autonomousTurn = undefined;
+    await this.finish(task, state, undefined, "event");
+  }
+
+  /** Whether the task stands for an autonomous turn, which a stop interrupts. */
+  isAutonomousTurn(taskId: string): boolean {
+    return this.tasks.get(taskId)?.autonomousTurn === true;
+  }
+
   /** Whether a task of the tool call went to the background, so the client gets it. */
   isBackgroundedToolCall(toolCallId: string): boolean {
     for (const task of this.tasks.values()) {
@@ -488,6 +560,8 @@ export class AsyncTaskRuntime {
   clear(): void {
     this.tasks.clear();
     this.outputPathsByToolCall.clear();
+    this.autonomousTurn = undefined;
+    this.lastNotificationSummary = undefined;
   }
 
   /**
@@ -510,6 +584,7 @@ export class AsyncTaskRuntime {
       taskType: "task",
       description: "Background task",
       showInTranscript: true,
+      monitor: false,
       announced: false,
       held: false,
       deferred: [],
@@ -520,6 +595,7 @@ export class AsyncTaskRuntime {
       stopAnnounced: false,
       state: "running",
       published: new Map(),
+      autonomousTurn: false,
     };
     this.tasks.set(taskId, task);
     return task;
@@ -529,6 +605,7 @@ export class AsyncTaskRuntime {
     task.startedObserved = true;
     const rawTaskType = field(message, "taskType", "task_type");
     if (rawTaskType !== undefined) task.taskType = friendlyTaskType(rawTaskType);
+    if (rawTaskType === "local_monitor") task.monitor = true;
     const description = nonBlankString(message.description);
     if (description) task.description = description;
     else if (task.description === "Background task")
@@ -586,6 +663,7 @@ export class AsyncTaskRuntime {
   private mergeLevel(task: AsyncTask, level: BackgroundTaskLevel): void {
     const rawTaskType = field(level, "taskType", "task_type");
     if (rawTaskType !== undefined) task.taskType = friendlyTaskType(rawTaskType);
+    if (rawTaskType === "local_monitor") task.monitor = true;
     const description = nonBlankString(level.description);
     if (description) {
       task.description = description;
@@ -610,25 +688,29 @@ export class AsyncTaskRuntime {
    * ends first, or when the prompt result ends the model turn
    * ({@link releaseHeld}). No guess by the command text binds a task.
    *
-   * A task that a `Monitor` tool call started is ignored: Monitor streams its
-   * output to the model only, so the task has nothing for the client. The
-   * tool_use streams before the tool runs, so the tool name is known when the
-   * spawn has the tool call id.
+   * A task that a `Monitor` tool call started is published as a monitor. The
+   * SDK reports it as `local_bash`, so the adapter names it a monitor instead of
+   * a shell. It has no transcript card because Monitor streams its output to
+   * the model only, and no Stop because stopping it only ends the agent's wait
+   * (the agent's own TaskStop still works). The tool_use streams before the
+   * tool runs, so the tool name is known when the spawn has the tool call id.
    */
   private async announce(
     task: AsyncTask,
     options: { withoutToolCall?: boolean } = {},
   ): Promise<void> {
     if (task.announced || task.ignored) return;
-    const toolName = task.toolCallId ? this.options.toolNameOf?.(task.toolCallId) : undefined;
-    if (toolName !== undefined && HIDDEN_TASK_TOOLS.has(toolName)) {
-      this.ignore(task);
-      return;
-    }
     if (!task.toolCallId && !options.withoutToolCall && !isTerminal(task.state)) {
       task.held = true;
       return;
     }
+    if (task.toolCallId && this.options.toolNameOf?.(task.toolCallId) === "Monitor") {
+      task.monitor = true;
+    }
+    if (task.monitor) {
+      task.taskType = "monitor";
+      task.showInTranscript = false;
+    }
     if (task.toolCallId) task.route ??= this.options.routeOf?.(task.toolCallId);
     await this.send(task, {
       sessionUpdate: "async_task_spawned",
@@ -637,7 +719,7 @@ export class AsyncTaskRuntime {
       taskType: task.taskType,
       description: task.description,
       showInTranscript: task.showInTranscript,
-      canStop: true,
+      canStop: !task.monitor,
       ...(task.outputFilePath ? { outputFilePath: task.outputFilePath } : {}),
       ...(task.toolCallId ? { toolCallId: task.toolCallId } : {}),
     });
@@ -781,18 +863,29 @@ function recordPublished(task: AsyncTask, fields: Record<string, unknown>): void
  * Recovers a background Bash task from the structured `backgroundTaskId` of
  * its tool result. The text of a tool result never gives a task id: a
  * foreground command can print any text.
+ *
+ * Claude Code sends no `tool_use_result` with a subagent's tool results. For
+ * those, `startedTaskOf` gives the background `local_bash` task whose
+ * `task_started` named the Bash call, which comes before the result.
  */
 export function backgroundBashTaskFromToolResult(
   content: unknown,
   toolUseResult: unknown,
   toolUses: Record<string, { name: string; input: unknown }>,
+  startedTaskOf?: (toolUseId: string) => string | undefined,
 ): (AsyncTaskStarted & { taskId: string; toolCallId: string }) | undefined {
   if (!Array.isArray(content)) return undefined;
   const toolResults = content.flatMap(toolResultBlock);
   const bashResults = toolResults.filter((result) => toolUses[result.toolUseId]?.name === "Bash");
   if (bashResults.length === 0) return undefined;
 
-  const backgroundResults = structuredBackgroundResults(toolUseResult, toolUses);
+  let backgroundResults = structuredBackgroundResults(toolUseResult, toolUses);
+  if (backgroundResults.length === 0 && startedTaskOf) {
+    backgroundResults = bashResults.flatMap((result) => {
+      const taskId = result.isError ? undefined : startedTaskOf(result.toolUseId);
+      return taskId ? [{ taskId, toolUseId: result.toolUseId }] : [];
+    });
+  }
   const distinctTaskIds = new Set(backgroundResults.map((result) => result.taskId));
   if (distinctTaskIds.size !== 1) return undefined;
   const taskId = [...distinctTaskIds][0];
@@ -985,13 +1078,6 @@ function isBackgroundTask(isBackgrounded: unknown, taskType: unknown): boolean {
   return taskType !== "local_bash" && taskType !== "local_agent";
 }
 
-/** The tools whose async tasks the client never sees. */
-const HIDDEN_TASK_TOOLS = new Set(["Monitor"]);
-
-function isMonitorTask(message: AsyncTaskStarted): boolean {
-  return field(message, "taskType", "task_type") === "local_monitor";
-}
-
 function isSubagentTask(message: AsyncTaskStarted): boolean {
   return (
     field(message, "subagentType", "subagent_type") !== undefined ||

src/auth-status.ts

@@ -210,6 +210,15 @@ export function fromCliStatus(stdout: string, apiKeyHelper?: string): AuthStatus
   if (!externalBackend && !status.loggedIn && !status.apiKeySource) {
     return notLoggedInAuthStatus();
   }
+  if (
+    status.loggedIn &&
+    status.authMethod === "oauth_token" &&
+    status.apiProvider === "firstParty" &&
+    !status.apiKeySource &&
+    !status.subscriptionType
+  ) {
+    return { kind: "account", label: "Claude subscription", detail: "OAuth token" };
+  }
   return mapAuthFields({
     apiProvider: status.apiProvider,
     subscriptionType: status.subscriptionType,

src/background-output.ts

@@ -0,0 +1,131 @@
+/**
+ * The output of a command that went to the background, read from the file
+ * that Claude Code writes it to. Claude Code streams no output of such a
+ * command, so its display terminal would show only the placeholder of the
+ * Bash result ("Command running in background with ID …") until the command
+ * exits. ACP v2 asks an Agent to keep a listed terminal's output current
+ * whenever it can read it (the v2 prompt lifecycle, "Background work").
+ *
+ * The file is polled: watching a file is not reliable on every platform, and
+ * a missing file only means that nothing was written yet.
+ */
+import { open } from "node:fs/promises";
+import { StringDecoder } from "node:string_decoder";
+
+/** How often a running command's output file is read. */
+export const BACKGROUND_OUTPUT_POLL_MS = 500;
+
+/** The most bytes one read takes, so a burst of output does not block the loop. */
+export const BACKGROUND_OUTPUT_READ_BYTES = 256 * 1024;
+
+/**
+ * The most unread bytes that are still sent. A command that writes faster
+ * than the polls read falls behind. Past this, the reads skip to the file's
+ * last bytes, as a snapshot: a terminal shows the latest output, and a
+ * client keeps a bounded amount of it anyway.
+ */
+export const BACKGROUND_OUTPUT_MAX_BACKLOG_BYTES = 1024 * 1024;
+
+/**
+ * Text that the file adds. A snapshot replaces the terminal's output so far:
+ * the first one replaces the placeholder of the Bash result, and a later one
+ * follows a skip or a file that shrank. Other text appends to it.
+ */
+export type BackgroundOutput = { text: string; replaces: boolean };
+
+/**
+ * Follows the output file `path` of one background command and hands each
+ * piece of new text to `publish`, in order. Reads never overlap. A read that
+ * fails, for example because the file does not exist yet, is tried again at
+ * the next poll. `publish` must not reject: the next read waits for it.
+ */
+export class BackgroundOutputTail {
+  private offset = 0;
+  private decoder = new StringDecoder("utf8");
+  /** Whether the next text replaces the terminal's output. */
+  private replaces = true;
+  private stopped = false;
+  private reading: Promise<void> = Promise.resolve();
+  private readonly timer: ReturnType<typeof setInterval>;
+
+  constructor(
+    private readonly path: string,
+    private readonly publish: (output: BackgroundOutput) => Promise<void>,
+  ) {
+    this.timer = setInterval(() => void this.read(false), BACKGROUND_OUTPUT_POLL_MS);
+    // A command that runs on must not keep the agent process alive.
+    this.timer.unref();
+  }
+
+  /**
+   * Reads the rest of the file and stops. The command ended, so what the file
+   * holds is its whole output, and it goes out before the terminal's exit.
+   */
+  async finish(): Promise<void> {
+    clearInterval(this.timer);
+    await this.read(true);
+    this.stopped = true;
+  }
+
+  /** Stops without reading more: the session ended. */
+  stop(): void {
+    clearInterval(this.timer);
+    this.stopped = true;
+  }
+
+  /**
+   * Reads what the file adds, one read of at most
+   * {@link BACKGROUND_OUTPUT_READ_BYTES} at a time, and publishes each read's
+   * text before the next. `toEnd` reads until the end of the file, and ends a
+   * character that the command cut off with a replacement character.
+   */
+  private read(toEnd: boolean): Promise<void> {
+    this.reading = this.reading.then(async () => {
+      if (this.stopped) return;
+      let file;
+      try {
+        file = await open(this.path, "r");
+      } catch {
+        // Nothing written yet, or the file is gone: try again at the next
+        // poll. At the end, the terminal keeps the output it has.
+        return;
+      }
+      try {
+        const { size } = await file.stat();
+        // A file that shrank is a new one: its output starts over. Past the
+        // backlog, the reads skip to the file's last bytes.
+        const start = size < this.offset ? 0 : this.offset;
+        const skipTo = Math.max(start, size - BACKGROUND_OUTPUT_MAX_BACKLOG_BYTES);
+        if (skipTo !== this.offset) {
+          this.offset = skipTo;
+          this.decoder = new StringDecoder("utf8");
+          this.replaces = true;
+        }
+        const buffer = Buffer.alloc(BACKGROUND_OUTPUT_READ_BYTES);
+        let bytesRead: number;
+        do {
+          ({ bytesRead } = await file.read(buffer, 0, buffer.length, this.offset));
+          this.offset += bytesRead;
+          const text = this.decoder.write(buffer.subarray(0, bytesRead));
+          if (text !== "") await this.send(text);
+        } while (toEnd && bytesRead > 0);
+        if (toEnd) {
+          const rest = this.decoder.end();
+          // A command that wrote nothing still replaces the placeholder.
+          if (rest !== "" || this.replaces) await this.send(rest);
+        }
+      } catch {
+        // The read failed: try again at the next poll.
+      } finally {
+        await file.close();
+      }
+    });
+    return this.reading;
+  }
+
+  private async send(text: string): Promise<void> {
+    const replaces = this.replaces;
+    this.replaces = false;
+    await this.publish({ text, replaces });
+  }
+}

src/background-work.ts

@@ -0,0 +1,629 @@
+/**
+ * The background work of a session: the work that Claude Code keeps running
+ * independently of the session's foreground work, which ACP v2 lists on every
+ * `state_update` of the session as `background` (the v2 prompt lifecycle,
+ * "Background work").
+ *
+ * The lists are built from Claude Code's live background task set
+ * (`background_tasks_changed`). Claude Code marks `ambient` its own
+ * housekeeping and every live-update watcher; those are left out, except a
+ * task that a tool call started, such as a `Monitor` call's. The root session and each
+ * announced subagent session (the subagents RFD form) has its own list. Each
+ * task is listed once, in the list of the session that runs it:
+ *
+ * - A command that went to the background: its display terminal, from the
+ *   Bash tool result until its task ends (`Session.backgroundTerminals`).
+ * - A detached subagent: its child session, in its parent's list, while it
+ *   works, and while it is idle with background work of its own.
+ * - A task that a tool call started, such as a `Monitor`, a `Workflow` or a
+ *   backgrounded MCP call: that tool call, kept `in_progress` (or `paused`)
+ *   from its tool result until its task ends (`Session.backgroundToolCalls`).
+ * - Any other task, once its `task_started` came and the tool call that
+ *   started it, if any, returned: a `_claude/task` item with the task's id
+ *   and description. For example, a task whose tool call ended before the
+ *   task joined the level.
+ *
+ * Only a session whose interrupt spares background tasks reports its lists
+ * (`Session.reportsBackground`): `session/cancel` must leave listed work
+ * running.
+ */
+import { RequestError } from "@agentclientprotocol/sdk/unstable";
+import type { AcpSessionNotification } from "./acp-subagents.js";
+import type { NativeSubagent } from "./native-subagents.js";
+import { type AcpToolCallRenderer, V2_CANCELLED, V2_PAUSED } from "./tool-calls/renderer.js";
+import { type BackgroundOutput, BackgroundOutputTail } from "./background-output.js";
+
+/** An item of a `background` list. */
+export type BackgroundItem =
+  | { type: "terminal"; terminalId: string }
+  | { type: "tool_call"; toolCallId: string }
+  | { type: "subagent"; sessionId: string }
+  | { type: "_claude/task"; taskId: string; description: string };
+
+/** The display terminal of a command that went to the background (see `Session.backgroundTerminals`). */
+export interface BackgroundTerminal {
+  /** The Bash tool call, whose id names the terminal. */
+  toolCallId: string;
+  /** The subagent tool call that ran the command, if any. */
+  parentToolUseId?: string;
+  /** The file that Claude Code writes the command's output to, from the Bash result. */
+  outputFilePath?: string;
+  /** Reads that file into the terminal while the command runs. */
+  output?: BackgroundOutputTail;
+}
+
+/** A tool call whose task runs on in the background (see `Session.backgroundToolCalls`). */
+export interface BackgroundToolCall {
+  toolCallId: string;
+  /** The tool use of the call, which Claude Code no longer caches after its result. */
+  toolUse: { name: string; input: unknown };
+  /** The subagent tool call that made the call, if any. */
+  parentToolUseId?: string;
+  paused?: boolean;
+}
+
+/** How a background task ended, as Claude Code reports it. Undefined when it did not say. */
+export type BackgroundTaskEnd = "completed" | "failed" | "stopped" | undefined;
+
+/** The live background task set of `background_tasks_changed`, by task id. */
+export type BackgroundLevel = Map<
+  string,
+  { ambient: boolean; taskType: string; description: string; parentTaskId?: string }
+>;
+
+/** The work state of a session, as its `state_update` names it. */
+export type WorkStateName = "idle" | "running" | "requires_action" | "unknown";
+
+/** A new list of the session `sessionId`, with what its repeated state needs. */
+export interface BackgroundReport {
+  sessionId: string;
+  items: BackgroundItem[];
+  /** The session's work state now, or undefined when it has none yet. */
+  state: WorkStateName | undefined;
+  /** The parent of a subagent session, which mirrors the child's state. */
+  parentSessionId?: string;
+}
+
+/** Where the agent reports the lists (see the agent's `background` option). */
+export interface BackgroundSink {
+  /** The list of a session changed, or is reported for the first time. */
+  changed(report: BackgroundReport): void;
+  /** The session ended: its list is no longer reported. */
+  forget(sessionId: string): void;
+}
+
+/**
+ * The state of a session that other modules own, and that the background
+ * work reads: Claude Code's tasks as the consumer tracks them, the subagent
+ * sessions, and the query that stops a task.
+ */
+export interface BackgroundOwner {
+  liveBackgroundTasks: Map<string, { parentToolUseId?: string; isSubagent: boolean }>;
+  nativeSubagentsByTaskId?: Map<string, NativeSubagent>;
+  query: { stopTask(taskId: string): Promise<void> };
+}
+
+/** A task of a `background_tasks_changed` payload. */
+export type LevelTask = {
+  task_id: string;
+  task_type: string;
+  description: string;
+  parent_task_id?: string;
+  ambient?: boolean;
+};
+
+/** The most returned tool calls that {@link SessionBackgroundWork} remembers. */
+const MAX_RETURNED_CALLS = 1024;
+
+/** The tools whose structured result names the task that the call started. */
+const TASK_TOOLS = new Set(["Monitor", "Workflow"]);
+
+/**
+ * The background work of one root session, and of its subagent sessions: the
+ * terminals and tool calls of the tasks that run in the background, and what
+ * the client is told of them.
+ *
+ * Terminals are kept for every client that renders them, as before the
+ * background lists. The rest is kept only when `reported`.
+ */
+export class SessionBackgroundWork {
+  /** Claude Code's live background task set, from its last `background_tasks_changed`. */
+  private level: BackgroundLevel = new Map();
+  /** The terminals of the commands that went to the background, by task id. */
+  private readonly terminals = new Map<string, BackgroundTerminal>();
+  /** The tool calls whose tasks went on in the background, by task id. */
+  private readonly toolCalls = new Map<string, BackgroundToolCall>();
+  /**
+   * The tool calls that returned, oldest first. A task that a call started
+   * is part of that call until it returns, and the foreground work waits on
+   * it. The task's `task_started` can come after the call returned. Bounded
+   * by {@link MAX_RETURNED_CALLS}: a task joins the level around the time its
+   * call returns.
+   */
+  private readonly returned = new Set<string>();
+
+  /**
+   * `reported`: whether the client gets the lists. Only when Claude Code's
+   * interrupt spares background tasks, as `perTaskStopAffordance` makes it.
+   */
+  constructor(
+    private readonly sessionId: string,
+    readonly reported: boolean,
+  ) {}
+
+  /**
+   * Keeps the display terminal of the command `taskId` running after its Bash
+   * result, until its task ends (see `withRunningTerminal`).
+   */
+  terminalStarted(taskId: string, terminal: BackgroundTerminal): void {
+    this.terminals.set(taskId, terminal);
+  }
+
+  /**
+   * Reads what a tool result message tells of the background tasks:
+   *
+   * - The returned calls no longer hold the tasks that they started.
+   * - Each call whose task goes on in the background is registered: a
+   *   `Monitor` or `Workflow` call, whose structured result names its task,
+   *   or a call that a live task names as its tool use, such as a
+   *   backgrounded MCP call. The task must be in the level: one that ended
+   *   already leaves its call as it is. Claude Code marks every live-update
+   *   watcher `ambient`, including the task of a `Monitor` call; a call
+   *   started it, so it is work the client can see and stop, and is
+   *   registered all the same. Ambient tasks without a call of their own,
+   *   such as watchers Claude Code starts by itself, are never registered.
+   *
+   * Returns the ids of the registered calls, whose result then reports
+   * `in_progress` (see `withRunningToolCall`).
+   */
+  toolResults(
+    owner: BackgroundOwner,
+    content: unknown,
+    toolUseResult: unknown,
+    toolUses: Record<string, { name: string; input: unknown }>,
+    parentToolUseId: string | null,
+  ): Set<string> {
+    const registered = new Set<string>();
+    if (!this.reported || !Array.isArray(content)) return registered;
+    const results = content.filter(
+      (block): block is { type: "tool_result"; tool_use_id: string; is_error?: boolean } =>
+        typeof block === "object" &&
+        block !== null &&
+        block.type === "tool_result" &&
+        typeof block.tool_use_id === "string",
+    );
+    for (const { tool_use_id: toolCallId } of results) {
+      this.returned.add(toolCallId);
+      if (this.returned.size > MAX_RETURNED_CALLS) {
+        this.returned.delete(this.returned.values().next().value!);
+      }
+    }
+    const succeeded = results.filter((block) => block.is_error !== true);
+    const structuredTaskId =
+      succeeded.length === 1 &&
+      typeof toolUseResult === "object" &&
+      toolUseResult !== null &&
+      typeof (toolUseResult as { taskId?: unknown }).taskId === "string"
+        ? (toolUseResult as { taskId: string }).taskId
+        : undefined;
+    for (const { tool_use_id: toolCallId } of succeeded) {
+      const toolUse = toolUses[toolCallId];
+      if (!toolUse) continue;
+      const taskId =
+        (TASK_TOOLS.has(toolUse.name) ? structuredTaskId : undefined) ??
+        [...owner.liveBackgroundTasks].find(
+          ([, task]) => task.parentToolUseId === toolCallId && !task.isSubagent,
+        )?.[0];
+      const task = taskId === undefined ? undefined : this.level.get(taskId);
+      if (!task || task.taskType === "local_bash" || task.taskType === "local_agent") {
+        continue;
+      }
+      this.toolCalls.set(taskId!, {
+        toolCallId,
+        toolUse,
+        ...(parentToolUseId ? { parentToolUseId } : {}),
+      });
+      registered.add(toolCallId);
+    }
+    return registered;
+  }
+
+  /**
+   * Starts reading the output of the background command `taskId` into its
+   * terminal, when the client gets the lists and the Bash result named the
+   * command's output file. `send` sends an update of the terminal's tool
+   * call, routed as the call's other updates. Called once the Bash result's
+   * own updates are sent: the first output replaces the placeholder that they
+   * gave the terminal.
+   */
+  followOutput(taskId: string, send: Send): void {
+    const terminal = this.terminals.get(taskId);
+    if (!this.reported || !terminal?.outputFilePath || terminal.output) return;
+    terminal.output = new BackgroundOutputTail(terminal.outputFilePath, (output) =>
+      send(terminalOutputUpdate(this.sessionId, terminal, output)),
+    );
+  }
+
+  /**
+   * The task `taskId` ended. Reads the rest of its command's output, then
+   * exits its terminal, and gives a tool call whose task it was its final
+   * status: `cancelled` for a task that Claude Code stopped, and `completed`
+   * for one that ended without saying how, such as one that the level
+   * dropped: it no longer runs, and reported no failure. Claude Code reports
+   * no exit code for a command, and `completed` does not mean 0: Claude Code
+   * accepts some non-zero codes as a success, such as grep's 1.
+   */
+  async taskEnded(taskId: string, end: BackgroundTaskEnd, send: Send): Promise<void> {
+    const terminal = this.terminals.get(taskId);
+    if (terminal) {
+      await terminal.output?.finish();
+      this.terminals.delete(taskId);
+      await send(terminalExit(this.sessionId, terminal));
+    }
+    const toolCall = this.toolCalls.get(taskId);
+    if (toolCall) {
+      this.toolCalls.delete(taskId);
+      await send(
+        toolCallStatusUpdate(
+          this.sessionId,
+          toolCall,
+          end === "stopped" ? V2_CANCELLED : end === "failed" ? "failed" : "completed",
+        ),
+      );
+    }
+  }
+
+  /**
+   * The update that reports the background tool call of the task `taskId` as
+   * `paused`, or as `in_progress` again, when `paused` changes it. Claude Code
+   * pauses a workflow this way.
+   */
+  taskPaused(taskId: string, paused: boolean): AcpSessionNotification | undefined {
+    const toolCall = this.toolCalls.get(taskId);
+    if (!toolCall || (toolCall.paused ?? false) === paused) return undefined;
+    toolCall.paused = paused;
+    return toolCallStatusUpdate(this.sessionId, toolCall, paused ? V2_PAUSED : "in_progress");
+  }
+
+  /**
+   * Takes Claude Code's new live background task set. The terminals and tool
+   * calls whose tasks it no longer holds end first, before a list drops them,
+   * as v2 requires. A terminal or tool call is registered at its tool result,
+   * after its task joined the level, so a later level without the task means
+   * that it ended. Claude Code usually sends a task's end before that level,
+   * which ends them first, but the SDK does not promise that order.
+   */
+  async levelChanged(tasks: LevelTask[], send: Send): Promise<void> {
+    if (!this.reported) return;
+    const level: BackgroundLevel = new Map(
+      tasks.map((task) => [
+        task.task_id,
+        {
+          ambient: task.ambient === true,
+          taskType: task.task_type,
+          description: task.description,
+          ...(task.parent_task_id !== undefined ? { parentTaskId: task.parent_task_id } : {}),
+        },
+      ]),
+    );
+    for (const taskId of [...this.terminals.keys(), ...this.toolCalls.keys()]) {
+      if (!level.has(taskId)) await this.taskEnded(taskId, undefined, send);
+    }
+    this.level = level;
+  }
+
+  /**
+   * The query closed: Claude Code's background tasks end with its process.
+   * Stops reading output, and returns the updates that exit the root
+   * session's terminals and cancel its tool calls. The level empties, so the
+   * next lists are empty. A subagent's command or tool call is left as it
+   * was: it is on the child's stream, which the closed query's routing owned.
+   */
+  queryClosed(): AcpSessionNotification[] {
+    for (const terminal of this.terminals.values()) terminal.output?.stop();
+    if (!this.reported) return [];
+    const updates: AcpSessionNotification[] = [];
+    for (const [taskId, terminal] of this.terminals) {
+      if (terminal.parentToolUseId) continue;
+      this.terminals.delete(taskId);
+      updates.push(terminalExit(this.sessionId, terminal));
+    }
+    for (const [taskId, toolCall] of this.toolCalls) {
+      if (toolCall.parentToolUseId) continue;
+      this.toolCalls.delete(taskId);
+      updates.push(toolCallStatusUpdate(this.sessionId, toolCall, V2_CANCELLED));
+    }
+    this.level = new Map();
+    this.returned.clear();
+    return updates;
+  }
+
+  /**
+   * The `background` list of the root session and of each of its announced
+   * subagent sessions, with what their repeated states need, deeper sessions
+   * first and the root last: a child's own list goes out before its parent's
+   * list drops it. Each list is empty while the level has not been reported:
+   * Claude Code sends none before the first background task starts.
+   */
+  reports(owner: BackgroundOwner, rootState: WorkStateName): BackgroundReport[] {
+    const children = [...(owner.nativeSubagentsByTaskId ?? [])].filter(
+      ([, child]) => child.announced,
+    );
+    const childByTask = new Map(children);
+    const childByToolUse = new Map(
+      children.flatMap(([, child]) =>
+        child.parentToolUseId ? [[child.parentToolUseId, child] as const] : [],
+      ),
+    );
+    const lists = new Map<string, BackgroundItem[]>([
+      [this.sessionId, []],
+      ...children.map(([, child]): [string, BackgroundItem[]] => [child.sessionId, []]),
+    ]);
+    // A subagent's command or tool call runs on the child's stream.
+    const ownerOf = (parentToolUseId: string | undefined) =>
+      parentToolUseId ? childByToolUse.get(parentToolUseId)?.sessionId : this.sessionId;
+    for (const [taskId, task] of this.level) {
+      // A registered call's task is listed even when ambient, as a `Monitor`
+      // call's is (see `toolResults`).
+      const toolCall = this.toolCalls.get(taskId);
+      if (toolCall) {
+        const session = ownerOf(toolCall.parentToolUseId);
+        if (session)
+          lists.get(session)!.push({ type: "tool_call", toolCallId: toolCall.toolCallId });
+        continue;
+      }
+      if (task.ambient) continue;
+      const terminal = this.terminals.get(taskId);
+      if (terminal) {
+        const session = ownerOf(terminal.parentToolUseId);
+        if (session)
+          lists.get(session)!.push({ type: "terminal", terminalId: terminal.toolCallId });
+        continue;
+      }
+      // A command without a terminal yet is one that foreground work waits on.
+      // A subagent is listed below, as its session.
+      if (task.taskType === "local_bash" || task.taskType === "local_agent") continue;
+      // A task joins the level before its `task_started`, and before the tool
+      // call that starts it returns. Until both, the task is unknown or part
+      // of that tool call.
+      const live = owner.liveBackgroundTasks.get(taskId);
+      if (!live || (live.parentToolUseId && !this.returned.has(live.parentToolUseId))) continue;
+      const parent = task.parentTaskId ? childByTask.get(task.parentTaskId) : undefined;
+      lists
+        .get(parent?.sessionId ?? this.sessionId)!
+        .push({ type: "_claude/task", taskId, description: task.description });
+    }
+    // A child is listed in its parent's list while it works in the background,
+    // and while it is idle with background work of its own. Deeper children
+    // first, so a child's list is whole before its parent's reads it.
+    const sessions = new Map(children.map(([, child]) => [child.sessionId, child]));
+    const depth = (child: NativeSubagent): number => {
+      const parent = sessions.get(child.parentSessionId);
+      return parent ? depth(parent) + 1 : 0;
+    };
+    const ordered = children.sort(([, a], [, b]) => depth(b) - depth(a));
+    for (const [taskId, child] of ordered) {
+      const task = this.level.get(taskId);
+      const working =
+        child.workState !== undefined &&
+        child.workState !== "idle" &&
+        task !== undefined &&
+        !task.ambient;
+      if (working || lists.get(child.sessionId)!.length > 0) {
+        lists.get(child.parentSessionId)?.push({ type: "subagent", sessionId: child.sessionId });
+      }
+    }
+    return [
+      ...ordered.map(([, child]) => ({
+        sessionId: child.sessionId,
+        items: lists.get(child.sessionId)!,
+        state: workStateName(child.workState),
+        parentSessionId: child.parentSessionId,
+      })),
+      { sessionId: this.sessionId, items: lists.get(this.sessionId)!, state: rootState },
+    ];
+  }
+
+  /**
+   * The current state of each background tool call in `toolCallIds`: the
+   * call as `renderer` shows its tool use, with its status now (see
+   * `ClaudeAcpAgent.publishBackgroundToolCalls`).
+   */
+  toolCallStates(
+    toolCallIds: string[],
+    renderer: AcpToolCallRenderer,
+    cwd: string,
+  ): AcpSessionNotification[] {
+    return [...this.toolCalls.values()]
+      .filter((toolCall) => toolCallIds.includes(toolCall.toolCallId))
+      .map((toolCall) => {
+        const update = renderer.toolCall({ id: toolCall.toolCallId, ...toolCall.toolUse }, { cwd });
+        const status = toolCall.paused ? V2_PAUSED : "in_progress";
+        return {
+          sessionId: this.sessionId,
+          update: { ...update, status } as AcpSessionNotification["update"],
+        };
+      });
+  }
+
+  /**
+   * The task of the terminal or tool call `target` that the session
+   * `sessionId` lists, or undefined when it lists no such item.
+   */
+  listedTask(
+    owner: BackgroundOwner,
+    sessionId: string,
+    target: BackgroundTarget,
+  ): string | undefined {
+    if (!this.reported) return undefined;
+    const listed = this.reports(owner, "idle")
+      .find((report) => report.sessionId === sessionId)
+      ?.items.some((item) =>
+        "terminalId" in target
+          ? item.type === "terminal" && item.terminalId === target.terminalId
+          : item.type === "tool_call" && item.toolCallId === target.toolCallId,
+      );
+    if (!listed) return undefined;
+    const id = "terminalId" in target ? target.terminalId : target.toolCallId;
+    const entries = "terminalId" in target ? this.terminals : this.toolCalls;
+    return [...entries].find(([, entry]) => entry.toolCallId === id)?.[0];
+  }
+}
+
+type Send = (notification: AcpSessionNotification) => Promise<void>;
+
+/** A terminal or tool call that `terminal/cancel` or `tool_call/cancel` names. */
+export type BackgroundTarget = { terminalId: string } | { toolCallId: string };
+
+/**
+ * Stops the task of a terminal or tool call that the session `sessionId`
+ * lists (v2 `terminal/cancel` and `tool_call/cancel`). `sessions` are the
+ * root sessions: a subagent session's list is built with its root's. The
+ * terminal exits, or the tool call gets its final status, when Claude Code
+ * reports the task stopped.
+ */
+export async function cancelBackgroundWork(
+  sessions: Array<BackgroundOwner & { background?: SessionBackgroundWork }>,
+  sessionId: string,
+  target: BackgroundTarget,
+): Promise<void> {
+  const notCancellable = () =>
+    "terminalId" in target
+      ? RequestError.invalidParams(
+          { sessionId, terminalId: target.terminalId },
+          `Terminal ${target.terminalId} is not a command running in the background, so it cannot be cancelled.`,
+        )
+      : RequestError.invalidParams(
+          { sessionId, toolCallId: target.toolCallId },
+          `Tool call ${target.toolCallId} is not running in the background, so it cannot be cancelled.`,
+        );
+  for (const session of sessions) {
+    const taskId = session.background?.listedTask(session, sessionId, target);
+    if (taskId === undefined) continue;
+    try {
+      await session.query.stopTask(taskId);
+    } catch (error) {
+      // The task ended meanwhile: it has ended on the client too, or is about to.
+      if (session.background?.listedTask(session, sessionId, target) === undefined) {
+        throw notCancellable();
+      }
+      throw error;
+    }
+    return;
+  }
+  throw notCancellable();
+}
+
+/** The update that gives the terminal of `terminal` the text `output`. */
+function terminalOutputUpdate(
+  sessionId: string,
+  terminal: BackgroundTerminal,
+  output: BackgroundOutput,
+): AcpSessionNotification {
+  const data = { terminal_id: terminal.toolCallId, data: output.text };
+  return {
+    sessionId,
+    update: {
+      sessionUpdate: "tool_call_update",
+      toolCallId: terminal.toolCallId,
+      _meta: {
+        ...(terminal.parentToolUseId
+          ? { claudeCode: { parentToolUseId: terminal.parentToolUseId } }
+          : {}),
+        ...(output.replaces ? { terminal_output: data } : { terminal_output_delta: data }),
+      },
+    },
+  };
+}
+
+/** The update that exits the terminal of `terminal`, with no exit code. */
+function terminalExit(sessionId: string, terminal: BackgroundTerminal): AcpSessionNotification {
+  return {
+    sessionId,
+    update: {
+      sessionUpdate: "tool_call_update",
+      toolCallId: terminal.toolCallId,
+      _meta: {
+        ...(terminal.parentToolUseId
+          ? { claudeCode: { parentToolUseId: terminal.parentToolUseId } }
+          : {}),
+        terminal_exit: { terminal_id: terminal.toolCallId, exit_code: null, signal: null },
+      },
+    },
+  };
+}
+
+function toolCallStatusUpdate(
+  sessionId: string,
+  toolCall: BackgroundToolCall,
+  status: NonNullable<
+    Extract<AcpSessionNotification["update"], { sessionUpdate: "tool_call_update" }>["status"]
+  >,
+): AcpSessionNotification {
+  return {
+    sessionId,
+    update: {
+      sessionUpdate: "tool_call_update",
+      toolCallId: toolCall.toolCallId,
+      status,
+      ...(toolCall.parentToolUseId
+        ? { _meta: { claudeCode: { parentToolUseId: toolCall.parentToolUseId } } }
+        : {}),
+    },
+  };
+}
+
+/**
+ * Publishes the lists of each session that reports them, each time one
+ * changes. The sink sends them to the client synchronously, so a list follows
+ * the updates sent before it.
+ */
+export class BackgroundWorkReporter {
+  /** The list last published for each session, as JSON, and the root session it is built with. */
+  private readonly published = new Map<string, { json: string; root: string }>();
+
+  constructor(private readonly sink?: BackgroundSink) {}
+
+  /** Whether the lists are reported at all. */
+  get enabled(): boolean {
+    return this.sink !== undefined;
+  }
+
+  /**
+   * Publishes each list of the root session `rootSessionId` that changed. The
+   * first call for a session publishes its list, also when it is empty.
+   * `rootState` is the root session's state now.
+   */
+  sync(
+    rootSessionId: string,
+    session: BackgroundOwner & { background?: SessionBackgroundWork },
+    rootState: WorkStateName,
+  ): void {
+    if (!this.sink || !session.background?.reported) return;
+    for (const report of session.background.reports(session, rootState)) {
+      const json = JSON.stringify(report.items);
+      if (this.published.get(report.sessionId)?.json === json) continue;
+      this.published.set(report.sessionId, { json, root: rootSessionId });
+      this.sink.changed(report);
+    }
+  }
+
+  /** The root session `rootSessionId` ended, and its subagent sessions with it. */
+  forget(rootSessionId: string): void {
+    for (const [sessionId, { root }] of this.published) {
+      if (root !== rootSessionId) continue;
+      this.published.delete(sessionId);
+      this.sink?.forget(sessionId);
+    }
+  }
+}
+
+/** A child's work state, when it is one that v2 names. */
+function workStateName(state: string | undefined): WorkStateName | undefined {
+  return state === "idle" ||
+    state === "running" ||
+    state === "requires_action" ||
+    state === "unknown"
+    ? state
+    : undefined;
+}

src/binary-entry.ts

@@ -0,0 +1,12 @@
+// Entry of the release executable (`scripts/build-binary.mjs`). It registers the
+// Claude CLI shipped next to the executable before importing the agent:
+// index.ts starts serving (or, with --cli, spawns the CLI) while it evaluates,
+// and a static import would evaluate it before this module's body runs.
+import { realpathSync } from "node:fs";
+import { dirname } from "node:path";
+import { useBundledClaudeCli } from "./claude-cli.js";
+
+// realpath, so a symlink to the executable (e.g. in /usr/local/bin) still finds
+// the CLI next to the real file.
+useBundledClaudeCli(dirname(realpathSync(process.execPath)));
+await import("./index.js");

src/blob-resources.ts

@@ -0,0 +1,125 @@
+/**
+ * Embedded `resource` prompt blocks whose resource is a base64 `blob`, and the
+ * Claude content each supported MIME type becomes.
+ */
+import type { BlobResourceContents } from "@agentclientprotocol/sdk/unstable";
+
+/** Image types the Messages API accepts as a base64 `image` block. */
+const IMAGE_MIME_TYPES = ["image/png", "image/jpeg", "image/gif", "image/webp"] as const;
+type ImageMimeType = (typeof IMAGE_MIME_TYPES)[number];
+
+/** Non-`text/*` types whose bytes are text, e.g. a `.json` or `.ts` file. */
+const TEXT_APPLICATION_MIME_TYPES = new Set([
+  "application/json",
+  "application/xml",
+  "application/javascript",
+  "application/typescript",
+  "application/x-yaml",
+  "application/yaml",
+  "application/toml",
+  "application/x-sh",
+  "application/sql",
+  "application/graphql",
+]);
+
+export type BlobResourceContent =
+  | {
+      kind: "image";
+      block: {
+        type: "image";
+        source: { type: "base64"; media_type: ImageMimeType; data: string };
+      };
+    }
+  | {
+      kind: "document";
+      block: {
+        type: "document";
+        source: { type: "base64"; media_type: "application/pdf"; data: string };
+      };
+    }
+  /** The decoded text, to send like a text resource. */
+  | { kind: "text"; text: string };
+
+/**
+ * The MIME type without parameters or case, e.g. `text/plain; charset=utf-8` ->
+ * `text/plain`. `image/jpg`, which some clients send, becomes `image/jpeg`.
+ */
+function baseMimeType(mimeType: string | null | undefined): string | undefined {
+  const base = mimeType?.split(";")[0].trim().toLowerCase();
+  if (base === "image/jpg") return "image/jpeg";
+  return base || undefined;
+}
+
+/**
+ * Decodes a text blob with the `charset` parameter of its MIME type, e.g.
+ * `text/csv; charset=iso-8859-1`, and UTF-8 when there is none or the label is
+ * unknown. A leading byte order mark is dropped.
+ */
+function decodeText(blob: string, mimeType: string | null | undefined): string {
+  const charset = /;\s*charset\s*=\s*"?([^";\s]+)/i.exec(mimeType ?? "")?.[1];
+  let decoder: TextDecoder;
+  try {
+    decoder = new TextDecoder(charset ?? "utf-8");
+  } catch {
+    decoder = new TextDecoder("utf-8");
+  }
+  return decoder.decode(Buffer.from(blob, "base64"));
+}
+
+function isImageMimeType(mimeType: string): mimeType is ImageMimeType {
+  return (IMAGE_MIME_TYPES as readonly string[]).includes(mimeType);
+}
+
+function isTextMimeType(mimeType: string): boolean {
+  return (
+    mimeType.startsWith("text/") ||
+    TEXT_APPLICATION_MIME_TYPES.has(mimeType) ||
+    mimeType.endsWith("+json") ||
+    mimeType.endsWith("+xml")
+  );
+}
+
+/**
+ * Whether {@link blobResourceToClaude} can send a blob of this MIME type. A blob
+ * without a MIME type is not supported: its bytes could be anything.
+ */
+export function isSupportedBlobMimeType(mimeType: string | null | undefined): boolean {
+  const base = baseMimeType(mimeType);
+  if (!base) return false;
+  return isImageMimeType(base) || base === "application/pdf" || isTextMimeType(base);
+}
+
+/**
+ * The Claude content for a blob resource: an `image` block for PNG, JPEG, GIF
+ * and WebP, a `document` block for PDF, and the decoded text for text
+ * types such as `text/markdown` or `application/json`. Returns `undefined` for
+ * any other type, e.g. `application/zip`.
+ */
+export function blobResourceToClaude(
+  resource: BlobResourceContents,
+): BlobResourceContent | undefined {
+  const mimeType = baseMimeType(resource.mimeType);
+  if (!mimeType) return undefined;
+  if (isImageMimeType(mimeType)) {
+    return {
+      kind: "image",
+      block: {
+        type: "image",
+        source: { type: "base64", media_type: mimeType, data: resource.blob },
+      },
+    };
+  }
+  if (mimeType === "application/pdf") {
+    return {
+      kind: "document",
+      block: {
+        type: "document",
+        source: { type: "base64", media_type: "application/pdf", data: resource.blob },
+      },
+    };
+  }
+  if (isTextMimeType(mimeType)) {
+    return { kind: "text", text: decodeText(resource.blob, resource.mimeType) };
+  }
+  return undefined;
+}

src/claude-cli.ts

@@ -0,0 +1,88 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const CLI_FILE_NAME = process.platform === "win32" ? "claude.exe" : "claude";
+
+let bundledCliDirectory: string | undefined;
+
+/**
+ * Called by the executable's entry (`src/binary-entry.ts`) before the agent
+ * starts. A `bun build --compile` executable has no `node_modules` to resolve
+ * the SDK's platform package from, so the release archive ships the Claude CLI
+ * next to it. The CLI isn't embedded: a child process can't run a file inside
+ * Bun's `$bunfs`, so an embedded copy would have to be extracted to disk first.
+ */
+export function useBundledClaudeCli(directory: string): void {
+  bundledCliDirectory = directory;
+}
+
+/**
+ * The Claude CLI binary to spawn: `CLAUDE_CODE_EXECUTABLE` if set, then the CLI
+ * shipped next to the executable, then the SDK's platform-specific package.
+ */
+export async function claudeCliPath(): Promise<string> {
+  if (process.env.CLAUDE_CODE_EXECUTABLE) {
+    return process.env.CLAUDE_CODE_EXECUTABLE;
+  }
+  if (bundledCliDirectory !== undefined) {
+    return bundledClaudeCliPath(bundledCliDirectory);
+  }
+  return installedClaudeCliPath();
+}
+
+function bundledClaudeCliPath(directory: string): string {
+  const path = join(directory, CLI_FILE_NAME);
+  // Without this check, spawning a missing CLI fails with a bare ENOENT.
+  if (!existsSync(path)) {
+    throw new Error(
+      `The Claude CLI is missing: expected ${path}. Keep ${CLI_FILE_NAME} from the release archive ` +
+        "in the same directory as claude-agent-acp, or set CLAUDE_CODE_EXECUTABLE to a Claude CLI binary.",
+    );
+  }
+  return path;
+}
+
+async function installedClaudeCliPath(): Promise<string> {
+  // 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.`,
+  );
+}
+
+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;
+}

src/clear-context-coordinator.ts

@@ -1,4 +1,4 @@
-import type { NewSessionRequest, SessionConfigOption } from "@agentclientprotocol/sdk";
+import type { NewSessionRequest, SessionConfigOption } from "@agentclientprotocol/sdk/unstable";
 import type {
   EffortLevel,
   Options,
@@ -39,11 +39,14 @@ export type ClearContextSession<Turn extends ClearContextTurn = ClearContextTurn
   configOptions: SessionConfigOption[];
   currentAgent: string;
   fastModeEnabled: boolean;
+  ultracodeEnabled: boolean;
   effortPinnedLevel?: string;
   activeTurn?: Turn | null;
   turnQueue?: Turn[];
   pendingExitPlanContextReset?: ClearContextReset;
   contextUsedTokens?: number;
+  contextWindowSize: number;
+  sentUserUuids?: Set<string>;
   input: { push(message: SDKUserMessage): unknown };
 };
 
@@ -58,10 +61,14 @@ export type ClearContextCoordinatorHost<
     options: { publicSessionId: string; permissionMode: PermissionMode },
   ): Promise<Session>;
   applyFastMode(session: Session, enabled: boolean): Promise<void>;
+  applyUltracode(session: Session, enabled: boolean): Promise<void>;
+  /** Publishes the fresh context's mode, config options, and usage: the
+   *  context starts empty in a window of `contextWindowSize` tokens. */
   publishSessionState(
     sessionId: string,
     mode: PermissionMode,
     configOptions: SessionConfigOption[],
+    contextWindowSize: number,
   ): Promise<void>;
   continuationMessage(sessionId: string, plan: string, promptUuid: string): SDKUserMessage;
   ensureConsumer(session: Session, sessionId: string): void;
@@ -145,6 +152,16 @@ export async function continuePlanInFreshContext<
     }
     assertRestartActive(freshSession);
   }
+  // The fresh query seeds ultracode from settings only, so a toggle made
+  // during the old session would otherwise be lost.
+  if (oldSession.ultracodeEnabled !== freshSession.ultracodeEnabled) {
+    try {
+      await host.applyUltracode(freshSession, oldSession.ultracodeEnabled);
+    } catch (error) {
+      host.logError("Failed to restore ultracode after clearing context:", error);
+    }
+    assertRestartActive(freshSession);
+  }
 
   oldSession.activeTurn = null;
   oldSession.turnQueue = [];
@@ -152,12 +169,18 @@ export async function continuePlanInFreshContext<
   freshSession.contextUsedTokens = 0;
 
   try {
-    await host.publishSessionState(sessionId, reset.mode, freshSession.configOptions);
+    await host.publishSessionState(
+      sessionId,
+      reset.mode,
+      freshSession.configOptions,
+      freshSession.contextWindowSize,
+    );
   } catch (error) {
     host.logError("Failed to publish clear-context session state:", error);
   }
   assertRestartActive(freshSession);
 
+  (freshSession.sentUserUuids ??= new Set()).add(turn.promptUuid);
   freshSession.input.push(host.continuationMessage(sessionId, reset.plan, turn.promptUuid));
   assertRestartActive(freshSession);
   host.ensureConsumer(freshSession, sessionId);

src/client-system-prompt.ts

@@ -18,7 +18,7 @@ import {
   RequestError,
   type SessionCapabilities,
   type SystemPrompt,
-} from "@agentclientprotocol/sdk";
+} from "@agentclientprotocol/sdk/unstable";
 
 /** The `sessionCapabilities.systemPrompt` the agent advertises: both modes. */
 export const SYSTEM_PROMPT_CAPABILITY = {

src/context-compaction-meta.ts

@@ -2,7 +2,7 @@ import { AIR_CONTEXT_COMPACTION_KEY, withAirMeta } from "./air-extension.js";
 
 export const CONTEXT_COMPACTION_META_VERSION = 1;
 
-export type ContextCompactionTrigger = "manual" | "automatic";
+export type ContextCompactionTrigger = "manual" | "automatic" | "idle";
 
 export interface ContextCompactionMetadata {
   version: typeof CONTEXT_COMPACTION_META_VERSION;

src/context-compaction.ts

@@ -1,6 +1,7 @@
-import { ClientCapabilities, SessionNotification } from "@agentclientprotocol/sdk";
+import { ClientCapabilities, SessionNotification } from "@agentclientprotocol/sdk/unstable";
 import {
   ContextCompactionMetadata,
+  ContextCompactionTrigger,
   createContextCompactionMeta,
 } from "./context-compaction-meta.js";
 import { compactionToolCall } from "./tool-calls/reporters/compaction.js";
@@ -66,7 +67,7 @@ const ANALYSIS_BLOCKS = [
  *  it as the post-compaction user message. */
 const CONTINUATION_PREAMBLE = /^\s*This session is being continued from a previous conversation/i;
 const PERSISTED_PREAMBLE =
-  /^\s*This session is being continued from a previous conversation[^\n]*\n+Summary:[ \t]*\r?\n/;
+  /^\s*This session is being continued from a previous conversation[^\n]*\n(?:[\s\S]*?\n)?Summary:[ \t]*\r?\n/;
 const PERSISTED_TRAILERS = [
   /\n+If you need specific details from before compaction[\s\S]*$/,
   /\n+(?:Please )?[Cc]ontinue the conversation from where it left (?:it )?off[\s\S]*$/,
@@ -408,14 +409,29 @@ function withoutError({
   return facts;
 }
 
-export function contextCompactionMetadataFromBoundary(compactMetadata: {
-  trigger: "manual" | "auto";
-  pre_tokens: number;
-  post_tokens?: number;
-  duration_ms?: number;
-}): Omit<ContextCompactionMetadata, "version"> {
+function compactionTrigger(
+  cliTrigger: "manual" | "auto",
+  sentByAdapter: boolean,
+): ContextCompactionTrigger {
+  // The CLI's own automatic compaction stays automatic, even inside the adapter's /compact turn.
+  if (cliTrigger === "auto") return "automatic";
+  // The CLI reports every /compact as manual; only the adapter knows it sent this one itself.
+  if (sentByAdapter) return "idle";
+  return "manual";
+}
+
+/** `idleCompaction` marks a `/compact` that the adapter sent itself (see `IdleCompaction`). */
+export function contextCompactionMetadataFromBoundary(
+  compactMetadata: {
+    trigger: "manual" | "auto";
+    pre_tokens: number;
+    post_tokens?: number;
+    duration_ms?: number;
+  },
+  { idleCompaction = false }: { idleCompaction?: boolean } = {},
+): Omit<ContextCompactionMetadata, "version"> {
   return {
-    trigger: compactMetadata.trigger === "auto" ? "automatic" : "manual",
+    trigger: compactionTrigger(compactMetadata.trigger, idleCompaction),
     preTokens: compactMetadata.pre_tokens,
     ...(compactMetadata.post_tokens !== undefined
       ? { postTokens: compactMetadata.post_tokens }

src/diff.ts

@@ -1,5 +1,5 @@
-import { ToolCallContent, ToolCallLocation } from "@agentclientprotocol/sdk";
-import type * as v2 from "@agentclientprotocol/sdk/experimental/v2";
+import { ToolCallContent, ToolCallLocation } from "@agentclientprotocol/sdk/unstable";
+import type * as v2 from "@agentclientprotocol/sdk/experimental/v2/unstable";
 import { structuredPatch } from "diff";
 import { constants } from "node:fs";
 import { type FileHandle, open } from "node:fs/promises";
@@ -89,7 +89,7 @@ export type PatchForm = "air" | "v2";
 /**
  * How a git patch names its file. `git` is git's own form: the leading slash
  * dropped and the `a/` and `b/` prefixes added. `absolute` is the form of an
- * ACP v2 `git_patch`, whose paths must be absolute: the path itself.
+ * ACP v2 `git_patch`, whose paths must be absolute: the native path itself.
  */
 type GitPatchPaths = "git" | "absolute";
 
@@ -438,11 +438,11 @@ export function gitPatchText(
 }
 
 function gitPatchHeader(filePath: string, change: FileChange, paths: GitPatchPaths): string[] {
-  // A Windows path gets forward slashes so the header names the same file on
-  // every platform.
-  const slashed = filePath.replaceAll("\\", "/");
-  // git drops one leading slash of an absolute path.
-  const name = paths === "git" ? slashed.replace(/^\/+/u, "") : slashed;
+  // git's form uses forward slashes, so the header names the same file on
+  // every platform, and drops one leading slash of an absolute path. An ACP v2
+  // patch keeps the native path so that, once unquoted, it equals the `changes`
+  // entry: `C:\work\App.ts` is written `"C:\\work\\App.ts"`.
+  const name = paths === "git" ? filePath.replaceAll("\\", "/").replace(/^\/+/u, "") : filePath;
   const oldName = quoteGitPath(paths === "git" ? "a/" : "", name);
   const newName = quoteGitPath(paths === "git" ? "b/" : "", name);
   // git ends a ---/+++ name that contains a space with a tab, for GNU patch.

src/elicitation.ts

@@ -1,12 +1,11 @@
 import { randomUUID } from "node:crypto";
-import { CreateElicitationResponse } from "@agentclientprotocol/sdk";
 import type {
   CreateElicitationRequest,
-  ElicitationAcceptAction,
+  CreateElicitationResponse,
   ElicitationPropertySchema,
   ElicitationSchema,
   EnumOption,
-} from "@agentclientprotocol/sdk";
+} from "@agentclientprotocol/sdk/unstable";
 import type { ElicitationRequest, ElicitationResult } from "@anthropic-ai/claude-agent-sdk";
 import type {
   AskUserQuestionInput,
@@ -75,17 +74,22 @@ export function mcpElicitationToCreateRequest(
 }
 
 /**
- * Content of an accepted elicitation response.
+ * Content of an accepted elicitation response, or `{}` when the response is
+ * no accept or its `content` is no JSON object.
  *
- * Uses the SDK's validating guard rather than an `action === "accept"` check:
- * the guard both narrows past the union's custom/future variant and validates
- * the payload, so a malformed accept (right tag, ill-typed content) yields
- * empty content — the same classification the SDK's wire validators apply.
+ * The values are not checked. v1 allows a string, number, boolean, or string
+ * array; v2 also allows any other JSON value, such as an object. An MCP
+ * server checks the content against its own `requestedSchema`, so it gets the
+ * content as the client sent it: before, an accept whose content held an
+ * object reached the server as `{ action: "accept", content: {} }`. Callers
+ * that read a field must check its type.
  */
-function acceptedElicitationContent(
-  response: CreateElicitationResponse,
-): NonNullable<ElicitationAcceptAction["content"]> {
-  return CreateElicitationResponse.isAccept(response) ? (response.content ?? {}) : {};
+function acceptedElicitationContent(response: CreateElicitationResponse): Record<string, unknown> {
+  if (response.action !== "accept") return {};
+  const content: unknown = (response as { content?: unknown }).content;
+  return content !== null && typeof content === "object" && !Array.isArray(content)
+    ? (content as Record<string, unknown>)
+    : {};
 }
 
 /**
@@ -97,7 +101,11 @@ export function createElicitationResponseToElicitResult(
 ): ElicitationResult {
   switch (response.action) {
     case "accept":
-      return { action: "accept", content: acceptedElicitationContent(response) };
+      // `ElicitResult` types the values as v1 does. The MCP server checks them.
+      return {
+        action: "accept",
+        content: acceptedElicitationContent(response) as ElicitationResult["content"],
+      };
     case "decline":
       return { action: "decline" };
     case "cancel":
@@ -280,14 +288,37 @@ function joinMultiSelectAnswer(items: string[]): string {
  * cannot make the selection disappear. Decline yields empty answers (the model
  * is told the user skipped rather than the turn aborting); cancel — and any
  * custom/future action we don't understand — aborts the tool call.
+ *
+ * With `reportUnanswered` set (the session's `system/init` listed
+ * `ask_user_question_unanswered_v1`), each question left without an answer
+ * also gets `annotations[question].unanswered`: `"dismissed"` for every
+ * question when the user declined the form, `"skipped"` for a question left
+ * blank in an accepted form. The model does not see this field; the tool
+ * result carries it for clients and transcripts. A CLI without the capability
+ * can refuse the whole answer over it, so it is left out there.
  */
 export function applyAskElicitationResponse(
   response: CreateElicitationResponse,
   toolInput: Record<string, unknown>,
   questions: AskUserQuestion[],
+  options: { reportUnanswered?: boolean } = {},
 ): AskUserQuestionOutcome {
+  // Typed against the output schema: as of SDK 0.3.319 only it lists
+  // `unanswered`, though the tool reads the same annotations from its input.
+  const annotations: NonNullable<AskUserQuestionOutput["annotations"]> = {};
+  const withAnnotations = (answers: AskUserQuestionOutput["answers"]) => ({
+    ...toolInput,
+    answers,
+    ...(Object.keys(annotations).length > 0 ? { annotations } : {}),
+  });
+
   if (response.action === "decline") {
-    return { action: "answered", updatedInput: { ...toolInput, answers: {} } };
+    if (options.reportUnanswered) {
+      for (const question of questions) {
+        annotations[question.question] = { unanswered: "dismissed" };
+      }
+    }
+    return { action: "answered", updatedInput: withAnnotations({}) };
   }
 
   if (response.action !== "accept") {
@@ -298,18 +329,17 @@ export function applyAskElicitationResponse(
   // Typed against the tool's own output schema so the answer/response shapes
   // stay in sync with what the built-in tool's call() expects to read back.
   const answers: AskUserQuestionOutput["answers"] = {};
-  const annotations: NonNullable<AskUserQuestionInput["annotations"]> = {};
   questions.forEach((question, index) => {
     const custom = content[questionCustomFieldKey(index)];
     const customText = typeof custom === "string" ? custom.trim() : "";
 
+    // A pick is a string, number, or boolean. Other values, such as an object
+    // that a v2 client may send, are dropped instead of read as "[object Object]".
     const value = content[questionFieldKey(index)];
-    const picks: string[] =
-      value === undefined || value === null
-        ? []
-        : Array.isArray(value)
-          ? value.filter((item) => item !== undefined && item !== null && item !== "").map(String)
-          : [String(value)];
+    const picks: string[] = (Array.isArray(value) ? value : [value])
+      .filter(isElicitationScalar)
+      .map(String)
+      .filter((item) => item !== "");
 
     // A multi-select is additive, and the form offers the selection and the
     // custom box as independent fields — a user who fills both means both, so
@@ -341,20 +371,27 @@ export function applyAskElicitationResponse(
     }
   });
 
-  return {
-    action: "answered",
-    updatedInput: {
-      ...toolInput,
-      answers,
-      ...(Object.keys(annotations).length > 0 ? { annotations } : {}),
-    },
-  };
+  if (options.reportUnanswered) {
+    for (const question of questions) {
+      if (answers[question.question] === undefined) {
+        annotations[question.question] = { unanswered: "skipped" };
+      }
+    }
+  }
+
+  return { action: "answered", updatedInput: withAnnotations(answers) };
+}
+
+function isElicitationScalar(value: unknown): value is string | number | boolean {
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
 }
 
 /**
  * Coerce an arbitrary MCP `requestedSchema` into an ACP `ElicitationSchema`.
  * The two are structurally compatible JSON Schemas; we just guarantee the
- * `type: "object"` discriminator is present.
+ * `type: "object"` discriminator and a `properties` map are present. The v2
+ * schema requires both, so a client on SDK 2.2.0 or later rejects an MCP
+ * schema such as `{ type: "object" }` that has no `properties`.
  */
 function normalizeElicitationSchema(
   schema: Record<string, unknown> | undefined,
@@ -362,7 +399,8 @@ function normalizeElicitationSchema(
   if (!schema || typeof schema !== "object") {
     return { type: "object", properties: {} };
   }
-  return { ...(schema as ElicitationSchema), type: "object" };
+  const { properties } = schema as Partial<ElicitationSchema>;
+  return { ...(schema as ElicitationSchema), type: "object", properties: properties ?? {} };
 }
 
 /**

src/exit-plan.ts

@@ -1,4 +1,4 @@
-import type { SessionNotification } from "@agentclientprotocol/sdk";
+import type { SessionNotification } from "@agentclientprotocol/sdk/unstable";
 import type { SDKResultMessage } from "@anthropic-ai/claude-agent-sdk";
 import {
   type ClearContextCoordinatorHost,
@@ -126,10 +126,9 @@ export function isExitPlanInterruptionResult(
   );
 }
 
-/** The id of the plan that an approved ExitPlanMode publishes. Claude Code
- * keeps one plan file per session, which a later plan mode rewrites, so each
- * approval replaces the plan before it. The TodoWrite checklist is a
- * separate plan. */
+/** The base ID of an approved plan. AIR appends the review ID to keep each
+ * approval in the transcript. Other clients replace one plan per session.
+ * The TodoWrite checklist is a separate plan. */
 export const PLAN_MODE_PLAN_ID = "plan-mode";
 
 /** The plan, trimmed, that a successful ExitPlanMode result approved: the plan
@@ -150,11 +149,19 @@ export function approvedPlan(input: unknown, output: unknown): string | undefine
 }
 
 /** The update that shows an approved plan to a client that supports plan
- * operations (the `plan` client capability, which every v2 client has). */
-export function planModeUpdate(plan: string): SessionNotification["update"] {
+ * operations (the `plan` client capability, which every v2 client has).
+ * For AIR, pass the review ID to join the plan to its approval card. */
+export function planModeUpdate(
+  plan: string,
+  reviewToolCallId?: string,
+): SessionNotification["update"] {
   return {
     sessionUpdate: "plan_update",
-    plan: { type: "markdown", planId: PLAN_MODE_PLAN_ID, content: plan },
+    plan: {
+      type: "markdown",
+      planId: reviewToolCallId ? `${PLAN_MODE_PLAN_ID}:${reviewToolCallId}` : PLAN_MODE_PLAN_ID,
+      content: plan,
+    },
   };
 }
 
@@ -178,6 +185,7 @@ export type ExitPlanRestartHost<
   sessionUpdate(notification: SessionNotification): Promise<void>;
   /** Whether the client takes plan operations (see planModeUpdate). */
   supportsPlanOperations(): boolean;
+  isAirClient(): boolean;
   destroyReplacement(sessionId: string, session: Session): void;
   settleCancelledTurn(oldSession: Session, turnSession: Session, turn: Turn): void;
   settleFailedTurn(turnSession: Session, turn: Turn, error: unknown): void;
@@ -205,7 +213,7 @@ export class ExitPlanCoordinator<
     try {
       const clearContextHost: ClearContextCoordinatorHost<Session, Turn> = {
         ...this.host,
-        publishSessionState: async (id, mode, configOptions) => {
+        publishSessionState: async (id, mode, configOptions, contextWindowSize) => {
           await this.host.sessionUpdate({
             sessionId: id,
             update: { sessionUpdate: "current_mode_update", currentModeId: mode },
@@ -214,11 +222,23 @@ export class ExitPlanCoordinator<
             sessionId: id,
             update: { sessionUpdate: "config_option_update", configOptions },
           });
+          // Otherwise the client shows the old context's usage until the fresh
+          // context first reports its own.
+          await this.host.sessionUpdate({
+            sessionId: id,
+            update: { sessionUpdate: "usage_update", used: 0, size: contextWindowSize },
+          });
           // The approved plan becomes the session's plan once the fresh
           // context that carries it out exists. Its ExitPlanMode ended with
           // an error result, so toAcpNotifications did not publish it.
           if (this.host.supportsPlanOperations()) {
-            await this.host.sessionUpdate({ sessionId: id, update: planModeUpdate(reset.plan) });
+            await this.host.sessionUpdate({
+              sessionId: id,
+              update: planModeUpdate(
+                reset.plan,
+                this.host.isAirClient() ? reset.toolUseId : undefined,
+              ),
+            });
           }
         },
         continuationMessage: (id, plan, promptUuid) => ({

src/fork-session.ts

@@ -1,4 +1,8 @@
-import { ForkSessionRequest, ForkSessionResponse, RequestError } from "@agentclientprotocol/sdk";
+import {
+  ForkSessionRequest,
+  ForkSessionResponse,
+  RequestError,
+} from "@agentclientprotocol/sdk/unstable";
 import {
   forkSession as forkClaudeSession,
   getSessionMessages,
@@ -65,10 +69,7 @@ function forkPointMessageIdCandidates(messageId: string): string[] {
   return protocolMessageId === messageId ? [messageId] : [messageId, protocolMessageId];
 }
 
-async function loadFullSessionHistory(
-  sessionId: string,
-  cwd: string,
-): Promise<SessionStoreEntry[]> {
+async function loadFullSessionHistory(sessionId: string): Promise<SessionStoreEntry[]> {
   // getSessionMessages returns only the active parentUuid chain. The import keeps inactive branches that AIR can still reference.
   const entries: SessionStoreEntry[] = [];
   const store: SessionStore = {
@@ -77,7 +78,7 @@ async function loadFullSessionHistory(
     },
     load: async () => null,
   };
-  await importSessionToStore(sessionId, store, { dir: cwd, includeSubagents: false });
+  await importSessionToStore(sessionId, store, { includeSubagents: false });
   return entries;
 }
 
@@ -175,14 +176,44 @@ function resolveFromFullHistory(
   return occurrenceMatches.length === 1 ? occurrenceMatches[0]?.uuid : undefined;
 }
 
+/**
+ * Whether `error` is the Claude SDK's report that `sessionId` has no
+ * transcript: `forkSession` and `importSessionToStore` throw
+ * `Error("Session <id> not found")`, and both throw
+ * `"Invalid sessionId: <id>"` for an id that is not a UUID.
+ */
+function isUnknownSessionError(error: unknown, sessionId: string): boolean {
+  if (!(error instanceof Error)) return false;
+  return (
+    error.message === `Session ${sessionId} not found` ||
+    error.message === `Invalid sessionId: ${sessionId}`
+  );
+}
+
 export async function forkSession(
   params: ForkSessionRequest,
   dependencies: ForkSessionDependencies,
+): Promise<ForkSessionResponse> {
+  try {
+    return await forkTranscript(params, dependencies);
+  } catch (error) {
+    if (isUnknownSessionError(error, params.sessionId)) {
+      throw RequestError.sessionNotFound(params.sessionId);
+    }
+    throw error;
+  }
+}
+
+async function forkTranscript(
+  params: ForkSessionRequest,
+  dependencies: ForkSessionDependencies,
 ): Promise<ForkSessionResponse> {
   const timing = new SessionTiming(dependencies.logger, "fork", params.sessionId);
   const point = forkPoint(params._meta);
+  // SDK `dir` scopes source lookup, not the fork's working directory. Search
+  // all projects: params.cwd can name a different workspace for the new session.
   if (!point) {
-    const forked = await forkClaudeSession(params.sessionId, { dir: params.cwd });
+    const forked = await forkClaudeSession(params.sessionId);
     timing.phase("sdk-fork", " resolution=latest");
     return { sessionId: forked.sessionId };
   }
@@ -191,9 +222,7 @@ export async function forkSession(
   const liveUuid = candidateIds
     .map((candidateId) => dependencies.liveMessageIdToUuid?.get(candidateId))
     .find(Boolean);
-  const history = liveUuid
-    ? undefined
-    : await getSessionMessages(params.sessionId, { dir: params.cwd });
+  const history = liveUuid ? undefined : await getSessionMessages(params.sessionId);
   timing.phase("active-history", ` resolution=${liveUuid ? "live" : "pending"}`);
   const messageUuid =
     liveUuid ??
@@ -209,7 +238,7 @@ export async function forkSession(
   const fullHistoryUuid = messageUuid
     ? undefined
     : resolveFromFullHistory(
-        await loadFullSessionHistory(params.sessionId, params.cwd),
+        await loadFullSessionHistory(params.sessionId),
         candidateIds,
         point,
         dependencies.messageIdForGrouping,
@@ -227,7 +256,6 @@ export async function forkSession(
   }
 
   const forked = await forkClaudeSession(params.sessionId, {
-    dir: params.cwd,
     upToMessageId: messageUuid ?? fullHistoryUuid,
   });
   timing.phase("sdk-fork");

src/goal-extension.ts

@@ -1,4 +1,4 @@
-import { RequestError } from "@agentclientprotocol/sdk";
+import { RequestError } from "@agentclientprotocol/sdk/unstable";
 import type { SDKActiveGoalMessage } from "@anthropic-ai/claude-agent-sdk";
 
 export const GOAL_EXTENSION_VERSION = 1 as const;

src/hide-claude-auth.ts

@@ -32,7 +32,7 @@
  * until the next prompt. Awaiting it would add a CLI run to every turn.
  */
 
-import { RequestError } from "@agentclientprotocol/sdk";
+import { RequestError } from "@agentclientprotocol/sdk/unstable";
 import type { AccountInfo, Query } from "@anthropic-ai/claude-agent-sdk";
 
 export function shouldHideClaudeAuth(): boolean {

src/idle-compaction.ts

@@ -0,0 +1,240 @@
+export type PromptCacheTtl = "5m" | "1h";
+
+export type IdleCompactionHost = {
+  /** Claude is working (`startTurn`'s check) or a permission request / user input is pending. */
+  isBusy(): boolean;
+  /** Context size after the last main-thread request, or undefined if unknown. */
+  contextTokens(): number | undefined;
+  /** Current merged Claude Code settings. */
+  settings(): {
+    idleCompaction?: boolean;
+    autoCompactEnabled?: boolean;
+    env?: Record<string, string | undefined>;
+  };
+  /** Runs `/compact` as an adapter-originated turn; settles with that turn. */
+  compact(): Promise<unknown>;
+  /** Debug-level log. */
+  log(message: string): void;
+};
+
+export type IdleCompactionOptions = {
+  env?: Record<string, string | undefined>;
+  setTimeout?: (callback: () => void, ms: number) => unknown;
+};
+
+/** The longest delay `setTimeout` takes; a longer one fires at once. */
+const MAX_TIMER_MS = 2_147_483_647;
+const HOUR_MS = 3_600_000;
+const DEFAULT_MIN_TOKENS = 200_000;
+const MIN_TOKENS_FLOOR = 100_000;
+// 54 min for a 1h cache: leaves a margin for the gap between the provider
+// writing the cache and the adapter receiving the response.
+const DEFAULT_DELAY_MS = 0.9 * HOUR_MS;
+// Node timers do not run while the machine sleeps, so one can fire hours after
+// its deadline, on a cache that expired meanwhile. Same threshold as Claude Code.
+const LAPSED_AFTER_MS = 60_000;
+// The values Claude Code reads as "on" for env flags such as DISABLE_COMPACT
+// (case-insensitive, trimmed).
+const TRUTHY_ENV = new Set(["1", "true", "yes", "on"]);
+
+function isTruthyEnv(value: string | undefined): boolean {
+  return value !== undefined && TRUTHY_ENV.has(value.trim().toLowerCase());
+}
+
+function parseCacheTtl(usage: unknown): PromptCacheTtl | undefined {
+  const creation = (usage as { cache_creation?: unknown } | null | undefined)?.cache_creation;
+  if (typeof creation !== "object" || creation === null) return undefined;
+  const { ephemeral_1h_input_tokens: hour, ephemeral_5m_input_tokens: fiveMin } = creation as {
+    ephemeral_1h_input_tokens?: unknown;
+    ephemeral_5m_input_tokens?: unknown;
+  };
+  if (typeof hour === "number" && hour > 0) return "1h";
+  if (typeof fiveMin === "number" && fiveMin > 0) return "5m";
+  return undefined;
+}
+
+/**
+ * Compacts a session shortly before its one-hour prompt cache expires, so the
+ * next prompt writes a short summary instead of the whole context. Claude Code
+ * has this feature but arms it only for "attended" sessions, which SDK sessions
+ * are not. One instance per session.
+ */
+export class IdleCompaction {
+  private readonly env: Record<string, string | undefined>;
+  private readonly setTimer: (callback: () => void, ms: number) => unknown;
+  private ttl: PromptCacheTtl | undefined;
+  private lastRequestAt: number | undefined;
+  private lastMessageId: string | undefined;
+  /** Set when `/compact` was sent, cleared by the next request: a compaction that failed,
+   *  or left the context large, would otherwise re-arm at once and loop until the user prompts. */
+  private compactedSinceLastRequest = false;
+  private timer: unknown;
+  private compacting = false;
+  private disposed = false;
+  private warnedInvalidDelay = false;
+  /** `status` of the last `rate_limit_event`; unknown until one arrives. */
+  private rateLimitStatus: string | undefined;
+
+  constructor(
+    private readonly host: IdleCompactionHost,
+    options: IdleCompactionOptions = {},
+  ) {
+    this.env = options.env ?? process.env;
+    this.setTimer = options.setTimeout ?? ((cb, ms) => setTimeout(cb, ms));
+  }
+
+  /** Whether an idle compaction it started is still running. `acp-agent.ts` reports
+   *  `trigger: "idle"` while it is true. A client's `/compact` queued behind is read
+   *  only after the adapter's turn's `result`, which clears `compacting`; this relies
+   *  on the CLI emitting that compaction's `compact_boundary` after the previous
+   *  result, which nothing here enforces. */
+  get isCompacting(): boolean {
+    return this.compacting;
+  }
+
+  /** A main-thread response arrived. Records its time and cache TTL, and drops any armed timer.
+   *  The provider writes the cache when the request starts, so the deadline is measured from the
+   *  response's first sighting: the `message_start` stream event, or its first `assistant` message
+   *  when it was not streamed. The CLI sends one `assistant` message per content block, and a
+   *  7-minute response would otherwise put the deadline 7 minutes after the cache was written.
+   *  A later call with the same `messageId` only updates the TTL. */
+  noteRequest(usage: unknown, messageId?: string): void {
+    if (this.disposed) return;
+    this.ttl = parseCacheTtl(usage) ?? this.ttl;
+    if (messageId !== undefined && messageId === this.lastMessageId) return;
+    this.lastMessageId = messageId;
+    this.lastRequestAt = Date.now();
+    this.compactedSinceLastRequest = false;
+    this.disarm("new request");
+  }
+
+  /** The session became idle. Arms the timer if every condition holds, else logs why not. */
+  onIdle(): void {
+    if (this.disposed) return;
+    const skip = this.skipReason();
+    if (skip) {
+      this.host.log(`[idle-compaction] skip: ${skip}`);
+      return;
+    }
+    this.disarm("rearm");
+    const deadline = this.lastRequestAt! + this.delayMs();
+    this.timer = this.setTimer(() => void this.fire(), Math.max(0, deadline - Date.now()));
+    (this.timer as { unref?: () => void } | undefined)?.unref?.();
+    this.host.log(`[idle-compaction] armed deadline=${new Date(deadline).toISOString()}`);
+  }
+
+  /** A `rate_limit_event` arrived (`SDKRateLimitInfo`). Anything but `allowed` skips compaction,
+   *  as in Claude Code. This is account state, so `reset()` keeps it. */
+  noteRateLimit(info: unknown): void {
+    const status = (info as { status?: unknown } | null | undefined)?.status;
+    if (typeof status === "string") this.rateLimitStatus = status;
+  }
+
+  /** Claude Code reported its compaction as failed. Its turn still ends normally, so `compact()` does not reject. */
+  noteCompactionFailed(error: string | undefined): void {
+    if (!this.compacting) return;
+    this.host.log(`[idle-compaction] compaction failed: ${error ?? "no reason given"}`);
+  }
+
+  /** The conversation was replaced (`/clear`): forgets the recorded request and TTL, and drops any armed timer. */
+  reset(): void {
+    this.ttl = undefined;
+    this.lastRequestAt = undefined;
+    this.lastMessageId = undefined;
+    this.compactedSinceLastRequest = false;
+    this.disarm("conversation reset");
+  }
+
+  /** Drops the armed timer, if any. `reason` is only logged. */
+  disarm(reason: string): void {
+    if (this.timer === undefined) return;
+    clearTimeout(this.timer as ReturnType<typeof setTimeout>);
+    this.timer = undefined;
+    this.host.log(`[idle-compaction] disarmed: ${reason}`);
+  }
+
+  /** Disarms and ignores every later call. */
+  dispose(): void {
+    this.disarm("disposed");
+    this.disposed = true;
+  }
+
+  private async fire(): Promise<void> {
+    this.timer = undefined;
+    if (this.disposed) return;
+    const skip = this.skipReason();
+    if (skip) {
+      this.host.log(`[idle-compaction] skip at fire: ${skip}`);
+      return;
+    }
+    this.host.log("[idle-compaction] firing /compact");
+    this.compacting = true;
+    this.compactedSinceLastRequest = true;
+    try {
+      await this.host.compact();
+    } catch (error) {
+      this.host.log(`[idle-compaction] compaction failed: ${error}`);
+    } finally {
+      this.compacting = false;
+    }
+  }
+
+  /** Why no compaction should be scheduled right now, or undefined if all conditions hold. */
+  private skipReason(): string | undefined {
+    if (this.compacting) return "compaction already running";
+    const disabled = this.disabledBy();
+    if (disabled) return `disabled by ${disabled}`;
+    if (this.lastRequestAt === undefined) return "no request recorded in this process";
+    if (Date.now() > this.lastRequestAt + this.delayMs() + LAPSED_AFTER_MS) {
+      return "cache lapsed: more than 60 s past the deadline";
+    }
+    if (this.rateLimitStatus !== undefined && this.rateLimitStatus !== "allowed") {
+      return `rate limit status is ${this.rateLimitStatus}`;
+    }
+    if (this.compactedSinceLastRequest) return "already compacted for this request";
+    if (this.ttl !== "1h") return `cache TTL is ${this.ttl ?? "unknown"}, not 1h`;
+    const tokens = this.host.contextTokens();
+    const min = this.minTokens();
+    if (tokens === undefined || tokens < min) {
+      return `context ${tokens ?? "unknown"} tokens is below the ${min} minimum`;
+    }
+    if (this.host.isBusy()) return "session is busy";
+    return undefined;
+  }
+
+  private disabledBy(): string | undefined {
+    const settings = this.host.settings();
+    if (settings.idleCompaction === false) return "idleCompaction setting";
+    if (settings.autoCompactEnabled === false) return "autoCompactEnabled setting";
+    for (const name of ["DISABLE_COMPACT", "DISABLE_AUTO_COMPACT"]) {
+      if (isTruthyEnv(this.claudeCodeEnv(name))) return name;
+    }
+    return undefined;
+  }
+
+  /** The CLI applies the settings `env` block after the launch env, so it wins. */
+  private claudeCodeEnv(name: string): string | undefined {
+    return this.host.settings().env?.[name] ?? this.env[name];
+  }
+
+  /** `0` and invalid values fall back to 200,000, as in the CLI, which declares the variable
+   *  with `min: 1` and computes `Math.max(100000, env ?? 200000)`. */
+  private minTokens(): number {
+    const raw = this.claudeCodeEnv("CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS");
+    const parsed = raw !== undefined && /^\d+$/.test(raw.trim()) ? Number(raw.trim()) : 0;
+    return Math.max(MIN_TOKENS_FLOOR, parsed > 0 ? parsed : DEFAULT_MIN_TOKENS);
+  }
+
+  private delayMs(): number {
+    const raw = this.env.CLAUDE_AGENT_ACP_IDLE_COMPACT_DELAY_MS;
+    if (raw === undefined) return DEFAULT_DELAY_MS;
+    if (/^\d+$/.test(raw.trim()) && Number(raw.trim()) <= MAX_TIMER_MS) return Number(raw.trim());
+    if (!this.warnedInvalidDelay) {
+      this.warnedInvalidDelay = true;
+      this.host.log(
+        `[idle-compaction] ignoring invalid CLAUDE_AGENT_ACP_IDLE_COMPACT_DELAY_MS=${raw}`,
+      );
+    }
+    return DEFAULT_DELAY_MS;
+  }
+}

src/index.ts

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
-import { claudeCliPath } from "./acp-agent.js";
+import { claudeCliPath } from "./claude-cli.js";
 import { applyManagedPolicyEnv } from "./managed-policy.js";
-import { serveAcp } from "./serve.js";
+import { acpProtocolsFromEnv, serveAcp } from "./serve.js";
 import packageJson from "../package.json" with { type: "json" };
 import { appendFileSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
@@ -83,9 +83,8 @@ if (process.argv.includes("--cli")) {
     : undefined;
   logger?.log("Claude ACP started");
 
-  // The draft ACP v2 is opt-in while it is a draft.
   const acp = serveAcp(logger, {
-    experimentalV2: process.env.CLAUDE_AGENT_ACP_EXPERIMENTAL_V2 === "1",
+    protocols: acpProtocolsFromEnv(process.env.CLAUDE_AGENT_ACP_PROTOCOL),
   });
 
   async function shutdown() {

src/mcp-command.ts

@@ -1,4 +1,4 @@
-import type { AvailableCommand } from "@agentclientprotocol/sdk";
+import type { AvailableCommand } from "@agentclientprotocol/sdk/unstable";
 import type { McpServerStatus, Query } from "@anthropic-ai/claude-agent-sdk";
 import { escapeMarkdown } from "./usage-markdown.js";
 import { raceTimeoutAndAbort } from "./utils.js";
@@ -111,8 +111,11 @@ function needsReconnect(status: McpServerStatus): boolean {
 function codeSpan(text: string): string {
   const longestRun = Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
   const fence = "`".repeat(longestRun + 1);
-  // CommonMark strips one space from each end of a span, so a pad keeps the text unchanged.
-  const pad = text.startsWith("`") || text.endsWith("`") || /^ .*[^ ].* $/.test(text) ? " " : "";
+  // CommonMark strips one space from each end of a span that is not all spaces
+  // (line endings count as spaces), so a pad keeps the text unchanged. Plain
+  // string checks, not one regex: `^ .*[^ ].* $` backtracks quadratically.
+  const strippedByCommonMark = text.startsWith(" ") && text.endsWith(" ") && /[^ \r\n]/.test(text);
+  const pad = text.startsWith("`") || text.endsWith("`") || strippedByCommonMark ? " " : "";
   return `${fence}${pad}${text}${pad}${fence}`;
 }
 

src/permissions/effects.ts

@@ -1,4 +1,4 @@
-import type { RequestPermissionResponse } from "@agentclientprotocol/sdk";
+import type { RequestPermissionResponse } from "@agentclientprotocol/sdk/unstable";
 import type {
   PermissionMode,
   PermissionResult,

src/permissions/modes.ts

@@ -1,4 +1,4 @@
-import type { PermissionMode } from "@anthropic-ai/claude-agent-sdk";
+import type { PermissionMode, Settings } from "@anthropic-ai/claude-agent-sdk";
 
 interface PermissionModeLogger {
   error: (...args: unknown[]) => void;
@@ -58,3 +58,10 @@ export function resolvePermissionMode(
 
   return mapped;
 }
+
+/** Claude Code reads `disableAutoMode` both at the top level and under `permissions`. */
+export function autoModeDisabled(settings: Settings): boolean {
+  return (
+    settings.disableAutoMode === "disable" || settings.permissions?.disableAutoMode === "disable"
+  );
+}

src/permissions/options.ts

@@ -1,4 +1,4 @@
-import type { PermissionOption } from "@agentclientprotocol/sdk";
+import type { PermissionOption } from "@agentclientprotocol/sdk/unstable";
 import {
   buildEditPermissionOptions,
   buildGlobPermissionOptions,

src/permissions/options/filesystem.ts

@@ -1,4 +1,4 @@
-import type { PermissionOption } from "@agentclientprotocol/sdk";
+import type { PermissionOption } from "@agentclientprotocol/sdk/unstable";
 import os from "node:os";
 import path from "node:path";
 import type { DurablePermissionChangeSet } from "../normalization.js";

src/permissions/options/shared.ts

@@ -1,4 +1,4 @@
-import type { PermissionOption } from "@agentclientprotocol/sdk";
+import type { PermissionOption } from "@agentclientprotocol/sdk/unstable";
 import type { DurablePermissionChangeSet } from "../normalization.js";
 
 export const PERMISSION_OPTION_ID = {
@@ -30,6 +30,9 @@ export interface PermissionOptionContext {
   /** The mode the session left when it entered plan mode. */
   prePlanMode?: string;
   contextUsedPercent?: number;
+  /** False when no ACP turn can continue an accepted plan in a fresh
+   *  context. Then an ExitPlanMode request offers no clear-context option. */
+  allowContextReset?: boolean;
 }
 
 export function allowOnce(name = "Yes"): PermissionOption {

src/permissions/options/shell.ts

@@ -1,4 +1,4 @@
-import type { PermissionOption } from "@agentclientprotocol/sdk";
+import type { PermissionOption } from "@agentclientprotocol/sdk/unstable";
 import path from "node:path";
 import type { DurablePermissionChangeSet } from "../normalization.js";
 import { plainString, type PermissionOptionContext, withOptionalUpdate } from "./shared.js";

src/permissions/options/tools.ts

@@ -1,4 +1,4 @@
-import type { PermissionOption } from "@agentclientprotocol/sdk";
+import type { PermissionOption } from "@agentclientprotocol/sdk/unstable";
 import {
   allowOnce,
   exactLocalAllowRule,
@@ -70,7 +70,7 @@ export function buildExitPlanModePermissionOptions(
       : (["auto", "bypassPermissions"] as const)
   ).filter((mode) => modes.has(mode));
   const preferredMode = elevatedModes[0] ?? "acceptEdits";
-  if (plainString(context.input.plan)) {
+  if (context.allowContextReset !== false && plainString(context.input.plan)) {
     const usage =
       context.contextUsedPercent === undefined ? "" : ` (${context.contextUsedPercent}% used)`;
     options.push(

src/permissions/presentation.ts

@@ -1,4 +1,4 @@
-import type { RequestPermissionRequest, ToolCallContent } from "@agentclientprotocol/sdk";
+import type { RequestPermissionRequest, ToolCallContent } from "@agentclientprotocol/sdk/unstable";
 import { AIR_PERMISSION_KEY, withAirMeta } from "../air-extension.js";
 import { ClientCapabilities } from "../tool-calls/client-capabilities.js";
 import { AcpToolCallRenderer } from "../tool-calls/renderer.js";

src/permissions/response.ts

@@ -1,5 +1,5 @@
-import type { RequestPermissionResponse } from "@agentclientprotocol/sdk";
-import type { PermissionOption } from "@agentclientprotocol/sdk";
+import type { RequestPermissionResponse } from "@agentclientprotocol/sdk/unstable";
+import type { PermissionOption } from "@agentclientprotocol/sdk/unstable";
 import type { PermissionMode, PermissionResult } from "@anthropic-ai/claude-agent-sdk";
 import type { DurablePermissionChangeSet } from "./normalization.js";
 import { applyClaudePermissionSelection, parseClaudePermissionSelection } from "./effects.js";

src/serve.ts

@@ -1,19 +1,32 @@
-import { ndJsonStream } from "@agentclientprotocol/sdk";
 import * as v2 from "@agentclientprotocol/sdk/experimental/v2";
 import { v1AgentApp, type ClaudeAcpAgent, type Logger } from "./acp-agent.js";
 import { nodeToWebReadable, nodeToWebWritable } from "./utils.js";
 import { v2AgentApp } from "./v2/agent.js";
 
 /**
- * Serves ACP on stdio.
- *
- * With `experimentalV2`, the connection goes through {@link acpProtocolRouter}.
- * Without it, the adapter serves ACP v1 alone and never routes by protocol
- * version, exactly as before.
+ * The ACP versions that the adapter serves: `v1` or `v2` alone, or both with
+ * `auto`, where the client's `initialize` picks the version.
  */
+export type AcpProtocols = "auto" | "v1" | "v2";
+
+/**
+ * Reads `CLAUDE_AGENT_ACP_PROTOCOL`: unset, empty, or `auto` serves both
+ * versions, and `v1` or `v2` serves that version alone. Throws on any other
+ * value, so that a typo such as `CLAUDE_AGENT_ACP_PROTOCOL=1` fails at startup
+ * instead of silently serving both.
+ */
+export function acpProtocolsFromEnv(value: string | undefined): AcpProtocols {
+  if (value === undefined || value === "") return "auto";
+  if (value === "auto" || value === "v1" || value === "v2") return value;
+  throw new Error(
+    `CLAUDE_AGENT_ACP_PROTOCOL must be "auto", "v1", or "v2", not ${JSON.stringify(value)}`,
+  );
+}
+
+/** Serves ACP on stdio through {@link acpProtocolRouter}. */
 export function serveAcp(
   logger: Logger | undefined,
-  options: { experimentalV2: boolean },
+  options: { protocols: AcpProtocols },
 ): { closed: Promise<void>; dispose(): Promise<void> } {
   const output = nodeToWebWritable(process.stdout);
   const input = nodeToWebReadable(process.stdin);
@@ -23,9 +36,9 @@ export function serveAcp(
   const onAgent = (created: ClaudeAcpAgent) => {
     agent = created;
   };
-  const { closed } = options.experimentalV2
-    ? acpProtocolRouter(logger, onAgent).connect(v2.ndJsonStream(output, input))
-    : v1AgentApp(logger, onAgent).connect(ndJsonStream(output, input));
+  const { closed } = acpProtocolRouter(logger, onAgent, options.protocols).connect(
+    v2.ndJsonStream(output, input),
+  );
   return {
     closed,
     dispose: async () => {
@@ -36,16 +49,19 @@ export function serveAcp(
 
 /**
  * Routes a connection to the protocol version that the client negotiates in
- * `initialize`: the experimental draft ACP v2 for a client that requests
- * version 2 or later, and ACP v1 otherwise. `onAgent` receives the agent of
- * the connection once the router has opened it.
+ * `initialize`. With `auto`, a client that requests version 2 or later gets
+ * the draft ACP v2, and every other client gets ACP v1. With `v1`, a v2
+ * client is negotiated down to v1. With `v2`, the router rejects the
+ * `initialize` of a v1 client as an unsupported protocol version. `onAgent`
+ * receives the agent of the connection once the router has opened it.
  */
 export function acpProtocolRouter(
   logger: Logger | undefined,
   onAgent: (agent: ClaudeAcpAgent) => void,
+  protocols: AcpProtocols = "auto",
 ): v2.AgentProtocolRouter {
-  return v2
-    .agentProtocolRouter()
-    .withV1(v1AgentApp(logger, onAgent))
-    .withV2(v2AgentApp(logger, onAgent));
+  const router = v2.agentProtocolRouter();
+  if (protocols !== "v2") router.withV1(v1AgentApp(logger, onAgent));
+  if (protocols !== "v1") router.withV2(v2AgentApp(logger, onAgent));
+  return router;
 }

src/session-config-ids.ts

@@ -2,3 +2,4 @@
 export const DEFAULT_MODEL_ID = "default";
 export const DEFAULT_AGENT_ID = "default";
 export const EFFORT_CONFIG_ID = "effort";
+export const ULTRACODE_CONFIG_ID = "ultracode";

src/session-effort.ts

@@ -1,4 +1,4 @@
-import type { SessionConfigOption } from "@agentclientprotocol/sdk";
+import type { SessionConfigOption } from "@agentclientprotocol/sdk/unstable";
 import type { EffortLevel, ModelInfo, Settings } from "@anthropic-ai/claude-agent-sdk";
 import { AIR_RECOMMENDED_CONFIG_VALUE_CAPABILITY, withAirMeta } from "./air-extension.js";
 import { EFFORT_CONFIG_ID } from "./session-config-ids.js";
@@ -14,14 +14,15 @@ export function toSdkEffortLevel(value: string | undefined): EffortLevel | null
 
 // Since CLI 2.1.284 an `effortLevel` that changes the level, sent without an
 // `ultracode` key, turns ultracode off. The CLI's own effort control keeps
-// ultracode on at any level, so carry a settings-requested ultracode along
-// with every effort apply.
+// ultracode on at any level, so send `ultracode: true` with every effort apply
+// while the session has ultracode on. When it is off, the key is omitted: an
+// effort change then leaves ultracode off, as it already was.
 export function effortFlagSettings(
   value: string | undefined,
-  settings: Settings,
+  ultracode: boolean,
 ): { effortLevel: EffortLevel | null; ultracode?: true } {
   const effortLevel = toSdkEffortLevel(value);
-  return settings.ultracode === true ? { effortLevel, ultracode: true } : { effortLevel };
+  return ultracode ? { effortLevel, ultracode: true } : { effortLevel };
 }
 
 function canonicalizeModelSettingsKey(value: string): string {
@@ -79,6 +80,13 @@ export function mergeEffortSettings(base: Settings, override: Settings | undefin
   };
 }
 
+export function effortLevelName(level: string): string {
+  return level
+    .split(/[_-]/)
+    .map((part) => (part ? part.charAt(0).toUpperCase() + part.slice(1) : part))
+    .join(" ");
+}
+
 export function buildEffortConfigOption(
   modelInfos: ModelInfo[],
   currentModelId: string,
@@ -98,10 +106,7 @@ export function buildEffortConfigOption(
     ...(useRecommendedValue ? [] : [{ value: "default", name: "Default" }]),
     ...supportedLevels.map((level) => ({
       value: level,
-      name: level
-        .split(/[_-]/)
-        .map((part) => (part ? part.charAt(0).toUpperCase() + part.slice(1) : part))
-        .join(" "),
+      name: effortLevelName(level),
     })),
   ];
   const includes = (level: string) =>

src/session-failure-extension.ts

@@ -1,4 +1,4 @@
-import type { ClientCapabilities, SessionNotification } from "@agentclientprotocol/sdk";
+import type { ClientCapabilities, SessionNotification } from "@agentclientprotocol/sdk/unstable";
 import {
   getSessionMessages,
   type SDKAssistantMessageError,

src/session-index/activity.ts

@@ -11,6 +11,10 @@
  * - an interactive CLI that is not driven by an SDK holds it, and its registry
  *   status is newer than the transcript: the registry status (an idle one is
  *   `error` after such a turn);
+ * - a turn that ended with an open background task is `running`, also after
+ *   10 minutes: Claude Code wakes the session again when the task ends. The
+ *   wait ends when the registry status is `idle`, because a task can end
+ *   without a transcript record (a stop in the task UI);
  * - otherwise the transcript tail: a finished turn is `idle` (`error` after
  *   an API error), an unfinished turn written in the last 10 minutes is
  *   `running`, and anything else has no known state.
@@ -72,6 +76,14 @@ function usesRegistryStatus(record: LiveRecord, transcriptMtimeMs: number): bool
   );
 }
 
+/** Whether the last turn ended while a background task of the session is
+ *  open. */
+function waitsForBackgroundTasks(facts: TranscriptFacts): boolean {
+  if (facts.turnState !== "finished") return false;
+  const openTasks = facts.backgroundTasks?.open ?? [];
+  return openTasks.length > 0;
+}
+
 function iso(ms: number | undefined): string | undefined {
   return ms === undefined || !Number.isFinite(ms) ? undefined : new Date(ms).toISOString();
 }
@@ -103,6 +115,9 @@ export function deriveActivity(input: {
     // A busy or waiting CLI wins; an idle one shows how its turn ended.
     state = registryState(live.status);
     if (state === "idle" && failed) state = "error";
+  } else if (waitsForBackgroundTasks(facts) && live.status !== "idle") {
+    // Claude Code wakes the session again when an open task ends.
+    state = "running";
   } else if (failed) {
     state = "error";
   } else if (facts.turnState === "finished") {

src/session-index/background-tasks.ts

@@ -0,0 +1,223 @@
+/**
+ * The background tasks of a session that did not end yet, from its transcript.
+ *
+ * A Claude Code session can start a background shell command or a background
+ * sub-agent and end its turn at once. When the task ends, Claude Code wakes
+ * the session with a `<task-notification>` input for a short turn. So a turn
+ * end with an open task is no end of the work: the session list keeps such a
+ * session `running` (see `activity.ts`).
+ *
+ * The records, as Claude Code 2.1.299 writes them, in the rules of AIR's
+ * native Claude provider:
+ *
+ * - a tool result opens a task when its `toolUseResult` has a
+ *   `backgroundTaskId` (a shell command), or `isAsync: true` with an
+ *   `agentId` (a sub-agent);
+ * - a task closes when its notification reaches the session: as a user
+ *   record, or as a `queue-operation` `remove` when a running turn takes it
+ *   in. A notification that waits in the queue (`enqueue`) keeps the task
+ *   open, because the session still runs a turn for it;
+ * - only a notification with a `<status>` closes a task. A notification
+ *   without one comes while the task still runs: the check-in of a quiet
+ *   shell ("is still running after …", since Claude Code 2.1.303) or a
+ *   `Monitor` event;
+ * - a `TaskStop` result closes the task of its `toolUseResult.task_id`:
+ *   Claude Code writes no notification for it. The result does not name its
+ *   tool, so its `tool_use_id` must match a `TaskStop` call. A `task_id` in
+ *   the result of another tool keeps the task open;
+ * - a resumed CLI writes a `stopped` notification for each task of the
+ *   previous process;
+ * - a sidechain record belongs to a sub-agent and opens or closes no task of
+ *   the session.
+ *
+ * A background shell that does not end, for example a dev server, keeps its
+ * task open, so its session stays `running` while the CLI holds it.
+ *
+ * A task that a sub-agent starts is not seen. Its start record is only in the
+ * transcript of the sub-agent, so the session can be `idle` while the
+ * sub-agent waits for it.
+ */
+
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import { TASK_NOTIFICATION_TAG, taskNotificationsOf } from "../task-notifications.js";
+
+export type BackgroundTasks = {
+  /** The ids of the tasks that started and did not end, in start order. */
+  open: string[];
+  /** The `tool_use` ids of the `TaskStop` calls without a result. */
+  stopCalls: string[];
+  /** Whether the sets hold the records of the whole file. A set from the
+   *  tail window only does not know a task that started before it. */
+  complete: boolean;
+};
+
+/** The fields of a transcript record that bear on a task. */
+type TranscriptRecord = {
+  type?: string;
+  isSidechain?: boolean;
+  /** Of a `queue-operation` record: `enqueue`, `remove`, ... */
+  operation?: string;
+  /** Of a `queue-operation` record: the queued input. */
+  content?: string;
+  message?: { content?: string | ContentBlock[] };
+  toolUseResult?: ToolUseResult;
+};
+
+type ContentBlock = {
+  type?: string;
+  text?: string;
+  /** Of a `tool_use` block. */
+  id?: string;
+  name?: string;
+  /** Of a `tool_result` block. */
+  tool_use_id?: string;
+};
+
+type ToolUseResult = {
+  /** The task of a background shell command. */
+  backgroundTaskId?: string;
+  /** With `agentId`: an async sub-agent. */
+  isAsync?: boolean;
+  agentId?: string;
+  /** The task that a `TaskStop` call stopped. Another tool can give one. */
+  task_id?: string;
+};
+
+const NOTIFICATION_TAG = `<${TASK_NOTIFICATION_TAG}>`;
+
+/** Text that a line must hold to bear on a task, so that the other lines
+ *  are not parsed. */
+const TASK_MARKERS = ["backgroundTaskId", '"isAsync"', NOTIFICATION_TAG, "TaskStop", "task_id"];
+
+function parseRecord(line: string): TranscriptRecord | undefined {
+  try {
+    return JSON.parse(line) as TranscriptRecord;
+  } catch {
+    return undefined;
+  }
+}
+
+function blocksOf(record: TranscriptRecord): ContentBlock[] {
+  const content = record.message?.content;
+  return Array.isArray(content) ? content : [];
+}
+
+/** The input of a user record: its string content, else its first text
+ *  block. */
+function inputTextOf(record: TranscriptRecord): string | undefined {
+  const content = record.message?.content;
+  if (typeof content === "string") return content;
+  return blocksOf(record).find((block) => block.type === "text")?.text;
+}
+
+/** The task that a `<task-notification>` input ends: only an input that
+ *  starts with the tag, after whitespace, as AIR's `TaskNotification` reads
+ *  it. Only a notification with a `<status>` ends a task (see
+ *  `taskNotificationsOf`). */
+export function endedTaskId(input: string | undefined): string | undefined {
+  if (!input?.trimStart().startsWith(NOTIFICATION_TAG)) return undefined;
+  return taskNotificationsOf(input)[0]?.task_id;
+}
+
+/** The task that a tool result started: a background shell command, or an
+ *  async sub-agent. */
+function startedTaskId(record: TranscriptRecord): string | undefined {
+  if (record.type !== "user") return undefined;
+  const result = record.toolUseResult;
+  if (result?.backgroundTaskId) return result.backgroundTaskId;
+  if (result?.isAsync) return result.agentId;
+  return undefined;
+}
+
+/** The task whose notification reached the session: as a user record, or
+ *  as a queue `remove` when a running turn takes it in. */
+function deliveredTaskId(record: TranscriptRecord): string | undefined {
+  if (record.type === "user") return endedTaskId(inputTextOf(record));
+  if (record.type === "queue-operation" && record.operation === "remove") {
+    return endedTaskId(record.content);
+  }
+  return undefined;
+}
+
+/** Collects the tasks of the lines it is given, in file order. */
+class TaskTracker {
+  private readonly open: Set<string>;
+  private readonly stopCalls: Set<string>;
+
+  constructor(after?: BackgroundTasks) {
+    this.open = new Set(after?.open);
+    this.stopCalls = new Set(after?.stopCalls);
+  }
+
+  add(line: string): void {
+    const mayBearOnTask = TASK_MARKERS.some((marker) => line.includes(marker));
+    if (!mayBearOnTask) return;
+    const record = parseRecord(line);
+    // A sidechain record belongs to a sub-agent, which receives the
+    // notifications of its own tasks.
+    if (!record || record.isSidechain) return;
+    this.apply(record);
+  }
+
+  result({ complete }: { complete: boolean }): BackgroundTasks {
+    return { open: [...this.open], stopCalls: [...this.stopCalls], complete };
+  }
+
+  private apply(record: TranscriptRecord): void {
+    const started = startedTaskId(record);
+    if (started) this.open.add(started);
+    const delivered = deliveredTaskId(record);
+    if (delivered) this.open.delete(delivered);
+    this.applyTaskStop(record);
+  }
+
+  /** A `task_id` stops its task only in the result of a `TaskStop` call:
+   *  another tool can give a `task_id` too. */
+  private applyTaskStop(record: TranscriptRecord): void {
+    let isTaskStopResult = false;
+    for (const block of blocksOf(record)) {
+      if (block.type === "tool_use" && block.name === "TaskStop" && block.id) {
+        this.stopCalls.add(block.id);
+      }
+      const resultId = block.tool_use_id;
+      if (resultId && this.stopCalls.has(resultId)) {
+        this.stopCalls.delete(resultId);
+        isTaskStopResult = true;
+      }
+    }
+    const stopped = record.toolUseResult?.task_id;
+    if (isTaskStopResult && stopped) this.open.delete(stopped);
+  }
+}
+
+/**
+ * The tasks of the lines of `text`, applied on the tasks `after`.
+ *
+ * `after` can be what an earlier scan found for a shorter copy of the file,
+ * and `text` can repeat records of that copy. The result is still the same:
+ * the last record that opens or closes a task decides, and `text` holds the
+ * last records.
+ */
+export function backgroundTasksOf(
+  text: string,
+  options: { complete: boolean; after?: BackgroundTasks },
+): BackgroundTasks {
+  const tracker = new TaskTracker(options.after);
+  for (const line of text.split("\n")) tracker.add(line);
+  return tracker.result({ complete: options.complete });
+}
+
+/** The tasks of the first `size` bytes of `filePath`, from all its records.
+ *  Reads the whole file, so only for a session that a live process holds. */
+export async function searchBackgroundTasks(
+  filePath: string,
+  size: number,
+): Promise<BackgroundTasks> {
+  const tracker = new TaskTracker();
+  if (size === 0) return tracker.result({ complete: true });
+  const stream = createReadStream(filePath, { start: 0, end: size - 1, encoding: "utf8" });
+  const lines = createInterface({ input: stream, crlfDelay: Infinity });
+  for await (const line of lines) tracker.add(line);
+  return tracker.result({ complete: true });
+}

src/session-index/connection.ts

@@ -15,11 +15,12 @@ import {
   type InitializeRequest,
   type ListSessionsRequest,
   type ListSessionsResponse,
-} from "@agentclientprotocol/sdk";
+} from "@agentclientprotocol/sdk/unstable";
 import type { Query } from "@anthropic-ai/claude-agent-sdk";
 import type { AcpClient, Logger, Session } from "../acp-agent.js";
 import {
   AIR_SESSION_ARCHIVE_CAPABILITY,
+  AIR_SESSION_BATCH_GET_CAPABILITY,
   AIR_SESSION_INDEX_CAPABILITY,
   AIR_SESSION_LIST_SUBSCRIBE_CAPABILITY,
   AIR_SESSION_RENAME_CAPABILITY,
@@ -46,6 +47,8 @@ import {
   renameTo,
   parseRenameSessionRequest,
   parseSessionIdRequest,
+  parseBatchGetSessionsRequest,
+  SESSION_BATCH_GET_METHOD,
   SESSION_ARCHIVE_METHOD,
   SESSION_RENAME_METHOD,
   SESSION_UNARCHIVE_METHOD,
@@ -54,6 +57,8 @@ import {
   type RetitleOptions,
   type SessionIdRequest,
   type TitleChange,
+  type BatchGetSessionsRequest,
+  type BatchGetSessionsResponse,
 } from "./service.js";
 
 /** What the session index keeps on each `Session`. */
@@ -144,12 +149,13 @@ export class SessionIndexConnection {
   }
 
   /** The AIR capabilities the agent advertises for the index: the index
-   *  itself, archive, rename, the list subscription and the `agentWorktree`
+   *  itself, batch get, archive, rename, the list subscription and the `agentWorktree`
    *  row field, all only to a client that declared `sessionIndex`. */
   capabilities(): string[] {
     return this.service
       ? [
           AIR_SESSION_INDEX_CAPABILITY,
+          AIR_SESSION_BATCH_GET_CAPABILITY,
           AIR_SESSION_ARCHIVE_CAPABILITY,
           AIR_SESSION_RENAME_CAPABILITY,
           AIR_SESSION_LIST_SUBSCRIBE_CAPABILITY,
@@ -230,6 +236,12 @@ export class SessionIndexConnection {
     return this.service?.list(params, (sessionId) => this.ownSessionState(sessionId));
   }
 
+  batchGet(params: BatchGetSessionsRequest): Promise<BatchGetSessionsResponse> {
+    return this.requireService(SESSION_BATCH_GET_METHOD).batchGet(params, (sessionId) =>
+      this.ownSessionState(sessionId),
+    );
+  }
+
   /** An AIR client archives with session/delete (see {@link deleteSession}):
    *  its archived sessions (an archived custom title) stay hidden from the
    *  old list, as when the delete removed them. */
@@ -448,6 +460,7 @@ export class SessionIndexConnection {
 
 /** The agent methods behind the session index extension methods. */
 type SessionIndexMethods = {
+  batchGetSessions(params: BatchGetSessionsRequest): Promise<BatchGetSessionsResponse>;
   subscribeSessionList(params: ListSubscribeRequest): Promise<ListSubscribeResponse>;
   unsubscribeSessionList(params: ListUnsubscribeRequest): Promise<EmptyResponse>;
   renameSessionTitle(params: RenameSessionRequest): Promise<EmptyResponse>;
@@ -455,10 +468,15 @@ type SessionIndexMethods = {
   unarchiveSession(params: SessionIdRequest): Promise<EmptyResponse>;
 };
 
-/** Routes `_session/list/subscribe`, `_session/list/unsubscribe`,
+/** Routes `_session/batch_get`, `_session/list/subscribe`, `_session/list/unsubscribe`,
  *  `_session/rename`, `_session/archive` and `_session/unarchive`. */
 export function onSessionIndexRequests(app: AgentApp, agent: () => SessionIndexMethods): AgentApp {
   return app
+    .onRequest<BatchGetSessionsRequest, BatchGetSessionsResponse>(
+      SESSION_BATCH_GET_METHOD,
+      { parse: parseBatchGetSessionsRequest },
+      (ctx) => agent().batchGetSessions(ctx.params),
+    )
     .onRequest<ListSubscribeRequest, ListSubscribeResponse>(
       LIST_SUBSCRIBE_METHOD,
       { parse: parseListSubscribeRequest },

src/session-index/list-subscriptions.ts

@@ -40,7 +40,7 @@ import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as fsp from "node:fs/promises";
 import * as path from "node:path";
-import { RequestError, type SessionInfo } from "@agentclientprotocol/sdk";
+import { RequestError, type SessionInfo } from "@agentclientprotocol/sdk/unstable";
 import type { OwnSessionState } from "./activity.js";
 import {
   bySession,

src/session-index/project-dirs.ts

@@ -104,6 +104,17 @@ export async function canonicalPath(cwd: string): Promise<string> {
   }
 }
 
+/** Whether the path exists, including a symlink whose target is missing. */
+export async function exists(target: string): Promise<boolean> {
+  try {
+    await fs.lstat(target);
+    return true;
+  } catch (error) {
+    if (errorCode(error) === "ENOENT" || errorCode(error) === "ENOTDIR") return false;
+    throw error;
+  }
+}
+
 /** The names of the project directories of `cwd` among `rootEntries`. */
 export function projectDirsOf(cwd: string, rootEntries: readonly string[]): string[] {
   const exact = encodeProjectPath(cwd);

src/session-index/service.ts

@@ -15,7 +15,8 @@ import {
   RequestError,
   type ListSessionsRequest,
   type ListSessionsResponse,
-} from "@agentclientprotocol/sdk";
+  type SessionInfo,
+} from "@agentclientprotocol/sdk/unstable";
 import { deleteSession as sdkDeleteSession } from "@anthropic-ai/claude-agent-sdk";
 import { airExtensionMeta } from "../air-extension.js";
 import { sanitizeTitle } from "../session-titles.js";
@@ -37,7 +38,7 @@ import {
 import { LiveSessionRegistry } from "./live-registry.js";
 import {
   canonicalPath,
-  errorCode,
+  exists,
   isExactProjectDir,
   isSessionId,
   projectDirMatches,
@@ -65,6 +66,7 @@ import { sessionInfoOf } from "./session-info.js";
 export const SESSION_RENAME_METHOD = "_session/rename";
 export const SESSION_ARCHIVE_METHOD = "_session/archive";
 export const SESSION_UNARCHIVE_METHOD = "_session/unarchive";
+export const SESSION_BATCH_GET_METHOD = "_session/batch_get";
 
 /** The JSON-RPC code of an unknown session (ACP `ResourceNotFound`). */
 const RESOURCE_NOT_FOUND = -32002;
@@ -73,6 +75,27 @@ const CURSOR_VERSION = 5;
 
 export type SessionIdRequest = { sessionId: string };
 export type RenameSessionRequest = { sessionId: string; title: string };
+export type BatchGetSessionsRequest = { sessionIds: string[] };
+export type BatchGetSessionsResponse = {
+  sessions: SessionInfo[];
+};
+
+export function parseBatchGetSessionsRequest(value: unknown): BatchGetSessionsRequest {
+  const record = asRecord(value);
+  const ids = record.sessionIds;
+  if (
+    Object.keys(record).length !== 1 ||
+    !Array.isArray(ids) ||
+    ids.some((id) => typeof id !== "string" || !id.trim()) ||
+    new Set(ids).size !== ids.length
+  ) {
+    throw RequestError.invalidParams(
+      undefined,
+      "params require only sessionIds: distinct, non-blank strings",
+    );
+  }
+  return { sessionIds: ids };
+}
 
 export function sessionNotFound(sessionId: string): RequestError {
   return new RequestError(RESOURCE_NOT_FOUND, `Session not found: ${sessionId}`, { sessionId });
@@ -364,26 +387,6 @@ function isSdkNotFound(error: unknown): boolean {
   return error instanceof Error && /^Session \S+ not found in /.test(error.message);
 }
 
-async function exists(target: string): Promise<boolean> {
-  try {
-    await fs.lstat(target);
-    return true;
-  } catch (error) {
-    if (errorCode(error) === "ENOENT" || errorCode(error) === "ENOTDIR") return false;
-    throw error;
-  }
-}
-
-/** The error the SDK `deleteSession` gives for a session id it rejects or
- *  does not find, which a client without `sessionIndex` got before. */
-function sdkDeleteError(sessionId: string): Error {
-  return new Error(
-    isSessionId(sessionId)
-      ? `Session ${sessionId} not found in any project directory`
-      : `Invalid sessionId: ${sessionId}`,
-  );
-}
-
 /**
  * `session/delete` of a client that is neither AIR nor a `sessionIndex` client:
  * the SDK delete of the session's transcript. A session without one succeeds,
@@ -409,16 +412,18 @@ export async function deleteSessionIfStored(
 /**
  * `session/delete` of an AIR client without `sessionIndex`, which uses delete
  * to mark a session done: archives it instead, so the transcript survives. A
- * session without a transcript fails as the SDK delete did.
+ * session without a transcript has nothing to archive and succeeds, as ACP
+ * asks of a delete of a session that never existed (see
+ * {@link deleteSessionIfStored}).
  */
 export async function archiveInsteadOfDelete(
   sessionId: string,
   service: SessionIndexService,
 ): Promise<void> {
-  if (!isSessionId(sessionId)) throw sdkDeleteError(sessionId);
+  if (!isSessionId(sessionId)) return;
   // The SDK delete skips empty transcripts, so they do not count.
   const found = await service.index.findTranscripts(sessionId);
-  if (found.length === 0) throw sdkDeleteError(sessionId);
+  if (found.length === 0) return;
   await service.retitle(sessionId, archiveTo(true), { sidecar: "existing" });
 }
 
@@ -476,12 +481,18 @@ export class SessionIndexService {
   private readonly deleteSession: (sessionId: string) => Promise<void>;
 
   constructor(private readonly deps: SessionIndexDeps) {
-    this.index = new SessionIndex();
     this.registry = deps.registry ?? new LiveSessionRegistry();
+    this.index = new SessionIndex({ isLive: (sessionId) => this.isLive(sessionId) });
     this.now = deps.now ?? Date.now;
     this.deleteSession = deps.deleteSession ?? ((id) => sdkDeleteSession(id));
   }
 
+  /** Whether a live process holds the session, by the live registry. */
+  private async isLive(sessionId: string): Promise<boolean> {
+    const live = await this.registry.snapshot();
+    return live.has(sessionId);
+  }
+
   /** `session/list` of a `sessionIndex` client. `own` reports the sessions
    *  that this connection runs. */
   async list(
@@ -514,6 +525,22 @@ export class SessionIndexService {
     return hasMore && last ? { sessions, nextCursor: encodeListCursor(last, scope) } : { sessions };
   }
 
+  /** Metadata for known ids, independent of list pages and project filters. */
+  async batchGet(
+    { sessionIds }: BatchGetSessionsRequest,
+    own: (sessionId: string) => OwnSessionState | undefined,
+  ): Promise<BatchGetSessionsResponse> {
+    if (sessionIds.length === 0) return { sessions: [] };
+    const live = await this.registry.snapshot();
+    const now = this.now();
+    const rows = await this.index.getSessions(sessionIds);
+    return {
+      sessions: rows.map((row) =>
+        sessionInfoOf(row, own(row.sessionId), live.get(row.sessionId), now),
+      ),
+    };
+  }
+
   /** Runs `mutation` after the previous mutation of the session ended. */
   private exclusive<T>(sessionId: string, mutation: () => Promise<T>): Promise<T> {
     const previous = this.mutations.get(sessionId) ?? Promise.resolve();

src/session-index/session-index.ts

@@ -26,6 +26,8 @@ import { effectiveTitle, visibleTitle } from "./archive-title.js";
 import {
   canonicalPath,
   encodeProjectPath,
+  errorCode,
+  exists,
   isExactProjectDir,
   isSessionId,
   normalizePath,
@@ -52,16 +54,21 @@ import {
   type SdkTitles,
   type TranscriptFacts,
 } from "./transcript-scan.js";
+import { searchBackgroundTasks } from "./background-tasks.js";
 import { DirListings, statFiles } from "./dir-listing.js";
 import { isInLinkedWorktree, worktreeCounterparts } from "./worktrees.js";
 
 export const DEFAULT_LIST_LIMIT = 50;
 export const MAX_LIST_LIMIT = 200;
+/** Discovery could not establish which sessions the store contains. */
+export class SessionStoreUnavailableError extends Error {}
 /** Entries of the metadata cache: a few hundred bytes each, so the
  *  transcripts of a large history (tens of thousands) stay cached and deep
  *  pages do not read them again. */
 const METADATA_CACHE_SIZE = 50_000;
 const READ_BATCH_SIZE = 16;
+/** Session ids looked up together by {@link SessionIndex.getSessions}. */
+const LOOKUP_CHUNK_SIZE = 100;
 /** Transcripts read at most per directory to recover a sibling's cwd. */
 const MAX_CWD_PROBES_PER_DIR = 64;
 /** How long a directory that gave no cwd is not probed again. */
@@ -96,6 +103,24 @@ export type TranscriptCandidate = {
   ino: number;
 };
 
+type TranscriptFile = Pick<
+  TranscriptCandidate,
+  "sessionId" | "filePath" | "dirName" | "projectPath"
+>;
+
+/** Non-empty transcript files, with bounded stats shared by lists and id lookups. */
+async function transcriptCandidates(
+  files: readonly TranscriptFile[],
+): Promise<TranscriptCandidate[]> {
+  const stats = await statFiles(files.map(({ filePath }) => filePath));
+  return files.flatMap((file, i) => {
+    const current = stats[i];
+    return current?.isFile() && current.size > 0
+      ? [{ ...file, mtimeMs: current.mtimeMs, size: current.size, ino: current.ino }]
+      : [];
+  });
+}
+
 /** The cached metadata of one transcript. */
 type TranscriptMetadata = {
   /** The visible title: without the archive prefix. */
@@ -400,7 +425,15 @@ function scopeOf(
   };
 }
 
+export type SessionIndexOptions = {
+  /** Whether a live process holds the session. Only for such a session the
+   *  whole transcript is searched for its background tasks. */
+  isLive?: (sessionId: string) => Promise<boolean>;
+};
+
 export class SessionIndex {
+  constructor(private readonly options: SessionIndexOptions = {}) {}
+
   private readonly listings = new DirListings();
   private readonly metadata = new Lru<string, CacheEntry>(METADATA_CACHE_SIZE);
   /** The metadata reads in flight, by path: a list and a subscription that
@@ -517,25 +550,16 @@ export class SessionIndex {
     const listed = await this.listings.namesOfAll(dirPaths);
     const files = dirs.flatMap(({ dirName, projectPath }, i) =>
       listed[i]!.filter((name) => name.endsWith(".jsonl") && isSessionId(name.slice(0, -6))).map(
-        (name) => ({ name, filePath: path.join(root, dirName, name), dirName, projectPath }),
+        (name) => ({
+          sessionId: name.slice(0, -6),
+          filePath: path.join(root, dirName, name),
+          dirName,
+          projectPath,
+        }),
       ),
     );
-    const stats = await statFiles(files.map(({ filePath }) => filePath));
-    const all: TranscriptCandidate[] = [];
-    files.forEach(({ name, filePath, dirName, projectPath }, i) => {
-      const fileStats = stats[i];
-      if (!fileStats?.isFile() || fileStats.size === 0) return;
-      all.push({
-        sessionId: name.slice(0, -6),
-        filePath,
-        dirName,
-        projectPath,
-        mtimeMs: fileStats.mtimeMs,
-        size: fileStats.size,
-        ino: fileStats.ino,
-      });
-    });
-    return { dirs: [root, ...dirPaths], names: [rootNames, ...listed], candidates: all };
+    const candidates = await transcriptCandidates(files);
+    return { dirs: [root, ...dirPaths], names: [rootNames, ...listed], candidates };
   }
 
   /**
@@ -571,6 +595,90 @@ export class SessionIndex {
     };
   }
 
+  /** Known ids in request order, using the same rows as the list.
+   *  Addresses exact filenames; only rows without a cwd need sibling discovery. */
+  async getSessions(sessionIds: readonly string[]): Promise<IndexRow[]> {
+    if (sessionIds.length === 0) return [];
+    const root = projectsRoot();
+    let projectEntries: string[];
+    try {
+      projectEntries = await fs.readdir(root);
+    } catch (cause) {
+      if (errorCode(cause) === "ENOENT" && !(await exists(root))) {
+        return [];
+      }
+      throw new SessionStoreUnavailableError("Session store could not be read", { cause });
+    }
+    const ids = sessionIds.filter(isSessionId);
+    const byId = new Map<string, IndexRow>();
+    // Paths are project directories × ids: bound them per chunk, not per request.
+    for (let start = 0; start < ids.length; start += LOOKUP_CHUNK_SIZE) {
+      const chunk = ids.slice(start, start + LOOKUP_CHUNK_SIZE);
+      for (const row of await this.lookupRows(root, projectEntries, chunk)) {
+        byId.set(row.sessionId, row);
+      }
+    }
+    return sessionIds.flatMap((id) => {
+      const row = byId.get(id);
+      return row ? [row] : [];
+    });
+  }
+
+  /** The rows of `ids` found under `projectEntries`. All copies of an id are
+   *  in the same call, so copy selection is unchanged by chunking. */
+  private async lookupRows(
+    root: string,
+    projectEntries: readonly string[],
+    ids: readonly string[],
+  ): Promise<IndexRow[]> {
+    let candidates = await transcriptCandidates(
+      projectEntries.flatMap((dirName) =>
+        ids.map((sessionId) => ({
+          sessionId,
+          filePath: path.join(root, dirName, `${sessionId}.jsonl`),
+          dirName,
+        })),
+      ),
+    );
+    if (CASE_INSENSITIVE_PATHS) {
+      // On a case-insensitive file system, stat of `ABC.jsonl` also finds
+      // `abc.jsonl`. Keep a file only when its real name is the requested one,
+      // or differs by more than case (a symlink, as the list would read it).
+      // A failed realpath means the file is unreadable, so the id is omitted.
+      const exact = await Promise.all(
+        candidates.map(async ({ filePath }) => {
+          try {
+            const actual = path.basename(await fs.realpath(filePath));
+            const expected = path.basename(filePath);
+            return actual === expected || actual.toLowerCase() !== expected.toLowerCase();
+          } catch {
+            return false;
+          }
+        }),
+      );
+      candidates = candidates.filter((_, i) => exact[i]);
+    }
+    return this.collectRows(candidates.sort(byMtimeDescending), {
+      inScope: scopeOf(undefined),
+      archived: "all",
+      wanted: Infinity,
+      unread: async (read, dirNames) => {
+        const dirs = [...dirNames];
+        const listed = await this.listings.namesOfAll(dirs.map((dir) => path.join(root, dir)));
+        const siblings = dirs.flatMap((dirName, i) =>
+          listed[i]!.filter((name) => name.endsWith(".jsonl") && isSessionId(name.slice(0, -6)))
+            .map((name) => ({
+              sessionId: name.slice(0, -6),
+              filePath: path.join(root, dirName, name),
+              dirName,
+            }))
+            .filter(({ filePath }) => !read.has(filePath)),
+        );
+        return (await transcriptCandidates(siblings)).sort(byMtimeDescending);
+      },
+    });
+  }
+
   /** Every transcript file of `sessionId` (see {@link scanSession}). Empty
    *  files only with `includeEmpty`. */
   async findTranscripts(
@@ -769,9 +877,12 @@ export class SessionIndex {
       archived: ArchivedFilter;
       after?: ListCursor;
       wanted: number;
-      /** The transcripts not read (by path), which may supply a sibling's
-       *  cwd. */
-      unread: (read: ReadonlySet<string>) => readonly TranscriptCandidate[];
+      /** The unread transcripts of the directories still eligible for cwd
+       *  recovery. Called only after checking the negative cache. */
+      unread?: (
+        read: ReadonlySet<string>,
+        dirNames: ReadonlySet<string>,
+      ) => readonly TranscriptCandidate[] | Promise<readonly TranscriptCandidate[]>;
       restat?: boolean;
     },
   ): Promise<IndexRow[]> {
@@ -843,14 +954,15 @@ export class SessionIndex {
       }
       await settlePending();
     }
-    if (pending.length > 0) {
+    const unread = options.unread;
+    if (pending.length > 0 && unread) {
       // A row recovered after the scan stopped still sorts into the page: it
       // was read before the stop, and more rows only raise the bound. A
       // sibling that the archive filter or the cursor leaves out may still
       // supply the cwd.
       await this.learnDirCwds(
         new Set(pending.map(({ candidate }) => candidate.dirName)),
-        options.unread(read),
+        (dirNames) => unread(read, dirNames),
         options.restat ?? false,
       );
       await settlePending();
@@ -884,7 +996,9 @@ export class SessionIndex {
    *  changes. `restat` as in {@link collectRows}. */
   private async learnDirCwds(
     dirNames: ReadonlySet<string>,
-    unread: readonly TranscriptCandidate[],
+    unread: (
+      dirNames: ReadonlySet<string>,
+    ) => readonly TranscriptCandidate[] | Promise<readonly TranscriptCandidate[]>,
     restatFirst: boolean,
   ): Promise<void> {
     const root = projectsRoot();
@@ -900,8 +1014,9 @@ export class SessionIndex {
       if (known && known.mtimeMs === mtimeMs && now - known.at < NO_CWD_RETRY_MS) continue;
       mtimes.set(dirName, mtimeMs);
     }
+    if (mtimes.size === 0) return;
     const probes = new Map<string, number>();
-    let remaining = unread.filter((candidate) => {
+    let remaining = (await unread(new Set(mtimes.keys()))).filter((candidate) => {
       if (!mtimes.has(candidate.dirName)) return false;
       const count = probes.get(candidate.dirName) ?? 0;
       if (count >= MAX_CWD_PROBES_PER_DIR) return false;
@@ -992,14 +1107,15 @@ export class SessionIndex {
     this.reads++;
     const headTail = await readHeadTail(candidate.filePath, candidate.size);
     if (isSidechainTranscript(headTail.head)) return null;
-    const facts = await scanTranscriptFile(
+    const scanned = await scanTranscriptFile(
       candidate.filePath,
       candidate.size,
       headTail,
       previous,
       candidate.ino,
     );
-    if (!facts.hasMessages) return null;
+    if (!scanned.hasMessages) return null;
+    const facts = await this.withAllBackgroundTasks(candidate, scanned);
     // The last relocation names the session's cwd, as the SDK reads it; the
     // messages before it keep the old one.
     const fileCwd = await this.recoverCwd(candidate.dirName, [
@@ -1032,6 +1148,24 @@ export class SessionIndex {
     };
   }
 
+  /**
+   * `facts` with the background tasks of the whole transcript, when the
+   * tasks of its tail are not complete: a task can start before the tail.
+   * Only a finished turn of a live session waits for the tasks, so only
+   * then the whole transcript is read.
+   */
+  private async withAllBackgroundTasks(
+    candidate: TranscriptCandidate,
+    facts: TranscriptFacts,
+  ): Promise<TranscriptFacts> {
+    if (facts.turnState !== "finished") return facts;
+    if (facts.backgroundTasks?.complete) return facts;
+    const isLive = await this.options.isLive?.(candidate.sessionId);
+    if (!isLive) return facts;
+    const backgroundTasks = await searchBackgroundTasks(candidate.filePath, candidate.size);
+    return { ...facts, backgroundTasks };
+  }
+
   /**
    * The titles the SDK gives the listed transcript (`customTitle` and
    * `summary` of its `getSessionInfo`), by the SDK's rule from the head and

src/session-index/session-info.ts

@@ -4,7 +4,7 @@
  * the RFDs in `_meta.jetbrains.air`.
  */
 
-import type { SessionInfo } from "@agentclientprotocol/sdk";
+import type { SessionInfo } from "@agentclientprotocol/sdk/unstable";
 import { withAirMeta } from "../air-extension.js";
 import { deriveActivity, selectCost, type OwnSessionState } from "./activity.js";
 import type { LiveRecord } from "./live-registry.js";

src/session-index/transcript-scan.ts

@@ -7,9 +7,13 @@
  *
  * A last message longer than the tail window leaves no message in it: then
  * the tail window grows, up to {@link MAX_TAIL_SIZE}, until it holds one.
+ *
+ * The open background tasks come from the tail, on top of the tasks of an
+ * earlier scan (see `background-tasks.ts`).
  */
 
 import * as fs from "node:fs/promises";
+import { backgroundTasksOf, type BackgroundTasks } from "./background-tasks.js";
 import { firstPrompt, isUserPrompt, mediaPrompt, promptOf } from "./first-prompt.js";
 
 const CHUNK_SIZE = 64 * 1024;
@@ -56,6 +60,9 @@ export type TranscriptFacts = {
    *  worktree and the session is in it), false when it says otherwise.
    *  Undefined when no such record was read. See {@link agentWorktreeOf}. */
   agentWorktree?: boolean;
+  /** The background tasks that did not end. From the tail, on top of what
+   *  an earlier scan found when the file only grew within the tail. */
+  backgroundTasks?: BackgroundTasks;
   /** Whether the head or the tail holds a user or an assistant message. A
    *  transcript without one is a metadata-only stub. */
   hasMessages: boolean;
@@ -77,7 +84,7 @@ const INHERITED_FACTS = ["model", "tailCwd", "lastTurnEndedAt", "agentWorktree"]
 /** What an earlier scan of the same file found, at `size`. */
 export type PreviousScan = { size: number } & Pick<
   TranscriptFacts,
-  "lastPromptAt" | "promptSearched" | (typeof INHERITED_FACTS)[number]
+  "lastPromptAt" | "promptSearched" | "backgroundTasks" | (typeof INHERITED_FACTS)[number]
 >;
 
 /** The last `window` bytes of a file of `size` bytes, without the first,
@@ -157,6 +164,8 @@ export async function scanTranscriptFile(
       }
     }
   }
+  const previousTasks = grownWithinTail ? previous.backgroundTasks : undefined;
+  facts.backgroundTasks = tailBackgroundTasks(read.tail, size, previousTasks);
   // No worktree record in the tail (or before it, by an earlier scan): the
   // one `claude --worktree` writes at the start may still be in the head.
   if (facts.agentWorktree === undefined) {
@@ -174,7 +183,8 @@ export async function scanTranscriptFile(
   if (!facts.hasMessages || complete(facts) || size <= CHUNK_SIZE) return facts;
   const key = `${filePath}\0${size}\0${identity ?? ""}`;
   const searched = fullySearched.get(key);
-  if (searched) return searched;
+  // The tasks can differ by the earlier scan.
+  if (searched) return { ...searched, backgroundTasks: facts.backgroundTasks };
   let result = facts;
   const handle = await fs.open(filePath, "r");
   try {
@@ -218,6 +228,7 @@ export async function scanTranscriptFile(
         // A turn end the wider tail lacks may lie before it: the
         // narrow scan inherited it from an earlier scan of this file.
         lastTurnEndedAt: wider.lastTurnEndedAt ?? facts.lastTurnEndedAt,
+        backgroundTasks: facts.backgroundTasks,
         hasMessages: facts.hasMessages,
         lastPromptAt,
         // Searched to the start of the file, or found.
@@ -237,6 +248,22 @@ export async function scanTranscriptFile(
   return result;
 }
 
+/**
+ * The background tasks of the tail of a file of `size` bytes. `previous`:
+ * the tasks of an earlier scan, when the file only grew within the tail
+ * since. The set is complete when the tail is the whole file, or when it
+ * holds all records after a complete earlier set.
+ */
+function tailBackgroundTasks(
+  tail: string,
+  size: number,
+  previous: BackgroundTasks | undefined,
+): BackgroundTasks {
+  if (size <= CHUNK_SIZE) return backgroundTasksOf(tail, { complete: true });
+  if (previous?.complete) return backgroundTasksOf(tail, { complete: true, after: previous });
+  return backgroundTasksOf(tail, { complete: false });
+}
+
 const RELOCATED_MARKER = '"relocated"';
 
 /** The cwd of the last `relocated` record of the tail: where the session

src/session-mode.ts

@@ -5,7 +5,7 @@ import {
   type SessionNotification,
   type SetSessionModeRequest,
   type SetSessionModeResponse,
-} from "@agentclientprotocol/sdk";
+} from "@agentclientprotocol/sdk/unstable";
 import type {
   ModelInfo,
   PermissionMode,
@@ -66,29 +66,50 @@ type ModeConfigSession = SessionMode & {
   configOptions: SessionConfigOption[];
 };
 
-type InitializeSessionModeParams = {
-  query: Pick<Query, "setPermissionMode">;
-  requestedMode: PermissionMode;
-  currentModelInfo?: ModelInfo;
-  currentModelId: string;
+/** Which optional modes the session's mode catalog offers. */
+export type ModeAvailability = {
   /** When false, bypassPermissions is omitted from the mode catalog. */
   allowBypass: boolean;
+  /** When false (`disableAutoMode: "disable"` in settings), auto is omitted. */
+  allowAuto: boolean;
+};
+
+type InitializeSessionModeParams = ModeAvailability & {
+  query: Pick<Query, "setPermissionMode">;
+  requestedMode: PermissionMode;
+  /** The mode is the built-in default: no request, transcript or setting chose it. */
+  builtInDefault?: boolean;
+  currentModelInfo?: ModelInfo;
+  currentModelId: string;
 };
 
 /**
  * The permission mode a new Claude query starts in.
  *
  * An explicit mode wins. A resume or a load continues in the mode of the last
- * user record of the transcript. If that mode is unknown or not available now,
- * for example bypass, the session starts in `defaultMode` of the settings.
+ * user record of the transcript. If that mode is unknown or absent from the
+ * session's mode catalog, use an available `defaultMode` from settings, or
+ * `default` when that setting is unavailable too.
+ *
+ * With no `defaultMode` set, the session starts in `auto` when the catalog
+ * offers it and in `default` otherwise (`builtInDefault: true`), like an
+ * interactive Claude Code session. Claude Code also starts organizations with
+ * the HIPAA configuration in `default`; the SDK does not report that
+ * configuration, so those sessions start in `auto` here.
  */
 export function resolveInitialPermissionMode(
   sources: { explicit?: PermissionMode; resumed?: string; defaultMode?: unknown },
   logger: { error: (...args: unknown[]) => void },
-  allowBypass: boolean,
-): PermissionMode {
+  availability: ModeAvailability,
+): { mode: PermissionMode; builtInDefault: boolean } {
+  const { allowBypass } = availability;
+  const available = (mode: PermissionMode) =>
+    buildAvailableModes(availability).some((entry) => entry.id === mode);
   if (sources.explicit !== undefined) {
-    return resolvePermissionMode(sources.explicit, logger, allowBypass);
+    return {
+      mode: resolvePermissionMode(sources.explicit, logger, allowBypass),
+      builtInDefault: false,
+    };
   }
   if (sources.resumed !== undefined) {
     let rejected = false;
@@ -97,13 +118,23 @@ export function resolveInitialPermissionMode(
       { error: () => (rejected = true) },
       allowBypass,
     );
-    if (!rejected) return mode;
+    if (!rejected && available(mode)) {
+      return { mode, builtInDefault: false };
+    }
     logger.error(
       `Ignoring permission mode "${sources.resumed}" of the resumed transcript: ` +
         `not available in this session.`,
     );
   }
-  return resolvePermissionMode(sources.defaultMode, logger, allowBypass);
+  if (sources.defaultMode === undefined) {
+    return { mode: available("auto") ? "auto" : "default", builtInDefault: true };
+  }
+  const configuredMode = resolvePermissionMode(sources.defaultMode, logger, allowBypass);
+  // A rejected transcript mode falls back only to a mode this session can offer.
+  if (sources.resumed !== undefined && !available(configuredMode)) {
+    return { mode: "default", builtInDefault: false };
+  }
+  return { mode: configuredMode, builtInDefault: false };
 }
 
 /** Owns session-mode policy and the ACP/SDK synchronization it requires. */
@@ -113,22 +144,40 @@ export class SessionModeManager<S extends SessionMode> {
   async initialize({
     query,
     requestedMode,
+    builtInDefault = false,
     currentModelInfo,
     currentModelId,
     allowBypass,
+    allowAuto,
   }: InitializeSessionModeParams): Promise<{
     modes: SessionModeState;
     autoModeFallbackWarningPending: boolean;
   }> {
-    const availableModes = this.buildAvailableModes(allowBypass);
+    const availableModes = buildAvailableModes(
+      { allowBypass, allowAuto },
+      this.options.airClient?.() ?? false,
+    );
     let effectiveMode = requestedMode;
     let autoModeFallbackWarningPending = false;
 
-    if (
+    const autoUnsupported =
       effectiveMode === "auto" &&
       currentModelInfo !== undefined &&
-      currentModelInfo.supportsAutoMode !== true
-    ) {
+      currentModelInfo.supportsAutoMode !== true;
+    if (!this.isAvailable(availableModes, effectiveMode)) {
+      this.options.logError(
+        `permissions.defaultMode "${effectiveMode}" is not available in ` +
+          `this session; falling back to "default".`,
+      );
+      effectiveMode = "default";
+      await this.trySyncMode(query, effectiveMode, "Failed to sync clamped permissionMode to SDK:");
+    } else if (autoUnsupported && builtInDefault) {
+      // Like Claude Code: a built-in Auto default the model can't serve starts
+      // in Manual, without a warning. Nobody chose Auto, so don't escalate to
+      // acceptEdits.
+      effectiveMode = "default";
+      await this.trySyncMode(query, effectiveMode, "Failed to sync clamped permissionMode to SDK:");
+    } else if (autoUnsupported) {
       this.options.logError(
         `permissions.defaultMode "auto" is not available for model ` +
           `"${currentModelId}"; falling back to "${AUTO_MODE_FALLBACK}".`,
@@ -136,13 +185,6 @@ export class SessionModeManager<S extends SessionMode> {
       effectiveMode = AUTO_MODE_FALLBACK;
       autoModeFallbackWarningPending = true;
       await this.trySyncMode(query, effectiveMode, "Failed to sync clamped permissionMode to SDK:");
-    } else if (!this.isAvailable(availableModes, effectiveMode)) {
-      this.options.logError(
-        `permissions.defaultMode "${effectiveMode}" is not available in ` +
-          `this session; falling back to "default".`,
-      );
-      effectiveMode = "default";
-      await this.trySyncMode(query, effectiveMode, "Failed to sync clamped permissionMode to SDK:");
     }
 
     return {
@@ -247,7 +289,10 @@ export class SessionModeManager<S extends SessionMode> {
     const session = this.requireOpenSession(sessionId);
     const requestedMode = this.parseMode(modeId);
     if (!this.isAvailable(session.modes.availableModes, requestedMode)) {
-      throw new Error(`Mode ${modeId} is not available in this session`);
+      throw RequestError.invalidParams(
+        undefined,
+        `Mode ${modeId} is not available in this session`,
+      );
     }
 
     const effectiveMode = this.effectiveMode(session, requestedMode);
@@ -314,7 +359,7 @@ export class SessionModeManager<S extends SessionMode> {
 
   private requireOpenSession(sessionId: string): S {
     const session = this.options.getSession(sessionId);
-    if (!session) throw new Error("Session not found");
+    if (!session) throw RequestError.sessionNotFound(sessionId);
     if (session.queryClosed) {
       throw RequestError.internalError(undefined, this.options.sessionEndedMessage);
     }
@@ -343,54 +388,10 @@ export class SessionModeManager<S extends SessionMode> {
       case "plan":
         return modeId;
       default:
-        throw new Error("Invalid Mode");
+        throw RequestError.invalidParams(undefined, `Invalid Mode: ${modeId}`);
     }
   }
 
-  private buildAvailableModes(allowBypass: boolean): SessionModeState["availableModes"] {
-    // Only AIR gets the mode kind.
-    const air = this.options.airClient?.() ?? false;
-    const kind = (value: string) => {
-      const meta = airOnlyMeta(air, AIR_KIND_KEY, value);
-      return meta ? { _meta: meta } : {};
-    };
-    const modes: SessionModeState["availableModes"] = [
-      {
-        id: "default",
-        name: "Manual",
-        description: "Always ask before making changes",
-        ...kind("standard"),
-      },
-      {
-        id: "acceptEdits",
-        name: "Accept edits",
-        description: "Automatically accept all file edits",
-        ...kind("standard"),
-      },
-      {
-        id: "plan",
-        name: "Plan",
-        description: "Create a plan before making changes",
-        ...kind("plan"),
-      },
-      {
-        id: "auto",
-        name: "Auto",
-        description: "Claude handles permission decisions",
-        ...kind("auto_review"),
-      },
-    ];
-    if (allowBypass) {
-      modes.push({
-        id: "bypassPermissions",
-        name: "Bypass permissions",
-        description: "Accepts all permissions",
-        ...kind("full_access"),
-      });
-    }
-    return modes;
-  }
-
   private async trySyncMode(
     query: Pick<Query, "setPermissionMode">,
     mode: PermissionMode,
@@ -403,3 +404,51 @@ export class SessionModeManager<S extends SessionMode> {
     }
   }
 }
+
+function buildAvailableModes(
+  { allowBypass, allowAuto }: ModeAvailability,
+  air = false,
+): SessionModeState["availableModes"] {
+  // Only AIR gets the mode kind.
+  const kind = (value: string) => {
+    const meta = airOnlyMeta(air, AIR_KIND_KEY, value);
+    return meta ? { _meta: meta } : {};
+  };
+  const modes: SessionModeState["availableModes"] = [
+    {
+      id: "default",
+      name: "Manual",
+      description: "Always ask before making changes",
+      ...kind("standard"),
+    },
+    {
+      id: "acceptEdits",
+      name: "Accept edits",
+      description: "Automatically accept all file edits",
+      ...kind("standard"),
+    },
+    {
+      id: "plan",
+      name: "Plan",
+      description: "Create a plan before making changes",
+      ...kind("plan"),
+    },
+  ];
+  if (allowAuto) {
+    modes.push({
+      id: "auto",
+      name: "Auto",
+      description: "Claude handles permission decisions",
+      ...kind("auto_review"),
+    });
+  }
+  if (allowBypass) {
+    modes.push({
+      id: "bypassPermissions",
+      name: "Bypass permissions",
+      description: "Accepts all permissions",
+      ...kind("full_access"),
+    });
+  }
+  return modes;
+}

src/session-model.ts

@@ -1,4 +1,4 @@
-import type { SessionConfigOption } from "@agentclientprotocol/sdk";
+import type { SessionConfigOption } from "@agentclientprotocol/sdk/unstable";
 import type { ModelInfo, Query, Settings } from "@anthropic-ai/claude-agent-sdk";
 import { AIR_RECOMMENDED_CONFIG_VALUE_CAPABILITY, withAirMeta } from "./air-extension.js";
 import { bedrockRegionPrefix } from "./gateway-models.js";
@@ -210,22 +210,12 @@ export function buildModelConfigOption(
     ? models.availableModels.filter((model) => model.modelId !== "default")
     : models.availableModels;
 
-  return {
-    id: MODEL_CONFIG_ID,
-    name: "Model",
-    description: "AI model to use",
-    category: "model",
-    type: "select",
-    currentValue:
-      concreteRecommendation && models.currentModelId === "default"
-        ? recommended.value
-        : models.currentModelId,
-    ...(concreteRecommendation
-      ? {
-          _meta: withAirMeta(undefined, AIR_RECOMMENDED_CONFIG_VALUE_CAPABILITY, recommended.value),
-        }
-      : {}),
-    options: available.map((model) => {
+  const currentValue =
+    concreteRecommendation && models.currentModelId === "default"
+      ? recommended.value
+      : models.currentModelId;
+  const options: Array<{ value: string; name: string; description?: string }> = available.map(
+    (model) => {
       if (model.modelId === "default" && defaultInfo?.resolvedModel) {
         const named = modelInfos.find(
           (info) => info.value !== "default" && info.resolvedModel === defaultInfo.resolvedModel,
@@ -241,7 +231,35 @@ export function buildModelConfigOption(
         name: model.name,
         description: model.description ?? undefined,
       };
-    }),
+    },
+  );
+  // ACP requires `currentValue` to be one of `options`. A session can run a
+  // model the picker does not list: resumed onto a model excluded by the
+  // `availableModels` allowlist, or switched by a refusal fallback. List that
+  // model as its own entry. It is not added to `models.availableModels`, so the
+  // next rebuild after switching to a listed model drops it.
+  if (!options.some((option) => option.value === currentValue)) {
+    const info = modelInfos.find((model) => model.value === currentValue);
+    options.push({
+      value: currentValue,
+      name: info?.displayName || currentValue,
+      description: info?.description || undefined,
+    });
+  }
+
+  return {
+    id: MODEL_CONFIG_ID,
+    name: "Model",
+    description: "AI model to use",
+    category: "model",
+    type: "select",
+    currentValue,
+    ...(concreteRecommendation
+      ? {
+          _meta: withAirMeta(undefined, AIR_RECOMMENDED_CONFIG_VALUE_CAPABILITY, recommended.value),
+        }
+      : {}),
+    options,
   };
 }
 
@@ -264,25 +282,40 @@ function resolveSettingsModel(
 const MODEL_FAMILY_ALIASES = new Set(["opus", "sonnet", "haiku", "fable"]);
 
 /** A model id without the spellings that name the same model: provider
- *  prefixes, dates, version suffixes, `-fast` and context hints. `deniedModels`
- *  and gateway listings both match on it. */
+ *  prefixes, dates, version suffixes, `:variant` suffixes, dotted versions,
+ *  `-fast` and context hints. `deniedModels` and gateway listings both match on
+ *  it. OpenRouter lists `anthropic/claude-opus-5.5:batch[1m]`, which normalizes
+ *  to `claude-opus-5-5`; `anthropic/openai/gpt-5` keeps its `openai/` prefix and
+ *  matches no Claude id. */
 function normalizeModelId(value: string): string {
   let id = stripContextHints(value.trim().toLowerCase());
   const providerPrefix = id.lastIndexOf("anthropic.");
   if (providerPrefix !== -1) id = id.slice(providerPrefix + "anthropic.".length);
-  return id
-    .replace(/@.*$/, "")
-    .replace(/-v\d+(?::\d+)?$/, "")
-    .replace(/-fast$/, "")
-    .replace(/-\d{8}$/, "");
+  return (
+    id
+      // Only a leading `anthropic/`: OpenRouter's `anthropic/openai/gpt-5` must
+      // keep `openai/`, which `lastIndexOf` would strip along with it.
+      .replace(/^anthropic\//, "")
+      // `:batch`, `:free`. A letter must follow the colon, so Bedrock's `-v1:0`
+      // is left for the `-vN:M` step below.
+      .replace(/:[a-z][a-z0-9-]*$/, "")
+      // `claude-opus-5.5` -> `claude-opus-5-5`; only dots between two digits.
+      .replace(/(?<=\d)\.(?=\d)/g, "-")
+      .replace(/@.*$/, "")
+      .replace(/-v\d+(?::\d+)?$/, "")
+      .replace(/-fast$/, "")
+      .replace(/-\d{8}$/, "")
+  );
 }
 
 /**
  * Whether managed `deniedModels` blocks a model id, following the CLI's rules
  * closely enough for the picker: a family alias blocks the whole family, and a
  * model id blocks that version in every spelling plus the later minor versions
- * it prefixes (`claude-opus-5` also blocks `claude-opus-5-5`). The CLI stays
- * the enforcer; this only keeps the picker from offering a refused row.
+ * it prefixes (`claude-opus-5` also blocks `claude-opus-5-5`). Entries share
+ * `normalizeModelId`, so `claude-opus-4.5` or `anthropic/claude-opus-4.5` also
+ * blocks `claude-opus-4-5`, which the CLI may still allow. The CLI stays the
+ * enforcer; this only keeps the picker from offering a refused row.
  */
 export function isDeniedModel(modelId: string, deniedModels: readonly string[]): boolean {
   const id = normalizeModelId(modelId);
@@ -580,14 +613,107 @@ export async function getAvailableModels(
   for (const name of displayNames) {
     displayNameCounts.set(name, (displayNameCounts.get(name) ?? 0) + 1);
   }
+  const names = models.map((model, index) =>
+    displayNameCounts.get(displayNames[index]) === 1 ? displayNames[index] : model.displayName,
+  );
+  const nameCounts = new Map<string, number>();
+  for (const name of names) {
+    nameCounts.set(name, (nameCounts.get(name) ?? 0) + 1);
+  }
 
   return {
     availableModels: models.map((model, index) => ({
       modelId: model.value,
-      name:
-        displayNameCounts.get(displayNames[index]) === 1 ? displayNames[index] : model.displayName,
+      // Allowlisted aliases can inherit the same SDK label. Keep every ID
+      // selectable, but distinguish the rows for clients that show only names.
+      name: nameCounts.get(names[index]) === 1 ? names[index] : `${names[index]} (${model.value})`,
       description: model.description,
     })),
     currentModelId: currentModel.value,
   };
 }
+
+/** The display name of the model id `model` in `modelInfos`, if it is there. */
+export function modelDisplayName(modelInfos: ModelInfo[], model: string): string | undefined {
+  let byModel = displayNameCache.get(modelInfos);
+  if (!byModel) displayNameCache.set(modelInfos, (byModel = new Map()));
+  if (!byModel.has(model)) {
+    const info = modelInfos.find((info) => info.value === model || info.resolvedModel === model);
+    byModel.set(model, info?.displayName);
+  }
+  return byModel.get(model);
+}
+
+/** {@link modelDisplayName} per model list, which a session replaces and never edits. */
+const displayNameCache = new WeakMap<ModelInfo[], Map<string, string | undefined>>();
+
+/** The flat entries of a session's `model` select option. */
+function modelOptionEntries(option: SessionConfigOption): Array<{ value: string; name: string }> {
+  if (option.type !== "select") return [];
+  return option.options.flatMap((entry) =>
+    "value" in entry ? [{ value: entry.value, name: entry.name }] : entry.options,
+  );
+}
+
+/**
+ * The entry of the `model` option among `configOptions` for `model`, a model
+ * id that a response reported, so that a client can compare it with the
+ * session's own model. Best first:
+ *
+ * 1. the current entry, when it runs that model up to a context hint: a
+ *    session on `opus[1m]` or `default` that answers as `claude-opus-4-6`;
+ * 2. the entry whose value or resolved model is that id;
+ * 3. an entry that runs that model up to a context hint.
+ *
+ * Among several entries for one model, a concrete entry comes before
+ * `default`, as in {@link resolveModelPreference}. Undefined when no entry
+ * matches. A model's resolved id comes from `modelInfos`
+ * (`ModelInfo.resolvedModel`), the wire id that a response reports, as for
+ * {@link matchResumedModel}. It is compared as it is: a dated id such as
+ * `claude-haiku-4-5-20251001` matches only the same dated id.
+ */
+export function modelEntryFor(
+  configOptions: readonly SessionConfigOption[],
+  modelInfos: ModelInfo[],
+  model: string,
+): { value: string; name: string } | undefined {
+  // Each response of a subagent reports its model, so the result is kept per
+  // list. A session replaces its lists on a change and never edits them.
+  let byInfos = modelEntryCache.get(configOptions);
+  if (!byInfos) modelEntryCache.set(configOptions, (byInfos = new WeakMap()));
+  let byModel = byInfos.get(modelInfos);
+  if (!byModel) byInfos.set(modelInfos, (byModel = new Map()));
+  if (byModel.has(model)) return byModel.get(model);
+  const entry = findModelEntry(configOptions, modelInfos, model);
+  byModel.set(model, entry);
+  return entry;
+}
+
+const modelEntryCache = new WeakMap<
+  readonly SessionConfigOption[],
+  WeakMap<ModelInfo[], Map<string, { value: string; name: string } | undefined>>
+>();
+
+function findModelEntry(
+  configOptions: readonly SessionConfigOption[],
+  modelInfos: ModelInfo[],
+  model: string,
+): { value: string; name: string } | undefined {
+  const option = configOptions.find((candidate) => candidate.id === MODEL_CONFIG_ID);
+  if (option?.type !== "select") return undefined;
+  // Concrete entries first; `sort` keeps the list order otherwise.
+  const entries = modelOptionEntries(option).sort(
+    (left, right) => Number(left.value === "default") - Number(right.value === "default"),
+  );
+  const observed = canonicalizeModelId(model);
+  const resolved = (value: string) =>
+    canonicalizeModelId(modelInfos.find((info) => info.value === value)?.resolvedModel ?? value);
+  const sameModel = (value: string) =>
+    stripContextHints(resolved(value)) === stripContextHints(observed);
+  const current = entries.find((entry) => entry.value === option.currentValue);
+  if (current && sameModel(current.value)) return current;
+  return (
+    entries.find((entry) => entry.value === model || resolved(entry.value) === observed) ??
+    entries.find((entry) => sameModel(entry.value))
+  );
+}

src/session-notices.ts

@@ -1,4 +1,4 @@
-import type { ClientCapabilities, SessionNotification } from "@agentclientprotocol/sdk";
+import type { ClientCapabilities, SessionNotification } from "@agentclientprotocol/sdk/unstable";
 
 /** Fire-and-forget advisory text for the user: live events rather than
  *  conversation history. See the ACP Session Notices RFD
@@ -50,11 +50,35 @@ export function noticeOrTranscriptUpdate(
   if (supportsNotices) return noticeUpdate(notice);
   return {
     sessionUpdate: "agent_message_chunk",
-    content: { type: "text", text: transcriptText },
+    content: { type: "text", text: transcriptBlock(transcriptText) },
     ...(transcriptMeta ? { _meta: transcriptMeta } : {}),
   };
 }
 
+/** Clients render consecutive agent_message_chunks as one markdown stream, so
+ *  a bare `**Notice:** …` chunk lands mid-sentence: "…all done.**Notice:** Stop
+ *  says: …". Put it in its own blockquote paragraph, blank lines on both sides,
+ *  so it starts on a new line and Claude's next chunk does not continue the
+ *  quote. */
+export function transcriptBlock(text: string): string {
+  const lines = text.trim().split(/\r?\n/);
+  return `\n\n${lines.map((line) => (line ? `> ${line}` : ">")).join("\n")}\n\n`;
+}
+
+const HOOK_SPEAKER = /^[^\n:]{1,80} says: /;
+
+/** Claude Code prefixes every line of a hook's `systemMessage` with
+ *  "<HookEvent> says: ", so a two-line message reads "Stop says: a\nStop says:
+ *  b". Keep the prefix on the first line only when every line repeats it. */
+export function collapseHookSpeaker(text: string): string {
+  const lines = text.split(/\r?\n/);
+  const prefix = lines[0].match(HOOK_SPEAKER)?.[0];
+  if (!prefix || lines.length < 2 || !lines.every((line) => line.startsWith(prefix))) {
+    return text;
+  }
+  return [lines[0], ...lines.slice(1).map((line) => line.slice(prefix.length))].join("\n");
+}
+
 /** Fragments that read on after a bold label stand alone as a notice
  *  description, so start them with a capital. */
 export function sentenceCase(text: string): string {

src/session-titles.ts

@@ -1,20 +1,25 @@
 /**
  * AI-generated session titles.
  *
- * Claude Code's own auto-title generation never runs under the Agent SDK — the
- * latch that arms it is pre-set in the headless path — so `SDKSessionInfo.summary`
- * degrades to the raw first prompt. This module asks the CLI for a real title
- * instead, via the `generate_session_title` control request, and publishes it
- * over ACP as a `session_info_update`.
+ * Claude Code titles a new SDK session itself: when it reads the first prompt,
+ * it asks a small model for a title and stores it in the transcript as an
+ * `ai-title` entry, a few seconds in. It sends no message when it does. This
+ * module asks for the title with the `generate_session_title` control request,
+ * which returns the stored title or waits for the one being generated, and
+ * publishes it over ACP as a `session_info_update`. Where the CLI does not
+ * title the session itself (a resumed session, or one with
+ * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` or
+ * `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` set), the same request generates it.
  *
  * {@link SessionTitles} holds the per-session state and is owned by `Session`.
- * `acp-agent.ts` drives it from four places: {@link SessionTitles.onPrompt} and
+ * `acp-agent.ts` drives it from five places: {@link SessionTitles.onPrompt} and
  * {@link SessionTitles.onAssistantText} to collect text,
+ * {@link SessionTitles.onPromptQueued} once a prompt is sent to the CLI,
  * {@link SessionTitles.onTurnEnd} at `session_state_changed: idle`, and
  * {@link SessionTitles.reset} on `conversation_reset`.
  */
 
-import type { ContentBlock, PromptRequest } from "@agentclientprotocol/sdk";
+import type { ContentBlock, PromptRequest } from "@agentclientprotocol/sdk/unstable";
 import { getSessionInfo, type Query, type SDKSessionInfo } from "@anthropic-ai/claude-agent-sdk";
 import type { ClaudeAcpAgent, Session } from "./acp-agent.js";
 import { ExplicitTitle } from "./session-index/explicit-title.js";
@@ -77,6 +82,11 @@ export function appendTitleContext(previous: string | undefined, text: string):
   return next.length > MAX_TITLE_CONTEXT_LENGTH ? next.slice(-MAX_TITLE_CONTEXT_LENGTH) : next;
 }
 
+/** The text chunks of a prompt, one per line. */
+function promptText(prompt: PromptRequest["prompt"]): string {
+  return prompt.flatMap((chunk) => (chunk.type === "text" ? [chunk.text] : [])).join("\n");
+}
+
 /** Whether this SDK still offers on-demand title generation. */
 function supportsTitleGeneration(query: Query): boolean {
   return typeof (query as TitleCapableQuery).generateSessionTitle === "function";
@@ -100,6 +110,11 @@ export class SessionTitles {
    *  one. Released by {@link reset}, and when generation yields nothing. */
   private settled = false;
 
+  /** Whether {@link onPromptQueued} asked for a title from the latest prompt.
+   *  A turn end then does not ask again: like the CLI, a prompt that yields
+   *  no title gets one try, and the next prompt tries again. */
+  private askedAtPrompt = false;
+
   /** The title a client set, which no generated title replaces. */
   private readonly explicit = new ExplicitTitle();
 
@@ -132,11 +147,33 @@ export class SessionTitles {
     if (this.settled) {
       return;
     }
-    const promptText = prompt
-      .flatMap((chunk) => (chunk.type === "text" ? [chunk.text] : []))
-      .join("\n");
+    this.context = appendTitleContext(this.context, `\n${promptText(prompt)}\n`);
+  }
 
-    this.context = appendTitleContext(this.context, `\n${promptText}\n`);
+  /** Ask for the title as soon as a prompt is sent to the CLI, instead of
+   *  waiting for `idle`: `idle` comes only after the whole turn and its
+   *  background tasks, often minutes after the CLI stored its title. The CLI
+   *  answers `generate_session_title` while the turn runs, and with the title
+   *  it stored or is generating, so this makes no second model call. The
+   *  prompt alone is the description, because the CLI titles from the prompt
+   *  alone. When this yields no title, the stored summary is published and
+   *  the next prompt tries again. */
+  onPromptQueued(session: Session, prompt: PromptRequest["prompt"]): void {
+    this.askedAtPrompt = false;
+    // `session.cancelled` is not checked: after a cancelled turn it stays set
+    // until the next turn starts, which is after this prompt is queued.
+    if (this.settled || this.explicit.active || session.queryClosed) {
+      return;
+    }
+    if (!supportsTitleGeneration(session.query)) {
+      return;
+    }
+    const description = promptText(prompt).trim();
+    if (description.length < MIN_TITLE_CONTEXT_LENGTH) {
+      return;
+    }
+    this.askedAtPrompt = true;
+    this.startGeneration(() => this.titleFromPrompt(session, description));
   }
 
   /** Collect the assistant's own answer for the title. Chunks are appended
@@ -152,6 +189,7 @@ export class SessionTitles {
    *  `conversation_reset`, which mounts a fresh transcript. */
   reset(): void {
     this.settled = false;
+    this.askedAtPrompt = false;
     this.explicit.reset();
     this.context = undefined;
     this.lastTitle = undefined;
@@ -165,10 +203,12 @@ export class SessionTitles {
    *  title — a user `/rename` or one generated earlier; the SDK folds both into
    *  that one field. Adopt it and latch, so neither is ever titled over.
    *
-   *  With no title yet, ask the SDK to generate one in the background: it is a
-   *  ~2s small-model call and turn-end must not wait on it. Only when that is
-   *  not possible do we fall back to `summary`, which for an SDK-driven session
-   *  is just the raw first prompt. */
+   *  With no title yet, and none asked for at the latest prompt (see
+   *  {@link onPromptQueued}), ask the SDK to generate one in the background
+   *  from the prompts and replies so far: it is a ~2s small-model call and
+   *  turn-end must not wait on it. That covers a prompt too short to title
+   *  from, such as "hi". Only when that is not possible do we fall back to
+   *  `summary`, which for an SDK-driven session is just the raw first prompt. */
   async onTurnEnd(session: Session): Promise<void> {
     if (this.explicit.settledByClient) {
       // No title is generated over the one the client set, but a custom title
@@ -200,17 +240,9 @@ export class SessionTitles {
       ? { title: info.summary, lastModified: info.lastModified }
       : undefined;
 
-    if (this.canRequest(session)) {
-      this.settled = true;
-
-      this.explicit.track(
-        this.requestGenerateTitle(session, fallback).catch((error) => {
-          this.agent.logger.error(
-            `Session ${this.sessionId}: session title update failed: ${error}`,
-          );
-        }),
-      );
-
+    if (!this.askedAtPrompt && this.canRequest(session)) {
+      const description = this.context?.trim() ?? "";
+      this.startGeneration(() => this.requestGenerateTitle(session, description, fallback));
       return;
     }
     // Only while this session has no title of its own: `summary` degrades to the
@@ -264,6 +296,32 @@ export class SessionTitles {
     });
   }
 
+  /** Sends the session's current title and `updatedAt`, even when the client
+   *  was already sent that title: a client that resumes the session may not
+   *  have it. Both come from the session file, as `session/list` reports
+   *  them; a session with no file yet sends the last title published, if any,
+   *  without `updatedAt`. */
+  async publishCurrent(session: Session): Promise<void> {
+    const info = await this.readSessionInfo(session);
+    // A title published but not yet stored (a generated title still being
+    // written) wins over `summary`, which is then only the raw first prompt.
+    const stored =
+      info?.customTitle || (this.settled && this.lastTitle ? undefined : info?.summary);
+    const title = stored
+      ? sanitizeTitle(this.agent.clientTitle?.(stored) ?? stored)
+      : this.lastTitle;
+    if (!title) return;
+    this.lastTitle = title;
+    await this.agent.client.sessionUpdate({
+      sessionId: this.sessionId,
+      update: {
+        sessionUpdate: "session_info_update",
+        title,
+        ...(info ? { updatedAt: new Date(info.lastModified).toISOString() } : {}),
+      },
+    });
+  }
+
   /** Records a title the CLI took, as soon as it took it. */
   rememberStoredTitle(title: string): void {
     this.persistedTitle = title;
@@ -309,17 +367,48 @@ export class SessionTitles {
     return (this.context?.trim().length ?? 0) >= MIN_TITLE_CONTEXT_LENGTH;
   }
 
-  /** Generate a title from the session's own text and publish it. `persist`
-   *  writes it to the session file, which is what carries it into
-   *  `session/list` and `session/load`. A null or failed generation releases the
-   *  latch so a later turn retries, and publishes `fallback` (the stored
-   *  summary) so a backend that can't generate titles is no worse off than
-   *  before. */
+  /** Latch the title and run `generation` in the background, so neither the
+   *  prompt nor turn-end waits on a model call. A client title change waits
+   *  for it to finish (see {@link ExplicitTitle.track}). */
+  private startGeneration(generation: () => Promise<void>): void {
+    this.settled = true;
+    this.explicit.track(
+      generation().catch((error) => {
+        this.agent.logger.error(`Session ${this.sessionId}: session title update failed: ${error}`);
+      }),
+    );
+  }
+
+  /** The prompt-time title: the one the session file already holds (a resumed
+   *  session's title, or a `/rename`), else one generated from `description`.
+   *  The file is read first because the CLI checks only the titles it holds in
+   *  memory before generating one. */
+  private async titleFromPrompt(session: Session, description: string): Promise<void> {
+    const info = await this.readSessionInfo(session);
+    if (this.agent.sessions[this.sessionId] !== session || this.explicit.active) {
+      return;
+    }
+    if (info?.customTitle) {
+      this.context = undefined;
+      await this.publish(info.customTitle, info.lastModified);
+      return;
+    }
+    const fallback = info?.summary
+      ? { title: info.summary, lastModified: info.lastModified }
+      : undefined;
+    await this.requestGenerateTitle(session, description, fallback);
+  }
+
+  /** Generate a title from `description` and publish it. `persist` writes it
+   *  to the session file, which is what carries it into `session/list` and
+   *  `session/load`. A null or failed generation releases the latch so a later
+   *  prompt or turn end retries, and publishes `fallback` (the stored summary)
+   *  so a backend that can't generate titles is no worse off than before. */
   private async requestGenerateTitle(
     session: Session,
+    description: string,
     fallback: TitleFallback | undefined,
   ): Promise<void> {
-    const description = this.context?.trim() ?? "";
     let title: string | null = null;
 
     try {

src/session-ultracode.ts

@@ -0,0 +1,140 @@
+import { RequestError } from "@agentclientprotocol/sdk/unstable";
+import type {
+  SessionConfigOption,
+  SetSessionConfigOptionRequest,
+} from "@agentclientprotocol/sdk/unstable";
+import type { ModelInfo, Query } from "@anthropic-ai/claude-agent-sdk";
+import { ULTRACODE_CONFIG_ID } from "./session-config-ids.js";
+
+export { ULTRACODE_CONFIG_ID } from "./session-config-ids.js";
+
+/** Select-fallback values for clients without boolean config options. */
+export const ULTRACODE_ON = "on";
+export const ULTRACODE_OFF = "off";
+const ULTRACODE_DESCRIPTION = "Dynamic workflows on every task, at any effort level";
+
+/** Ultracode state from the CLI's `get_settings` control response
+ *  (`applied.ultracodeAvailable` / `applied.ultracodeRequested`). Each field is
+ *  undefined when the CLI does not report it. */
+export type UltracodeSettingsReport = {
+  /** Workflows are enabled and the current model supports ultracode. */
+  available?: boolean;
+  /** Ultracode is turned on for the session, whether or not it can take
+   *  effect on the current model. */
+  requested?: boolean;
+};
+
+// `Query.getSettings()` exists at runtime (sdk.mjs) but is missing from the
+// SDK's type declarations as of 0.3.319.
+type GetSettingsQuery = Query & {
+  getSettings?: () => Promise<{
+    applied?: { ultracodeAvailable?: unknown; ultracodeRequested?: unknown };
+  }>;
+};
+
+/** Ask the CLI whether ultracode is available and requested for the session.
+ *  Returns undefined when the SDK has no `getSettings` or the request fails;
+ *  callers then fall back to {@link modelSupportsUltracode}. */
+export async function readUltracodeSettings(
+  query: Query,
+): Promise<UltracodeSettingsReport | undefined> {
+  const getSettings = (query as GetSettingsQuery).getSettings;
+  if (typeof getSettings !== "function") return undefined;
+  try {
+    const applied = (await getSettings.call(query))?.applied;
+    return {
+      available:
+        typeof applied?.ultracodeAvailable === "boolean" ? applied.ultracodeAvailable : undefined,
+      requested:
+        typeof applied?.ultracodeRequested === "boolean" ? applied.ultracodeRequested : undefined,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/** The CLI supports ultracode on exactly the models that support `xhigh`
+ *  effort (both use the same capability check), and `supportedEffortLevels`
+ *  lists `xhigh` only for those models. E.g. Opus 4.7+, Sonnet 5+ and Haiku
+ *  5.5 qualify; Opus 4.6 and Haiku 4.5 do not. */
+export function modelSupportsUltracode(modelInfo: ModelInfo | undefined): boolean {
+  return (
+    modelInfo?.supportsEffort === true &&
+    modelInfo.supportedEffortLevels?.includes("xhigh") === true
+  );
+}
+
+/** Whether dynamic workflows are enabled for the session, inferred from the
+ *  CLI's `ultracodeAvailable` for the model the session started on. This is
+ *  the part of availability that does not change with the model: the plan
+ *  default (off on Pro), `enableWorkflows`/`disableWorkflows` and org policy.
+ *  Undefined when the report can't tell, e.g. `ultracodeAvailable: false` on a
+ *  model that lacks ultracode support anyway. */
+export function ultracodeWorkflowsEnabled(
+  report: UltracodeSettingsReport | undefined,
+  modelInfo: ModelInfo | undefined,
+): boolean | undefined {
+  if (report?.available === true) return true;
+  if (report?.available === false && modelSupportsUltracode(modelInfo)) return false;
+  return undefined;
+}
+
+/** Whether to offer the ultracode toggle for `modelInfo`. An unknown workflows
+ *  state shows the toggle: the CLI keeps an unavailable request without
+ *  error, so the toggle is merely inert there. */
+export function ultracodeSupported(
+  workflowsEnabled: boolean | undefined,
+  modelInfo: ModelInfo | undefined,
+): boolean {
+  return workflowsEnabled !== false && modelSupportsUltracode(modelInfo);
+}
+
+/** Ultracode state threaded into `buildConfigOptions`. The option is only
+ *  surfaced while `supported`. */
+export type UltracodeOptionState = {
+  supported: boolean;
+  enabled: boolean;
+  /** Whether the client opted into boolean config options. */
+  useBooleanOption: boolean;
+};
+
+/** Build the ultracode toggle: a native boolean for clients that opted into
+ *  boolean config options, otherwise an "on"/"off" select. */
+export function createUltracodeConfigOption(
+  enabled: boolean,
+  useBooleanOption: boolean,
+): SessionConfigOption {
+  const base = {
+    id: ULTRACODE_CONFIG_ID,
+    name: "Ultracode",
+    description: ULTRACODE_DESCRIPTION,
+    category: "model_config",
+  } as const;
+
+  if (useBooleanOption) {
+    return { ...base, type: "boolean", currentValue: enabled };
+  }
+
+  return {
+    ...base,
+    type: "select",
+    currentValue: enabled ? ULTRACODE_ON : ULTRACODE_OFF,
+    options: [
+      { value: ULTRACODE_ON, name: "On" },
+      { value: ULTRACODE_OFF, name: "Off" },
+    ],
+  };
+}
+
+/** Read the requested ultracode value from a `session/set_config_option`
+ *  request: a boolean, or the "on"/"off" select-fallback strings. */
+export function resolveUltracodeEnabled(params: SetSessionConfigOptionRequest): boolean {
+  const value = params.value;
+  if (typeof value === "boolean") return value;
+  if (value === ULTRACODE_ON) return true;
+  if (value === ULTRACODE_OFF) return false;
+  throw RequestError.invalidParams(
+    undefined,
+    `Invalid value for config option ${ULTRACODE_CONFIG_ID}: ${value}`,
+  );
+}

src/startup-failure.ts

@@ -0,0 +1,42 @@
+import { RequestError } from "@agentclientprotocol/sdk/unstable";
+import type { SDKStartupFailureReason } from "@anthropic-ai/claude-agent-sdk";
+
+/** Makes the CLI write an `error_during_execution` result with a
+ *  `startup_failure_reason` before it exits on a known startup failure. Without
+ *  it, some failures (e.g. `proxy_invalid`) end with stderr and an exit code
+ *  alone. The SDK then rejects `initializationResult()` with an error that
+ *  carries the reason as `startupFailureReason`. */
+export const STARTUP_FAILURE_RESULTS_ENV = { CLAUDE_CODE_STARTUP_FAILURE_RESULTS: "1" };
+
+/** The SDK's prefix on the message of an error built from an error result. */
+const ERROR_RESULT_PREFIX = "Claude Code returned an error result: ";
+
+/** Reasons that signing in again, or with another account, can fix. */
+const AUTH_REQUIRED_REASONS: ReadonlySet<SDKStartupFailureReason> = new Set([
+  "gateway_signin_required",
+  "org_pin_mismatch",
+  "org_config_refused",
+]);
+
+/** The ACP error for a CLI that refused to start, or `undefined` when `error`
+ *  carries no `startupFailureReason` (older CLIs, failures without a known
+ *  cause). The message is the CLI's own, which says what to fix, e.g.
+ *  `Invalid proxy URL in HTTPS_PROXY: … Fix or unset HTTPS_PROXY and restart
+ *  Claude Code.`; `data.startupFailureReason` carries the reason. */
+export function startupFailureError(error: unknown): RequestError | undefined {
+  if (!(error instanceof Error)) return undefined;
+  const reason = (error as { startupFailureReason?: unknown }).startupFailureReason;
+  if (typeof reason !== "string" || reason === "") return undefined;
+
+  const message = error.message.startsWith(ERROR_RESULT_PREFIX)
+    ? error.message.slice(ERROR_RESULT_PREFIX.length)
+    : error.message;
+  const data = { startupFailureReason: reason };
+  if (AUTH_REQUIRED_REASONS.has(reason as SDKStartupFailureReason)) {
+    return RequestError.authRequired(data, message);
+  }
+  if (reason === "cwd_unavailable") {
+    return RequestError.invalidParams(data, message);
+  }
+  return RequestError.internalError(data, message);
+}

src/subagent-history.ts

@@ -24,6 +24,11 @@ export interface SubagentRecord {
   background: boolean;
   /** Whether the user stopped it. */
   stoppedByUser: boolean;
+  /**
+   * Its working directory, when Claude Code placed it outside its parent's:
+   * in a worktree of its own or of an ancestor, or in a `cwd` of its own.
+   */
+  cwd?: string;
 }
 
 /** Where the subagent transcripts of a session are. */
@@ -43,7 +48,9 @@ export interface SubagentHistory {
  * Claude keeps the history of a subagent in its own transcript,
  * `<session>/subagents/agent-<id>.jsonl`, next to the session transcript.
  * The `agent-<id>.meta.json` file beside it names the launching tool use.
- * The ids are empty for a session without a local transcript.
+ * For a child that Claude Code placed elsewhere, it has `worktreePath`,
+ * `inheritedWorktreePath` or `cwd`; then the child's working directory is the
+ * `cwd` of its transcript's records. The ids are empty for a session without a local transcript.
  */
 export async function subagentHistory(sessionId: string): Promise<SubagentHistory> {
   const agents = new Map<string, SubagentRecord>();
@@ -67,6 +74,12 @@ export async function subagentHistory(sessionId: string): Promise<SubagentHistor
         > | null;
         if (typeof meta?.toolUseId !== "string") return;
         const text = (value: unknown) => (typeof value === "string" ? value : undefined);
+        const placement = [meta.cwd, meta.worktreePath, meta.inheritedWorktreePath]
+          .map(text)
+          .find((value) => value && path.isAbsolute(value));
+        const cwd = placement
+          ? ((await recordedCwd(path.join(directory, `agent-${match[1]!}.jsonl`))) ?? placement)
+          : undefined;
         agents.set(meta.toolUseId, {
           agentId: match[1]!,
           name: text(meta.name),
@@ -74,6 +87,7 @@ export async function subagentHistory(sessionId: string): Promise<SubagentHistor
           description: text(meta.description),
           background: meta.requestShape === "background",
           stoppedByUser: meta.stoppedByUser === true,
+          ...(cwd ? { cwd } : {}),
         });
       } catch {
         // A damaged meta file leaves its subagent without history.
@@ -87,6 +101,31 @@ export async function subagentHistory(sessionId: string): Promise<SubagentHistor
   return dir ? { agents, dir } : { agents };
 }
 
+/**
+ * The `cwd` of the first record of the transcript `file` that has one, or
+ * undefined when the file cannot be read. Claude Code writes the working
+ * directory of the session or subagent on each record.
+ */
+async function recordedCwd(file: string): Promise<string | undefined> {
+  const stream = createReadStream(file, { encoding: "utf8" });
+  try {
+    for await (const line of readline.createInterface({ input: stream, crlfDelay: Infinity })) {
+      if (!line.includes('"cwd"')) continue;
+      try {
+        const cwd = (JSON.parse(line) as { cwd?: unknown } | null)?.cwd;
+        if (typeof cwd === "string" && path.isAbsolute(cwd)) return cwd;
+      } catch {
+        // A damaged record; a later one can have the `cwd`.
+      }
+    }
+  } catch {
+    // An unreadable transcript; the caller falls back to the metadata's path.
+  } finally {
+    stream.destroy();
+  }
+  return undefined;
+}
+
 /** The folder of the subagent transcripts, next to the session transcript `transcript`. */
 function subagentsDirectory(transcript: string, sessionId: string): string {
   return path.join(path.dirname(transcript), sessionId, "subagents");
@@ -162,6 +201,7 @@ export async function subagentLineage(
       agentId: current,
       launchId: launch.launchId,
       ...(launcher !== null ? { parentAgentId: launcher } : {}),
+      ...(launch.record.cwd ? { cwd: launch.record.cwd } : {}),
       ...(launch.record.name ? { name: launch.record.name } : {}),
       ...(launch.record.agentType ? { agentType: launch.record.agentType } : {}),
       ...(launch.record.description ? { description: launch.record.description } : {}),
@@ -202,7 +242,8 @@ async function readLaunchIdsFromTranscript(
   const stream = createReadStream(file, { encoding: "utf8" });
   try {
     for await (const line of readline.createInterface({ input: stream, crlfDelay: Infinity })) {
-      if (!line.includes('"tool_use"')) continue;
+      const forkDirective = owner !== null && line.includes(FORK_BOILERPLATE_OPEN);
+      if (!line.includes('"tool_use"') && !forkDirective) continue;
       let record: {
         type?: unknown;
         isSidechain?: unknown;
@@ -214,6 +255,13 @@ async function readLaunchIdsFromTranscript(
       } catch {
         continue;
       }
+      // Every record of a fork child's transcript before its directive message
+      // is inherited context: a copy of the launching message, whose launch
+      // calls are the parent's, not the fork's.
+      if (forkDirective && record !== null && isForkDirectiveMessage(record)) {
+        launches.clear();
+        continue;
+      }
       if (record?.type !== "assistant") continue;
       if (
         owner === null
@@ -248,11 +296,72 @@ export async function readSubagentMessages(
   try {
     if (history.dir) {
       const messages = await getSubagentMessages(sessionId, agentId, { dir: history.dir });
-      if (messages.length > 0) return messages;
+      if (messages.length > 0) return stripForkPrefix(messages);
     }
-    return await getSubagentMessages(sessionId, agentId);
+    return stripForkPrefix(await getSubagentMessages(sessionId, agentId));
   } catch (error) {
     logger.error(`Failed to read the history of subagent ${agentId}:`, error);
     return [];
   }
 }
+
+/** How Claude Code opens the directive message of a `subagent_type: "fork"` child. */
+const FORK_BOILERPLATE_OPEN = "<fork-boilerplate>";
+/** What follows the boilerplate, right before the prompt of the Agent call. */
+const FORK_DIRECTIVE_MARKER = "</fork-boilerplate>\nYour directive: ";
+
+/** Whether `block` is the text block of a fork child's directive message. */
+function isForkDirectiveText(block: unknown): block is { type: "text"; text: string } {
+  return (
+    typeof block === "object" &&
+    block !== null &&
+    (block as { type?: unknown }).type === "text" &&
+    typeof (block as { text?: unknown }).text === "string" &&
+    (block as { text: string }).text.startsWith(FORK_BOILERPLATE_OPEN)
+  );
+}
+
+/** Whether the transcript record `message` is the directive message of a fork child. */
+function isForkDirectiveMessage(message: { type?: unknown; message?: unknown }): boolean {
+  if (message.type !== "user") return false;
+  const content = (message.message as { content?: unknown } | null | undefined)?.content;
+  return Array.isArray(content) && content.some(isForkDirectiveText);
+}
+
+/**
+ * The transcript of a `subagent_type: "fork"` child without the context it
+ * inherited. A fork transcript starts with a copy of the parent's launching
+ * assistant message (its text, thinking and every tool_use, including the
+ * Agent call itself), then a user message with a placeholder tool_result for
+ * each of those tool_uses and the text
+ * `<fork-boilerplate>…</fork-boilerplate>\nYour directive: <prompt>`. Since
+ * Claude Code 2.1.307 the fork's own Agent call gets "Fork started — that fork
+ * is you." and the other tool_uses get "This is the parent's call, not
+ * yours. …"; before that, every one got "Fork started — processing in
+ * background". Only the directive text is matched here. A fork
+ * launched from inside a subagent also gets a copy of that subagent's history
+ * before them. None of it is the child's own work: replayed as is, the
+ * parent's text and tool calls would show again in the child.
+ *
+ * This drops every record before the directive message, and reduces that
+ * message to the prompt. Other transcripts are returned unchanged.
+ */
+export function stripForkPrefix(messages: SessionMessage[]): SessionMessage[] {
+  const index = messages.findIndex(isForkDirectiveMessage);
+  if (index === -1) return messages;
+  const directive = messages[index];
+  const content = (directive.message as { content: unknown[] }).content;
+  const prompt = content.flatMap((block) => {
+    if (!isForkDirectiveText(block)) return [];
+    const start = block.text.indexOf(FORK_DIRECTIVE_MARKER);
+    return start === -1
+      ? []
+      : [{ type: "text", text: block.text.slice(start + FORK_DIRECTIVE_MARKER.length) }];
+  });
+  const rest = messages.slice(index + 1);
+  if (prompt.length === 0) return rest;
+  return [
+    { ...directive, message: { ...(directive.message as object), content: prompt } },
+    ...rest,
+  ];
+}

src/subagent-replay.ts

@@ -6,19 +6,50 @@
  * `subagentHistory`). The replay announces each child right after that call,
  * under the session id it had live, the SDK agent id, and sends the child's
  * history to the child session. Every child's end goes out before the replay
- * ends, since no subagent from before the reload still runs.
+ * ends. These states are history to the client, so each child's current
+ * state goes out again after the load response (`currentStates`).
+ *
+ * As live, the parent is not shown the Agent or Task call of a child that the
+ * replay announces: the launch's prompt is the parent's outgoing message, and
+ * a foreground child's answer is its reply to the parent. A child's
+ * successful SubagentHandback call is its message to the parent instead.
+ * Unlike live, the replay does not tell runs apart, so a child that handed
+ * back any report gets no reply from its launch's result.
+ *
+ * A SendMessage call whose message the replay delivered to a child before it
+ * reached the call is that message too: the sender's outgoing view, at the
+ * call, and the child's incoming one, in the child's history. A child's
+ * history follows its launch, so a call to a child from its parent is always
+ * delivered first. Any other SendMessage call stays a tool call.
+ *
+ * Right after its announcement, each child gets its `model` option: the model
+ * of its first response, in its transcript. A later response with another
+ * model sends it again. A child without responses gets none. After the load
+ * response, a model goes again only when the session's model list, which the
+ * replay can lack, maps it to another entry.
  *
  * A launch without metadata has no known id, so it is not announced: the RFD
  * forbids inventing one. Its Agent call stays an ordinary tool call of the
  * parent, and a notice says that subagent history is missing.
  */
+import type { SessionConfigOption } from "@agentclientprotocol/sdk/unstable";
 import type { SessionMessage } from "@anthropic-ai/claude-agent-sdk";
+import { statSync } from "node:fs";
 import type { AcpSessionNotification, SubagentState } from "./acp-subagents.js";
 import {
+  childModelOption,
+  HANDBACK_TOOL,
+  handbackMessage,
   isNativeSubagentControlTool,
+  launchReply,
+  linkedSessionMessages,
+  type ModelEntry,
   nativeSubagentState,
+  responseModelEntry,
   rfdEndState,
   rfdLabels,
+  sameDirectory,
+  type SubagentModels,
   type WorkState,
 } from "./native-subagents.js";
 import { noticeUpdate } from "./session-notices.js";
@@ -42,7 +73,15 @@ export type ReplayChild = {
   /** The state of the child's last persisted task notification. */
   notified?: SubagentState;
   announced: boolean;
+  /** The `cwd` that the replay reported for it; undefined while it inherits its parent's. */
+  cwd?: string;
   promptSent: boolean;
+  /** Whether it handed a report to its parent with a SubagentHandback call. */
+  handedBack?: boolean;
+  /** The `model` option entry that the replay sent. */
+  model?: ModelEntry;
+  /** The model id of the latest response in its transcript. */
+  responseModel?: string;
 };
 
 type SendMessageCall = {
@@ -50,7 +89,12 @@ type SendMessageCall = {
   to: string;
   message: string;
   senderSessionId: string;
-  delivered: boolean;
+  /** The child the replay delivered the message to. */
+  recipientSessionId?: string;
+  /** The replay reached the call before the delivery, so it stays a tool call. */
+  shownAsToolCall: boolean;
+  /** The sender's view of the message went out, at the call. */
+  outgoingSent: boolean;
 };
 
 export class RfdSubagentReplay {
@@ -62,10 +106,24 @@ export class RfdSubagentReplay {
   private readonly omitted = new Set<string>();
   /** Children whose transcript could not be read: only their association is replayed. */
   private withoutHistory = 0;
+  /** The SubagentHandback calls, with their report and whether their result failed. */
+  private readonly handbacks = new Map<
+    string,
+    { message: string; failed: boolean; sent: boolean }
+  >();
 
   constructor(
     private readonly history: SubagentHistory,
     private readonly publish: Publish,
+    private readonly models?: SubagentModels,
+    /**
+     * Whether the replay maps a model to the session's model list as it goes.
+     * A load lacks the list until the CLI started, so it maps only in
+     * {@link currentStates}, after the load response.
+     */
+    private readonly mapsDuringReplay = true,
+    /** The working directory of the root session, which a child inherits unless it reports its own. */
+    private readonly rootCwd?: string,
   ) {}
 
   /**
@@ -78,6 +136,9 @@ export class RfdSubagentReplay {
         if (block.type === "tool_use" && typeof block.id === "string") {
           if (isNativeSubagentControlTool(block.name)) {
             this.registerLaunch(block.id, inputOf(block), ownerSessionId);
+          } else if (block.name === HANDBACK_TOOL) {
+            const message = handbackMessage(block.input);
+            if (message) this.handbacks.set(block.id, { message, failed: false, sent: false });
           } else if (block.name === "SendMessage") {
             const input = inputOf(block);
             if (typeof input.to === "string" && typeof input.message === "string") {
@@ -86,11 +147,14 @@ export class RfdSubagentReplay {
                 to: input.to,
                 message: input.message,
                 senderSessionId: ownerSessionId,
-                delivered: false,
+                shownAsToolCall: false,
+                outgoingSent: false,
               });
             }
           }
         } else if (block.type === "tool_result" && typeof block.tool_use_id === "string") {
+          const handback = this.handbacks.get(block.tool_use_id);
+          if (handback && block.is_error === true) handback.failed = true;
           const child = this.children.get(block.tool_use_id);
           // A background launch answers at once; its result is not the end.
           if (child && !child.record.background) {
@@ -106,14 +170,25 @@ export class RfdSubagentReplay {
     return this.children.get(toolUseId);
   }
 
-  /** Announces `child` on its parent, as live: running, with the parent's labels. */
-  async announce(child: ReplayChild): Promise<void> {
+  /**
+   * Announces `child` on its parent, as live: running, with the parent's
+   * labels, and with its recorded `cwd` when that differs from its parent's.
+   * Then it sends `firstModel`, the model of the child's first response, when
+   * the transcript has one.
+   */
+  async announce(child: ReplayChild, firstModel?: string): Promise<void> {
     if (child.announced) return;
     const labels = rfdLabels(
       child.record.name ?? child.input.name,
       child.record.agentType ?? child.input.subagent_type,
       child.record.description ?? child.input.description,
     );
+    const inherited = this.effectiveCwd(child.parentSessionId);
+    const cwd =
+      child.record.cwd &&
+      (inherited === undefined || !(await sameDirectory(child.record.cwd, inherited)))
+        ? child.record.cwd
+        : undefined;
     await this.publish({
       sessionId: child.parentSessionId,
       update: {
@@ -121,10 +196,51 @@ export class RfdSubagentReplay {
         sessionId: child.sessionId,
         ...(labels.title ? { title: labels.title } : {}),
         ...(labels.description ? { description: labels.description } : {}),
+        ...(cwd ? { cwd } : {}),
         state: { state: "running" },
       },
     });
+    child.cwd = cwd;
     child.announced = true;
+    await this.responseModel(child, firstModel);
+  }
+
+  /**
+   * The working directory of the session `sessionId` as the client holds it:
+   * a child's reported `cwd`, else its parent's, up to the root's.
+   */
+  private effectiveCwd(sessionId: string): string | undefined {
+    const seen = new Set<string>();
+    let child = this.byAgentId.get(sessionId);
+    while (child && !seen.has(child.sessionId)) {
+      if (child.cwd) return child.cwd;
+      seen.add(child.sessionId);
+      child = this.byAgentId.get(child.parentSessionId);
+    }
+    return this.rootCwd;
+  }
+
+  /**
+   * Takes the model of a replayed response of the child `owner`. A child
+   * whose model changes gets its `model` option again.
+   */
+  async responseModel(owner: ReplayChild, model: string | undefined): Promise<void> {
+    const entry = responseModelEntry(model, this.mapsDuringReplay ? this.models : undefined);
+    if (!entry || !owner.announced) return;
+    owner.responseModel = model;
+    await this.sendModel(owner, entry);
+  }
+
+  private async sendModel(child: ReplayChild, model: ModelEntry): Promise<void> {
+    if (child.model?.value === model.value && child.model.name === model.name) return;
+    child.model = model;
+    await this.publish({
+      sessionId: child.sessionId,
+      update: {
+        sessionUpdate: "config_option_update",
+        configOptions: [childModelOption(model)],
+      },
+    });
   }
 
   /**
@@ -167,6 +283,70 @@ export class RfdSubagentReplay {
     }
   }
 
+  /**
+   * Takes a replayed update of a tool call, from the transcript of `owner`
+   * when it is a child's. Returns whether the client is not shown it: an
+   * update of the launch of a child that the replay shows, of a SendMessage
+   * call whose message the replay already delivered, or of a successful
+   * SubagentHandback call of `owner`. A foreground launch's completed result
+   * goes out as the child's reply, a delivered SendMessage as the sender's
+   * outgoing message, and a hand-back as the child's message to its parent.
+   */
+  async toolCallUpdate(
+    update: AcpSessionNotification["update"],
+    owner: ReplayChild | undefined,
+  ): Promise<boolean> {
+    if (update.sessionUpdate !== "tool_call" && update.sessionUpdate !== "tool_call_update") {
+      return false;
+    }
+    const sendMessage = this.sendMessages.find((call) => call.toolUseId === update.toolCallId);
+    if (sendMessage) {
+      if (sendMessage.recipientSessionId === undefined) {
+        sendMessage.shownAsToolCall = true;
+        return false;
+      }
+      if (!sendMessage.outgoingSent) {
+        sendMessage.outgoingSent = true;
+        const [outgoing] = linkedSessionMessages(
+          sendMessage.toolUseId,
+          sendMessage.senderSessionId,
+          sendMessage.recipientSessionId,
+          sendMessage.message,
+        );
+        if (outgoing) await this.publish(outgoing);
+      }
+      return true;
+    }
+    const handback = owner ? this.handbacks.get(update.toolCallId) : undefined;
+    if (owner && handback && !handback.failed) {
+      if (!handback.sent) {
+        handback.sent = true;
+        owner.handedBack = true;
+        for (const view of linkedSessionMessages(
+          update.toolCallId,
+          owner.sessionId,
+          owner.parentSessionId,
+          handback.message,
+        )) {
+          await this.publish(view);
+        }
+      }
+      return true;
+    }
+    const child = this.children.get(update.toolCallId);
+    if (!child) return false;
+    if (
+      update.status === "completed" &&
+      child.announced &&
+      !child.record.background &&
+      !child.handedBack
+    ) {
+      const reply = launchReply(child.launchId, child.sessionId, child.parentSessionId, update);
+      if (reply) await this.publish(reply);
+    }
+    return true;
+  }
+
   /**
    * Takes a persisted task notification. Returns whether it was a child's:
    * its task id is the agent id.
@@ -179,19 +359,19 @@ export class RfdSubagentReplay {
   }
 
   /**
-   * Sends the end of every announced child, and a notice when subagent history
-   * is missing. The end is the state of the child's last task notification,
-   * else `cancelled` for a child the user stopped, else the result of its
-   * foreground launch, else `idle` with no stop reason.
+   * Sends the end of every announced child (see `endState`), and a notice when
+   * subagent history is missing.
    */
   async finish(supportsNotices: boolean, rootSessionId: string): Promise<void> {
     for (const child of [...this.children.values()].reverse()) {
       if (!child.announced) continue;
-      const end = child.notified ?? (child.record.stoppedByUser ? "cancelled" : child.launchEnd);
-      const state: WorkState = end ? rfdEndState(end, undefined) : { state: "idle" };
       await this.publish({
         sessionId: child.parentSessionId,
-        update: { sessionUpdate: "subagent_update", sessionId: child.sessionId, state },
+        update: {
+          sessionUpdate: "subagent_update",
+          sessionId: child.sessionId,
+          state: endState(child),
+        },
       });
     }
     const missing = this.omitted.size + this.withoutHistory;
@@ -210,6 +390,61 @@ export class RfdSubagentReplay {
     }
   }
 
+  /**
+   * The current state of each announced child, to send after the load
+   * response. The RFD makes that response the freshness boundary: a client
+   * treats the replayed states before it as history, so they show no current
+   * activity and allow no cancel.
+   *
+   * `live` gives the work state of a child that still runs in this process, as
+   * when a live session is loaded again. Such a child reports that state and
+   * can be cancelled, as live. Any other child cannot be running, because the
+   * process that ran it is gone, so its replayed end is its current state.
+   *
+   * A replayed `cwd` whose directory is gone, such as a worktree that Claude
+   * Code removed when the child finished, is cleared with `cwd: null`, as the
+   * RFD requires after a reconnection.
+   */
+  currentStates(
+    live: (sessionId: string) => WorkState["state"] | undefined,
+    liveConfiguration?: (sessionId: string) => SessionConfigOption[] | undefined,
+  ): AcpSessionNotification[] {
+    return [...this.children.values()]
+      .filter((child) => child.announced)
+      .flatMap((child): AcpSessionNotification[] => {
+        const liveState = live(child.sessionId);
+        const state: WorkState =
+          liveState === undefined || liveState === "idle" ? endState(child) : { state: liveState };
+        // The session's model list may be known only now, after the load response.
+        const entry = responseModelEntry(child.responseModel, this.models);
+        const replayed = child.model ? JSON.stringify([childModelOption(child.model)]) : undefined;
+        const current =
+          liveConfiguration?.(child.sessionId) ?? (entry ? [childModelOption(entry)] : undefined);
+        // A configuration that the replay already sent does not go again.
+        const configOptions = current && JSON.stringify(current) !== replayed ? current : undefined;
+        return [
+          {
+            sessionId: child.parentSessionId,
+            update: {
+              sessionUpdate: "subagent_update",
+              sessionId: child.sessionId,
+              ...(liveState !== undefined ? { capabilities: { cancel: {} } } : {}),
+              ...(child.cwd && !isDirectory(child.cwd) ? { cwd: null } : {}),
+              state,
+            },
+          },
+          ...(configOptions
+            ? [
+                {
+                  sessionId: child.sessionId,
+                  update: { sessionUpdate: "config_option_update" as const, configOptions },
+                },
+              ]
+            : []),
+        ];
+      });
+  }
+
   private registerLaunch(
     toolUseId: string,
     input: Record<string, unknown>,
@@ -234,10 +469,17 @@ export class RfdSubagentReplay {
     this.byAgentId.set(record.agentId, child);
   }
 
-  /** The prompt of the launch, with the launch's id, as live. */
+  /** The prompt of the launch, with the launch's id, to the parent and the child, as live. */
   private async sendPrompt(child: ReplayChild, text: string): Promise<void> {
     child.promptSent = true;
-    await this.sendMessage(child, child.launchId, text, child.parentSessionId);
+    for (const view of linkedSessionMessages(
+      child.launchId,
+      child.parentSessionId,
+      child.sessionId,
+      text,
+    )) {
+      await this.publish(view);
+    }
   }
 
   /**
@@ -247,6 +489,9 @@ export class RfdSubagentReplay {
    * first undelivered SendMessage to the child whose message the delivered
    * text contains. With that call, the message has the call's id and text and
    * its sender, as live; without it, its transcript id and the delivered text.
+   * Unless the replay already showed the call as a tool call, the message
+   * replaces it, so this view names the sender's view, which goes out at the
+   * call (see {@link toolCallUpdate}).
    */
   private async sendDelivery(
     child: ReplayChild,
@@ -256,13 +501,15 @@ export class RfdSubagentReplay {
     const names = [child.sessionId, child.record.name, child.input.name];
     const call = this.sendMessages.find(
       (candidate) =>
-        !candidate.delivered &&
+        candidate.recipientSessionId === undefined &&
         names.includes(candidate.to) &&
         text.includes(candidate.message.trim()),
     );
     if (call) {
-      call.delivered = true;
-      await this.sendMessage(child, call.toolUseId, call.message, call.senderSessionId);
+      call.recipientSessionId = child.sessionId;
+      await this.sendMessage(child, call.toolUseId, call.message, call.senderSessionId, {
+        linked: !call.shownAsToolCall,
+      });
     } else {
       await this.sendMessage(child, message.uuid, text, undefined);
     }
@@ -273,6 +520,7 @@ export class RfdSubagentReplay {
     messageId: string,
     text: string,
     sender: string | undefined,
+    { linked = false }: { linked?: boolean } = {},
   ): Promise<void> {
     await this.publish({
       sessionId: child.sessionId,
@@ -281,12 +529,23 @@ export class RfdSubagentReplay {
         messageId,
         ...(sender ? { senderSessionId: sender } : {}),
         recipientSessionId: child.sessionId,
+        ...(linked ? { senderMessageId: messageId } : {}),
         content: [{ type: "text", text }],
       },
     });
   }
 }
 
+/** The model of the first response in `messages`, a subagent's transcript. */
+export function firstResponseModel(messages: readonly SessionMessage[]): string | undefined {
+  for (const message of messages) {
+    if (message.type !== "assistant") continue;
+    const model = (message.message as { model?: unknown } | undefined)?.model;
+    if (typeof model === "string" && model && model !== "<synthetic>") return model;
+  }
+  return undefined;
+}
+
 /**
  * The end of a foreground launch from its tool result: an error result that
  * names a stop is a cancellation, any other error a failure.
@@ -301,6 +560,16 @@ export function replaySubagentTerminalState(
     : "failed";
 }
 
+/**
+ * How `child`'s work ended: the state of its last task notification, else
+ * `cancelled` for a child the user stopped, else the result of its foreground
+ * launch, else `idle` with no stop reason.
+ */
+function endState(child: ReplayChild): WorkState {
+  const end = child.notified ?? (child.record.stoppedByUser ? "cancelled" : child.launchEnd);
+  return end ? rfdEndState(end, undefined) : { state: "idle" };
+}
+
 function replayContentText(value: unknown, seen = new Set<unknown>()): string {
   if (typeof value === "string") return value;
   if (typeof value !== "object" || value === null || seen.has(value)) return "";
@@ -340,6 +609,15 @@ function textOf(content: unknown): string {
     .join("\n");
 }
 
+/** Whether `dir` is an existing directory. */
+function isDirectory(dir: string): boolean {
+  try {
+    return statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 /** A message that a SendMessage call delivered to the child. */
 function isDelivery(message: SessionMessage): boolean {
   return (message as { origin?: { kind?: unknown } | null }).origin?.kind === "coordinator";

src/task-notifications.ts

@@ -0,0 +1,75 @@
+/**
+ * The `<task-notification>` inputs that Claude Code writes to a transcript
+ * when a background task stops. The replay of a session (`acp-agent.ts`) and
+ * the session index (`session-index/background-tasks.ts`) read them here, so
+ * both read the same fields.
+ */
+
+export const TASK_NOTIFICATION_TAG = "task-notification";
+
+/** The text between the first `<tag>` and the next `</tag>` after it. */
+export function markerTagText(text: string, tag: string): string | undefined {
+  const open = `<${tag}>`;
+  const close = `</${tag}>`;
+  const start = text.indexOf(open);
+  if (start === -1) return undefined;
+  const end = text.indexOf(close, start + open.length);
+  if (end === -1) return undefined;
+  return text.slice(start + open.length, end);
+}
+
+/** The fields of a persisted `<task-notification>`, in the shape of the SDK
+ *  `task_notification` frame that reported the same stop live. */
+export type PersistedTaskNotification = {
+  task_id: string;
+  status: string;
+  tool_use_id?: string;
+  summary?: string;
+  output_file?: string;
+};
+
+/**
+ * Returns each `<task-notification>` in user-message content (a string or its
+ * text blocks). The `<result>` body is model context that the live frame does
+ * not carry, so the scan stops at it and a tag quoted in it cannot match.
+ *
+ * Only a notification with a `<task-id>` and a `<status>` is returned. A
+ * notification without a status comes while its task still runs: the
+ * check-in of a quiet shell ("is still running after …") or a `Monitor`
+ * event.
+ */
+export function taskNotificationsOf(content: unknown): PersistedTaskNotification[] {
+  const texts =
+    typeof content === "string"
+      ? [content]
+      : Array.isArray(content)
+        ? content.flatMap((block) =>
+            block?.type === "text" && typeof block.text === "string" ? [block.text as string] : [],
+          )
+        : [];
+  const open = `<${TASK_NOTIFICATION_TAG}>`;
+  const close = `</${TASK_NOTIFICATION_TAG}>`;
+  const notifications: PersistedTaskNotification[] = [];
+  for (const text of texts) {
+    let start = text.indexOf(open);
+    while (start !== -1) {
+      const end = text.indexOf(close, start + open.length);
+      if (end === -1) break;
+      const body = text.slice(start + open.length, end).split("<result>", 1)[0];
+      const field = (tag: string) => markerTagText(body, tag)?.trim() || undefined;
+      const taskId = field("task-id");
+      const status = field("status");
+      if (taskId && status) {
+        notifications.push({
+          task_id: taskId,
+          status,
+          tool_use_id: field("tool-use-id"),
+          summary: field("summary"),
+          output_file: field("output-file"),
+        });
+      }
+      start = text.indexOf(open, end + close.length);
+    }
+  }
+  return notifications;
+}

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

@@ -42,6 +42,7 @@ describe("ClaudeAcpAgent settings", () => {
               value: "claude-sonnet-4-6",
               displayName: "Claude Sonnet 4.5",
               description: "Default",
+              supportsAutoMode: true,
             },
           ],
         }),
@@ -284,7 +285,7 @@ describe("ClaudeAcpAgent settings", () => {
 
   it("drops escalating defaultMode when it comes from project-tier settings", async () => {
     // bypassPermissions in .claude/settings.json (a repo-committed tier) is
-    // filtered by the SDK's trust policy and clamps to 'default'.
+    // filtered by the SDK's trust policy, so the built-in default applies.
     const projectDir = path.join(tempDir, "project");
     await fs.promises.mkdir(path.join(projectDir, ".claude"), { recursive: true });
     await fs.promises.writeFile(
@@ -303,8 +304,8 @@ describe("ClaudeAcpAgent settings", () => {
       _meta: { disableBuiltInTools: true },
     });
 
-    expect(getCapturedOptions().permissionMode).toBe("default");
-    expect(response.modes.currentModeId).toBe("default");
+    expect(getCapturedOptions().permissionMode).toBe("auto");
+    expect(response.modes.currentModeId).toBe("auto");
   });
 
   it("honors the host opt-out from bypassPermissions", async () => {
@@ -380,7 +381,7 @@ describe("ClaudeAcpAgent settings", () => {
     },
   );
 
-  it("defaults to 'default' when no permissions.defaultMode is set", async () => {
+  it("defaults to 'auto' when no permissions.defaultMode is set", async () => {
     const projectDir = path.join(tempDir, "project");
     await fs.promises.mkdir(projectDir, { recursive: true });
 
@@ -395,8 +396,37 @@ describe("ClaudeAcpAgent settings", () => {
       _meta: { disableBuiltInTools: true },
     });
 
-    expect(getCapturedOptions().permissionMode).toBe("default");
+    expect(getCapturedOptions().permissionMode).toBe("auto");
+    expect(response.modes.currentModeId).toBe("auto");
+  });
+
+  it.each([
+    { name: "top-level disableAutoMode", settings: { disableAutoMode: "disable" } },
+    {
+      name: "permissions.disableAutoMode with defaultMode 'auto'",
+      settings: { permissions: { disableAutoMode: "disable", defaultMode: "auto" } },
+    },
+  ])("starts in 'default' without Auto in the catalog for $name", async ({ settings }) => {
+    await fs.promises.writeFile(path.join(tempDir, "settings.json"), JSON.stringify(settings));
+    const projectDir = path.join(tempDir, "project");
+    await fs.promises.mkdir(projectDir, { recursive: true });
+
+    mockQuery();
+
+    const { ClaudeAcpAgent } = await import("../acp-agent.js");
+    const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+    (agent as any).logger = { log: () => {}, error: () => {} };
+
+    const response = await (agent as any).createSession({
+      cwd: projectDir,
+      mcpServers: [],
+      _meta: { disableBuiltInTools: true },
+    });
+
     expect(response.modes.currentModeId).toBe("default");
+    expect(response.modes.availableModes.map((mode: { id: string }) => mode.id)).not.toContain(
+      "auto",
+    );
   });
 
   describe("on resume", () => {
@@ -464,6 +494,16 @@ describe("ClaudeAcpAgent settings", () => {
       expect(response.modes.currentModeId).toBe("plan");
     });
 
+    it("uses the available configured mode when the restored mode is not in the catalog", async () => {
+      const { permissionMode, response } = await resume([user("dontAsk")]);
+
+      expect(permissionMode).toBe("plan");
+      expect(response.modes.currentModeId).toBe("plan");
+      expect(response.configOptions.find((option: any) => option.id === "mode").currentValue).toBe(
+        "plan",
+      );
+    });
+
     it("uses permissions.defaultMode when bypass is not available now", async () => {
       const { permissionMode, response } = await resume([user("bypassPermissions")], {
         claudeCode: { options: { allowDangerouslySkipPermissions: false } },
@@ -515,27 +555,28 @@ describe("ClaudeAcpAgent settings", () => {
         _meta: { disableBuiltInTools: true },
       });
       await agent.setSessionMode({ sessionId, modeId: "default" });
-      const { RequestError } = await import("@agentclientprotocol/sdk");
+      const { RequestError } = await import("@agentclientprotocol/sdk/unstable");
       const createSession = (agent as any).createSession.bind(agent);
       const creations: object[] = [];
       (agent as any).createSession = async (params: object, options: { resume?: string }) => {
         creations.push(options);
         // The CLI never wrote the conversation, so the resume fails.
-        if (options.resume) throw RequestError.resourceNotFound(sessionId);
+        if (options.resume) throw RequestError.sessionNotFound(sessionId);
         return createSession(params, options);
       };
 
-      await (agent as any).recreateSignedOutQuery(sessionId, (agent as any).sessions[sessionId]);
+      const husk = (agent as any).sessions[sessionId];
+      await (agent as any).recreateSignedOutQuery(sessionId, husk);
 
       expect(creations).toEqual([
-        { resume: sessionId, permissionMode: "default" },
-        { reuseSessionId: sessionId, permissionMode: "default" },
+        { resume: sessionId, permissionMode: "default", replacingSession: husk },
+        { reuseSessionId: sessionId, permissionMode: "default", replacingSession: husk },
       ]);
       expect(getCapturedOptions().permissionMode).toBe("default");
     });
   });
 
-  it("falls back to 'default' when permissions.defaultMode is invalid", async () => {
+  it("falls back to the built-in default when permissions.defaultMode is invalid", async () => {
     await fs.promises.writeFile(
       path.join(tempDir, "settings.json"),
       JSON.stringify({
@@ -559,9 +600,9 @@ describe("ClaudeAcpAgent settings", () => {
       _meta: { disableBuiltInTools: true },
     });
 
-    // Bad mode is ignored at the usage site; session creation must not throw.
-    expect(getCapturedOptions().permissionMode).toBe("default");
-    expect(response.modes.currentModeId).toBe("default");
+    // Settings resolution drops the bad mode; session creation must not throw.
+    expect(getCapturedOptions().permissionMode).toBe("auto");
+    expect(response.modes.currentModeId).toBe("auto");
   });
 
   it("ignores model from settings when it is not a string", async () => {
@@ -703,6 +744,30 @@ describe("ClaudeAcpAgent settings", () => {
       expect(modeIds).not.toContain("dontAsk");
     });
 
+    it("starts the built-in Auto default in Manual on an unsupported model", async () => {
+      const projectDir = path.join(tempDir, "project");
+      await fs.promises.mkdir(projectDir, { recursive: true });
+
+      const { setPermissionModeSpy } = mockQueryWithModels([
+        { value: "claude-haiku-4-5", displayName: "Claude Haiku", description: "Fast" },
+      ]);
+
+      const { ClaudeAcpAgent } = await import("../acp-agent.js");
+      const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(createMockClient());
+
+      const response = await (agent as any).createSession({
+        cwd: projectDir,
+        mcpServers: [],
+        _meta: { disableBuiltInTools: true },
+      });
+
+      expect(setPermissionModeSpy).toHaveBeenCalledWith("default");
+      expect(response.modes.currentModeId).toBe("default");
+      expect((agent as any).sessions[response.sessionId].autoModeFallbackWarningPending).toBe(
+        false,
+      );
+    });
+
     it("falls back permissions.defaultMode='auto' to Accept edits on an unsupported model", async () => {
       await fs.promises.writeFile(
         path.join(tempDir, "settings.json"),

src/tests/acp-scenarios-v2.test.ts

@@ -37,6 +37,7 @@ vi.mock("@anthropic-ai/claude-agent-sdk", async (importOriginal) => {
     ...actual,
     query: harness.mockedQuery,
     getSessionMessages: harness.mockedSessionMessages,
+    getSessionInfo: harness.mockedSessionInfo,
   };
 });
 

src/tests/acp-scenarios/__snapshots__/air/network-permission.jsonl

@@ -1,4 +1,5 @@
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"claudeCode":{"toolName":"SandboxNetworkAccess"}},"content":[],"kind":"other","name":"SandboxNetworkAccess","rawInput":{"host":"example.com"},"sessionUpdate":"tool_call","status":"pending","title":"SandboxNetworkAccess","toolCallId":"toolu_net"}}}
 {"kind":"requestPermission","payload":{"_meta":{"jetbrains":{"air":{"permission":{"description":"Reason: Sandbox blocks network","title":"example.com","version":1},"version":1}}},"options":[{"kind":"allow_once","name":"Yes","optionId":"allow-once"},{"kind":"reject_once","name":"No","optionId":"reject"}],"sessionId":"<session>","toolCall":{"rawInput":{"host":"example.com"},"title":"example.com","toolCallId":"toolu_net"}}}
+{"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"sessionUpdate":"tool_call_update","status":"completed","toolCallId":"toolu_net"}}}
 {"kind":"promptResponse","payload":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}

src/tests/acp-scenarios/__snapshots__/air/session-load-replay.jsonl

@@ -1,4 +1,4 @@
-{"kind":"initialize","payload":{"_meta":{"jetbrains":{"air":{"capabilities":["sessionFailure","agentFileChangeReport","nativeSubagentSessions","asyncTasks","customInstructions","recommendedValue","diffPatch","planFile"],"goal":{"actions":["set","clear"],"controlMethod":"_session/goal","version":1},"version":1}},"steering":{"supported":true}},"agentCapabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"auth":{"logout":{}},"loadSession":true,"mcpCapabilities":{"http":true,"sse":true},"promptCapabilities":{"embeddedContext":true,"image":true},"providers":{},"sessionCapabilities":{"additionalDirectories":{},"close":{},"delete":{},"fork":{},"list":{},"resume":{},"subagents":{},"systemPrompt":{"mode":{"override":{}}}}},"agentInfo":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"authMethods":[],"protocolVersion":1}}
+{"kind":"initialize","payload":{"_meta":{"jetbrains":{"air":{"capabilities":["sessionFailure","agentFileChangeReport","nativeSubagentSessions","asyncTasks","customInstructions","recommendedValue","diffPatch","planFile","backgroundSubagents"],"goal":{"actions":["set","clear"],"controlMethod":"_session/goal","version":1},"version":1}},"steering":{"supported":true}},"agentCapabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"auth":{"logout":{}},"loadSession":true,"mcpCapabilities":{"http":true,"sse":true},"promptCapabilities":{"embeddedContext":true,"image":true},"providers":{},"sessionCapabilities":{"additionalDirectories":{},"close":{},"delete":{},"fork":{},"list":{},"resume":{},"subagents":{},"systemPrompt":{"mode":{"override":{}}}}},"agentInfo":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"authMethods":[],"protocolVersion":1}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"content":{"text":"Fix the bug","type":"text"},"messageId":"00000000-0000-4000-8000-00000000c001","sessionUpdate":"user_message_chunk"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"content":{"text":"Check the file.","type":"text"},"messageId":"msg_r1","sessionUpdate":"agent_thought_chunk"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"content":{"text":"I will edit it.","type":"text"},"messageId":"msg_r1","sessionUpdate":"agent_message_chunk"}}}
@@ -8,8 +8,10 @@
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"terminal_output_delta":{"data":"app.ts","terminal_id":"toolu_r_bash"}},"sessionUpdate":"tool_call_update","toolCallId":"toolu_r_bash"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"terminal_exit":{"exit_code":0,"signal":null,"terminal_id":"toolu_r_bash"}},"sessionUpdate":"tool_call_update","status":"completed","toolCallId":"toolu_r_bash"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"rawOutput":"The file <cwd>/src/app.ts has been updated successfully.","sessionUpdate":"tool_call_update","status":"completed","toolCallId":"toolu_r_edit"}}}
+{"kind":"sessionUpdate","payload":{"sessionId":"<session>:replay-subagent:toolu_r_task","update":{"configOptions":[{"category":"model","currentValue":"claude-sonnet-4-6","id":"model","name":"Model","options":[{"name":"claude-sonnet-4-6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionUpdate":"config_option_update"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>:replay-subagent:toolu_r_task","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_r_task"}},"content":{"text":"Subagent text.","type":"text"},"messageId":"msg_r_sub","sessionUpdate":"agent_message_chunk"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"content":{"text":"Fixed.","type":"text"},"messageId":"msg_r2","sessionUpdate":"agent_message_chunk"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"sessionUpdate":"subagent_state_update","state":"completed","subagentSessionId":"<session>:replay-subagent:toolu_r_task"}}}
-{"kind":"loadSession","payload":{"configOptions":[{"category":"mode","currentValue":"default","description":"Session permission mode","id":"mode","name":"Mode","options":[{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Always ask before making changes","name":"Manual","value":"default"},{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"_meta":{"jetbrains":{"air":{"kind":"plan","version":1}}},"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"_meta":{"jetbrains":{"air":{"kind":"auto_review","version":1}}},"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"_meta":{"jetbrains":{"air":{"kind":"full_access","version":1}}},"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","id":"model","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"modes":{"availableModes":[{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Always ask before making changes","id":"default","name":"Manual"},{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Automatically accept all file edits","id":"acceptEdits","name":"Accept edits"},{"_meta":{"jetbrains":{"air":{"kind":"plan","version":1}}},"description":"Create a plan before making changes","id":"plan","name":"Plan"},{"_meta":{"jetbrains":{"air":{"kind":"auto_review","version":1}}},"description":"Claude handles permission decisions","id":"auto","name":"Auto"},{"_meta":{"jetbrains":{"air":{"kind":"full_access","version":1}}},"description":"Accepts all permissions","id":"bypassPermissions","name":"Bypass permissions"}],"currentModeId":"default"},"sessionId":"<session>"}}
+{"kind":"loadSession","payload":{"configOptions":[{"category":"mode","currentValue":"auto","description":"Session permission mode","id":"mode","name":"Mode","options":[{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Always ask before making changes","name":"Manual","value":"default"},{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"_meta":{"jetbrains":{"air":{"kind":"plan","version":1}}},"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"_meta":{"jetbrains":{"air":{"kind":"auto_review","version":1}}},"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"_meta":{"jetbrains":{"air":{"kind":"full_access","version":1}}},"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","id":"model","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"modes":{"availableModes":[{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Always ask before making changes","id":"default","name":"Manual"},{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Automatically accept all file edits","id":"acceptEdits","name":"Accept edits"},{"_meta":{"jetbrains":{"air":{"kind":"plan","version":1}}},"description":"Create a plan before making changes","id":"plan","name":"Plan"},{"_meta":{"jetbrains":{"air":{"kind":"auto_review","version":1}}},"description":"Claude handles permission decisions","id":"auto","name":"Auto"},{"_meta":{"jetbrains":{"air":{"kind":"full_access","version":1}}},"description":"Accepts all permissions","id":"bypassPermissions","name":"Bypass permissions"}],"currentModeId":"auto"},"sessionId":"<session>"}}
+{"kind":"sessionUpdate","payload":{"sessionId":"<session>:replay-subagent:toolu_r_task","update":{"configOptions":[{"category":"model","currentValue":"claude-sonnet-4-6","id":"model","name":"Model","options":[{"name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionUpdate":"config_option_update"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}

src/tests/acp-scenarios/__snapshots__/air/session-setup.jsonl

@@ -1,3 +1,3 @@
-{"kind":"initialize","payload":{"_meta":{"jetbrains":{"air":{"capabilities":["sessionFailure","agentFileChangeReport","nativeSubagentSessions","asyncTasks","customInstructions","recommendedValue","diffPatch","planFile"],"goal":{"actions":["set","clear"],"controlMethod":"_session/goal","version":1},"version":1}},"steering":{"supported":true}},"agentCapabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"auth":{"logout":{}},"loadSession":true,"mcpCapabilities":{"http":true,"sse":true},"promptCapabilities":{"embeddedContext":true,"image":true},"providers":{},"sessionCapabilities":{"additionalDirectories":{},"close":{},"delete":{},"fork":{},"list":{},"resume":{},"subagents":{},"systemPrompt":{"mode":{"override":{}}}}},"agentInfo":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"authMethods":[],"protocolVersion":1}}
-{"kind":"newSession","payload":{"configOptions":[{"category":"mode","currentValue":"default","description":"Session permission mode","id":"mode","name":"Mode","options":[{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Always ask before making changes","name":"Manual","value":"default"},{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"_meta":{"jetbrains":{"air":{"kind":"plan","version":1}}},"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"_meta":{"jetbrains":{"air":{"kind":"auto_review","version":1}}},"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"_meta":{"jetbrains":{"air":{"kind":"full_access","version":1}}},"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","id":"model","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"modes":{"availableModes":[{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Always ask before making changes","id":"default","name":"Manual"},{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Automatically accept all file edits","id":"acceptEdits","name":"Accept edits"},{"_meta":{"jetbrains":{"air":{"kind":"plan","version":1}}},"description":"Create a plan before making changes","id":"plan","name":"Plan"},{"_meta":{"jetbrains":{"air":{"kind":"auto_review","version":1}}},"description":"Claude handles permission decisions","id":"auto","name":"Auto"},{"_meta":{"jetbrains":{"air":{"kind":"full_access","version":1}}},"description":"Accepts all permissions","id":"bypassPermissions","name":"Bypass permissions"}],"currentModeId":"default"},"sessionId":"<session>"}}
+{"kind":"initialize","payload":{"_meta":{"jetbrains":{"air":{"capabilities":["sessionFailure","agentFileChangeReport","nativeSubagentSessions","asyncTasks","customInstructions","recommendedValue","diffPatch","planFile","backgroundSubagents"],"goal":{"actions":["set","clear"],"controlMethod":"_session/goal","version":1},"version":1}},"steering":{"supported":true}},"agentCapabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"auth":{"logout":{}},"loadSession":true,"mcpCapabilities":{"http":true,"sse":true},"promptCapabilities":{"embeddedContext":true,"image":true},"providers":{},"sessionCapabilities":{"additionalDirectories":{},"close":{},"delete":{},"fork":{},"list":{},"resume":{},"subagents":{},"systemPrompt":{"mode":{"override":{}}}}},"agentInfo":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"authMethods":[],"protocolVersion":1}}
+{"kind":"newSession","payload":{"configOptions":[{"category":"mode","currentValue":"auto","description":"Session permission mode","id":"mode","name":"Mode","options":[{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Always ask before making changes","name":"Manual","value":"default"},{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"_meta":{"jetbrains":{"air":{"kind":"plan","version":1}}},"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"_meta":{"jetbrains":{"air":{"kind":"auto_review","version":1}}},"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"_meta":{"jetbrains":{"air":{"kind":"full_access","version":1}}},"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","id":"model","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"modes":{"availableModes":[{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Always ask before making changes","id":"default","name":"Manual"},{"_meta":{"jetbrains":{"air":{"kind":"standard","version":1}}},"description":"Automatically accept all file edits","id":"acceptEdits","name":"Accept edits"},{"_meta":{"jetbrains":{"air":{"kind":"plan","version":1}}},"description":"Create a plan before making changes","id":"plan","name":"Plan"},{"_meta":{"jetbrains":{"air":{"kind":"auto_review","version":1}}},"description":"Claude handles permission decisions","id":"auto","name":"Auto"},{"_meta":{"jetbrains":{"air":{"kind":"full_access","version":1}}},"description":"Accepts all permissions","id":"bypassPermissions","name":"Bypass permissions"}],"currentModeId":"auto"},"sessionId":"<session>"}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]"},"name":"mcp"}],"sessionUpdate":"available_commands_update"}}}

src/tests/acp-scenarios/__snapshots__/air/subagent-agent-async.jsonl

@@ -2,6 +2,7 @@
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":3}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"capabilities":{},"name":"Background review","prompt":"Review the diff","sessionUpdate":"subagent_spawned","subagentSessionId":"a2","task":"Review the diff"}}}
+{"kind":"sessionUpdate","payload":{"sessionId":"a2","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_agent"}},"configOptions":[{"category":"model","currentValue":"claude-sonnet-4-6","id":"model","name":"Model","options":[{"name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionUpdate":"config_option_update"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"a2","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_agent"}},"content":{"text":"Reviewi","type":"text"},"messageId":"msg_async_sub","sessionUpdate":"agent_message_chunk"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"a2","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_agent"}},"content":{"text":"ng now.","type":"text"},"messageId":"msg_async_sub","sessionUpdate":"agent_message_chunk"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"sessionUpdate":"subagent_state_update","state":"completed","subagentSessionId":"a2"}}}

src/tests/acp-scenarios/__snapshots__/air/subagent-late-child-update.jsonl

@@ -2,6 +2,7 @@
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":3}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"capabilities":{},"name":"Check the logs","prompt":"Check logs","sessionUpdate":"subagent_spawned","subagentSessionId":"agent_late","task":"Check logs"}}}
+{"kind":"sessionUpdate","payload":{"sessionId":"agent_late","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_late"}},"configOptions":[{"category":"model","currentValue":"claude-sonnet-4-6","id":"model","name":"Model","options":[{"name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionUpdate":"config_option_update"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"agent_late","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_late","toolName":"Read"}},"content":[],"kind":"read","locations":[],"name":"Read","sessionUpdate":"tool_call","status":"pending","title":"Read File","toolCallId":"toolu_late_read"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"agent_late","update":{"locations":[{"line":1,"path":"/var/log/app.log"}],"rawInput":{"file_path":"/var/log/app.log"},"sessionUpdate":"tool_call_update","title":"Read /var/log/app.log","toolCallId":"toolu_late_read"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"sessionUpdate":"subagent_state_update","state":"completed","subagentSessionId":"agent_late"}}}

src/tests/acp-scenarios/__snapshots__/air/subagent-native-sessions.jsonl

@@ -2,6 +2,7 @@
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":3}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"capabilities":{},"name":"Fix the build","prompt":"Make the build pass","sessionUpdate":"subagent_spawned","subagentSessionId":"agent_n","task":"Make the build pass"}}}
+{"kind":"sessionUpdate","payload":{"sessionId":"agent_n","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_native"}},"configOptions":[{"category":"model","currentValue":"claude-sonnet-4-6","id":"model","name":"Model","options":[{"name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionUpdate":"config_option_update"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"agent_n","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_native"}},"content":{"text":"Running t","type":"text"},"messageId":"msg_native_sub_1","sessionUpdate":"agent_message_chunk"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"agent_n","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_native"}},"content":{"text":"he build.","type":"text"},"messageId":"msg_native_sub_1","sessionUpdate":"agent_message_chunk"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"agent_n","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_native","toolName":"Grep"}},"content":[],"kind":"search","name":"Grep","sessionUpdate":"tool_call","status":"pending","title":"grep","toolCallId":"toolu_native_grep"}}}

src/tests/acp-scenarios/__snapshots__/air/subagent-nested.jsonl

@@ -2,7 +2,9 @@
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":3}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"capabilities":{},"name":"Plan the work","prompt":"Plan it","sessionUpdate":"subagent_spawned","subagentSessionId":"agent_outer","task":"Plan it"}}}
+{"kind":"sessionUpdate","payload":{"sessionId":"agent_outer","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_outer"}},"configOptions":[{"category":"model","currentValue":"claude-sonnet-4-6","id":"model","name":"Model","options":[{"name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionUpdate":"config_option_update"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"agent_outer","update":{"capabilities":{},"name":"Read the spec","prompt":"Read spec.md","sessionUpdate":"subagent_spawned","subagentSessionId":"agent_inner","task":"Read spec.md"}}}
+{"kind":"sessionUpdate","payload":{"sessionId":"agent_inner","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_inner"}},"configOptions":[{"category":"model","currentValue":"claude-sonnet-4-6","id":"model","name":"Model","options":[{"name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionUpdate":"config_option_update"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"agent_inner","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_inner","toolName":"Read"}},"content":[],"kind":"read","locations":[],"name":"Read","sessionUpdate":"tool_call","status":"pending","title":"Read File","toolCallId":"toolu_grandchild_read"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"agent_inner","update":{"locations":[{"line":1,"path":"/spec.md"}],"rawInput":{"file_path":"/spec.md"},"sessionUpdate":"tool_call_update","title":"Read /spec.md","toolCallId":"toolu_grandchild_read"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"agent_inner","update":{"sessionUpdate":"tool_call_update","status":"completed","toolCallId":"toolu_grandchild_read"}}}

src/tests/acp-scenarios/__snapshots__/air/subagent-task-legacy.jsonl

@@ -2,6 +2,7 @@
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":3}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"capabilities":{},"name":"Explore code","prompt":"Find the parser","sessionUpdate":"subagent_spawned","subagentSessionId":"agent_1","task":"Find the parser"}}}
+{"kind":"sessionUpdate","payload":{"sessionId":"agent_1","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_task"}},"configOptions":[{"category":"model","currentValue":"claude-sonnet-4-6","id":"model","name":"Model","options":[{"name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionUpdate":"config_option_update"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"agent_1","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_task"}},"content":{"text":"Looking for","type":"text"},"messageId":"msg_sub_1","sessionUpdate":"agent_message_chunk"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"agent_1","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_task"}},"content":{"text":" the parser.","type":"text"},"messageId":"msg_sub_1","sessionUpdate":"agent_message_chunk"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"agent_1","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_task","toolName":"Read"}},"content":[],"kind":"read","locations":[],"name":"Read","sessionUpdate":"tool_call","status":"pending","title":"Read File","toolCallId":"toolu_sub_read"}}}

src/tests/acp-scenarios/__snapshots__/air/subagent-transcript-extension.jsonl

@@ -2,6 +2,7 @@
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":3}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"<session>","update":{"capabilities":{},"name":"Summarize","prompt":"Summarize the repo","sessionUpdate":"subagent_spawned","subagentSessionId":"agent_t","task":"Summarize the repo"}}}
+{"kind":"sessionUpdate","payload":{"sessionId":"agent_t","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_transcript"}},"configOptions":[{"category":"model","currentValue":"claude-sonnet-4-6","id":"model","name":"Model","options":[{"name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionUpdate":"config_option_update"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"agent_t","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_transcript"}},"content":{"text":"Look at t","type":"text"},"messageId":"msg_transcript_sub","sessionUpdate":"agent_thought_chunk"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"agent_t","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_transcript"}},"content":{"text":"he layout.","type":"text"},"messageId":"msg_transcript_sub","sessionUpdate":"agent_thought_chunk"}}}
 {"kind":"sessionUpdate","payload":{"sessionId":"agent_t","update":{"_meta":{"claudeCode":{"parentToolUseId":"toolu_transcript"}},"content":{"text":"The repo has ","type":"text"},"messageId":"msg_transcript_sub","sessionUpdate":"agent_message_chunk"}}}

src/tests/acp-scenarios/__snapshots__/v2/ask-user-question.jsonl

@@ -1,15 +1,15 @@
 {"kind":"response","method":"initialize","payload":{"authMethods":[],"capabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"providers":{},"session":{"additionalDirectories":{},"delete":{},"fork":{},"mcp":{"http":{},"stdio":{}},"prompt":{"embeddedContext":{},"image":{}},"systemPrompt":{"mode":{"override":{}}}}},"info":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"protocolVersion":2}}
-{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"default","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
+{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp","type":"command"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"auto","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"text":"prompt 1","type":"text"}],"messageId":"<id-1>","sessionUpdate":"user_message"}}}
 {"kind":"response","method":"session/prompt","payload":{"messageId":"<id-1>"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[],"kind":"other","name":"AskUserQuestion","rawInput":{},"sessionUpdate":"tool_call_update","status":"pending","title":"Asking for your input","toolCallId":"toolu_ask"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":3}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"content":{"text":"Which database?","type":"text"},"type":"content"}],"rawInput":{"questions":[{"header":"Database","multiSelect":false,"options":[{"description":"Relational","label":"Postgres","preview":"CREATE TABLE t ();"},{"description":"Key-value","label":"Redis"}],"question":"Which database?"}]},"sessionUpdate":"tool_call_update","title":"Which database?","toolCallId":"toolu_ask"}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"requires_action"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"requires_action"}}}
 {"kind":"request","method":"elicitation/create","payload":{"message":"Which database?","mode":"form","requestedSchema":{"properties":{"question_0":{"oneOf":[{"_meta":{"_claude/askUserQuestionOption":{"preview":"CREATE TABLE t ();"}},"const":"Postgres","description":"Relational","title":"Postgres"},{"const":"Redis","description":"Key-value","title":"Redis"}],"title":"Database","type":"string"},"question_0_custom":{"description":"Type your own answer, or add a note to the option you chose above (optional).","title":"Other","type":"string"}},"type":"object"},"sessionId":"<session>","toolCallId":"toolu_ask"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"content":{"text":"User has answered your questions: \"Which database?\"=\"Postgres\".","type":"text"},"type":"content"}],"rawOutput":"User has answered your questions: \"Which database?\"=\"Postgres\".","sessionUpdate":"tool_call_update","status":"completed","toolCallId":"toolu_ask"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"cost":{"amount":0,"currency":"USD"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"background":[],"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}

src/tests/acp-scenarios/__snapshots__/v2/async-task-ends-before-tool-id.jsonl

@@ -1,6 +1,6 @@
 {"kind":"response","method":"initialize","payload":{"authMethods":[],"capabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"providers":{},"session":{"additionalDirectories":{},"delete":{},"fork":{},"mcp":{"http":{},"stdio":{}},"prompt":{"embeddedContext":{},"image":{}},"systemPrompt":{"mode":{"override":{}}}}},"info":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"protocolVersion":2}}
-{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"default","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
+{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp","type":"command"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"auto","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"text":"prompt 1","type":"text"}],"messageId":"<id-1>","sessionUpdate":"user_message"}}}
 {"kind":"response","method":"session/prompt","payload":{"messageId":"<id-1>"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"background":[],"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}

src/tests/acp-scenarios/__snapshots__/v2/async-task-held-until-tool-id.jsonl

@@ -1,6 +1,6 @@
 {"kind":"response","method":"initialize","payload":{"authMethods":[],"capabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"providers":{},"session":{"additionalDirectories":{},"delete":{},"fork":{},"mcp":{"http":{},"stdio":{}},"prompt":{"embeddedContext":{},"image":{}},"systemPrompt":{"mode":{"override":{}}}}},"info":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"protocolVersion":2}}
-{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"default","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
+{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp","type":"command"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"auto","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"text":"prompt 1","type":"text"}],"messageId":"<id-1>","sessionUpdate":"user_message"}}}
 {"kind":"response","method":"session/prompt","payload":{"messageId":"<id-1>"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"background":[],"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}

src/tests/acp-scenarios/__snapshots__/v2/async-task-released-at-turn-end.jsonl

@@ -1,6 +1,6 @@
 {"kind":"response","method":"initialize","payload":{"authMethods":[],"capabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"providers":{},"session":{"additionalDirectories":{},"delete":{},"fork":{},"mcp":{"http":{},"stdio":{}},"prompt":{"embeddedContext":{},"image":{}},"systemPrompt":{"mode":{"override":{}}}}},"info":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"protocolVersion":2}}
-{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"default","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
+{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp","type":"command"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"auto","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"text":"prompt 1","type":"text"}],"messageId":"<id-1>","sessionUpdate":"user_message"}}}
 {"kind":"response","method":"session/prompt","payload":{"messageId":"<id-1>"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"background":[],"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}

src/tests/acp-scenarios/__snapshots__/v2/bash-background.jsonl

@@ -1,8 +1,8 @@
 {"kind":"response","method":"initialize","payload":{"authMethods":[],"capabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"providers":{},"session":{"additionalDirectories":{},"delete":{},"fork":{},"mcp":{"http":{},"stdio":{}},"prompt":{"embeddedContext":{},"image":{}},"systemPrompt":{"mode":{"override":{}}}}},"info":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"protocolVersion":2}}
-{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"default","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
+{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp","type":"command"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"auto","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"text":"prompt 1","type":"text"}],"messageId":"<id-1>","sessionUpdate":"user_message"}}}
 {"kind":"response","method":"session/prompt","payload":{"messageId":"<id-1>"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"terminal_update","terminalId":"toolu_bg"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"terminalId":"toolu_bg","type":"terminal"}],"kind":"execute","name":"Bash","rawInput":{},"sessionUpdate":"tool_call_update","status":"pending","title":"Terminal","toolCallId":"toolu_bg"}}}
@@ -15,4 +15,4 @@
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"exitStatus":{},"sessionUpdate":"terminal_update","terminalId":"toolu_bg"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"tool_call_update","status":"completed","toolCallId":"toolu_bg"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"cost":{"amount":0,"currency":"USD"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"background":[],"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}

src/tests/acp-scenarios/__snapshots__/v2/bash-error.jsonl

@@ -1,8 +1,8 @@
 {"kind":"response","method":"initialize","payload":{"authMethods":[],"capabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"providers":{},"session":{"additionalDirectories":{},"delete":{},"fork":{},"mcp":{"http":{},"stdio":{}},"prompt":{"embeddedContext":{},"image":{}},"systemPrompt":{"mode":{"override":{}}}}},"info":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"protocolVersion":2}}
-{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"default","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
+{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp","type":"command"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"auto","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"text":"prompt 1","type":"text"}],"messageId":"<id-1>","sessionUpdate":"user_message"}}}
 {"kind":"response","method":"session/prompt","payload":{"messageId":"<id-1>"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"terminal_update","terminalId":"toolu_bash"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"terminalId":"toolu_bash","type":"terminal"}],"kind":"execute","name":"Bash","rawInput":{},"sessionUpdate":"tool_call_update","status":"pending","title":"Terminal","toolCallId":"toolu_bash"}}}
@@ -14,4 +14,4 @@
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"exitStatus":{"exitCode":1},"sessionUpdate":"terminal_update","terminalId":"toolu_bash"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"tool_call_update","status":"failed","toolCallId":"toolu_bash"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"cost":{"amount":0,"currency":"USD"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"background":[],"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}

src/tests/acp-scenarios/__snapshots__/v2/bash-foreground.jsonl

@@ -1,8 +1,8 @@
 {"kind":"response","method":"initialize","payload":{"authMethods":[],"capabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"providers":{},"session":{"additionalDirectories":{},"delete":{},"fork":{},"mcp":{"http":{},"stdio":{}},"prompt":{"embeddedContext":{},"image":{}},"systemPrompt":{"mode":{"override":{}}}}},"info":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"protocolVersion":2}}
-{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"default","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
+{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp","type":"command"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"auto","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"text":"prompt 1","type":"text"}],"messageId":"<id-1>","sessionUpdate":"user_message"}}}
 {"kind":"response","method":"session/prompt","payload":{"messageId":"<id-1>"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"terminal_update","terminalId":"toolu_bash"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"terminalId":"toolu_bash","type":"terminal"}],"kind":"execute","name":"Bash","rawInput":{},"sessionUpdate":"tool_call_update","status":"pending","title":"Terminal","toolCallId":"toolu_bash"}}}
@@ -10,9 +10,9 @@
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"rawInput":{"command":"ls -la"},"sessionUpdate":"tool_call_update","title":"ls -la","toolCallId":"toolu_bash"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":3}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"rawInput":{"command":"ls -la","description":"List files"},"sessionUpdate":"tool_call_update","toolCallId":"toolu_bash"}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"requires_action"}}}
-{"kind":"request","method":"session/request_permission","payload":{"options":[{"kind":"allow_once","name":"Yes","optionId":"allow-once"},{"kind":"reject_once","name":"No","optionId":"reject"}],"sessionId":"<session>","subject":{"toolCall":{"content":[{"terminalId":"toolu_bash","type":"terminal"}],"kind":"execute","name":"Bash","rawInput":{"command":"ls -la","description":"List files"},"status":"pending","title":"ls -la","toolCallId":"toolu_bash"},"type":"tool_call"},"title":"ls -la"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"requires_action"}}}
+{"kind":"request","method":"session/request_permission","payload":{"options":[{"kind":"allow_once","name":"Yes","optionId":"allow-once"},{"kind":"reject_once","name":"No","optionId":"reject"}],"sessionId":"<session>","subject":{"toolCall":{"content":[{"terminalId":"toolu_bash","type":"terminal"}],"kind":"execute","name":"Bash","rawInput":{"command":"ls -la","description":"List files"},"title":"ls -la","toolCallId":"toolu_bash"},"type":"tool_call"},"title":"ls -la"}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"output":{"data":"YS50cwpiLnRz"},"sessionUpdate":"terminal_update","terminalId":"toolu_bash"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"exitStatus":{"exitCode":0},"sessionUpdate":"terminal_update","terminalId":"toolu_bash"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"tool_call_update","status":"completed","toolCallId":"toolu_bash"}}}
@@ -20,4 +20,4 @@
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":{"text":"ne.","type":"text"},"messageId":"msg_done","sessionUpdate":"agent_message_chunk"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":3}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"cost":{"amount":0,"currency":"USD"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"background":[],"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}

src/tests/acp-scenarios/__snapshots__/v2/compaction-failed-legacy.jsonl

@@ -1,8 +1,8 @@
 {"kind":"response","method":"initialize","payload":{"authMethods":[],"capabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"providers":{},"session":{"additionalDirectories":{},"delete":{},"fork":{},"mcp":{"http":{},"stdio":{}},"prompt":{"embeddedContext":{},"image":{}},"systemPrompt":{"mode":{"override":{}}}}},"info":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"protocolVersion":2}}
-{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"default","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
+{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp","type":"command"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"auto","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"text":"prompt 1","type":"text"}],"messageId":"<id-1>","sessionUpdate":"user_message"}}}
 {"kind":"response","method":"session/prompt","payload":{"messageId":"<id-1>"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"compactionId":"00000000-0000-4000-8000-000000000001","sessionUpdate":"compaction_update","status":"in_progress"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"compactionId":"00000000-0000-4000-8000-000000000001","error":"Context too small","sessionUpdate":"compaction_update","status":"failed"}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"background":[],"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}

src/tests/acp-scenarios/__snapshots__/v2/compaction-legacy.jsonl

@@ -1,11 +1,11 @@
 {"kind":"response","method":"initialize","payload":{"authMethods":[],"capabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"providers":{},"session":{"additionalDirectories":{},"delete":{},"fork":{},"mcp":{"http":{},"stdio":{}},"prompt":{"embeddedContext":{},"image":{}},"systemPrompt":{"mode":{"override":{}}}}},"info":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"protocolVersion":2}}
-{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"default","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
+{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp","type":"command"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"auto","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"text":"prompt 1","type":"text"}],"messageId":"<id-1>","sessionUpdate":"user_message"}}}
 {"kind":"response","method":"session/prompt","payload":{"messageId":"<id-1>"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"compactionId":"00000000-0000-4000-8000-000000000001","sessionUpdate":"compaction_update","status":"in_progress"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"compactionId":"00000000-0000-4000-8000-000000000001","content":{"text":"The summary.","type":"text"},"sessionUpdate":"compaction_summary_chunk"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"compactionId":"00000000-0000-4000-8000-000000000001","sessionUpdate":"compaction_update","status":"completed"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"usage_update","size":200000,"used":100}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"cost":{"amount":0,"currency":"USD"},"sessionUpdate":"usage_update","size":200000,"used":100}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"background":[],"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}

src/tests/acp-scenarios/__snapshots__/v2/compaction-update.jsonl

@@ -1,11 +1,11 @@
 {"kind":"response","method":"initialize","payload":{"authMethods":[],"capabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"providers":{},"session":{"additionalDirectories":{},"delete":{},"fork":{},"mcp":{"http":{},"stdio":{}},"prompt":{"embeddedContext":{},"image":{}},"systemPrompt":{"mode":{"override":{}}}}},"info":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"protocolVersion":2}}
-{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"default","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
+{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp","type":"command"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"auto","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"text":"prompt 1","type":"text"}],"messageId":"<id-1>","sessionUpdate":"user_message"}}}
 {"kind":"response","method":"session/prompt","payload":{"messageId":"<id-1>"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"compactionId":"00000000-0000-4000-8000-000000000001","sessionUpdate":"compaction_update","status":"in_progress"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"compactionId":"00000000-0000-4000-8000-000000000001","content":{"text":"The summary.","type":"text"},"sessionUpdate":"compaction_summary_chunk"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"compactionId":"00000000-0000-4000-8000-000000000001","sessionUpdate":"compaction_update","status":"completed"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"usage_update","size":200000,"used":100}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"cost":{"amount":0,"currency":"USD"},"sessionUpdate":"usage_update","size":200000,"used":100}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"background":[],"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}

src/tests/acp-scenarios/__snapshots__/v2/edit-rejected.jsonl

@@ -1,8 +1,8 @@
 {"kind":"response","method":"initialize","payload":{"authMethods":[],"capabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"providers":{},"session":{"additionalDirectories":{},"delete":{},"fork":{},"mcp":{"http":{},"stdio":{}},"prompt":{"embeddedContext":{},"image":{}},"systemPrompt":{"mode":{"override":{}}}}},"info":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"protocolVersion":2}}
-{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"default","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
+{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp","type":"command"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"auto","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"text":"prompt 1","type":"text"}],"messageId":"<id-1>","sessionUpdate":"user_message"}}}
 {"kind":"response","method":"session/prompt","payload":{"messageId":"<id-1>"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[],"kind":"edit","locations":[],"name":"Edit","rawInput":{},"sessionUpdate":"tool_call_update","status":"pending","title":"Edit","toolCallId":"toolu_edit"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"locations":[{"path":"<cwd>/src/app.ts"}],"rawInput":{"file_path":"<cwd>/src/app.ts"},"sessionUpdate":"tool_call_update","title":"Edit src/app.ts","toolCallId":"toolu_edit"}}}
@@ -10,9 +10,9 @@
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":3}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"rawInput":{"file_path":"<cwd>/src/app.ts","new_string":"value = 2","old_string":"value = 1"},"sessionUpdate":"tool_call_update","toolCallId":"toolu_edit"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"changes":[{"fileType":"text","operation":"modify","path":"<cwd>/src/app.ts"}],"patch":{"format":"git_patch","text":"diff --git <cwd>/src/app.ts <cwd>/src/app.ts\n--- <cwd>/src/app.ts\n+++ <cwd>/src/app.ts\n@@ -1 +1 @@\n-const value = 1;\n+const value = 2;\n"},"type":"diff"}],"sessionUpdate":"tool_call_update","toolCallId":"toolu_edit"}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"requires_action"}}}
-{"kind":"request","method":"session/request_permission","payload":{"options":[{"kind":"allow_once","name":"Yes","optionId":"allow-once"},{"kind":"reject_once","name":"No","optionId":"reject"}],"sessionId":"<session>","subject":{"toolCall":{"content":[{"changes":[{"fileType":"text","operation":"modify","path":"<cwd>/src/app.ts"}],"patch":{"format":"git_patch","text":"diff --git <cwd>/src/app.ts <cwd>/src/app.ts\n--- <cwd>/src/app.ts\n+++ <cwd>/src/app.ts\n@@ -1 +1 @@\n-const value = 1;\n+const value = 2;\n"},"type":"diff"}],"kind":"edit","locations":[{"path":"<cwd>/src/app.ts"}],"name":"Edit","rawInput":{"file_path":"<cwd>/src/app.ts","new_string":"value = 2","old_string":"value = 1"},"status":"pending","title":"Edit src/app.ts","toolCallId":"toolu_edit"},"type":"tool_call"},"title":"Edit src/app.ts"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"requires_action"}}}
+{"kind":"request","method":"session/request_permission","payload":{"options":[{"kind":"allow_once","name":"Yes","optionId":"allow-once"},{"kind":"reject_once","name":"No","optionId":"reject"}],"sessionId":"<session>","subject":{"toolCall":{"content":[{"changes":[{"fileType":"text","operation":"modify","path":"<cwd>/src/app.ts"}],"patch":{"format":"git_patch","text":"diff --git <cwd>/src/app.ts <cwd>/src/app.ts\n--- <cwd>/src/app.ts\n+++ <cwd>/src/app.ts\n@@ -1 +1 @@\n-const value = 1;\n+const value = 2;\n"},"type":"diff"}],"kind":"edit","locations":[{"path":"<cwd>/src/app.ts"}],"name":"Edit","rawInput":{"file_path":"<cwd>/src/app.ts","new_string":"value = 2","old_string":"value = 1"},"title":"Edit src/app.ts","toolCallId":"toolu_edit"},"type":"tool_call"},"title":"Edit src/app.ts"}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"content":{"text":"```\nThe user doesn't want to proceed with this tool use. The tool use was rejected.\n```","type":"text"},"type":"content"}],"rawOutput":"The user doesn't want to proceed with this tool use. The tool use was rejected.","sessionUpdate":"tool_call_update","status":"failed","toolCallId":"toolu_edit"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"cost":{"amount":0,"currency":"USD"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"background":[],"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}

src/tests/acp-scenarios/__snapshots__/v2/edit-with-permission.jsonl

@@ -1,8 +1,8 @@
 {"kind":"response","method":"initialize","payload":{"authMethods":[],"capabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"providers":{},"session":{"additionalDirectories":{},"delete":{},"fork":{},"mcp":{"http":{},"stdio":{}},"prompt":{"embeddedContext":{},"image":{}},"systemPrompt":{"mode":{"override":{}}}}},"info":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"protocolVersion":2}}
-{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"default","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
+{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp","type":"command"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"auto","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"text":"prompt 1","type":"text"}],"messageId":"<id-1>","sessionUpdate":"user_message"}}}
 {"kind":"response","method":"session/prompt","payload":{"messageId":"<id-1>"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[],"kind":"edit","locations":[],"name":"Edit","rawInput":{},"sessionUpdate":"tool_call_update","status":"pending","title":"Edit","toolCallId":"toolu_edit"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"locations":[{"path":"<cwd>/src/app.ts"}],"rawInput":{"file_path":"<cwd>/src/app.ts"},"sessionUpdate":"tool_call_update","title":"Edit src/app.ts","toolCallId":"toolu_edit"}}}
@@ -10,10 +10,10 @@
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":3}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"rawInput":{"file_path":"<cwd>/src/app.ts","new_string":"const value = 2;","old_string":"const value = 1;"},"sessionUpdate":"tool_call_update","toolCallId":"toolu_edit"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"changes":[{"fileType":"text","operation":"modify","path":"<cwd>/src/app.ts"}],"patch":{"format":"git_patch","text":"diff --git <cwd>/src/app.ts <cwd>/src/app.ts\n--- <cwd>/src/app.ts\n+++ <cwd>/src/app.ts\n@@ -1,3 +1,3 @@\n line 1\n-const value = 1;\n+const value = 2;\n line 3\n"},"type":"diff"}],"sessionUpdate":"tool_call_update","toolCallId":"toolu_edit"}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"requires_action"}}}
-{"kind":"request","method":"session/request_permission","payload":{"options":[{"kind":"allow_once","name":"Yes","optionId":"allow-once"},{"kind":"reject_once","name":"No","optionId":"reject"}],"sessionId":"<session>","subject":{"toolCall":{"content":[{"changes":[{"fileType":"text","operation":"modify","path":"<cwd>/src/app.ts"}],"patch":{"format":"git_patch","text":"diff --git <cwd>/src/app.ts <cwd>/src/app.ts\n--- <cwd>/src/app.ts\n+++ <cwd>/src/app.ts\n@@ -1,3 +1,3 @@\n line 1\n-const value = 1;\n+const value = 2;\n line 3\n"},"type":"diff"}],"kind":"edit","locations":[{"path":"<cwd>/src/app.ts"}],"name":"Edit","rawInput":{"file_path":"<cwd>/src/app.ts","new_string":"const value = 2;","old_string":"const value = 1;"},"status":"pending","title":"Edit src/app.ts","toolCallId":"toolu_edit"},"type":"tool_call"},"title":"Edit src/app.ts"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"requires_action"}}}
+{"kind":"request","method":"session/request_permission","payload":{"options":[{"kind":"allow_once","name":"Yes","optionId":"allow-once"},{"kind":"reject_once","name":"No","optionId":"reject"}],"sessionId":"<session>","subject":{"toolCall":{"content":[{"changes":[{"fileType":"text","operation":"modify","path":"<cwd>/src/app.ts"}],"patch":{"format":"git_patch","text":"diff --git <cwd>/src/app.ts <cwd>/src/app.ts\n--- <cwd>/src/app.ts\n+++ <cwd>/src/app.ts\n@@ -1,3 +1,3 @@\n line 1\n-const value = 1;\n+const value = 2;\n line 3\n"},"type":"diff"}],"kind":"edit","locations":[{"path":"<cwd>/src/app.ts"}],"name":"Edit","rawInput":{"file_path":"<cwd>/src/app.ts","new_string":"const value = 2;","old_string":"const value = 1;"},"title":"Edit src/app.ts","toolCallId":"toolu_edit"},"type":"tool_call"},"title":"Edit src/app.ts"}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"rawOutput":"The file <cwd>/src/app.ts has been updated successfully.","sessionUpdate":"tool_call_update","status":"completed","toolCallId":"toolu_edit"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"locations":[{"line":1,"path":"<cwd>/src/app.ts"}],"sessionUpdate":"tool_call_update","toolCallId":"toolu_edit"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"cost":{"amount":0,"currency":"USD"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"background":[],"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}

src/tests/acp-scenarios/__snapshots__/v2/exit-plan-approve.jsonl

@@ -1,17 +1,17 @@
 {"kind":"response","method":"initialize","payload":{"authMethods":[],"capabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"providers":{},"session":{"additionalDirectories":{},"delete":{},"fork":{},"mcp":{"http":{},"stdio":{}},"prompt":{"embeddedContext":{},"image":{}},"systemPrompt":{"mode":{"override":{}}}}},"info":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"protocolVersion":2}}
-{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"default","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
+{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp","type":"command"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"auto","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"text":"prompt 1","type":"text"}],"messageId":"<id-1>","sessionUpdate":"user_message"}}}
 {"kind":"response","method":"session/prompt","payload":{"messageId":"<id-1>"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[],"kind":"switch_mode","name":"ExitPlanMode","rawInput":{},"sessionUpdate":"tool_call_update","status":"pending","title":"Approve Plan","toolCallId":"toolu_plan"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":3}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"content":{"text":"# Plan\n1. Do it","type":"text"},"type":"content"}],"rawInput":{"plan":"# Plan\n1. Do it"},"sessionUpdate":"tool_call_update","toolCallId":"toolu_plan"}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"requires_action"}}}
-{"kind":"request","method":"session/request_permission","payload":{"options":[{"kind":"allow_once","name":"Yes, manually approve edits","optionId":"exit-plan-default"},{"kind":"allow_always","name":"Yes, clear context (0% used) and use auto mode","optionId":"exit-plan-clear-auto"},{"kind":"allow_always","name":"Yes, and use auto mode","optionId":"exit-plan-auto"},{"kind":"allow_always","name":"Yes, and bypass permissions","optionId":"exit-plan-bypass"},{"kind":"reject_once","name":"No, keep planning","optionId":"reject"}],"sessionId":"<session>","subject":{"toolCall":{"content":[{"content":{"text":"# Plan\n1. Do it","type":"text"},"type":"content"}],"kind":"switch_mode","name":"ExitPlanMode","rawInput":{"plan":"# Plan\n1. Do it"},"status":"pending","title":"Approve Plan","toolCallId":"toolu_plan"},"type":"tool_call"},"title":"Ready to code?"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"requires_action"}}}
+{"kind":"request","method":"session/request_permission","payload":{"options":[{"kind":"allow_once","name":"Yes, manually approve edits","optionId":"exit-plan-default"},{"kind":"allow_always","name":"Yes, clear context (0% used) and use auto mode","optionId":"exit-plan-clear-auto"},{"kind":"allow_always","name":"Yes, and use auto mode","optionId":"exit-plan-auto"},{"kind":"allow_always","name":"Yes, and bypass permissions","optionId":"exit-plan-bypass"},{"kind":"reject_once","name":"No, keep planning","optionId":"reject"}],"sessionId":"<session>","subject":{"toolCall":{"content":[{"content":{"text":"# Plan\n1. Do it","type":"text"},"type":"content"}],"kind":"switch_mode","name":"ExitPlanMode","rawInput":{"plan":"# Plan\n1. Do it"},"title":"Approve Plan","toolCallId":"toolu_plan"},"type":"tool_call"},"title":"Ready to code?"}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"configOptions":[{"category":"mode","configId":"mode","currentValue":"default","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionUpdate":"config_option_update"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"rawOutput":"User has approved your plan. You can now start coding.\n\n## Approved Plan:\n# Plan\n1. Do it","sessionUpdate":"tool_call_update","status":"completed","title":"Exited Plan Mode","toolCallId":"toolu_plan"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"plan":{"content":"# Plan\n1. Do it","planId":"plan-mode","type":"markdown"},"sessionUpdate":"plan_update"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"cost":{"amount":0,"currency":"USD"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"background":[],"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}

src/tests/acp-scenarios/__snapshots__/v2/exit-plan-reject.jsonl

@@ -1,15 +1,15 @@
 {"kind":"response","method":"initialize","payload":{"authMethods":[],"capabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"providers":{},"session":{"additionalDirectories":{},"delete":{},"fork":{},"mcp":{"http":{},"stdio":{}},"prompt":{"embeddedContext":{},"image":{}},"systemPrompt":{"mode":{"override":{}}}}},"info":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"protocolVersion":2}}
-{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"default","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
+{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp","type":"command"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"auto","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"text":"prompt 1","type":"text"}],"messageId":"<id-1>","sessionUpdate":"user_message"}}}
 {"kind":"response","method":"session/prompt","payload":{"messageId":"<id-1>"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[],"kind":"switch_mode","name":"ExitPlanMode","rawInput":{},"sessionUpdate":"tool_call_update","status":"pending","title":"Approve Plan","toolCallId":"toolu_plan"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"sessionUpdate":"usage_update","size":200000,"used":3}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"content":{"text":"# Plan\n1. Do it","type":"text"},"type":"content"}],"rawInput":{"plan":"# Plan\n1. Do it"},"sessionUpdate":"tool_call_update","toolCallId":"toolu_plan"}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"requires_action"}}}
-{"kind":"request","method":"session/request_permission","payload":{"options":[{"kind":"allow_once","name":"Yes, manually approve edits","optionId":"exit-plan-default"},{"kind":"allow_always","name":"Yes, clear context (0% used) and use auto mode","optionId":"exit-plan-clear-auto"},{"kind":"allow_always","name":"Yes, and use auto mode","optionId":"exit-plan-auto"},{"kind":"allow_always","name":"Yes, and bypass permissions","optionId":"exit-plan-bypass"},{"kind":"reject_once","name":"No, keep planning","optionId":"reject"}],"sessionId":"<session>","subject":{"toolCall":{"content":[{"content":{"text":"# Plan\n1. Do it","type":"text"},"type":"content"}],"kind":"switch_mode","name":"ExitPlanMode","rawInput":{"plan":"# Plan\n1. Do it"},"status":"pending","title":"Approve Plan","toolCallId":"toolu_plan"},"type":"tool_call"},"title":"Ready to code?"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"requires_action"}}}
+{"kind":"request","method":"session/request_permission","payload":{"options":[{"kind":"allow_once","name":"Yes, manually approve edits","optionId":"exit-plan-default"},{"kind":"allow_always","name":"Yes, clear context (0% used) and use auto mode","optionId":"exit-plan-clear-auto"},{"kind":"allow_always","name":"Yes, and use auto mode","optionId":"exit-plan-auto"},{"kind":"allow_always","name":"Yes, and bypass permissions","optionId":"exit-plan-bypass"},{"kind":"reject_once","name":"No, keep planning","optionId":"reject"}],"sessionId":"<session>","subject":{"toolCall":{"content":[{"content":{"text":"# Plan\n1. Do it","type":"text"},"type":"content"}],"kind":"switch_mode","name":"ExitPlanMode","rawInput":{"plan":"# Plan\n1. Do it"},"title":"Approve Plan","toolCallId":"toolu_plan"},"type":"tool_call"},"title":"Ready to code?"}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"content":{"text":"```\n```\nThe user doesn't want to proceed with this tool use.\n```\n```","type":"text"},"type":"content"}],"rawOutput":"The user doesn't want to proceed with this tool use.","sessionUpdate":"tool_call_update","status":"failed","toolCallId":"toolu_plan"}}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"_claude/model":"claude-sonnet-4-6"},"cost":{"amount":0,"currency":"USD"},"sessionUpdate":"usage_update","size":200000,"used":2}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"background":[],"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}

src/tests/acp-scenarios/__snapshots__/v2/goal.jsonl

@@ -1,6 +1,6 @@
 {"kind":"response","method":"initialize","payload":{"authMethods":[],"capabilities":{"_meta":{"authStatus":{},"claudeCode":{"promptQueueing":true}},"providers":{},"session":{"additionalDirectories":{},"delete":{},"fork":{},"mcp":{"http":{},"stdio":{}},"prompt":{"embeddedContext":{},"image":{}},"systemPrompt":{"mode":{"override":{}}}}},"info":{"name":"@agentclientprotocol/claude-agent-acp","title":"Claude Agent","version":"<version>"},"protocolVersion":2}}
-{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"default","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
+{"kind":"response","method":"session/new","payload":{"availableCommands":[{"description":"Show the MCP servers and their status, or reconnect, enable, or disable a server","input":{"hint":"[reconnect|enable|disable [<server>|all]]","type":"text"},"name":"mcp","type":"command"}],"configOptions":[{"category":"mode","configId":"mode","currentValue":"auto","description":"Session permission mode","name":"Mode","options":[{"description":"Always ask before making changes","name":"Manual","value":"default"},{"description":"Automatically accept all file edits","name":"Accept edits","value":"acceptEdits"},{"description":"Create a plan before making changes","name":"Plan","value":"plan"},{"description":"Claude handles permission decisions","name":"Auto","value":"auto"},{"description":"Accepts all permissions","name":"Bypass permissions","value":"bypassPermissions"}],"type":"select"},{"category":"model","configId":"model","currentValue":"claude-sonnet-4-6","description":"AI model to use","name":"Model","options":[{"description":"Fast","name":"Claude Sonnet 4.6","value":"claude-sonnet-4-6"}],"type":"select"}],"sessionId":"<session>"}}
 {"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"content":[{"text":"/goal Ship the feature","type":"text"}],"messageId":"<id-1>","sessionUpdate":"user_message"}}}
 {"kind":"response","method":"session/prompt","payload":{"messageId":"<id-1>"}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"sessionUpdate":"state_update","state":"running"}}}
-{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"background":[],"sessionUpdate":"state_update","state":"running"}}}
+{"kind":"notification","method":"session/update","payload":{"sessionId":"<session>","update":{"_meta":{"quota":{"model_usage":[],"token_count":{"cachedInputTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"reasoningOutputTokens":0,"totalTokens":0}}},"background":[],"sessionUpdate":"state_update","state":"idle","stopReason":"end_turn","usage":{"cachedReadTokens":0,"cachedWriteTokens":0,"inputTokens":0,"outputTokens":0,"totalTokens":0}}}}