chore(main): release 0.71.0 (#1016 )

🤖 I have created a release *beep* *boop* --- ## [0.71.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.70.0...v0.71.0) (2026-08-31) ### Features * add ai generated session title ([#984](https://github.com/agentclientprotocol/claude-agent-acp/issues/984)) ([d334766](d334766ef9)) * align Claude modes and clear-context planning ([#1004](https://github.com/agentclientprotocol/claude-agent-acp/issues/1004)) ([996d488](996d488589)) * **deps:** Bump @anthropic-ai/claude-agent-sdk to 0.3.238 ([#1018](https://github.com/agentclientprotocol/claude-agent-acp/issues/1018)) ([ee9f300](ee9f300db4)) * expose native subagents and async tasks ([#1017](https://github.com/agentclientprotocol/claude-agent-acp/issues/1017)) ([14d192d](14d192d108)) * expose permission mode kinds ([#1025](https://github.com/agentclientprotocol/claude-agent-acp/issues/1025)) ([caf609b](caf609b56c)) * report per-model token usage on prompt responses ([#1037](https://github.com/agentclientprotocol/claude-agent-acp/issues/1037)) ([fad4d10](fad4d10e46)) * support message-specific ACP session forks ([#1046](https://github.com/agentclientprotocol/claude-agent-acp/issues/1046)) ([c3ff343](c3ff343884)) ### Bug Fixes * change min zod version to 4.x to avoid failing directory imports on 'v4' ([#1057](https://github.com/agentclientprotocol/claude-agent-acp/issues/1057)) ([7c66108](7c6610835f)) * defer steering while user input is pending ([#1045](https://github.com/agentclientprotocol/claude-agent-acp/issues/1045)) ([8710ce1](8710ce1cbc)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: acp-release-bot[bot] <246668977+acp-release-bot[bot]@users.noreply.github.com>
fix(LLM-25012): OAuth2 Authentication for MCP Server Connections (#1059 )
2026-11-06 17:31:36 +00:00 · 2026-09-01 19:31:24 +02:00 · 2026-09-01 17:31:21 +00:00 · 2026-08-31 14:11:17 +02:00 · 2026-08-28 10:33:14 +02:00 · 2026-08-27 14:11:13 +02:00
58 changed files with 16738 additions and 2050 deletions
--- a/.release-please-manifest.json
+++ b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "0.67.0"
+  ".": "0.71.0"
 }
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,45 @@
 # Changelog

+## [0.71.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.70.0...v0.71.0) (2026-08-31)
+
+
+### Features
+
+* add ai generated session title ([#984](https://github.com/agentclientprotocol/claude-agent-acp/issues/984)) ([d334766](https://github.com/agentclientprotocol/claude-agent-acp/commit/d334766ef95dd89201979d42252e3d2a5a259cb9))
+* align Claude modes and clear-context planning ([#1004](https://github.com/agentclientprotocol/claude-agent-acp/issues/1004)) ([996d488](https://github.com/agentclientprotocol/claude-agent-acp/commit/996d488589b8db7a0f9af3dfc7b886d9d47ebae9))
+* **deps:** Bump @anthropic-ai/claude-agent-sdk to 0.3.238 ([#1018](https://github.com/agentclientprotocol/claude-agent-acp/issues/1018)) ([ee9f300](https://github.com/agentclientprotocol/claude-agent-acp/commit/ee9f300db4562e8b7958cec9fa63dab05a5c2eb0))
+* expose native subagents and async tasks ([#1017](https://github.com/agentclientprotocol/claude-agent-acp/issues/1017)) ([14d192d](https://github.com/agentclientprotocol/claude-agent-acp/commit/14d192d1087ea8662392b5c61c9fcdd496c5a179))
+* expose permission mode kinds ([#1025](https://github.com/agentclientprotocol/claude-agent-acp/issues/1025)) ([caf609b](https://github.com/agentclientprotocol/claude-agent-acp/commit/caf609b56c91f677ffe82b6e9d11d9e9dfd99d45))
+* report per-model token usage on prompt responses ([#1037](https://github.com/agentclientprotocol/claude-agent-acp/issues/1037)) ([fad4d10](https://github.com/agentclientprotocol/claude-agent-acp/commit/fad4d10e46c5e65fc6d426c98074bbb76067bf25))
+* support message-specific ACP session forks ([#1046](https://github.com/agentclientprotocol/claude-agent-acp/issues/1046)) ([c3ff343](https://github.com/agentclientprotocol/claude-agent-acp/commit/c3ff3438844f5249d6a7f5c297906e2cd3d5fa7f))
+
+
+### Bug Fixes
+
+* change min zod version to 4.x to avoid failing directory imports on 'v4' ([#1057](https://github.com/agentclientprotocol/claude-agent-acp/issues/1057)) ([7c66108](https://github.com/agentclientprotocol/claude-agent-acp/commit/7c6610835f26f18cd162b78dff74a7b7cd74497a))
+* defer steering while user input is pending ([#1045](https://github.com/agentclientprotocol/claude-agent-acp/issues/1045)) ([8710ce1](https://github.com/agentclientprotocol/claude-agent-acp/commit/8710ce1cbccf562cb04b4bcc30e053e960aee05f))
+
+## [0.70.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.69.0...v0.70.0) (2026-08-17)
+
+
+### Features
+
+* switch providers for loaded Claude sessions ([#1002](https://github.com/agentclientprotocol/claude-agent-acp/issues/1002)) ([50a9543](https://github.com/agentclientprotocol/claude-agent-acp/commit/50a95434e94318456f2d07c3d21aaf3595c3407d))
+
+## [0.69.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.68.0...v0.69.0) (2026-08-16)
+
+
+### Features
+
+* report changed files to AIR ([#1001](https://github.com/agentclientprotocol/claude-agent-acp/issues/1001)) ([450d6b1](https://github.com/agentclientprotocol/claude-agent-acp/commit/450d6b19dc46a041128356a6fa3cfa3ce6a5a382))
+
+## [0.68.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.67.0...v0.68.0) (2026-08-14)
+
+
+### Features
+
+* align typed session failures with AIR protocol ([#992](https://github.com/agentclientprotocol/claude-agent-acp/issues/992)) ([0581b9c](https://github.com/agentclientprotocol/claude-agent-acp/commit/0581b9cf397ffd88f2830db721c2d8e3689045e4))
+
 ## [0.67.0](https://github.com/agentclientprotocol/claude-agent-acp/compare/v0.66.0...v0.67.0) (2026-08-14)


--- a/README.md
+++ b/README.md
@@ -17,19 +17,21 @@ This tool implements an ACP agent by using the official [Claude Agent SDK](https
 - Custom [Slash commands](https://docs.anthropic.com/en/docs/claude-code/slash-commands)
 - Client MCP servers
 - Session-scoped long-running goals through the provider-neutral [goal extension](docs/goal-extension.md)
+- Structured errors, recovery, and warnings through the opt-in [session failure extension](docs/session-failure-extension.md)
+- Tool permission presentation, editable choices, and durable effects through the [permission extension](docs/permission-extension.md)

 Learn more about the [Agent Client Protocol](https://agentclientprotocol.com/).

-### Nested subagent transcripts
+### Subagent sessions

-ACP 1.2 has no standard subagent tool kind or nested-message relationship. Clients that can render
-nested transcripts can opt in with `clientCapabilities._meta["subagent-transcript"] = true`.
-The agent then forwards subagent text, thinking, and tool calls, relating nested updates to the
-launching Agent/Task call through `_meta.claudeCode.parentToolUseId`. Agent/Task calls are marked
-with `_meta.claudeCode.subagent = true`.
-
-Clients that do not advertise the capability retain the legacy flattened behavior. In both modes,
-the normal Agent/Task tool result is preserved as the protocol-compatible fallback.
+Subagents are exposed only after bilateral capability negotiation. Until the released ACP SDKs
+preserve the draft `clientCapabilities.subagents` field, a supporting client may advertise
+`nativeSubagentSessions` in `_meta.jetbrains.air.capabilities`; the adapter mirrors the capability
+in its initialize response. The canonical field remains supported and takes precedence once it is
+available. Without either client signal, Agent/Task lifecycle keeps its legacy ordinary ACP
+tool-call representation and child interactions stay on the root session. Clients that use the
+historical `_meta["subagent-transcript"]` capability or `forwardSubagentText` session option retain
+the flattened child transcript behavior.

 ## Contribution Policy

--- a/docs/permission-extension.md
+++ b/docs/permission-extension.md
@@ -0,0 +1,243 @@
+# Permission extension
+
+This document defines the experimental permission presentation extension implemented by
+`claude-agent-acp`. The adapter uses standard ACP permission requests and responses, while `_meta`
+adds compact request presentation text.
+
+The extension does not replace ACP permissions. `RequestPermissionRequest.toolCall`, `options`,
+`RequestPermissionResponse.outcome`, and each option's standard `kind` remain authoritative. A client
+that does not understand the extension can ignore `_meta` and render the ordinary ACP request.
+
+## Request lifecycle
+
+When the Claude Agent SDK invokes `canUseTool`, the adapter:
+
+1. stops immediately if the tool-call signal is already aborted;
+2. ensures the referenced ACP `tool_call` has been emitted;
+3. validates and snapshots any SDK `suggestions: PermissionUpdate[]`;
+4. builds a tool-specific presentation and ordered option list;
+5. sends `session/request_permission` with the tool-call cancellation signal;
+6. validates that the selected option was offered in the exact request;
+7. maps the selection to a Claude SDK `PermissionResult`.
+
+The eager `tool_call` announcement always precedes the permission request. If the announcement fails,
+its de-duplication marker is removed so the normal streamed tool-use path may retry it.
+
+Request-level presentation metadata requires no capability negotiation. It is an additive `_meta`
+record and may be ignored by clients that do not render it.
+
+## Request presentation
+
+The request-level record is placed under `RequestPermissionRequest._meta.permission`:
+
+```json
+{
+  "sessionId": "session-1",
+  "toolCall": {
+    "toolCallId": "toolu_1",
+    "name": "Bash",
+    "status": "pending",
+    "rawInput": { "command": "npm test" }
+  },
+  "options": [
+    { "optionId": "allow-once", "name": "Yes", "kind": "allow_once" },
+    { "optionId": "reject", "name": "No", "kind": "reject_once" }
+  ],
+  "_meta": {
+    "permission": {
+      "version": 1,
+      "title": "npm test",
+      "description": "Reason: Needed to verify the change."
+    }
+  }
+}
+```
+
+| Field         | Required | Type             | Meaning                                   |
+| ------------- | -------: | ---------------- | ----------------------------------------- |
+| `version`     |      yes | integer `1`      | Permission presentation schema version.   |
+| `title`       |      yes | non-empty string | The standard tool-call operation title.   |
+| `description` |       no | string           | Temporary diagnostic SDK decision reason. |
+
+The permission title normally duplicates `toolCall.title`: one operation has one heading across the
+tool card and approval UI. `ExitPlanMode` is the deliberate exception and uses the action-oriented
+permission heading `Ready to code?`. Commands, paths, URLs, and other structured details remain in
+`rawInput`, `content`, and `locations`.
+
+`description` temporarily carries the SDK's non-blank `decisionReason` for diagnostics, prefixed
+with `Reason: `. The SDK `description` operation subtitle is not copied there.
+
+## Tool-call presentation
+
+The permission request carries the same standard ACP tool information used for normal tool updates:
+
+- `name`, `kind`, `title`, `content`, and `locations` come from `toolInfoFromToolUse`;
+- `status` is `pending`;
+- `rawInput` is the original SDK input object;
+- `blockedPath` is appended to `locations` when it is valid and not already present;
+- subagent calls include `_meta.claudeCode.parentToolUseId` on the tool call;
+- Sandbox Network and Computer Use requests synthesize JSON content when the normal renderer has no
+  content.
+
+Compact text removes control characters, collapses whitespace where appropriate, and enforces length
+limits. Invalid optional presentation text is omitted instead of being truncated into misleading UI.
+
+Permission options are fixed. When a durable suggestion contains a command prefix, path, host, or
+other rule, the adapter includes that value directly in `PermissionOption.name`, for example
+`Yes, and don't ask again for npm test commands`. Selecting the option applies the exact snapshotted
+Claude SDK `PermissionUpdate`; the client cannot edit it. A selected reject is distinct from
+`{ "outcome": "cancelled" }`: cancellation aborts the tool use instead of returning a user rejection.
+
+## Standard option ids
+
+| Option id                      | Meaning                                                     |
+| ------------------------------ | ----------------------------------------------------------- |
+| `allow-once`                   | Allow this call without changing permission state.          |
+| `allow-with-updates`           | Allow and apply the displayed durable effect.               |
+| `allow-skill-exact`            | Allow the exact Skill invocation in local settings.         |
+| `allow-skill-prefix`           | Allow the parameterized Skill prefix in local settings.     |
+| `exit-plan-auto`               | Exit plan mode and set session mode to `auto`.              |
+| `exit-plan-bypass`             | Exit plan mode and set session mode to `bypassPermissions`. |
+| `exit-plan-accept-edits`       | Exit plan mode and set session mode to `acceptEdits`.       |
+| `exit-plan-default`            | Exit plan mode and set session mode to `default`.           |
+| `exit-plan-clear-auto`         | Clear context, continue the plan, and use `auto`.           |
+| `exit-plan-clear-bypass`       | Clear context, continue the plan, and bypass permissions.   |
+| `exit-plan-clear-accept-edits` | Clear context, continue the plan, and accept edits.         |
+| `reject`                       | Deny the call, optionally returning feedback to Claude.     |
+
+The adapter stably groups options as `allow_once`, `allow_always`, then reject kinds. Options of the
+same kind retain their builder order. Clients must return the selected option id unchanged.
+
+## Durable SDK suggestions
+
+Claude may provide `suggestions: PermissionUpdate[]`. Before a suggestion can appear as a durable
+choice, the adapter validates the complete array and takes a structured clone. Validation recognizes:
+
+- `addRules`, `replaceRules`, and `removeRules`;
+- `setMode` for known Claude permission modes;
+- `addDirectories` and `removeDirectories`;
+- known destinations and rule behaviors;
+- bounded array sizes and bounded non-empty strings.
+
+Unknown update types, invalid values, oversized bundles, non-cloneable data, and empty suggestion
+arrays are omitted. The snapshot prevents the label shown to the user from diverging from the effect
+returned after a delayed response.
+
+An SDK suggestion is offered only when the tool-specific builder can accurately describe the entire
+effect. The adapter never labels one part of a mixed bundle while silently applying the rest.
+
+When `matchedAskRule` is present, all persistent choices are suppressed. A configured `ask` rule must
+continue asking; accepting a generated allow rule that cannot override it would be misleading.
+
+## Tool-specific behavior
+
+| Tool family                 | Permission choices and effects                                                                                     |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Bash / PowerShell           | One-time allow; exact representable SDK bundle with its complete effect in the option label; reject.               |
+| Read / Glob / Grep          | One-time allow; matching session-scoped read grant; reject.                                                        |
+| Edit / Write / NotebookEdit | One-time allow; matching session edit grant, including `.claude` handling; reject.                                 |
+| WebFetch                    | One-time allow; generated `domain:<hostname>` local rule; reject.                                                  |
+| Skill                       | One-time allow; exact skill and optional `prefix:*` local rules; reject.                                           |
+| EnterPlanMode               | Enter plan mode once, or reject and continue implementing.                                                         |
+| ExitPlanMode                | One keep-context and one clear-context elevated mode (`auto` > bypass > accept edits), manual approval, or reject. |
+| SandboxNetworkAccess        | One-time allow; exact SDK host rule when representable; reject.                                                    |
+| Computer Use MCP            | One-time allow; exact representable SDK allow suggestion; reject.                                                  |
+| MCP                         | One-time allow; exact representable SDK allow suggestion for that tool; reject.                                    |
+| WebSearch / Agent / Task    | One-time allow; generated whole-tool local rule; reject.                                                           |
+| ReviewArtifact / Workflow   | Generic fallback behavior until SDK renderer state is available.                                                   |
+| Monitor / unknown tools     | Generic fallback behavior.                                                                                         |
+
+Generated WebFetch, Skill, and non-MCP fallback effects use `localSettings`. Filesystem grants are
+offered only when the SDK bundle is session-scoped and covers the current path. Shell labels may
+describe command rules, read paths, additional directories, or a representable combination.
+
+`AskUserQuestion` is not a permission dialog. With ACP form elicitation support it is routed through
+ACP elicitation; without that support it is disabled when the Claude session is created.
+
+## Permission modes and bypass
+
+The session exposes the Claude modes available for the current model using Claude Code's labels:
+`Manual`, `Accept edits`, `Plan`, conditional `Auto`, and conditional `Bypass permissions`. The
+internal `dontAsk` SDK mode is accepted from settings for compatibility but is not advertised as a
+user-selectable mode.
+
+The ACP mode ids are the Claude SDK wire ids: `default`, `acceptEdits`, `plan`, `auto`, and
+`bypassPermissions`. `Manual` deliberately retains the SDK id `default`; `manual` is only a settings
+input alias. The adapter does not invent parallel ids for presentation labels.
+
+Like Claude Code, `ExitPlanMode` offers one elevated keep-context choice by priority: `auto`, then
+`bypassPermissions`, then `acceptEdits`. A non-empty plan also gets exactly one clear-context choice
+with the same priority. This requires no ACP capability or setting: after selection the adapter
+interrupts the old private Claude query, hides that internal rejection from the client, creates a
+new private query under the same public ACP session, and continues the pending turn with
+`Implement the following plan:` followed by the complete plan. Mode, model, agent, effort, Fast
+mode, and accumulated turn usage are preserved.
+
+The SDK cannot reapply `allowedPrompts` through a public control request, so those renderer hints do
+not survive this internal handoff. Ultraplan remains unavailable because its required renderer state
+is not exposed by the SDK.
+
+The adapter does not auto-allow a callback merely because the session advertises
+`bypassPermissions`. Claude Code applies bypass before invoking `canUseTool`. A request that still
+reaches the callback is bypass-immune, safety-sensitive, interactive, or forced by an explicit ask
+rule and must remain visible to the user.
+
+## Cancellation and failures
+
+The SDK tool-call `AbortSignal` is forwarded to the ACP client. The adapter also races the client
+request locally against the same signal, so a client that ignores cancellation cannot leave Claude's
+tool call waiting forever.
+
+These cases all abort the tool use with `Tool use aborted`:
+
+- the signal was already aborted;
+- the signal aborts while the permission request is open;
+- the client returns a cancelled outcome;
+- the client rejects after cancellation.
+
+A normal selected reject returns `behavior: "deny"`, `decisionClassification: "user_reject"`, and
+the default refusal message.
+
+## Client requirements
+
+A client implementing version 1 should:
+
+- render standard ACP tool-call content and locations as the action subject;
+- treat request `_meta.permission.title` and `description` as optional presentation hints;
+- preserve option ids;
+- ignore unknown `_meta` fields and future feature names;
+- settle the request when its cancellation signal fires.
+
+The client must not infer storage scope, lifetime, or permission effects from `kind` or button text.
+The adapter owns the Claude `PermissionUpdate` and applies it only after validating the response.
+
+## Current limits
+
+The SDK does not expose enough renderer state to reproduce every Claude Code dialog. Version 1 does
+not implement:
+
+- Bash output-redirection rewriting;
+- classifier-specific prompt state;
+- ExitPlanMode Ultraplan actions;
+- Computer Use macOS/TCC or application-allowlist dialogs;
+- structured permission lifetime or storage metadata for clients.
+
+These omissions do not weaken the one-time choice. When a durable effect cannot be represented
+honestly, the adapter sends only one-time allow and reject.
+
+## Verification
+
+The executable contract lives in:
+
+- `src/tests/permission-presentation.test.ts` for capability and request presentation;
+- `src/tests/permission-options.test.ts` for tool-specific option construction;
+- `src/tests/permission-effects.test.ts` for response validation and effects;
+- `src/tests/acp-agent.test.ts` for request ordering, cancellation, bypass, and subagent attribution;
+- `src/tests/session-config-options.test.ts` for plan-mode integration;
+- `src/tests/live-capability-*-audit.test.ts` for opt-in live SDK audits.
+
+```sh
+npm run build
+npm run check
+npm run test:run
+```
--- a/docs/session-failure-extension.md
+++ b/docs/session-failure-extension.md
@@ -0,0 +1,208 @@
+# Session failure extension
+
+This document defines the provider-neutral experimental `sessionFailure` extension implemented by
+`claude-agent-acp`. Warnings and errors are durable transcript entries shown in order beside user,
+agent, and tool messages. They are not assistant-authored text and not ephemeral chat banners.
+
+## Capability negotiation
+
+The extension is opt-in. A client advertises it in `initialize`:
+
+```json
+{
+  "clientCapabilities": {
+    "_meta": {
+      "jetbrains": {
+        "air": {
+          "version": 1,
+          "capabilities": ["sessionFailure"]
+        }
+      }
+    }
+  }
+}
+```
+
+The adapter enables the extension only when `version` is a finite integer greater than or equal to
+`1` and `capabilities` contains `sessionFailure`. Otherwise it preserves the legacy ACP behavior.
+
+## Wire record
+
+The record is placed under `_meta.jetbrains.air.sessionFailure`:
+
+```json
+{
+  "_meta": {
+    "jetbrains": {
+      "air": {
+        "version": 1,
+        "sessionFailure": {
+          "id": "prompt-uuid:error",
+          "revision": 1,
+          "category": "limit",
+          "severity": "error",
+          "title": "You've hit your individual spend limit · run /usage-credits to ask your admin for a higher limit",
+          "actions": []
+        }
+      }
+    }
+  }
+}
+```
+
+| Field      | Required | Type                 | Meaning                                                                 |
+| ---------- | -------: | -------------------- | ----------------------------------------------------------------------- |
+| `id`       |      yes | non-empty string     | Stable identity of one logical incident.                                |
+| `revision` |      yes | positive integer     | Monotonically increasing version of that incident.                      |
+| `category` |      yes | category enum        | Broad machine-readable visual group.                                    |
+| `severity` |      yes | `warning` or `error` | Inline warning or error presentation.                                   |
+| `title`    |      yes | string               | Complete normal user-facing presentation.                               |
+| `details`  |       no | string               | Long explanation used only when required text is too large for `title`. |
+| `actions`  |      yes | ordered string array | Recovery actions recommended by the adapter.                            |
+
+There are no `phase`, `source`, `safeMessage`, `retryable`, `retryAfterMs`, `turnId`, retry-counter,
+or provider-code fields. Retry progress belongs in `title` when Claude supplies it. Transcript order
+and persistence time come from the receiving ACP event.
+
+## Identity, revisions, and history
+
+`id` identifies one occurrence, not an error type.
+
+- The first record for an incident creates one transcript entry at the current stream position.
+- The same `id` with a higher `revision` updates that entry in place without moving it.
+- The same or a lower revision is idempotently ignored by the client.
+- A later independent occurrence uses a new `id`, even when its category and text are identical.
+- Consecutive updates for the same notice may reuse one id and increment its revision.
+- Different ids are never deduplicated by comparing title or category.
+
+Live turn failures use `<turnId>:error`. Session-scoped incidents use an adapter-session epoch plus an
+incident sequence. Notices have their own `:notice:` namespace. Replayed usage-limit failures recover
+the persisted user-message UUID used as the live turn id, so the same occurrence keeps the same id.
+Malformed history without a preceding user message falls back to
+`<sessionId>:history-error:<messageUuid>`.
+
+Resolved records remain in transcript history. Recovery removes only the adapter's internal active
+state; it does not publish a clear tombstone and does not delete or rewrite the historical entry. A
+producer may publish a higher revision only when it has a real new user-facing status to show.
+
+## Delivery surfaces
+
+A turn-terminal failure is attached to the successful ACP `PromptResponse` in `_meta`; the response
+uses `stopReason: end_turn`. Session-scoped, replay-restored, warning, and background incidents use a
+`session_info_update`. The schema is identical on both carriers.
+
+A warning does not end a turn. An error record does not independently invent ACP lifecycle state;
+the prompt response or transport lifecycle remains authoritative. If no capable client negotiated
+the extension, existing JSON-RPC errors and transcript text remain unchanged.
+
+## Categories
+
+Categories are deliberately broad and drive only iconography and generic accessibility labels.
+
+| Category     | Covers                                                                |
+| ------------ | --------------------------------------------------------------------- |
+| `connection` | Lost transport, stopped or shutting-down worker, unavailable runtime. |
+| `access`     | Authentication required, rejected credentials, denied access.         |
+| `limit`      | Rate, quota, token, context, turn, or configured budget limit.        |
+| `request`    | Invalid input, unsupported model or operation, rejected request.      |
+| `service`    | Provider overload, provider failure, adapter/internal failure.        |
+| `unknown`    | A warning or failure that does not fit another group.                 |
+
+Claude SDK conditions map to these groups:
+
+| Claude condition                                                                         | Category                           |
+| ---------------------------------------------------------------------------------------- | ---------------------------------- |
+| `authentication_failed`, `oauth_org_not_allowed`, synthetic login message                | `access`                           |
+| `billing_error`, `rate_limit`, `max_output_tokens`, usage/spend limit, budget/turn limit | `limit`                            |
+| `invalid_request`, `model_not_found`                                                     | `request`                          |
+| `overloaded`, `server_error`, unknown provider error, adapter internal error             | `service`                          |
+| API retry without an HTTP response, query transport loss, worker shutdown                | `connection`                       |
+| model fallback notice                                                                    | `unknown` with `severity: warning` |
+
+Unknown SDK error kinds degrade to `service`; they never become success. Category does not determine
+message text or client behavior beyond presentation.
+
+## Severity
+
+- `warning` means the operation may still succeed and normally has no actions while recovery is in
+  progress. It does not terminate the turn. SDK `api_retry` progress reuses the active turn failure id;
+  a later terminal failure updates that record with a higher revision.
+- `error` means the operation cannot continue without user action or another request.
+
+Severity is always explicit.
+
+## Title and details
+
+`title` is the complete normal presentation: what happened, retry progress when present, and a short
+next step. The adapter must not replace a real Claude message with category-specific canned wording.
+
+For Claude SDK failures the title is copied from the user-facing text Claude already emitted:
+
+- top-level assistant error text, including synthetic usage-limit and login messages;
+- otherwise the terminal SDK result or error text;
+- the exact model-fallback notice for warning records.
+
+Adapter-authored fallback text is allowed only when no Claude user-facing message exists, such as a
+query iterator throwing, worker-shutdown EOF, or an internal missing-result invariant. Raw thrown
+exceptions, stack traces, transport URLs, tokens, headers, environment values, and private paths are
+never used as titles.
+
+`details` is reserved exclusively for required explanations too large to fit reasonably in `title`.
+If the complete message fits in `title`, `details` must be omitted. It is not a place for status text,
+retry counters, provider payloads, or diagnostics.
+
+## Actions
+
+Version 1 defines only:
+
+| Action        | Meaning                                            |
+| ------------- | -------------------------------------------------- |
+| `retry`       | Retry the operation associated with this incident. |
+| `login`       | Start authentication.                              |
+| `new_session` | Start a fresh agent session/runtime.               |
+
+The adapter supplies action ordering. The client filters actions it cannot safely execute and ignores
+unknown or duplicate values. The client must not infer actions from category.
+
+Current Claude policies are:
+
+- authentication: `login`;
+- provider overload/error and recoverable internal error: `retry`;
+- transport loss or worker shutdown: `new_session`;
+- context or configured session-budget exhaustion: `new_session`;
+- account quota and invalid request: no action.
+
+## Internal recovery
+
+Recovery policy is internal adapter state and is not serialized:
+
+- restored quota remains active until a real model answer;
+- authentication remains active until successful `auth_status`;
+- transport loss and worker shutdown remain active until runtime replacement;
+- other turn-scoped failures stop being active at a later confirmed attempt boundary;
+- notices are not cleared merely by generic success.
+
+Recovery never removes the transcript record. Publishing another incident is not evidence that an
+older one recovered.
+
+## History replay
+
+`session/load` scans top-level assistant history for SDK synthetic usage-limit messages. It recognizes
+only `<synthetic>` messages beginning with SDK-owned stable prefixes, not arbitrary model prose. Every
+recognized occurrence is replayed as a typed record at its original transcript position. The latest
+matching message stays active until a later real-model answer proves recovery; older and recovered
+records remain historical typed entries.
+
+For a capable client, replay suppresses duplicate assistant prose and restores typed errors using the
+exact stored Claude text as `title`. Legacy clients receive the original transcript and no typed record.
+
+## Verification
+
+The executable contract lives primarily in `src/tests/acp-agent.test.ts`, under `usage-limit failure
+replay`, `stop reason propagation`, and `model refusal fallback handling`.
+
+```sh
+npm run build
+npm run check
+npm run test:run
+```
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,25 +1,25 @@
 {
  "name": "@agentclientprotocol/claude-agent-acp",
-  "version": "0.67.0",
+  "version": "0.71.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "@agentclientprotocol/claude-agent-acp",
-      "version": "0.67.0",
+      "version": "0.71.0",
      "license": "Apache-2.0",
      "dependencies": {
        "@agentclientprotocol/sdk": "1.3.0",
-        "@anthropic-ai/claude-agent-sdk": "0.3.232",
+        "@anthropic-ai/claude-agent-sdk": "0.3.238",
        "zod": "^3.25.0 || ^4.0.0"
      },
      "bin": {
        "claude-agent-acp": "dist/index.js"
      },
      "devDependencies": {
-        "@anthropic-ai/sdk": "0.117.1",
+        "@anthropic-ai/sdk": "0.120.0",
        "@eslint/js": "10.0.1",
-        "@tsconfig/node22": "22.0.5",
+        "@tsconfig/node22": "22.0.6",
        "@types/node": "26.2.0",
        "@typescript-eslint/eslint-plugin": "8.67.0",
        "@typescript-eslint/parser": "8.67.0",
@@ -29,7 +29,7 @@
        "prettier": "3.9.6",
        "ts-node": "10.9.2",
        "typescript": "6.0.3",
-        "vitest": "4.1.10"
+        "vitest": "4.1.11"
      },
      "engines": {
        "node": ">=22"
@@ -45,22 +45,22 @@
      }
    },
    "node_modules/@anthropic-ai/claude-agent-sdk": {
-      "version": "0.3.232",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/-/claude-agent-sdk-0.3.232.tgz",
-      "integrity": "sha512-8od7hJk9fZnF1/oYYiR9PvroGbZRQrpmNgKirjHNGoj5ur5YcAZLohI70XVUAUe3KvjB1msLxtkvmlAT9sqFAg==",
+      "version": "0.3.238",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/-/claude-agent-sdk-0.3.238.tgz",
+      "integrity": "sha512-ppRfbAflZuV7HPqr8BkHPEk8c7gih3PK+GHnZq6zP0Uo7bJHXAJwc4Za8LJRm4hXMixBNMjK1cU/VWfQ9fE2sg==",
      "license": "SEE LICENSE IN README.md",
      "engines": {
        "node": ">=18.0.0"
      },
      "optionalDependencies": {
-        "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.3.232",
-        "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.3.232",
-        "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.3.232",
-        "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.3.232",
-        "@anthropic-ai/claude-agent-sdk-linux-x64": "0.3.232",
-        "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.3.232",
-        "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.3.232",
-        "@anthropic-ai/claude-agent-sdk-win32-x64": "0.3.232"
+        "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.3.238",
+        "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.3.238",
+        "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.3.238",
+        "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.3.238",
+        "@anthropic-ai/claude-agent-sdk-linux-x64": "0.3.238",
+        "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.3.238",
+        "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.3.238",
+        "@anthropic-ai/claude-agent-sdk-win32-x64": "0.3.238"
      },
      "peerDependencies": {
        "@anthropic-ai/sdk": ">=0.93.0",
@@ -69,9 +69,9 @@
      }
    },
    "node_modules/@anthropic-ai/claude-agent-sdk-darwin-arm64": {
-      "version": "0.3.232",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-darwin-arm64/-/claude-agent-sdk-darwin-arm64-0.3.232.tgz",
-      "integrity": "sha512-+/4PX+dwmQAjlOlooocwa3kClulZfMo133xQH3LYDlK7D5bzze16lwlDGPVAYGEarpvXg7G5JK8QjfWAJ2HYbg==",
+      "version": "0.3.238",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-darwin-arm64/-/claude-agent-sdk-darwin-arm64-0.3.238.tgz",
+      "integrity": "sha512-7KctNItTzHRiDg+jFxTM46o+Y/YS52V6HSopaWPggO6BbR+3MV/rKMmq+zP93If7eVwadW9Yg9vHLjXDKIw9OQ==",
      "cpu": [
        "arm64"
      ],
@@ -82,9 +82,9 @@
      ]
    },
    "node_modules/@anthropic-ai/claude-agent-sdk-darwin-x64": {
-      "version": "0.3.232",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-darwin-x64/-/claude-agent-sdk-darwin-x64-0.3.232.tgz",
-      "integrity": "sha512-EHZ1Y3aGyZ2mFZ6QLR1bM3/HiIn2cLrPjU+k3/oCIW6omJFodfzf410aWjDPSnMj7CE4d6t7MSjBWekMUbcv0g==",
+      "version": "0.3.238",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-darwin-x64/-/claude-agent-sdk-darwin-x64-0.3.238.tgz",
+      "integrity": "sha512-aDt8LXjWISwLzqeCBHxJC5AR1iVYlY5UYIm2VLztjI1U0PCb1BiH/IfyyjjizqRhhEwyQp9YAJeZZq8n/2vQEA==",
      "cpu": [
        "x64"
      ],
@@ -95,15 +95,12 @@
      ]
    },
    "node_modules/@anthropic-ai/claude-agent-sdk-linux-arm64": {
-      "version": "0.3.232",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-arm64/-/claude-agent-sdk-linux-arm64-0.3.232.tgz",
-      "integrity": "sha512-wW2opwA5s7gLghjU6B2ADMAtoc7bAZMevUzi4g+1PXMJ8MGcPvbnx92EDYJrVDcZmAl1+fz19XyPsaShlisTzw==",
+      "version": "0.3.238",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-arm64/-/claude-agent-sdk-linux-arm64-0.3.238.tgz",
+      "integrity": "sha512-P7V9TFokcNRdIJPUzDQ0GLBfMuoewWEH4rh6U3e7RaEAxzdeUcdS9P0N4arXqK2YAOtK1o93QSEtiGUF1fTfWw==",
      "cpu": [
        "arm64"
      ],
-      "libc": [
-        "glibc"
-      ],
      "license": "SEE LICENSE IN LICENSE.md",
      "optional": true,
      "os": [
@@ -111,15 +108,12 @@
      ]
    },
    "node_modules/@anthropic-ai/claude-agent-sdk-linux-arm64-musl": {
-      "version": "0.3.232",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-arm64-musl/-/claude-agent-sdk-linux-arm64-musl-0.3.232.tgz",
-      "integrity": "sha512-XkLcb9UT/l42Rtw7KBApzgxUe/kwoWJ9KCPcVEnYojzIvVR+AwBCl/QReNU5+6c72w48dYBMmLebI64gQbN0tg==",
+      "version": "0.3.238",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-arm64-musl/-/claude-agent-sdk-linux-arm64-musl-0.3.238.tgz",
+      "integrity": "sha512-ankSEMAMTVulKYg0NT8fZ7a5+q+aIzfiqhcrLe9zYPeuhE+lpNeq0JPMcHyOtUAENxVI0/2J2q5OXGl9O0qWcg==",
      "cpu": [
        "arm64"
      ],
-      "libc": [
-        "musl"
-      ],
      "license": "SEE LICENSE IN LICENSE.md",
      "optional": true,
      "os": [
@@ -127,15 +121,12 @@
      ]
    },
    "node_modules/@anthropic-ai/claude-agent-sdk-linux-x64": {
-      "version": "0.3.232",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-x64/-/claude-agent-sdk-linux-x64-0.3.232.tgz",
-      "integrity": "sha512-6Px1xDiwQyLkSxwRQ34/kPA8WMXQ2rHYGkwockND7+9yMw+ShI3AfLkyi9G7JtJHObWFT6B82eSHjDS/Fy+9hQ==",
+      "version": "0.3.238",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-x64/-/claude-agent-sdk-linux-x64-0.3.238.tgz",
+      "integrity": "sha512-/arAOSqtIAWDu7Z4Uf2Un3n+/5Zg3NpxZKzMQEDnYNkbJRhr44sM59TFaEOiWq1FqlUJKi6wHjgm+TW5B8DWWg==",
      "cpu": [
        "x64"
      ],
-      "libc": [
-        "glibc"
-      ],
      "license": "SEE LICENSE IN LICENSE.md",
      "optional": true,
      "os": [
@@ -143,15 +134,12 @@
      ]
    },
    "node_modules/@anthropic-ai/claude-agent-sdk-linux-x64-musl": {
-      "version": "0.3.232",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-x64-musl/-/claude-agent-sdk-linux-x64-musl-0.3.232.tgz",
-      "integrity": "sha512-L1x2ge9NpXMLTczmT44TKPQ88PHE+gsCakQMVEOa8rXFvfBoqvcpxM0DT8wrqYWUHhQEYR8NXxQTP9a1NVRj8Q==",
+      "version": "0.3.238",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-linux-x64-musl/-/claude-agent-sdk-linux-x64-musl-0.3.238.tgz",
+      "integrity": "sha512-buo3IBSd7EmYcQsH+OKARgNNbSF1+l/+z1hDXSXGKzwD1LFioJZ/k9FWWWC166SoQ93jPmN+G/ksTzEUB3zRGQ==",
      "cpu": [
        "x64"
      ],
-      "libc": [
-        "musl"
-      ],
      "license": "SEE LICENSE IN LICENSE.md",
      "optional": true,
      "os": [
@@ -159,9 +147,9 @@
      ]
    },
    "node_modules/@anthropic-ai/claude-agent-sdk-win32-arm64": {
-      "version": "0.3.232",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-win32-arm64/-/claude-agent-sdk-win32-arm64-0.3.232.tgz",
-      "integrity": "sha512-fDiuwL5dm1elOy7fNp4Qmdor8so4R8npj2pUGQA1G/xKfJhaK236aTWezvZid3L/O7cRdFeN9IVofOAlWLQcsw==",
+      "version": "0.3.238",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-win32-arm64/-/claude-agent-sdk-win32-arm64-0.3.238.tgz",
+      "integrity": "sha512-yW8lhV7QgYiNu3NatjgmkhUspgJsG2N2N6lmm/7B99sWFobKTbVLMLsXxj6A46R6qE2C4Zzm6PjxgGaMYOMn0g==",
      "cpu": [
        "arm64"
      ],
@@ -172,9 +160,9 @@
      ]
    },
    "node_modules/@anthropic-ai/claude-agent-sdk-win32-x64": {
-      "version": "0.3.232",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-win32-x64/-/claude-agent-sdk-win32-x64-0.3.232.tgz",
-      "integrity": "sha512-Hc/9uy1BI9mqKVyB1b/zoUnm3MFgtVNzQY6p5zgaq9DaIjCKDpR4a4L1aDZM4lMqUcWFMZM+u7juOhh+m39NBQ==",
+      "version": "0.3.238",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk-win32-x64/-/claude-agent-sdk-win32-x64-0.3.238.tgz",
+      "integrity": "sha512-6Fb2JRrBci282fBfhCGB0Tpq7N8V5HMMqsO3YGFkc9hhbn/y9G7glNKSNgRtxD5Ujjxj8rhiaYstXW2DJzanzw==",
      "cpu": [
        "x64"
      ],
@@ -185,9 +173,9 @@
      ]
    },
    "node_modules/@anthropic-ai/sdk": {
-      "version": "0.117.1",
-      "resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.117.1.tgz",
-      "integrity": "sha512-Yn2QlXfyCiKJ5YGCOOay7ZE78ISvII2XY621WMCiflmG8IYgwx59IBwPExxki3Xk9jKUtnD/Sj6UvplWr0rZxg==",
+      "version": "0.120.0",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.120.0.tgz",
+      "integrity": "sha512-ZlvmNFT/iIF6JD13rxbbMWD8nvGR0RaUp6yMQnoc+4Af0YjVVe/bIdW1XSQQsoxXAtg1NaT6Vak0LKFlJ4d37Q==",
      "license": "MIT",
      "dependencies": {
        "json-schema-to-ts": "^3.1.1",
@@ -343,9 +331,9 @@
      }
    },
    "node_modules/@hono/node-server": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-2.1.0.tgz",
-      "integrity": "sha512-XovyyCCnBzW+zKu+z/zq8hwNs4KOR5rEMAOxo2f40Q5xoOI37IMm6MIg2COOUtUApo0i6850MTBKH2u4QLGIqg==",
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-2.1.1.tgz",
+      "integrity": "sha512-ELuehkj5VCBdgEw9zs+ivkKwyzzUCSQuE96YmiPvn1ECBoZCczbFXJLeEGMTYjphP6gydh4pHMqEYPVMYUVgQg==",
      "license": "MIT",
      "peer": true,
      "engines": {
@@ -491,19 +479,36 @@
      }
    },
    "node_modules/@oxc-project/types": {
-      "version": "0.144.0",
-      "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.144.0.tgz",
-      "integrity": "sha512-nuhZIOLuI6TFQ32I/WnUx+SCPY7SdSKwgnFHydAuoS1+Z4BRcaP+RRJmGzl9lw+0OFF7UmaESf7KQRXaNLHypg==",
+      "version": "0.146.0",
+      "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.146.0.tgz",
+      "integrity": "sha512-XC0QsnnhVe7sLIWmYmdPw7x5P0h4W8vUU3Nv1ySgWXtvCz8NizoAEpGXA0sOYoJQV2Rl13LgURAHQ5cI5ILCSA==",
      "dev": true,
      "license": "MIT",
      "funding": {
        "url": "https://github.com/sponsors/Boshen"
      }
    },
+    "node_modules/@rolldown/binding-android-arm-eabi": {
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm-eabi/-/binding-android-arm-eabi-1.2.5.tgz",
+      "integrity": "sha512-DLe/i+l8ynIBY7XEQ191TeZvCoowIGa18R+dIV30GW7DiOtp74i/xX8hs8GUjW5ARV7VZuie3d6AumSmCwbeRA==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+      }
+    },
    "node_modules/@rolldown/binding-android-arm64": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.2.4.tgz",
-      "integrity": "sha512-jHC2cnyKz5xU2fhECtFl8OZ83cYNt13GZQD+0uMJ/X3o+ijmd56okHhTUwxVSHPx1IRVIJEZ1/1pPzeLCU6XKA==",
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.2.5.tgz",
+      "integrity": "sha512-zXcwKlQApYAOELHd8PwKDFkagYF9Wy4e0RJ+0qnzl9Pjnpj75TEG8ufv40p2J7kCEfwZAsNiuzRIyNNMWT38ig==",
      "cpu": [
        "arm64"
      ],
@@ -518,9 +523,9 @@
      }
    },
    "node_modules/@rolldown/binding-darwin-arm64": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.2.4.tgz",
-      "integrity": "sha512-Dc5mPD8F5F/FS8i01syd7FTF6yB2fVthH/TRkjwJkzUK6EpoxHtqvZQP5Zwq80/5z19TWYHIg1KOHboCgVx/aQ==",
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.2.5.tgz",
+      "integrity": "sha512-dK4QakI42nzWgJT5sm4y4y/O//D4OxM75/cH28RLV+nzIN9AY+YsbuUVrUTjlLjXR6vpyxFbSsbmNuJ6BP9sww==",
      "cpu": [
        "arm64"
      ],
@@ -535,9 +540,9 @@
      }
    },
    "node_modules/@rolldown/binding-darwin-x64": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.2.4.tgz",
-      "integrity": "sha512-fpDm4oBo6SqLvWUYCmFhdde3U9KH2fRNNMeAnAPAIwxRL345xutL0EtEUcuoxsoazdJGv/MuDBQHlCDrtbvqOg==",
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.2.5.tgz",
+      "integrity": "sha512-fqSALaUu1Wjd1nK2uW2kJDWdLCc8lx1IcY+MTY26Aurfdx19anlzhqXOgCFbBFQnlFDTn4TC1/7Nz4Bl2mLP3A==",
      "cpu": [
        "x64"
      ],
@@ -552,9 +557,9 @@
      }
    },
    "node_modules/@rolldown/binding-freebsd-x64": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.2.4.tgz",
-      "integrity": "sha512-rSJoreDE/HoIzoaib6MTp5jQtCTdMHKIvItAKT/ImS6Y6Ww76oUaeMyp4Vc/fAgd/ehji068IxetHXAnqUwN9A==",
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.2.5.tgz",
+      "integrity": "sha512-/vCnNxlkxs9tKxNDcyWUePpJ/PgTzxIaVhoM5SmG8UV+GR/IcPam4VYxi7GIMo7PSDuNqlJqvprqii9NqqVCMw==",
      "cpu": [
        "x64"
      ],
@@ -569,9 +574,9 @@
      }
    },
    "node_modules/@rolldown/binding-linux-arm-gnueabihf": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.2.4.tgz",
-      "integrity": "sha512-/jm8OGHgn7oGaJu3i/qZI9spUGcJ+y/lk43ttQ/iO1tOd9NissG6o97bighBCiL+BKRngmcDuR6ikfwYdJmVuQ==",
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.2.5.tgz",
+      "integrity": "sha512-abk0NLA519LxRCszmbE0jYKuQ9YPocOXTiOXOo6Yr+YAT95VH+PtqYAjOJvGKt3viEd/x4qzabAlwd5bHOOARg==",
      "cpu": [
        "arm"
      ],
@@ -586,16 +591,13 @@
      }
    },
    "node_modules/@rolldown/binding-linux-arm64-gnu": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.2.4.tgz",
-      "integrity": "sha512-tIP06BeD9EqvECBrPZ+sqdPlYrT+aYaAiu1wYziVx5elRK/ftm33JxVDy2bXGbr6J0CrtirCkR87/X5a2euEng==",
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.2.5.tgz",
+      "integrity": "sha512-Y7eALiJ8lr0M2HH103Js+g7V34wf6snlpZLAsHI90uLhr3PVlNsbFVAXJC9d/V6BnPyKtpSwI+NcB/RLxsQxuA==",
      "cpu": [
        "arm64"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -606,16 +608,13 @@
      }
    },
    "node_modules/@rolldown/binding-linux-arm64-musl": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.2.4.tgz",
-      "integrity": "sha512-Ql1Q0EQqVThvn9VAVlwNzsUvbSFtCMGjLpRRi4pk5i7NZZ4n5ISiLMjHYtus4VQ2PvkSw24zyaCVsiS+sXPj1w==",
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.2.5.tgz",
+      "integrity": "sha512-xMvZgnbZg4YVnR/AX2b3oOPDTFYJvUVaJg5FedA/LuvexAtXibZQej4cnTkw3rjsJ/ggUROB64TdtETiim+FYA==",
      "cpu": [
        "arm64"
      ],
      "dev": true,
-      "libc": [
-        "musl"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -626,16 +625,13 @@
      }
    },
    "node_modules/@rolldown/binding-linux-ppc64-gnu": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.2.4.tgz",
-      "integrity": "sha512-GjbjXD4XXfN19D0LZNbmiCBUoDiRACsYHr0yaIbbn8aFsXjHZifcYqu/W5Er5X2X990WjHXFrxarn5chzItorQ==",
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.2.5.tgz",
+      "integrity": "sha512-GRjeqTUDHTo5GwntsLaAMcBahG3nlpjftXWZLN73HiYQlhwEowvarFgQnRnQZtIp4keXX7quXFbG38uPZBa2EA==",
      "cpu": [
        "ppc64"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -646,16 +642,13 @@
      }
    },
    "node_modules/@rolldown/binding-linux-s390x-gnu": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.2.4.tgz",
-      "integrity": "sha512-p5WR0NOwaRmJ/B1b6IjEFLLivwEsf3PrdBIhRbhTCQisbo2SvHHpG4ELB/+FgQNnB88LTOF86upmJmbvZdQ2lw==",
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.2.5.tgz",
+      "integrity": "sha512-vLNTR45F2Uwc8AufkNXPmB4VliaXs+FvcheEogIzOXzO4l+LzieXF5A/TWxLy5HtqpsRCHUfd0lPVrrdgXdLHQ==",
      "cpu": [
        "s390x"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -666,16 +659,13 @@
      }
    },
    "node_modules/@rolldown/binding-linux-x64-gnu": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.2.4.tgz",
-      "integrity": "sha512-4/GyVjmhR+Tc6HLJvwc1sOhPqAZtySiSMesOZyX6JQ5XBxoTDEMKQzvo07NIK6nTon/SivlZqvhzvuVBNQhObQ==",
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.2.5.tgz",
+      "integrity": "sha512-Mgj59/HTuYeK9Gz2MA+mBWKnHsAgkBSec15ZMb1st3oIfFbX7gCjOae7GydHhzcyQi9Z/7M1QuN9bR3oFqF0jQ==",
      "cpu": [
        "x64"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -686,16 +676,13 @@
      }
    },
    "node_modules/@rolldown/binding-linux-x64-musl": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.2.4.tgz",
-      "integrity": "sha512-l9eeLsCNvPpmSXUej0etw/J1eqV0Jj1D5G/xG6YTijmE6dkv6E2QezgWbTfQk63v952DPqrjOCoiqxq7Bw0YUQ==",
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.2.5.tgz",
+      "integrity": "sha512-mY8AP0/ichsbhAxGnLa3d3+MwV0EfgrPND2bplI3Ym8T6R2pJ0N87bvrKVwNXmdy3jnr6eQBecdqx/HMknBmpA==",
      "cpu": [
        "x64"
      ],
      "dev": true,
-      "libc": [
-        "musl"
-      ],
      "license": "MIT",
      "optional": true,
      "os": [
@@ -706,9 +693,9 @@
      }
    },
    "node_modules/@rolldown/binding-openharmony-arm64": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.2.4.tgz",
-      "integrity": "sha512-e0F355MSTMm3+UOqtV3L24gFUp2N5m1f8L/7d56deik6va+AXdrt9F8LbzGpeWGWRbZEDq4m8NVnJDeBtf9DZg==",
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.2.5.tgz",
+      "integrity": "sha512-8SLssA2oweAxyRgDp789ACfRb/3P+zNRJpzZxSizxF9m8NUDQ4+3xjo8ttjhVGGw6Qxb70oZiEtIjaKikCO7Yw==",
      "cpu": [
        "arm64"
      ],
@@ -723,9 +710,9 @@
      }
    },
    "node_modules/@rolldown/binding-win32-arm64-msvc": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.2.4.tgz",
-      "integrity": "sha512-AWLi0uBRYh6QlE7OKhiz+phZC0qwtij2QZmhmOdsLdFn64m7oMpooE9ICE3lhm9xMb4SpDo2WbHcxX1iFLFtqw==",
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.2.5.tgz",
+      "integrity": "sha512-vGbruD5zquhoc8D9SViXgN2FBJtNdTyQ4DtG+SWiEGlJiAzoKcZ2xp+xuXCffhubVdt0NJlTZqkeRuERy7g8Cw==",
      "cpu": [
        "arm64"
      ],
@@ -740,9 +727,9 @@
      }
    },
    "node_modules/@rolldown/binding-win32-x64-msvc": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.2.4.tgz",
-      "integrity": "sha512-UwSDJOg3dqCAejWdxclJjCsh3Qq4vLYMDxmyHqo1btz3stK2VqgwNd3mm5tuIwzSlGIQ/1H9Hr+Zn09mrezNqQ==",
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.2.5.tgz",
+      "integrity": "sha512-e/SXpgISz+IoqVcSSI0rx/d/he8zqLex+/rCWpnHpmVfmPIUjag9H6P7zotf0gJHwPUhQxZ/mF8tr6acebT9yw==",
      "cpu": [
        "x64"
      ],
@@ -777,9 +764,9 @@
      "license": "MIT"
    },
    "node_modules/@tsconfig/node10": {
-      "version": "1.0.12",
-      "resolved": "https://registry.npmjs.org/@tsconfig/node10/-/node10-1.0.12.tgz",
-      "integrity": "sha512-UCYBaeFvM11aU2y3YPZ//O5Rhj+xKyzy7mvcIoAjASbigy8mHMryP5cK7dgjlz2hWxh1g5pLw084E0a/wlUSFQ==",
+      "version": "1.0.13",
+      "resolved": "https://registry.npmjs.org/@tsconfig/node10/-/node10-1.0.13.tgz",
+      "integrity": "sha512-gcLdvR9HO1ZJBypsOGqaP6TFEzb6vIta0KSTLt9NAQ6pXQO3cRgSVyCN6pzYqI9DlJgY71XKO0dpDhCf08b3pg==",
      "dev": true,
      "license": "MIT"
    },
@@ -805,9 +792,9 @@
      "license": "MIT"
    },
    "node_modules/@tsconfig/node22": {
-      "version": "22.0.5",
-      "resolved": "https://registry.npmjs.org/@tsconfig/node22/-/node22-22.0.5.tgz",
-      "integrity": "sha512-hLf2ld+sYN/BtOJjHUWOk568dvjFQkHnLNa6zce25GIH+vxKfvTgm3qpaH6ToF5tu/NN0IH66s+Bb5wElHrLcw==",
+      "version": "22.0.6",
+      "resolved": "https://registry.npmjs.org/@tsconfig/node22/-/node22-22.0.6.tgz",
+      "integrity": "sha512-/5thavHAnWDZwH2H6eEn/T8pBEBhtuKaWGMslsj82kJfvzQgOgEMK7X4goBbIUjgVtAzPTtM9Ml64LA0uxO6Iw==",
      "dev": true,
      "license": "MIT"
    },
@@ -1094,16 +1081,16 @@
      }
    },
    "node_modules/@vitest/expect": {
-      "version": "4.1.10",
-      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.10.tgz",
-      "integrity": "sha512-YsCn+qAk1GWjQOWFEsEcL2gNQ0zmVmQu3T03qP6UyjhtmdtwtbuI+DASn/7iQB3HGTXkdBwGddzxPlmiql5vlA==",
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.1.11.tgz",
+      "integrity": "sha512-VX2x5vNJXET47KAFzwERI+KRMtTTCSWTfSMKsW7JsUsXV4psq++e3DvZpuTDOpHcxytiDs6p2nhVb2tVDiiUYw==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
        "@standard-schema/spec": "^1.1.0",
        "@types/chai": "^5.2.2",
-        "@vitest/spy": "4.1.10",
-        "@vitest/utils": "4.1.10",
+        "@vitest/spy": "4.1.11",
+        "@vitest/utils": "4.1.11",
        "chai": "^6.2.2",
        "tinyrainbow": "^3.1.0"
      },
@@ -1112,13 +1099,13 @@
      }
    },
    "node_modules/@vitest/mocker": {
-      "version": "4.1.10",
-      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.10.tgz",
-      "integrity": "sha512-v0xaezt+DKEmKfaxg133ldzADrwLGd7Ze1MfQQTYfvs8OqZIwbxyxaYURivwV7sWy5fqn3rH5uOrSp07bp44Ow==",
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.1.11.tgz",
+      "integrity": "sha512-2XJVD55d1o5AZous5CCGKS74g/riOj9odEt2bQpCVZeblHyHdnMeFl4jl0XjU21stf4mbjUkew2eXQZt65g5CQ==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@vitest/spy": "4.1.10",
+        "@vitest/spy": "4.1.11",
        "estree-walker": "^3.0.3",
        "magic-string": "^0.30.21"
      },
@@ -1139,9 +1126,9 @@
      }
    },
    "node_modules/@vitest/pretty-format": {
-      "version": "4.1.10",
-      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.10.tgz",
-      "integrity": "sha512-W1HsjSH4MXQ9YfmmhLAoIYf1HRfekQCGngeIgcei6MP5QQGWUe0gkopdZQaVCFO+JDJMrAJGwa5pRpNpvy4P8Q==",
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.1.11.tgz",
+      "integrity": "sha512-yiZzPbGTS9Sr/JpFl8zHrcIkAofNbFV6k21vIgQN/cY/oxZeXhJv5sc/MBJ5jFKWmWs+oJHw0UXLZjmf931+Vw==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
@@ -1152,13 +1139,13 @@
      }
    },
    "node_modules/@vitest/runner": {
-      "version": "4.1.10",
-      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.10.tgz",
-      "integrity": "sha512-IKI6kpIH+LmpROplyLwBBaCfMgOZOMsygVa6BARD6ahA04VRuJSa6OaVG7kRvSEMD870Vd91rSSw0eegtWyLGg==",
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.1.11.tgz",
+      "integrity": "sha512-LztvUgdwMNJMIkj3hQnnxiC2Xy1zNxq928W/xhjCLaNCzqTZOudjwbQf6v9IntZGPw132i2Lq2rgTRZHD3JHNw==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@vitest/utils": "4.1.10",
+        "@vitest/utils": "4.1.11",
        "pathe": "^2.0.3"
      },
      "funding": {
@@ -1166,14 +1153,14 @@
      }
    },
    "node_modules/@vitest/snapshot": {
-      "version": "4.1.10",
-      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.10.tgz",
-      "integrity": "sha512-xRkfOT1qpTAi/Ti4Y1LtfRc3kEuqxGw59eN2jN9pRWMtS/XDevekhcFSqvQqjUNGksfjMJu3Y+oJ+4Ypn2OaJw==",
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.1.11.tgz",
+      "integrity": "sha512-pN7ikn1ON7h8ee4gIAp4AzyK+zBtJPzVbqOgu5LCEh4VaJVbPQcgYQYJIMGQPXVeJJq1fnfazis7a5pFNPahog==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@vitest/pretty-format": "4.1.10",
-        "@vitest/utils": "4.1.10",
+        "@vitest/pretty-format": "4.1.11",
+        "@vitest/utils": "4.1.11",
        "magic-string": "^0.30.21",
        "pathe": "^2.0.3"
      },
@@ -1182,9 +1169,9 @@
      }
    },
    "node_modules/@vitest/spy": {
-      "version": "4.1.10",
-      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.10.tgz",
-      "integrity": "sha512-PLf/Ugvoq5wO/b4rwYCR1h2PSIdXz7wnkQFMiUpLdtM7l6pqVFcQIBEHyT1+l+cj7mNwAfZHzqXqDyjvOuwbDw==",
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.1.11.tgz",
+      "integrity": "sha512-apNa/prQy2qCeywhnixOHPRCgGNhvg7T4Dapfl1GahLp/R+uhBm5cPyFoNVyqsNd2h1nJxL6BqqdIjiABL60YA==",
      "dev": true,
      "license": "MIT",
      "funding": {
@@ -1192,13 +1179,13 @@
      }
    },
    "node_modules/@vitest/utils": {
-      "version": "4.1.10",
-      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.10.tgz",
-      "integrity": "sha512-fy9am/HWxbaGt/Sawrp90vt6Y6jQwf1RX77cz3uwoJwJVMli/e1IEwRPnMNJ7vKfPTwo0diXifkpPvwH9v7nGA==",
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.1.11.tgz",
+      "integrity": "sha512-zTCVGpyFsGWBhllOyKlTw/vnr6D9qxsfSDyfbyZmTyjHw5N/VuvzHpHoQjm2ZJzn4RJgx5w4r7V0er69CmLgPQ==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@vitest/pretty-format": "4.1.10",
+        "@vitest/pretty-format": "4.1.11",
        "convert-source-map": "^2.0.0",
        "tinyrainbow": "^3.1.0"
      },
@@ -1618,9 +1605,9 @@
      }
    },
    "node_modules/es-module-lexer": {
-      "version": "2.3.1",
-      "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.3.1.tgz",
-      "integrity": "sha512-shc1dbU90Yl/xq1QrC7QRtfcwURZuVRfPhZbDoldJ1cn1gzDvBaBWlv0eFolj5+0znnPJz5TXLxsN77X/12KTA==",
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/es-module-lexer/-/es-module-lexer-2.3.2.tgz",
+      "integrity": "sha512-poHGpORABojJJucnV9KbOavETW8lBVnphkW77ER5/BQ5Fz7oXSoCNek7IH3vR5nRjdsEz926ibFYX8KtLQmdyw==",
      "dev": true,
      "license": "MIT"
    },
@@ -2420,9 +2407,9 @@
      "license": "ISC"
    },
    "node_modules/jose": {
-      "version": "6.2.8",
-      "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.8.tgz",
-      "integrity": "sha512-Bsdjwm3Qsd/P0jR+BHDe3LytDfY7WBq2HmCCLIwuVRHMuEC9ae7/R474GIUdF1NgCyZjzVo/A9DOiOBtXq8ZoQ==",
+      "version": "6.2.9",
+      "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.9.tgz",
+      "integrity": "sha512-XrchZOFZUl/T3vTwRe8XK+cJrGtMF4th1ARnDfwbBXFKThGhlsxEE4Zu03AD/bjJSt/9jT/mxrOCkJWOg77aPA==",
      "license": "MIT",
      "peer": true,
      "funding": {
@@ -2637,9 +2624,6 @@
        "arm64"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "MPL-2.0",
      "optional": true,
      "os": [
@@ -2661,9 +2645,6 @@
        "arm64"
      ],
      "dev": true,
-      "libc": [
-        "musl"
-      ],
      "license": "MPL-2.0",
      "optional": true,
      "os": [
@@ -2685,9 +2666,6 @@
        "x64"
      ],
      "dev": true,
-      "libc": [
-        "glibc"
-      ],
      "license": "MPL-2.0",
      "optional": true,
      "os": [
@@ -2709,9 +2687,6 @@
        "x64"
      ],
      "dev": true,
-      "libc": [
-        "musl"
-      ],
      "license": "MPL-2.0",
      "optional": true,
      "os": [
@@ -3246,13 +3221,13 @@
      }
    },
    "node_modules/rolldown": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.2.4.tgz",
-      "integrity": "sha512-rSr7irW0K7QRWzjdJXqZowkcRdDtjRduh43rBltnVKd0VFq839l1lJoDvGJb6gl7+4rTTCrPWu+YfujUL8Ug7w==",
+      "version": "1.2.5",
+      "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.2.5.tgz",
+      "integrity": "sha512-VD2IE5PUG4Oj8zz2VGykiYd5wbnjdIiSsNQb8Qu5B+noEp+A78mu2iVvpp27g8es14Tk9rofNs5Tku9iQCS4fA==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@oxc-project/types": "=0.144.0",
+        "@oxc-project/types": "=0.146.0",
        "@rolldown/pluginutils": "^1.0.0"
      },
      "bin": {
@@ -3262,20 +3237,21 @@
        "node": "^20.19.0 || >=22.12.0"
      },
      "optionalDependencies": {
-        "@rolldown/binding-android-arm64": "1.2.4",
-        "@rolldown/binding-darwin-arm64": "1.2.4",
-        "@rolldown/binding-darwin-x64": "1.2.4",
-        "@rolldown/binding-freebsd-x64": "1.2.4",
-        "@rolldown/binding-linux-arm-gnueabihf": "1.2.4",
-        "@rolldown/binding-linux-arm64-gnu": "1.2.4",
-        "@rolldown/binding-linux-arm64-musl": "1.2.4",
-        "@rolldown/binding-linux-ppc64-gnu": "1.2.4",
-        "@rolldown/binding-linux-s390x-gnu": "1.2.4",
-        "@rolldown/binding-linux-x64-gnu": "1.2.4",
-        "@rolldown/binding-linux-x64-musl": "1.2.4",
-        "@rolldown/binding-openharmony-arm64": "1.2.4",
-        "@rolldown/binding-win32-arm64-msvc": "1.2.4",
-        "@rolldown/binding-win32-x64-msvc": "1.2.4"
+        "@rolldown/binding-android-arm-eabi": "1.2.5",
+        "@rolldown/binding-android-arm64": "1.2.5",
+        "@rolldown/binding-darwin-arm64": "1.2.5",
+        "@rolldown/binding-darwin-x64": "1.2.5",
+        "@rolldown/binding-freebsd-x64": "1.2.5",
+        "@rolldown/binding-linux-arm-gnueabihf": "1.2.5",
+        "@rolldown/binding-linux-arm64-gnu": "1.2.5",
+        "@rolldown/binding-linux-arm64-musl": "1.2.5",
+        "@rolldown/binding-linux-ppc64-gnu": "1.2.5",
+        "@rolldown/binding-linux-s390x-gnu": "1.2.5",
+        "@rolldown/binding-linux-x64-gnu": "1.2.5",
+        "@rolldown/binding-linux-x64-musl": "1.2.5",
+        "@rolldown/binding-openharmony-arm64": "1.2.5",
+        "@rolldown/binding-win32-arm64-msvc": "1.2.5",
+        "@rolldown/binding-win32-x64-msvc": "1.2.5"
      }
    },
    "node_modules/router": {
@@ -3739,16 +3715,16 @@
      }
    },
    "node_modules/vite": {
-      "version": "8.2.1",
-      "resolved": "https://registry.npmjs.org/vite/-/vite-8.2.1.tgz",
-      "integrity": "sha512-EU/eS7BH3XROHh2YnBefjM6DBKA6ZeMZEYQbj7NLWg5wHYlhB8B/Mayd5XsgWq+NFYccDOTemRpdETWR6Ka/lw==",
+      "version": "8.2.2",
+      "resolved": "https://registry.npmjs.org/vite/-/vite-8.2.2.tgz",
+      "integrity": "sha512-cFKLV/PRgAUlIRm5WjMjJ86jrftzpqcgH+Us+DS8mI3CDNiH30Whrz8uHL3+MOLPAgqbMBAqWdAHAphOAM+z/Q==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
        "lightningcss": "^1.33.0",
        "picomatch": "^4.0.5",
-        "postcss": "^8.5.25",
-        "rolldown": "~1.2.1",
+        "postcss": "^8.5.26",
+        "rolldown": "~1.2.4",
        "tinyglobby": "^0.2.17"
      },
      "bin": {
@@ -3765,7 +3741,7 @@
      },
      "peerDependencies": {
        "@types/node": "^20.19.0 || >=22.12.0",
-        "@vitejs/devtools": "^0.4.0",
+        "@vitejs/devtools": "^0.4.0 || ^0.5.0",
        "esbuild": "^0.27.0 || ^0.28.0",
        "jiti": ">=1.21.0",
        "less": "^4.0.0",
@@ -3817,19 +3793,19 @@
      }
    },
    "node_modules/vitest": {
-      "version": "4.1.10",
-      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.10.tgz",
-      "integrity": "sha512-R9jUTe5S4Qb0HCd4TNqpC7oGcrMssMRGXLW80ubjWsW9VH5GF8y1Y0SFLY9AbqSk6nt0PnOx4H4WNJYZ13GUPw==",
+      "version": "4.1.11",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.1.11.tgz",
+      "integrity": "sha512-fhACrNXUidIbGSBr5FlbuBkO7VWC1ZyLl0DO4CU2DrQoAPxX84Ysxs+HeGQpii5lZWV1Q4gBZTTu49mF+A6Edw==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "@vitest/expect": "4.1.10",
-        "@vitest/mocker": "4.1.10",
-        "@vitest/pretty-format": "4.1.10",
-        "@vitest/runner": "4.1.10",
-        "@vitest/snapshot": "4.1.10",
-        "@vitest/spy": "4.1.10",
-        "@vitest/utils": "4.1.10",
+        "@vitest/expect": "4.1.11",
+        "@vitest/mocker": "4.1.11",
+        "@vitest/pretty-format": "4.1.11",
+        "@vitest/runner": "4.1.11",
+        "@vitest/snapshot": "4.1.11",
+        "@vitest/spy": "4.1.11",
+        "@vitest/utils": "4.1.11",
        "es-module-lexer": "^2.0.0",
        "expect-type": "^1.3.0",
        "magic-string": "^0.30.21",
@@ -3857,12 +3833,12 @@
        "@edge-runtime/vm": "*",
        "@opentelemetry/api": "^1.9.0",
        "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",
-        "@vitest/browser-playwright": "4.1.10",
-        "@vitest/browser-preview": "4.1.10",
-        "@vitest/browser-webdriverio": "4.1.10",
-        "@vitest/coverage-istanbul": "4.1.10",
-        "@vitest/coverage-v8": "4.1.10",
-        "@vitest/ui": "4.1.10",
+        "@vitest/browser-playwright": "4.1.11",
+        "@vitest/browser-preview": "4.1.11",
+        "@vitest/browser-webdriverio": "4.1.11",
+        "@vitest/coverage-istanbul": "4.1.11",
+        "@vitest/coverage-v8": "4.1.11",
+        "@vitest/ui": "4.1.11",
        "happy-dom": "*",
        "jsdom": "*",
        "vite": "^6.0.0 || ^7.0.0 || ^8.0.0"
--- a/package.json
+++ b/package.json
@@ -3,7 +3,7 @@
  "publishConfig": {
    "access": "public"
  },
-  "version": "0.67.0",
+  "version": "0.71.0",
  "description": "An ACP-compatible coding agent powered by the Claude Agent SDK (TypeScript)",
  "main": "dist/lib.js",
  "types": "dist/lib.d.ts",
@@ -66,13 +66,13 @@
  },
  "dependencies": {
    "@agentclientprotocol/sdk": "1.3.0",
-    "@anthropic-ai/claude-agent-sdk": "0.3.232",
-    "zod": "^3.25.0 || ^4.0.0"
+    "@anthropic-ai/claude-agent-sdk": "0.3.238",
+    "zod": "^4.0.0"
  },
  "devDependencies": {
-    "@anthropic-ai/sdk": "0.117.1",
+    "@anthropic-ai/sdk": "0.120.0",
    "@eslint/js": "10.0.1",
-    "@tsconfig/node22": "22.0.5",
+    "@tsconfig/node22": "22.0.6",
    "@types/node": "26.2.0",
    "@typescript-eslint/eslint-plugin": "8.67.0",
    "@typescript-eslint/parser": "8.67.0",
@@ -82,6 +82,6 @@
    "prettier": "3.9.6",
    "ts-node": "10.9.2",
    "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "vitest": "4.1.11"
  }
 }
--- a/src/acp-agent.ts
+++ b/src/acp-agent.ts
--- a/src/acp-subagents.ts
+++ b/src/acp-subagents.ts
@@ -0,0 +1,118 @@
+import type {
+  ClientCapabilities,
+  SessionCapabilities,
+  SessionNotification,
+} from "@agentclientprotocol/sdk";
+import {
+  AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY,
+  clientSupportsAirCapability,
+} from "./air-extension.js";
+
+export { AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY } from "./air-extension.js";
+
+/**
+ * Temporary typed surface for agentclientprotocol/agent-client-protocol#1992.
+ *
+ * The wire contract is already defined by the ACP draft, but the published
+ * TypeScript SDK does not contain it yet. Keep the compatibility boundary in
+ * this file so it can be replaced by SDK exports without changing lifecycle
+ * code when the draft ships.
+ */
+export type SubagentSessionCapabilities = {
+  cancel?: boolean;
+  close?: boolean;
+  _meta?: Record<string, unknown> | null;
+};
+
+export type SubagentSpawnedUpdate = {
+  sessionUpdate: "subagent_spawned";
+  subagentSessionId: string;
+  name: string;
+  task: string;
+  capabilities: SubagentSessionCapabilities;
+  _meta?: Record<string, unknown> | null;
+};
+
+export type SubagentState = "completed" | "failed" | "cancelled" | "disconnected";
+
+export type SubagentStateUpdate = {
+  sessionUpdate: "subagent_state_update";
+  subagentSessionId: string;
+  state: SubagentState;
+  _meta?: Record<string, unknown> | null;
+};
+
+export type AsyncTaskState = "running" | "paused" | "completed" | "failed" | "stopped";
+
+export type AsyncTaskSpawnedUpdate = {
+  sessionUpdate: "async_task_spawned";
+  asyncTaskId: string;
+  name: string;
+  taskType: string;
+  description: string;
+  showInTranscript: boolean;
+  canStop: boolean;
+  outputFilePath?: string;
+  toolCallId?: string;
+  _meta?: Record<string, unknown> | null;
+};
+
+export type AsyncTaskProgressUpdate = {
+  sessionUpdate: "async_task_progress";
+  asyncTaskId: string;
+  description?: string;
+  summary?: string;
+  lastToolName?: string;
+  usage?: { totalTokens: number; toolUses: number; durationMs: number };
+  /** Latest durable task log path. May arrive after spawn. */
+  outputFilePath?: string;
+  /** Originating tool call, when correlation becomes known after spawn. */
+  toolCallId?: string;
+  _meta?: Record<string, unknown> | null;
+};
+
+export type AsyncTaskStateUpdate = {
+  sessionUpdate: "async_task_state_update";
+  asyncTaskId: string;
+  state: AsyncTaskState;
+  summary?: string;
+  /** Latest durable task log path, including terminal-only SDK reports. */
+  outputFilePath?: string;
+  /** Originating tool call, including terminal-only late correlation. */
+  toolCallId?: string;
+  _meta?: Record<string, unknown> | null;
+};
+
+export type AcpSessionUpdate =
+  | SessionNotification["update"]
+  | SubagentSpawnedUpdate
+  | SubagentStateUpdate
+  | AsyncTaskSpawnedUpdate
+  | AsyncTaskProgressUpdate
+  | AsyncTaskStateUpdate;
+
+export type AcpSessionNotification = Omit<SessionNotification, "update"> & {
+  update: AcpSessionUpdate;
+};
+
+export type SubagentAwareSessionCapabilities = SessionCapabilities & {
+  subagents?: Record<string, never>;
+};
+
+export function clientSupportsSubagents(capabilities?: ClientCapabilities | null): boolean {
+  const subagents = (
+    capabilities as (ClientCapabilities & { subagents?: unknown }) | null | undefined
+  )?.subagents;
+  if (typeof subagents === "object" && subagents !== null && !Array.isArray(subagents)) {
+    return true;
+  }
+
+  return clientSupportsAirCapability(capabilities, AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY);
+}
+
+/** The only cast needed until the TypeScript SDK publishes PR #1992. */
+export function asSdkSessionNotification(
+  notification: AcpSessionNotification,
+): SessionNotification {
+  return notification as SessionNotification;
+}
--- a/src/air-extension.ts
+++ b/src/air-extension.ts
@@ -0,0 +1,75 @@
+export const AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY = "nativeSubagentSessions";
+export const AIR_ASYNC_TASKS_CAPABILITY = "asyncTasks";
+export const AIR_SESSION_FAILURE_CAPABILITY = "sessionFailure";
+
+const JETBRAINS_META_KEY = "jetbrains";
+const AIR_META_KEY = "air";
+const AIR_EXTENSION_VERSION_KEY = "version";
+const AIR_EXTENSION_CAPABILITIES_KEY = "capabilities";
+const AIR_EXTENSION_VERSION = 1;
+
+/** The capability list this side advertises, as its own `_meta` object. */
+export function airCapabilityMeta(...capabilities: string[]) {
+  return withAirMeta(undefined, AIR_EXTENSION_CAPABILITIES_KEY, capabilities);
+}
+
+/**
+ * Merges one AIR extension payload into an existing `_meta`.
+ *
+ * Every other namespace is preserved: an update can carry both agent-native
+ * `claudeCode` metadata and an AIR payload, and two AIR payloads can share the
+ * same `air` object. Pass `undefined` to build a fresh `_meta`.
+ */
+export function withAirMeta(
+  meta: Record<string, unknown> | null | undefined,
+  capability: string,
+  payload: unknown,
+): Record<string, unknown> {
+  const jetbrains = asRecord(meta?.[JETBRAINS_META_KEY]);
+  const air = asRecord(jetbrains[AIR_META_KEY]);
+  return {
+    ...meta,
+    [JETBRAINS_META_KEY]: {
+      ...jetbrains,
+      [AIR_META_KEY]: {
+        ...air,
+        [AIR_EXTENSION_VERSION_KEY]: AIR_EXTENSION_VERSION,
+        [capability]: payload,
+      },
+    },
+  };
+}
+
+/** The `air` object inside a `_meta`, or undefined when the peer sent no AIR extension. */
+export function airExtensionMeta(meta: unknown): Record<string, unknown> | undefined {
+  const air = asRecord(asRecord(meta)[JETBRAINS_META_KEY])[AIR_META_KEY];
+  return air && typeof air === "object" && !Array.isArray(air)
+    ? (air as Record<string, unknown>)
+    : undefined;
+}
+
+/**
+ * Whether the peer advertised `capability`.
+ *
+ * Takes `unknown` because every caller is reading wire data: an ACP
+ * `ClientCapabilities`, or a bag whose `_meta` was never validated.
+ */
+export function clientSupportsAirCapability(capabilities: unknown, capability: string): boolean {
+  const air = airExtensionMeta(asRecord(capabilities)._meta);
+  const version = air?.[AIR_EXTENSION_VERSION_KEY];
+  const advertised = air?.[AIR_EXTENSION_CAPABILITIES_KEY];
+  return (
+    typeof version === "number" &&
+    Number.isFinite(version) &&
+    Number.isInteger(version) &&
+    version >= AIR_EXTENSION_VERSION &&
+    Array.isArray(advertised) &&
+    advertised.includes(capability)
+  );
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
--- a/src/async-tasks.ts
+++ b/src/async-tasks.ts
@@ -0,0 +1,757 @@
+import type { ClientCapabilities } from "@agentclientprotocol/sdk";
+import type { AcpSessionNotification, AsyncTaskState } from "./acp-subagents.js";
+import { AIR_ASYNC_TASKS_CAPABILITY, clientSupportsAirCapability } from "./air-extension.js";
+
+type Publish = (notification: AcpSessionNotification) => Promise<void>;
+type TerminalSource = "event" | "level" | "shutdown";
+
+type AsyncTask = {
+  id: string;
+  name: string;
+  taskType: string;
+  description: string;
+  showInTranscript: boolean;
+  outputFilePath?: string;
+  toolCallId?: string;
+  announced: boolean;
+  ignored: boolean;
+  startedObserved: boolean;
+  panelOnlyRecovery: boolean;
+  stopping: boolean;
+  stopAnnounced: boolean;
+  state: AsyncTaskState;
+  terminalSummary?: string;
+  terminalSource?: TerminalSource;
+};
+
+type TaskIdentity = { taskId?: unknown; task_id?: unknown };
+
+export type AsyncTaskStarted = TaskIdentity & {
+  taskType?: unknown;
+  task_type?: unknown;
+  description?: unknown;
+  subagentType?: unknown;
+  subagent_type?: unknown;
+  isBackgrounded?: unknown;
+  is_backgrounded?: unknown;
+  workflowName?: unknown;
+  workflow_name?: unknown;
+  skipTranscript?: unknown;
+  skip_transcript?: unknown;
+  outputFilePath?: unknown;
+  output_file?: unknown;
+  toolCallId?: unknown;
+  tool_use_id?: unknown;
+};
+
+export type AsyncTaskUpdated = TaskIdentity & { patch?: TaskPatch };
+
+type TaskPatch = {
+  status?: unknown;
+  description?: unknown;
+  isBackgrounded?: unknown;
+  is_backgrounded?: unknown;
+  error?: unknown;
+  outputFilePath?: unknown;
+  output_file?: unknown;
+};
+
+export type AsyncTaskNotification = TaskIdentity & {
+  status?: unknown;
+  summary?: unknown;
+  outputFilePath?: unknown;
+  output_file?: unknown;
+};
+
+type TaskProgress = TaskIdentity & {
+  description?: unknown;
+  summary?: unknown;
+  lastToolName?: unknown;
+  last_tool_name?: unknown;
+  usage?: unknown;
+  outputFilePath?: unknown;
+  output_file?: unknown;
+};
+
+type BackgroundTaskLevel = TaskIdentity & {
+  taskType?: unknown;
+  task_type?: unknown;
+  description?: unknown;
+};
+
+export function clientSupportsAsyncTasks(capabilities?: ClientCapabilities | null): boolean {
+  return clientSupportsAirCapability(capabilities, AIR_ASYNC_TASKS_CAPABILITY);
+}
+
+/** Publishes Claude's non-agent background work as a separate AIR task lifecycle. */
+export class AsyncTaskRuntime {
+  /**
+   * One registry owns both active tasks and terminal tombstones. Keeping an
+   * unannounced terminal record is intentional: the Bash result proving that
+   * a command was backgrounded can arrive after its terminal SDK edge.
+   */
+  private readonly tasks = new Map<string, AsyncTask>();
+
+  constructor(
+    readonly enabled: boolean,
+    private readonly sessionId: string,
+    private readonly publish: Publish,
+  ) {}
+
+  async taskStarted(message: AsyncTaskStarted): Promise<void> {
+    if (!this.enabled) return;
+    const taskId = taskIdOf(message);
+    if (!taskId) return;
+    const task = this.task(taskId);
+    if (isSubagentTask(message)) {
+      task.ignored = true;
+      return;
+    }
+
+    const previousOutputFilePath = task.outputFilePath;
+    const previousToolCallId = task.toolCallId;
+    const wasAnnounced = task.announced;
+    this.mergeStarted(task, message);
+    if (
+      isBackgroundTask(
+        field(message, "isBackgrounded", "is_backgrounded"),
+        field(message, "taskType", "task_type"),
+      )
+    ) {
+      await this.announce(task);
+    }
+    if (
+      wasAnnounced &&
+      (task.outputFilePath !== previousOutputFilePath || task.toolCallId !== previousToolCallId)
+    ) {
+      await this.publishMetadata(task);
+    }
+  }
+
+  async taskBackgrounded(message: AsyncTaskStarted): Promise<void> {
+    if (!this.enabled) return;
+    const taskId = taskIdOf(message);
+    if (!taskId) return;
+    const task = this.task(taskId);
+    if (isSubagentTask(message)) {
+      task.ignored = true;
+      return;
+    }
+
+    const previousOutputFilePath = task.outputFilePath;
+    const previousToolCallId = task.toolCallId;
+    const wasAnnounced = task.announced;
+    this.mergeStarted(task, message);
+    await this.announce(task);
+    if (
+      wasAnnounced &&
+      (task.outputFilePath !== previousOutputFilePath || task.toolCallId !== previousToolCallId)
+    ) {
+      await this.publishMetadata(task);
+    }
+  }
+
+  async taskUpdated(message: AsyncTaskUpdated): Promise<void>;
+  async taskUpdated(taskId: string, patch: TaskPatch): Promise<void>;
+  async taskUpdated(taskOrId: string | AsyncTaskUpdated, legacyPatch?: TaskPatch): Promise<void> {
+    if (!this.enabled) return;
+    const taskId = typeof taskOrId === "string" ? nonBlankString(taskOrId) : taskIdOf(taskOrId);
+    const patch = typeof taskOrId === "string" ? legacyPatch : taskOrId.patch;
+    if (!taskId || !patch) return;
+
+    const task = this.task(taskId);
+    const previousOutputFilePath = task.outputFilePath;
+    this.mergePatch(task, patch);
+    if (field(patch, "isBackgrounded", "is_backgrounded") === true) {
+      await this.announce(task);
+    }
+
+    const state = taskState(patch.status);
+    if (!state) {
+      if (task.announced && task.outputFilePath !== previousOutputFilePath) {
+        await this.publishMetadata(task);
+      }
+      return;
+    }
+
+    if (state === "running" || state === "paused") {
+      if (isTerminal(task.state)) {
+        if (task.announced && task.outputFilePath !== previousOutputFilePath) {
+          await this.publishMetadata(task);
+        }
+        return;
+      }
+      if (task.state !== state) {
+        task.state = state;
+        if (task.announced) await this.publishState(task, state, nonBlankString(patch.error));
+      } else if (task.announced && task.outputFilePath !== previousOutputFilePath) {
+        await this.publishMetadata(task);
+      }
+      return;
+    }
+
+    await this.finish(task, state, nonBlankString(patch.error), "event");
+  }
+
+  async taskProgress(message: TaskProgress): Promise<void> {
+    if (!this.enabled) return;
+    const taskId = taskIdOf(message);
+    if (!taskId) return;
+    const task = this.tasks.get(taskId);
+    if (!task || !task.announced || task.ignored) return;
+
+    const previousOutputFilePath = task.outputFilePath;
+    this.mergeOutputFilePath(task, message);
+    const outputChanged = task.outputFilePath !== previousOutputFilePath;
+    if (isTerminal(task.state)) {
+      if (outputChanged) await this.publishMetadata(task);
+      return;
+    }
+
+    const usage = taskUsage(message.usage);
+    const description = nonBlankString(message.description);
+    const summary = nonBlankString(message.summary);
+    const lastToolName = nonBlankString(field(message, "lastToolName", "last_tool_name"));
+    await this.publishProgress(task, {
+      ...(description ? { description } : {}),
+      ...(summary ? { summary } : {}),
+      ...(lastToolName ? { lastToolName } : {}),
+      ...(usage ? { usage } : {}),
+      ...(outputChanged && task.outputFilePath ? { outputFilePath: task.outputFilePath } : {}),
+    });
+  }
+
+  async taskNotification(message: AsyncTaskNotification): Promise<void>;
+  async taskNotification(
+    taskId: string,
+    status: unknown,
+    summary?: unknown,
+    outputFilePath?: unknown,
+  ): Promise<void>;
+  async taskNotification(
+    taskOrId: string | AsyncTaskNotification,
+    legacyStatus?: unknown,
+    legacySummary?: unknown,
+    legacyOutputFilePath?: unknown,
+  ): Promise<void> {
+    if (!this.enabled) return;
+    const message: AsyncTaskNotification =
+      typeof taskOrId === "string"
+        ? {
+            taskId: taskOrId,
+            status: legacyStatus,
+            summary: legacySummary,
+            outputFilePath: legacyOutputFilePath,
+          }
+        : taskOrId;
+    const taskId = taskIdOf(message);
+    const state = taskState(message.status);
+    if (!taskId || !state || state === "running" || state === "paused") return;
+
+    const task = this.task(taskId);
+    const wasTerminal = isTerminal(task.state);
+    const correctsLevelState = wasTerminal && task.terminalSource === "level";
+    const previousOutputFilePath = task.outputFilePath;
+    this.mergeOutputFilePath(task, message);
+    await this.finish(task, state, nonBlankString(message.summary), "event");
+    if (
+      wasTerminal &&
+      !correctsLevelState &&
+      task.announced &&
+      task.outputFilePath !== previousOutputFilePath
+    ) {
+      await this.publishMetadata(task);
+    }
+  }
+
+  /**
+   * Reconciles the SDK's replace-semantics background task level. It does not
+   * create unknown tasks because this level normally precedes task_started and
+   * carries no tool-call attribution. It can, however, promote a known
+   * foreground task and terminate an announced task whose edge was lost.
+   */
+  async backgroundTasksChanged(
+    tasksOrMessage: readonly BackgroundTaskLevel[] | { tasks?: unknown },
+  ): Promise<void> {
+    if (!this.enabled) return;
+    const value = Array.isArray(tasksOrMessage)
+      ? tasksOrMessage
+      : isRecord(tasksOrMessage)
+        ? tasksOrMessage.tasks
+        : undefined;
+    if (!Array.isArray(value)) return;
+
+    const live = new Set<string>();
+    for (const item of value) {
+      if (!isRecord(item)) continue;
+      const taskId = taskIdOf(item);
+      if (!taskId) continue;
+      live.add(taskId);
+      const task = this.task(taskId);
+      if (task.ignored || isTerminal(task.state)) continue;
+      if (field(item, "taskType", "task_type") === "local_agent") {
+        task.ignored = true;
+        continue;
+      }
+      if (!task.startedObserved) {
+        // The replace-level proves liveness but carries neither transcript
+        // policy nor full identity. Recover it for the Async Tasks panel only;
+        // creating a transcript card here would be irreversible if a late
+        // task_started says skip_transcript=true.
+        task.panelOnlyRecovery = true;
+        task.showInTranscript = false;
+      }
+      this.mergeLevel(task, item);
+      await this.announce(task);
+    }
+
+    for (const task of this.tasks.values()) {
+      if (task.announced && !task.ignored && !isTerminal(task.state) && !live.has(task.id)) {
+        // This replace-semantics level is itself the authoritative liveness
+        // boundary. Close immediately so a lost terminal edge cannot leave a
+        // permanent running card; a following task_notification may correct
+        // the best-effort stopped state to completed/failed.
+        await this.finish(task, "stopped", undefined, "level");
+      }
+    }
+  }
+
+  async finishAll(state: Extract<AsyncTaskState, "failed" | "stopped">): Promise<void> {
+    const errors: unknown[] = [];
+    for (const task of this.tasks.values()) {
+      if (task.announced && !task.ignored && !isTerminal(task.state)) {
+        try {
+          await this.finish(task, state, undefined, "shutdown");
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+    }
+    if (errors.length === 1) throw errors[0];
+    if (errors.length > 1) throw new AggregateError(errors, "Failed to finish async tasks");
+  }
+
+  canStop(taskId: string): boolean {
+    const task = this.tasks.get(taskId);
+    return task?.announced === true && !task.ignored && !task.stopping && !isTerminal(task.state);
+  }
+
+  claimStop(taskId: string): boolean {
+    if (!this.canStop(taskId)) return false;
+    this.tasks.get(taskId)!.stopping = true;
+    return true;
+  }
+
+  releaseStop(taskId: string): void {
+    const task = this.tasks.get(taskId);
+    if (task && !isTerminal(task.state)) task.stopping = false;
+  }
+
+  async taskStopped(taskId: string): Promise<void> {
+    const task = this.tasks.get(taskId);
+    if (!task || !task.announced || task.ignored || task.stopAnnounced) return;
+    task.stopAnnounced = true;
+    // 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");
+    // The transcript is where the acknowledgement has to land, and it is the
+    // only one the user gets -- the SDK injects nothing into the model's
+    // context for a stopped shell task.
+    //
+    // Terminal state deliberately does not gate this. The SDK's own
+    // `task_notification` routinely wins the race against the `stopTask`
+    // response that brought us here, so by now the task is usually already
+    // terminal: gating on that would silence the very stop the user asked for.
+    // `stopAnnounced` is what keeps this to one line per task.
+    //
+    // `showInTranscript` does not gate it either: that flag decides whether the
+    // task owns a transcript *card* (a background Bash task is already drawn as
+    // its tool call), not whether the agent may answer a direct user action.
+    await this.publish({
+      sessionId: this.sessionId,
+      update: {
+        sessionUpdate: "agent_message_chunk",
+        content: { type: "text", text: `**Task stopped by user:** ${task.name}.` },
+      },
+    });
+  }
+
+  clear(): void {
+    this.tasks.clear();
+  }
+
+  private task(taskId: string): AsyncTask {
+    let task = this.tasks.get(taskId);
+    if (task) return task;
+    task = {
+      id: taskId,
+      name: "Background task",
+      taskType: "task",
+      description: "Background task",
+      showInTranscript: true,
+      announced: false,
+      ignored: false,
+      startedObserved: false,
+      panelOnlyRecovery: false,
+      stopping: false,
+      stopAnnounced: false,
+      state: "running",
+    };
+    this.tasks.set(taskId, task);
+    return task;
+  }
+
+  private mergeStarted(task: AsyncTask, message: AsyncTaskStarted): void {
+    task.startedObserved = true;
+    const rawTaskType = field(message, "taskType", "task_type");
+    if (rawTaskType !== undefined) task.taskType = friendlyTaskType(rawTaskType);
+    const description = nonBlankString(message.description);
+    if (description) task.description = description;
+    else if (task.description === "Background task")
+      task.description = defaultDescription(task.taskType);
+    task.name = nonBlankString(field(message, "workflowName", "workflow_name")) ?? task.description;
+    const skipTranscript = field(message, "skipTranscript", "skip_transcript");
+    if (task.panelOnlyRecovery) {
+      // A level-only recovery was already announced without a transcript
+      // entry. Keep that decision monotonic: a late task_started can enrich
+      // the panel, but cannot retroactively create or mutate transcript UI.
+      task.showInTranscript = false;
+    } else if (skipTranscript !== undefined) {
+      task.showInTranscript = skipTranscript !== true;
+    }
+    this.mergeOutputFilePath(task, message);
+    const toolCallId = nonBlankString(field(message, "toolCallId", "tool_use_id"));
+    if (toolCallId) task.toolCallId = toolCallId;
+  }
+
+  private mergePatch(task: AsyncTask, patch: TaskPatch): void {
+    const description = nonBlankString(patch.description);
+    if (description) {
+      task.description = description;
+      task.name = description;
+    }
+    this.mergeOutputFilePath(task, patch);
+  }
+
+  private mergeLevel(task: AsyncTask, level: BackgroundTaskLevel): void {
+    const rawTaskType = field(level, "taskType", "task_type");
+    if (rawTaskType !== undefined) task.taskType = friendlyTaskType(rawTaskType);
+    const description = nonBlankString(level.description);
+    if (description) {
+      task.description = description;
+      task.name = description;
+    }
+  }
+
+  private mergeOutputFilePath(
+    task: AsyncTask,
+    value: { outputFilePath?: unknown; output_file?: unknown },
+  ): void {
+    const outputFilePath = nonBlankString(field(value, "outputFilePath", "output_file"));
+    if (outputFilePath) task.outputFilePath = outputFilePath;
+  }
+
+  private async announce(task: AsyncTask): Promise<void> {
+    if (task.announced || task.ignored) return;
+    await this.publish({
+      sessionId: this.sessionId,
+      update: {
+        sessionUpdate: "async_task_spawned",
+        asyncTaskId: task.id,
+        name: task.name,
+        taskType: task.taskType,
+        description: task.description,
+        showInTranscript: task.showInTranscript,
+        canStop: true,
+        ...(task.outputFilePath ? { outputFilePath: task.outputFilePath } : {}),
+        ...(task.toolCallId ? { toolCallId: task.toolCallId } : {}),
+      },
+    });
+    task.announced = true;
+    if (isTerminal(task.state)) {
+      await this.publishState(task, task.state, task.terminalSummary);
+    }
+  }
+
+  private async finish(
+    task: AsyncTask,
+    state: Extract<AsyncTaskState, "completed" | "failed" | "stopped">,
+    summary: string | undefined,
+    source: TerminalSource,
+  ): Promise<void> {
+    if (task.ignored) return;
+    if (isTerminal(task.state)) {
+      // A level event may precede the authoritative terminal edge. Correct its
+      // best-effort stopped state if that edge later arrives.
+      if (task.terminalSource !== "level" || source !== "event") return;
+    }
+    const previous = {
+      state: task.state,
+      terminalSummary: task.terminalSummary,
+      terminalSource: task.terminalSource,
+    };
+    task.state = state;
+    task.terminalSummary = summary;
+    task.terminalSource = source;
+    try {
+      if (task.announced) await this.publishState(task, state, summary);
+    } catch (error) {
+      task.state = previous.state;
+      task.terminalSummary = previous.terminalSummary;
+      task.terminalSource = previous.terminalSource;
+      throw error;
+    }
+  }
+
+  private async publishMetadata(task: AsyncTask): Promise<void> {
+    if (task.outputFilePath || task.toolCallId) {
+      if (isTerminal(task.state)) {
+        await this.publishState(task, task.state, task.terminalSummary);
+      } else {
+        await this.publishProgress(task, {
+          ...(task.outputFilePath ? { outputFilePath: task.outputFilePath } : {}),
+          ...(task.toolCallId ? { toolCallId: task.toolCallId } : {}),
+        });
+      }
+    }
+  }
+
+  private async publishProgress(
+    task: AsyncTask,
+    update: {
+      description?: string;
+      summary?: string;
+      lastToolName?: string;
+      usage?: { totalTokens: number; toolUses: number; durationMs: number };
+      outputFilePath?: string;
+      toolCallId?: string;
+    },
+  ): Promise<void> {
+    await this.publish({
+      sessionId: this.sessionId,
+      update: {
+        sessionUpdate: "async_task_progress",
+        asyncTaskId: task.id,
+        ...update,
+      },
+    });
+  }
+
+  private async publishState(
+    task: AsyncTask,
+    state: AsyncTaskState,
+    summary?: string,
+  ): Promise<void> {
+    await this.publish({
+      sessionId: this.sessionId,
+      update: {
+        sessionUpdate: "async_task_state_update",
+        asyncTaskId: task.id,
+        state,
+        ...(summary ? { summary } : {}),
+        ...(task.outputFilePath ? { outputFilePath: task.outputFilePath } : {}),
+        ...(task.toolCallId ? { toolCallId: task.toolCallId } : {}),
+      },
+    });
+  }
+}
+
+/** Recovers background Bash lifecycle data exposed only on its tool result. */
+export function backgroundBashTaskFromToolResult(
+  content: unknown,
+  toolUseResult: unknown,
+  toolUses: Record<string, { name: string; input: unknown }>,
+): AsyncTaskStarted | 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);
+  const distinctTaskIds = new Set([
+    ...backgroundResults.map((result) => result.taskId),
+    ...bashResults
+      .map((result) => backgroundTaskIdFromText(result.content))
+      .filter((taskId): taskId is string => taskId !== undefined),
+  ]);
+  if (distinctTaskIds.size !== 1) return undefined;
+  const taskId = [...distinctTaskIds][0];
+  if (!taskId) return undefined;
+
+  const hintedToolUseIds = new Set(
+    backgroundResults
+      .filter((result) => result.taskId === taskId && result.toolUseId)
+      .map((result) => result.toolUseId!),
+  );
+  let matches: typeof bashResults;
+  if (hintedToolUseIds.size > 0) {
+    matches = bashResults.filter((result) => hintedToolUseIds.has(result.toolUseId));
+  } else {
+    const pathMatches = bashResults.filter(
+      (result) => asyncTaskOutputFilePath(result.content, taskId) !== undefined,
+    );
+    matches = pathMatches.length > 0 ? pathMatches : bashResults.length === 1 ? bashResults : [];
+  }
+  if (matches.length !== 1) return undefined;
+
+  const match = matches[0];
+  const toolUse = toolUses[match.toolUseId];
+  const input = isRecord(toolUse?.input) ? toolUse.input : undefined;
+  return {
+    taskId,
+    taskType: "local_bash",
+    description: nonBlankString(input?.command),
+    isBackgrounded: true,
+    outputFilePath: asyncTaskOutputFilePath(match.content, taskId),
+    toolCallId: match.toolUseId,
+  };
+}
+
+function backgroundTaskIdFromText(content: unknown): string | undefined {
+  const text = textContent(content);
+  if (!text) return undefined;
+  const marker = "Command running in background with ID: ";
+  const start = text.indexOf(marker);
+  if (start < 0) return undefined;
+  const valueStart = start + marker.length;
+  const valueEnd = text.indexOf(".", valueStart);
+  return valueEnd < 0 ? undefined : nonBlankString(text.slice(valueStart, valueEnd));
+}
+
+function structuredBackgroundResults(
+  value: unknown,
+  toolUses: Record<string, { name: string; input: unknown }>,
+  hintedToolUseId?: string,
+  seen = new Set<unknown>(),
+): { taskId: string; toolUseId?: string }[] {
+  if (typeof value !== "object" || value === null || seen.has(value)) return [];
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.flatMap((item) =>
+      structuredBackgroundResults(item, toolUses, hintedToolUseId, seen),
+    );
+  }
+
+  const directTaskId = nonBlankString(field(value, "backgroundTaskId", "background_task_id"));
+  const directToolUseId =
+    nonBlankString(field(value, "toolUseId", "tool_use_id")) ?? hintedToolUseId;
+  const results: { taskId: string; toolUseId?: string }[] = directTaskId
+    ? [{ taskId: directTaskId, toolUseId: directToolUseId }]
+    : [];
+  for (const [key, child] of Object.entries(value)) {
+    if (key === "backgroundTaskId" || key === "background_task_id") continue;
+    results.push(
+      ...structuredBackgroundResults(child, toolUses, toolUses[key] ? key : directToolUseId, seen),
+    );
+  }
+  return results;
+}
+
+function toolResultBlock(value: unknown): { toolUseId: string; content?: unknown }[] {
+  if (!isRecord(value) || value.type !== "tool_result") return [];
+  const toolUseId = nonBlankString(field(value, "toolUseId", "tool_use_id"));
+  return toolUseId ? [{ toolUseId, content: value.content }] : [];
+}
+
+function asyncTaskOutputFilePath(content: unknown, taskId: string): string | undefined {
+  const text = textContent(content);
+  if (!text) return undefined;
+  const marker = "Output is being written to: ";
+  const start = text.indexOf(marker);
+  if (start < 0) return undefined;
+  const valueStart = start + marker.length;
+  const valueEnd = text.indexOf(". You will be notified", valueStart);
+  if (valueEnd < 0) return undefined;
+  const path = text.slice(valueStart, valueEnd).trim();
+  const expectedPosixSuffix = `/tasks/${taskId}.output`;
+  const expectedWindowsSuffix = `\\tasks\\${taskId}.output`;
+  return path.endsWith(expectedPosixSuffix) || path.endsWith(expectedWindowsSuffix)
+    ? path
+    : undefined;
+}
+
+function textContent(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    const parts = value.map(textContent).filter((part): part is string => part !== undefined);
+    return parts.length > 0 ? parts.join("") : undefined;
+  }
+  if (!isRecord(value)) return undefined;
+  if (typeof value.text === "string") return value.text;
+  return value.content === value ? undefined : textContent(value.content);
+}
+
+function friendlyTaskType(value: unknown): string {
+  if (value === "local_bash") return "shell";
+  if (value === "local_workflow") return "workflow";
+  if (value === "local_monitor" || value === "mcp") return "monitor";
+  return nonBlankString(value) ?? "task";
+}
+
+function defaultDescription(taskType: string): string {
+  return taskType === "task" ? "Background task" : taskType[0].toUpperCase() + taskType.slice(1);
+}
+
+function isBackgroundTask(isBackgrounded: unknown, taskType: unknown): boolean {
+  if (isBackgrounded === true) return true;
+  if (isBackgrounded === false) return false;
+  return taskType !== "local_bash" && taskType !== "local_agent";
+}
+
+function isSubagentTask(message: AsyncTaskStarted): boolean {
+  return (
+    field(message, "subagentType", "subagent_type") !== undefined ||
+    field(message, "taskType", "task_type") === "local_agent"
+  );
+}
+
+function taskState(value: unknown): AsyncTaskState | undefined {
+  if (value === "pending" || value === "running") return "running";
+  if (value === "paused") return "paused";
+  if (value === "completed") return "completed";
+  if (value === "failed") return "failed";
+  if (value === "killed" || value === "cancelled" || value === "stopped") return "stopped";
+  return undefined;
+}
+
+function isTerminal(state: AsyncTaskState): state is "completed" | "failed" | "stopped" {
+  return state === "completed" || state === "failed" || state === "stopped";
+}
+
+function taskUsage(
+  value: unknown,
+): { totalTokens: number; toolUses: number; durationMs: number } | undefined {
+  if (!isRecord(value)) return undefined;
+  const totalTokens = numberField(value, "totalTokens", "total_tokens");
+  const toolUses = numberField(value, "toolUses", "tool_uses");
+  const durationMs = numberField(value, "durationMs", "duration_ms");
+  if (totalTokens === undefined || toolUses === undefined || durationMs === undefined)
+    return undefined;
+  return { totalTokens, toolUses, durationMs };
+}
+
+function taskIdOf(value: TaskIdentity): string | undefined {
+  return nonBlankString(field(value, "taskId", "task_id"));
+}
+
+function field(value: object, camelCase: string, snakeCase: string): unknown {
+  const record = value as Record<string, unknown>;
+  return record[camelCase] !== undefined ? record[camelCase] : record[snakeCase];
+}
+
+function numberField(
+  value: Record<string, unknown>,
+  camelCase: string,
+  snakeCase: string,
+): number | undefined {
+  const result = field(value, camelCase, snakeCase);
+  return typeof result === "number" ? result : undefined;
+}
+
+function nonBlankString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
--- a/src/clear-context-coordinator.ts
+++ b/src/clear-context-coordinator.ts
@@ -0,0 +1,166 @@
+import type { NewSessionRequest, SessionConfigOption } from "@agentclientprotocol/sdk";
+import type {
+  EffortLevel,
+  Options,
+  PermissionMode,
+  SDKUserMessage,
+} from "@anthropic-ai/claude-agent-sdk";
+import { DEFAULT_AGENT_ID, DEFAULT_MODEL_ID, EFFORT_CONFIG_ID } from "./session-config-ids.js";
+
+export type ClearContextReset = {
+  toolUseId: string;
+  plan: string;
+  mode: PermissionMode;
+};
+
+type Usage = {
+  inputTokens: number;
+  outputTokens: number;
+  cachedReadTokens: number;
+  cachedWriteTokens: number;
+};
+
+export type ClearContextTurn = {
+  settled: boolean;
+  promptUuid: string;
+  carriedUsage?: Usage;
+  carriedModelUsage?: Record<string, Usage>;
+};
+
+/** The session state needed to replace Claude's private conversation without
+ * replacing the public ACP turn. Keeping this projection here makes the
+ * restart workflow independent from the agent's much larger Session record. */
+export type ClearContextSession<Turn extends ClearContextTurn = ClearContextTurn> = {
+  cwd: string;
+  creationParams?: NewSessionRequest;
+  accumulatedUsage: Usage;
+  accumulatedModelUsage?: Record<string, Usage>;
+  models: { currentModelId: string };
+  configOptions: SessionConfigOption[];
+  currentAgent: string;
+  fastModeEnabled: boolean;
+  activeTurn?: Turn | null;
+  turnQueue?: Turn[];
+  pendingExitPlanContextReset?: ClearContextReset;
+  contextUsedTokens?: number;
+  input: { push(message: SDKUserMessage): unknown };
+};
+
+export type ClearContextCoordinatorHost<
+  Session extends ClearContextSession<Turn>,
+  Turn extends ClearContextTurn,
+> = {
+  currentSession(sessionId: string): Session | undefined;
+  closeQueryStream(session: Session): void;
+  restartSession(
+    params: NewSessionRequest,
+    options: { publicSessionId: string; permissionMode: PermissionMode },
+  ): Promise<Session>;
+  applyFastMode(session: Session, enabled: boolean): Promise<void>;
+  publishSessionState(
+    sessionId: string,
+    mode: PermissionMode,
+    configOptions: SessionConfigOption[],
+  ): Promise<void>;
+  continuationMessage(sessionId: string, plan: string, promptUuid: string): SDKUserMessage;
+  ensureConsumer(session: Session, sessionId: string): void;
+  logError(message: string, error: unknown): void;
+};
+
+function restartParams<Session extends ClearContextSession>(session: Session): NewSessionRequest {
+  const originalParams = session.creationParams ?? { cwd: session.cwd, mcpServers: [] };
+  const currentEffort = session.configOptions.find(
+    (option) => option.id === EFFORT_CONFIG_ID,
+  )?.currentValue;
+  const originalMeta = originalParams._meta as
+    ({ claudeCode?: { options?: Options } } & Record<string, unknown>) | undefined;
+  const originalOptions = originalMeta?.claudeCode?.options;
+  const unmanagedOptions = { ...(originalOptions ?? {}) };
+  delete unmanagedOptions.model;
+  delete unmanagedOptions.agent;
+  delete unmanagedOptions.effort;
+
+  return {
+    ...originalParams,
+    _meta: {
+      ...(originalMeta ?? {}),
+      claudeCode: {
+        ...(originalMeta?.claudeCode ?? {}),
+        options: {
+          ...unmanagedOptions,
+          ...(session.models.currentModelId !== DEFAULT_MODEL_ID
+            ? { model: session.models.currentModelId }
+            : {}),
+          ...(session.currentAgent !== DEFAULT_AGENT_ID ? { agent: session.currentAgent } : {}),
+          ...(typeof currentEffort === "string" && currentEffort !== "default"
+            ? { effort: currentEffort as EffortLevel }
+            : {}),
+        },
+      },
+    },
+  };
+}
+
+/** Replace Claude's private conversation and attach the still-pending ACP turn
+ * to it. The host owns provider-specific creation and stream mechanics; this
+ * coordinator owns the ordering and state transfer invariants. */
+export async function continuePlanInFreshContext<
+  Turn extends ClearContextTurn,
+  Session extends ClearContextSession<Turn>,
+>(
+  sessionId: string,
+  oldSession: Session,
+  reset: ClearContextReset,
+  host: ClearContextCoordinatorHost<Session, Turn>,
+  signal?: AbortSignal,
+): Promise<void> {
+  const assertRestartActive = (session?: Session): void => {
+    if (signal?.aborted || (session && host.currentSession(sessionId) !== session)) {
+      throw new Error("Clear-context restart aborted");
+    }
+  };
+  assertRestartActive();
+  const turn = oldSession.activeTurn;
+  if (!turn || turn.settled || host.currentSession(sessionId) !== oldSession) {
+    throw new Error("Cannot clear context without an active ACP turn");
+  }
+
+  const params = restartParams(oldSession);
+  host.closeQueryStream(oldSession);
+
+  const freshSession = await host.restartSession(params, {
+    publicSessionId: sessionId,
+    permissionMode: reset.mode,
+  });
+  assertRestartActive(freshSession);
+
+  // Do not consume the reset or mutate the turn until a replacement exists.
+  // A failed restart must remain distinguishable from a lost query transport.
+  turn.carriedUsage = { ...oldSession.accumulatedUsage };
+  turn.carriedModelUsage = { ...oldSession.accumulatedModelUsage };
+  oldSession.pendingExitPlanContextReset = undefined;
+  if (oldSession.fastModeEnabled !== freshSession.fastModeEnabled) {
+    try {
+      await host.applyFastMode(freshSession, oldSession.fastModeEnabled);
+    } catch (error) {
+      host.logError("Failed to restore Fast mode after clearing context:", error);
+    }
+    assertRestartActive(freshSession);
+  }
+
+  oldSession.activeTurn = null;
+  oldSession.turnQueue = [];
+  freshSession.turnQueue = [turn];
+  freshSession.contextUsedTokens = 0;
+
+  try {
+    await host.publishSessionState(sessionId, reset.mode, freshSession.configOptions);
+  } catch (error) {
+    host.logError("Failed to publish clear-context session state:", error);
+  }
+  assertRestartActive(freshSession);
+
+  freshSession.input.push(host.continuationMessage(sessionId, reset.plan, turn.promptUuid));
+  assertRestartActive(freshSession);
+  host.ensureConsumer(freshSession, sessionId);
+}
--- a/src/exit-plan.ts
+++ b/src/exit-plan.ts
@@ -0,0 +1,217 @@
+import type { SessionNotification } from "@agentclientprotocol/sdk";
+import type { SDKResultMessage } from "@anthropic-ai/claude-agent-sdk";
+import {
+  type ClearContextCoordinatorHost,
+  type ClearContextReset,
+  type ClearContextSession,
+  type ClearContextTurn,
+  continuePlanInFreshContext,
+} from "./clear-context-coordinator.js";
+import { parseToolResultMeta } from "./tool-result-meta.js";
+
+export function acceptedPlanToolResult(
+  notification: SessionNotification,
+  toolUseId: string | undefined,
+): SessionNotification {
+  const update = notification.update;
+  if (
+    !toolUseId ||
+    update.sessionUpdate !== "tool_call_update" ||
+    update.toolCallId !== toolUseId
+  ) {
+    return notification;
+  }
+  const completed = { ...update };
+  delete completed.rawOutput;
+  delete completed.content;
+  return { ...notification, update: { ...completed, status: "completed" } };
+}
+
+function containsToolResultFor(content: unknown, toolUseId: string): boolean {
+  return (
+    Array.isArray(content) &&
+    content.some(
+      (block) =>
+        typeof block === "object" &&
+        block !== null &&
+        (block as { type?: unknown }).type === "tool_result" &&
+        (block as { tool_use_id?: unknown }).tool_use_id === toolUseId,
+    )
+  );
+}
+
+type ExitPlanState = {
+  toolUseCache: Record<string, { name: string } | undefined>;
+  pendingExitPlanModeInterruption?: { toolUseId: string; toolResultSeen: boolean };
+  pendingExitPlanContextReset?: ClearContextReset;
+};
+
+function rejectedExitPlanToolUseId(
+  content: unknown,
+  toolUseCache: ExitPlanState["toolUseCache"],
+  rawToolResultMeta: unknown,
+): string | undefined {
+  if (!Array.isArray(content)) return undefined;
+  const toolResultMeta = parseToolResultMeta(rawToolResultMeta);
+  if (!toolResultMeta) return undefined;
+  for (const block of content) {
+    if (typeof block !== "object" || block === null) continue;
+    const { type, tool_use_id: toolUseId, is_error: isError } = block as Record<string, unknown>;
+    if (
+      type === "tool_result" &&
+      typeof toolUseId === "string" &&
+      isError === true &&
+      toolResultMeta.get(toolUseId)?.nonExecutionKind === "user-rejected" &&
+      toolUseCache[toolUseId]?.name === "ExitPlanMode"
+    ) {
+      return toolUseId;
+    }
+  }
+  return undefined;
+}
+
+/** Reconcile an SDK user message with the two pending ExitPlanMode lanes and
+ * return the accepted plan tool id whose rendered update must be completed. */
+export function observeExitPlanToolResults(
+  message: { type: string; tool_result_meta?: unknown },
+  content: unknown,
+  state: ExitPlanState,
+): string | undefined {
+  if (message.type !== "user") return undefined;
+
+  const rejectedToolUseId = rejectedExitPlanToolUseId(
+    content,
+    state.toolUseCache,
+    message.tool_result_meta,
+  );
+  if (rejectedToolUseId) {
+    // The stream is authoritative: resumed queries can lose the short-lived
+    // marker installed by canUseTool, while metadata preserves correlation.
+    state.pendingExitPlanModeInterruption = {
+      toolUseId: rejectedToolUseId,
+      toolResultSeen: true,
+    };
+  }
+
+  const pendingInterruption = state.pendingExitPlanModeInterruption;
+  if (pendingInterruption && containsToolResultFor(content, pendingInterruption.toolUseId)) {
+    pendingInterruption.toolResultSeen = true;
+  }
+
+  const pendingReset = state.pendingExitPlanContextReset;
+  return pendingReset && containsToolResultFor(content, pendingReset.toolUseId)
+    ? pendingReset.toolUseId
+    : undefined;
+}
+
+export function executionDiagnostic(message: SDKResultMessage): string | undefined {
+  if (message.subtype === "success") {
+    return message.result.startsWith("[ede_diagnostic]") ? message.result : undefined;
+  }
+  return message.errors.find((error) => error.startsWith("[ede_diagnostic]"));
+}
+
+/** Claude wraps a rejected ExitPlanMode explanation in a Markdown code fence.
+ * Strip exactly one complete outer fence for that tool only. */
+export function exitPlanModeRawOutput(toolName: string, content: unknown): unknown {
+  if (toolName !== "ExitPlanMode" || typeof content !== "string") {
+    return content;
+  }
+  const fenced = /^\s*```[^\r\n]*\r?\n([\s\S]*?)\r?\n```\s*$/.exec(content);
+  return fenced?.[1] ?? content;
+}
+
+export type ExitPlanRestartHost<
+  Session extends ClearContextSession<Turn>,
+  Turn extends ClearContextTurn,
+> = Omit<
+  ClearContextCoordinatorHost<Session, Turn>,
+  "publishSessionState" | "continuationMessage"
+> & {
+  sessionUpdate(notification: SessionNotification): Promise<void>;
+  destroyReplacement(sessionId: string, session: Session): void;
+  settleCancelledTurn(oldSession: Session, turnSession: Session, turn: Turn): void;
+  settleFailedTurn(turnSession: Session, turn: Turn, error: unknown): void;
+};
+
+/** Owns the lifetime of accepted-plan context replacements. In particular, a
+ * session cancellation invalidates an in-progress async restart so a late
+ * restartSession result cannot recreate a closed public session. */
+export class ExitPlanCoordinator<
+  Session extends ClearContextSession<Turn>,
+  Turn extends ClearContextTurn,
+> {
+  private readonly restarts = new Map<string, AbortController>();
+
+  constructor(private readonly host: ExitPlanRestartHost<Session, Turn>) {}
+
+  cancel(sessionId: string): void {
+    this.restarts.get(sessionId)?.abort();
+  }
+
+  async restart(sessionId: string, oldSession: Session, reset: ClearContextReset): Promise<void> {
+    this.cancel(sessionId);
+    const controller = new AbortController();
+    this.restarts.set(sessionId, controller);
+    try {
+      const clearContextHost: ClearContextCoordinatorHost<Session, Turn> = {
+        ...this.host,
+        publishSessionState: async (id, mode, configOptions) => {
+          await this.host.sessionUpdate({
+            sessionId: id,
+            update: { sessionUpdate: "current_mode_update", currentModeId: mode },
+          });
+          await this.host.sessionUpdate({
+            sessionId: id,
+            update: { sessionUpdate: "config_option_update", configOptions },
+          });
+        },
+        continuationMessage: (id, plan, promptUuid) => ({
+          type: "user",
+          message: {
+            role: "user",
+            content: [{ type: "text", text: `Implement the following plan:\n\n${plan}` }],
+          },
+          session_id: id,
+          parent_tool_use_id: null,
+          origin: { kind: "human" },
+          uuid: promptUuid as `${string}-${string}-${string}-${string}-${string}`,
+        }),
+      };
+      await continuePlanInFreshContext(
+        sessionId,
+        oldSession,
+        reset,
+        clearContextHost,
+        controller.signal,
+      );
+    } catch (error) {
+      const currentSession = this.host.currentSession(sessionId);
+      const replacement = currentSession !== oldSession ? currentSession : undefined;
+      if (replacement) this.host.destroyReplacement(sessionId, replacement);
+
+      const turn = replacement?.activeTurn ?? oldSession.activeTurn;
+      if (turn && !turn.settled) {
+        const turnSession = replacement?.activeTurn === turn ? replacement : oldSession;
+        if (controller.signal.aborted) {
+          this.host.settleCancelledTurn(oldSession, turnSession, turn);
+        } else {
+          // A provider/session-creation failure is turn-scoped. Settling it
+          // here keeps it out of the query consumer's transport-loss catch.
+          this.host.settleFailedTurn(turnSession, turn, error);
+        }
+        oldSession.activeTurn = null;
+        oldSession.turnQueue = (oldSession.turnQueue ?? []).filter((queued) => queued !== turn);
+        if (replacement) {
+          replacement.activeTurn = null;
+          replacement.turnQueue = (replacement.turnQueue ?? []).filter((queued) => queued !== turn);
+        }
+      }
+      oldSession.pendingExitPlanContextReset = undefined;
+    } finally {
+      if (this.restarts.get(sessionId) === controller) {
+        this.restarts.delete(sessionId);
+      }
+    }
+  }
+}
--- a/src/file-change-audit.ts
+++ b/src/file-change-audit.ts
@@ -0,0 +1,451 @@
+import {
+  createSdkMcpServer,
+  type HookCallback,
+  type McpSdkServerConfigWithInstance,
+  type SdkMcpToolDefinition,
+} from "@anthropic-ai/claude-agent-sdk";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { z } from "zod";
+import { airExtensionMeta, clientSupportsAirCapability, withAirMeta } from "./air-extension.js";
+
+export const AGENT_FILE_CHANGE_REPORT_CAPABILITY = "agentFileChangeReport";
+export const FILE_CHANGE_AUDIT_SERVER_NAME = "claude_agent_acp";
+export const FILE_CHANGE_AUDIT_TOOL_NAME = "report_changed_files";
+export const FILE_CHANGE_AUDIT_WIRE_TOOL_NAME = `mcp__${FILE_CHANGE_AUDIT_SERVER_NAME}__${FILE_CHANGE_AUDIT_TOOL_NAME}`;
+
+const FILE_CHANGE_AUDIT_MARKER = "claude-agent-acp-file-change-audit";
+const MAX_REPORTED_PATHS = 1024;
+const MAX_REPORTED_PATH_LENGTH = 4096;
+export const AGENT_FILE_CHANGE_REPORT_MAX_BYTES = 256 * 1024;
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+
+export type FileChangeAuditTurnState = {
+  requestId: string;
+  phase: "requested" | "collecting" | "finished";
+};
+
+export type FileChangeAuditWorkspace = {
+  cwd: string;
+  additionalDirectories: string[];
+};
+
+export type AgentFileChangeReport = {
+  paths: string[];
+  complete: boolean;
+  uncertainty?: string;
+};
+
+export type AgentFileChangeReportResult = {
+  version: 1;
+  requestId: string;
+} & (
+  | {
+      status: "reported";
+      paths: string[];
+      declaredComplete: boolean;
+      truncated: boolean;
+      uncertainty?: string;
+    }
+  | {
+      status: "unavailable";
+      reason: FileChangeReportUnavailableReason;
+    }
+);
+
+export type FileChangeReportUnavailableReason =
+  "cancelled" | "timeout" | "invalidOutput" | "notReported" | "providerError";
+
+type FileChangeAuditSupportOptions = {
+  cwd: string;
+  additionalDirectories: string[];
+  getActiveState: () => FileChangeAuditTurnState | undefined;
+  publish: (result: AgentFileChangeReportResult) => Promise<void>;
+  logError: (message: string) => void;
+};
+
+export type FileChangeAuditSupport = {
+  mcpServer: McpSdkServerConfigWithInstance;
+  preToolUseHook: HookCallback;
+  stopHook: HookCallback;
+  finishUnavailable: (
+    state: FileChangeAuditTurnState,
+    reason: FileChangeReportUnavailableReason,
+  ) => Promise<void>;
+};
+
+const reportInputSchema = {
+  paths: z
+    .array(z.string())
+    .describe(
+      "Workspace file paths changed during this turn. Use absolute paths or paths relative to cwd.",
+    ),
+  complete: z
+    .boolean()
+    .describe("True only when paths contains every workspace file changed during this turn."),
+  uncertainty: z
+    .string()
+    .trim()
+    .min(1)
+    .max(2000)
+    .optional()
+    .describe("Why the report may be incomplete or uncertain."),
+};
+
+export function agentFileChangeReportRequestId(meta: unknown): string | undefined {
+  const air = airExtensionMeta(meta);
+  const request = air?.agentFileChangeReportRequest;
+  if (!request || typeof request !== "object" || Array.isArray(request)) return undefined;
+  const requestRecord = request as Record<string, unknown>;
+  const requestKeys = Object.keys(requestRecord);
+  if (
+    requestKeys.length !== 2 ||
+    !requestKeys.includes("version") ||
+    !requestKeys.includes("requestId") ||
+    requestRecord.version !== 1
+  )
+    return undefined;
+  const requestId = requestRecord.requestId;
+  return typeof requestId === "string" && REQUEST_ID_PATTERN.test(requestId)
+    ? requestId
+    : undefined;
+}
+
+export function supportsAgentFileChangeReport(capabilities: unknown): boolean {
+  return clientSupportsAirCapability(capabilities, AGENT_FILE_CHANGE_REPORT_CAPABILITY);
+}
+
+export function agentFileChangeReportMeta(
+  result: AgentFileChangeReportResult,
+): Record<string, unknown> {
+  return withAirMeta(undefined, AGENT_FILE_CHANGE_REPORT_CAPABILITY, result);
+}
+
+export function createFileChangeAuditTurnState(requestId: string): FileChangeAuditTurnState {
+  return {
+    requestId,
+    phase: "requested",
+  };
+}
+
+export function isFileChangeAuditReportPhase(state: FileChangeAuditTurnState | undefined): boolean {
+  return state?.phase === "collecting" || state?.phase === "finished";
+}
+
+export function isFileChangeAuditTool(toolName: string): boolean {
+  return toolName === FILE_CHANGE_AUDIT_WIRE_TOOL_NAME;
+}
+
+export function containsFileChangeAuditMarker(text: string): boolean {
+  return text.includes(`<${FILE_CHANGE_AUDIT_MARKER}>`);
+}
+
+export function createFileChangeAuditSupport(
+  options: FileChangeAuditSupportOptions,
+): FileChangeAuditSupport {
+  const workspace = normalizeWorkspace(options.cwd, options.additionalDirectories);
+
+  const finishUnavailable = async (
+    state: FileChangeAuditTurnState,
+    reason: FileChangeReportUnavailableReason,
+  ) => {
+    // Claim the terminal outcome before the first await. The report tool, a
+    // Stop hook, cancellation, and stream teardown can race, but only the
+    // winner may publish for this request id. Publication remains fail-open:
+    // an audit transport failure must never hold the user prompt open.
+    if (state.phase === "finished") return;
+    state.phase = "finished";
+    try {
+      await options.publish({
+        version: 1,
+        requestId: state.requestId,
+        status: "unavailable",
+        reason,
+      });
+    } catch (error) {
+      options.logError(`Failed to publish unavailable report ${state.requestId}: ${error}`);
+    }
+  };
+
+  const tool: SdkMcpToolDefinition<typeof reportInputSchema> = {
+    name: FILE_CHANGE_AUDIT_TOOL_NAME,
+    description:
+      "Internal audit tool. Call it only when a stop-hook message explicitly requests the file-change audit.",
+    inputSchema: reportInputSchema,
+    _meta: {
+      "anthropic/alwaysLoad": true,
+      "claude/endTurn": true,
+    },
+    handler: async (report) => {
+      const state = options.getActiveState();
+      if (!state || state.phase !== "collecting") {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `<${FILE_CHANGE_AUDIT_MARKER}>No file-change audit is active.</${FILE_CHANGE_AUDIT_MARKER}>`,
+            },
+          ],
+        };
+      }
+
+      // Flip before publishing: a client transport failure must not make the
+      // model retry the report and produce duplicates. Delivery is audit-only
+      // and fail-open; the normal turn must still finish.
+      state.phase = "finished";
+      const normalized = normalizeReportedPaths(report.paths, workspace);
+      const result = fitReportedAgentFileChangeReport({
+        version: 1,
+        requestId: state.requestId,
+        status: "reported",
+        paths: normalized.paths,
+        declaredComplete: report.complete && !normalized.truncated,
+        truncated: normalized.truncated,
+        ...(report.uncertainty ? { uncertainty: report.uncertainty } : {}),
+      });
+      try {
+        await options.publish(result);
+      } catch (error) {
+        options.logError(`Failed to publish file-change report ${state.requestId}: ${error}`);
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `<${FILE_CHANGE_AUDIT_MARKER}>File-change audit recorded.</${FILE_CHANGE_AUDIT_MARKER}>`,
+          },
+        ],
+        structuredContent: result,
+      };
+    },
+  };
+
+  // canUseTool is not guaranteed to run for tools that the current permission
+  // mode auto-allows (notably bypassPermissions). A PreToolUse hook is the
+  // enforcement boundary that keeps the hidden continuation read-only in every
+  // mode: it can submit the report, but cannot inspect or mutate more files.
+  const preToolUseHook: HookCallback = async (input) => {
+    if (input.hook_event_name !== "PreToolUse") return {};
+    const state = options.getActiveState();
+    const isReportTool = isFileChangeAuditTool(input.tool_name);
+    if (!isReportTool && !isFileChangeAuditReportPhase(state)) return {};
+
+    const allowReport = state?.phase === "collecting" && isReportTool;
+    return {
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: allowReport ? "allow" : "deny",
+        ...(!allowReport
+          ? {
+              permissionDecisionReason:
+                "Only the internal file-change report is allowed during the audit.",
+            }
+          : {}),
+      },
+    };
+  };
+
+  const stopHook: HookCallback = async (input) => {
+    if (input.hook_event_name !== "Stop") return {};
+    const state = options.getActiveState();
+    if (!state || state.phase === "finished") return {};
+    // A Stop can be only a pause while a background generator is still
+    // running. Keep the request pending so a later final Stop can include its
+    // writes instead of declaring a prematurely complete path set.
+    if (state.phase === "requested" && (input.background_tasks?.length ?? 0) > 0) return {};
+    if (state.phase === "collecting" || input.stop_hook_active) {
+      await finishUnavailable(state, "notReported");
+      return {};
+    }
+
+    // Set the phase before returning the continuation so every following SDK
+    // message is hidden even if the next stream starts immediately.
+    state.phase = "collecting";
+    return {
+      hookSpecificOutput: {
+        hookEventName: "Stop",
+        additionalContext:
+          `<${FILE_CHANGE_AUDIT_MARKER}>` +
+          `Before stopping, call ${FILE_CHANGE_AUDIT_WIRE_TOOL_NAME} exactly once. ` +
+          "Report every workspace file changed during this user turn, including files changed " +
+          "by commands, generators, version-control operations, and child processes. " +
+          "Do not call any other tool and do not emit user-facing prose. " +
+          "Set complete to false and explain uncertainty when you are not sure the list is complete." +
+          `</${FILE_CHANGE_AUDIT_MARKER}>`,
+      },
+    };
+  };
+
+  return {
+    mcpServer: createSdkMcpServer({
+      name: FILE_CHANGE_AUDIT_SERVER_NAME,
+      version: "1.0.0",
+      tools: [tool],
+      alwaysLoad: true,
+    }),
+    preToolUseHook,
+    stopHook,
+    finishUnavailable,
+  };
+}
+
+function normalizeWorkspace(
+  cwd: string,
+  additionalDirectories: string[],
+): FileChangeAuditWorkspace {
+  const normalizedCwd = canonicalizeWorkspaceRoot(path.resolve(cwd));
+  const seen = new Set([pathKey(normalizedCwd)]);
+  const normalizedAdditionalDirectories: string[] = [];
+  for (const directory of additionalDirectories) {
+    const normalized = canonicalizeWorkspaceRoot(path.resolve(normalizedCwd, directory));
+    const key = pathKey(normalized);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    normalizedAdditionalDirectories.push(normalized);
+  }
+  return {
+    cwd: normalizedCwd,
+    additionalDirectories: normalizedAdditionalDirectories,
+  };
+}
+
+function normalizeReportedPaths(
+  reportedPaths: string[],
+  workspace: FileChangeAuditWorkspace,
+): { paths: string[]; truncated: boolean } {
+  const roots = [workspace.cwd, ...workspace.additionalDirectories];
+  const seen = new Set<string>();
+  const result: string[] = [];
+  let totalBytes = 0;
+  let truncated = false;
+  for (const reportedPath of reportedPaths) {
+    if (
+      reportedPath.trim().length === 0 ||
+      reportedPath.length > MAX_REPORTED_PATH_LENGTH ||
+      hasControlCharacter(reportedPath)
+    ) {
+      truncated = true;
+      continue;
+    }
+    let normalized: string;
+    try {
+      normalized = canonicalizeReportedPath(path.resolve(workspace.cwd, reportedPath));
+    } catch {
+      truncated = true;
+      continue;
+    }
+    if (normalized.length > MAX_REPORTED_PATH_LENGTH || hasControlCharacter(normalized)) {
+      truncated = true;
+      continue;
+    }
+    if (!roots.some((root) => isWithinRoot(normalized, root))) {
+      truncated = true;
+      continue;
+    }
+    const key = pathKey(normalized);
+    if (roots.some((root) => pathKey(root) === key)) {
+      truncated = true;
+      continue;
+    }
+    if (seen.has(key)) {
+      continue;
+    }
+    const pathBytes = Buffer.byteLength(normalized, "utf8");
+    if (
+      result.length >= MAX_REPORTED_PATHS ||
+      totalBytes + pathBytes > AGENT_FILE_CHANGE_REPORT_MAX_BYTES
+    ) {
+      truncated = true;
+      continue;
+    }
+    seen.add(key);
+    result.push(normalized);
+    totalBytes += pathBytes;
+  }
+  return { paths: result, truncated };
+}
+
+/** Keep the complete serialized report within AIR's wire limit. */
+function fitReportedAgentFileChangeReport(
+  report: Extract<AgentFileChangeReportResult, { status: "reported" }>,
+): Extract<AgentFileChangeReportResult, { status: "reported" }> {
+  const paths = [...report.paths];
+  let fitted = report;
+  while (Buffer.byteLength(JSON.stringify(fitted), "utf8") > AGENT_FILE_CHANGE_REPORT_MAX_BYTES) {
+    if (paths.length === 0) {
+      // The fixed fields and bounded uncertainty are far below the cap. Keep
+      // this loud if the wire contract changes without updating this helper.
+      throw new Error("Agent file-change report exceeds the wire limit without paths");
+    }
+    paths.pop();
+    fitted = {
+      ...report,
+      paths: [...paths],
+      declaredComplete: false,
+      truncated: true,
+    };
+  }
+  return fitted;
+}
+
+function isWithinRoot(candidate: string, root: string): boolean {
+  const relative = path.relative(root, candidate);
+  return !path.isAbsolute(relative) && !relative.startsWith(`..${path.sep}`) && relative !== "..";
+}
+
+/**
+ * Resolve filesystem aliases in a workspace root, including macOS' /tmp ->
+ * /private/tmp alias. For a root that does not exist yet, resolve its nearest
+ * existing ancestor and retain the missing suffix.
+ */
+function canonicalizeWorkspaceRoot(value: string): string {
+  return canonicalizeFromExistingAncestor(value);
+}
+
+/**
+ * Canonicalize the parent but not the leaf itself. A changed path may be
+ * deleted, or it may be a symlink whose node (rather than target) changed.
+ */
+function canonicalizeReportedPath(value: string): string {
+  const parent = canonicalizeFromExistingAncestor(path.dirname(value));
+  return path.resolve(parent, path.basename(value));
+}
+
+function canonicalizeFromExistingAncestor(value: string): string {
+  const original = path.resolve(value);
+  let current = original;
+  const missingSegments: string[] = [];
+
+  while (true) {
+    try {
+      const canonical = fs.realpathSync.native(current);
+      return path.resolve(canonical, ...missingSegments.reverse());
+    } catch (error) {
+      if (!isMissingPathError(error)) return original;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) return original;
+    missingSegments.push(path.basename(current));
+    current = parent;
+  }
+}
+
+function isMissingPathError(error: unknown): boolean {
+  if (typeof error !== "object" || error === null || !("code" in error)) return false;
+  return error.code === "ENOENT" || error.code === "ENOTDIR";
+}
+
+function pathKey(value: string): string {
+  return process.platform === "win32" ? value.toLowerCase() : value;
+}
+
+function hasControlCharacter(value: string): boolean {
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index);
+    if (code <= 0x1f || (code >= 0x7f && code <= 0x9f)) return true;
+  }
+  return false;
+}
--- a/src/fork-session.ts
+++ b/src/fork-session.ts
@@ -0,0 +1,80 @@
+import { ForkSessionRequest, ForkSessionResponse, RequestError } from "@agentclientprotocol/sdk";
+import {
+  forkSession as forkClaudeSession,
+  getSessionMessages,
+} from "@anthropic-ai/claude-agent-sdk";
+
+type ForkSessionMeta = {
+  [key: string]: unknown;
+  jetbrains?: {
+    air?: {
+      fork?: {
+        version?: number;
+        messageId?: string;
+      };
+    };
+  };
+};
+
+type ForkSessionDependencies = {
+  liveMessageIdToUuid?: ReadonlyMap<string, string>;
+  messageIdForGrouping: (message: {
+    type?: string;
+    uuid?: string | null;
+    message?: unknown;
+  }) => string | undefined;
+};
+
+function forkPointMessageId(meta: unknown): string | undefined {
+  const fork = (meta as ForkSessionMeta | null | undefined)?.jetbrains?.air?.fork;
+  if (fork?.version !== 1) return undefined;
+  const messageId = fork.messageId?.trim();
+  return messageId || undefined;
+}
+
+function forkPointMessageIdCandidates(messageId: string): string[] {
+  // Older AIR builds sent their visible segment id. Prefer the exact id before its ACP source id.
+  const protocolMessageId = messageId.replace(/:segment:\d+$/, "");
+  return protocolMessageId === messageId ? [messageId] : [messageId, protocolMessageId];
+}
+
+export async function forkSession(
+  params: ForkSessionRequest,
+  dependencies: ForkSessionDependencies,
+): Promise<ForkSessionResponse> {
+  const messageId = forkPointMessageId(params._meta);
+  if (!messageId) {
+    const forked = await forkClaudeSession(params.sessionId, { dir: params.cwd });
+    return { sessionId: forked.sessionId };
+  }
+
+  const candidateIds = forkPointMessageIdCandidates(messageId);
+  const liveUuid = candidateIds
+    .map((candidateId) => dependencies.liveMessageIdToUuid?.get(candidateId))
+    .find(Boolean);
+  const history = liveUuid
+    ? undefined
+    : await getSessionMessages(params.sessionId, { dir: params.cwd });
+  const messageUuid =
+    liveUuid ??
+    candidateIds
+      .map(
+        (candidateId) =>
+          history?.find((message) => dependencies.messageIdForGrouping(message) === candidateId)
+            ?.uuid,
+      )
+      .find(Boolean);
+
+  if (!messageUuid) {
+    throw RequestError.invalidParams(
+      { messageId },
+      `Fork point message ${messageId} was not found in session ${params.sessionId}`,
+    );
+  }
+
+  const forked = await forkClaudeSession(params.sessionId, {
+    dir: params.cwd,
+    upToMessageId: messageUuid,
+  });
+  return { sessionId: forked.sessionId };
+}
--- a/src/index.ts
+++ b/src/index.ts
@@ -3,6 +3,8 @@
 import { resolveSettings } from "@anthropic-ai/claude-agent-sdk";
 import { claudeCliPath, runAcp } from "./acp-agent.js";
 import packageJson from "../package.json" with { type: "json" };
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";

 // `--cli` is checked first so that `--version`/`-v` (and any other flags) are
 // forwarded to the wrapped native CLI rather than swallowed by our own version
@@ -61,7 +63,29 @@ if (process.argv.includes("--cli")) {
    console.error("Unhandled Rejection at:", promise, "reason:", reason);
  });

-  const { connection, agent } = runAcp();
+  const logDirectory = process.env.CLAUDE_AGENT_LOGS;
+  const logger = logDirectory
+    ? (() => {
+        mkdirSync(logDirectory, { recursive: true });
+        const logFile = join(logDirectory, "agent.log");
+        const writeLog = (...args: unknown[]) => {
+          const rendered = args
+            .map((arg) => (arg instanceof Error ? (arg.stack ?? arg.message) : String(arg)))
+            .join(" ");
+          appendFileSync(logFile, `${new Date().toISOString()} pid=${process.pid} ${rendered}\n`);
+        };
+        return {
+          log: writeLog,
+          error: (...args: unknown[]) => {
+            console.error(...args);
+            writeLog(...args);
+          },
+        };
+      })()
+    : undefined;
+  logger?.log("Claude ACP started");
+
+  const { connection, agent } = runAcp(logger);

  async function shutdown() {
    await agent.dispose().catch((err) => {
--- a/src/native-subagents.ts
+++ b/src/native-subagents.ts
@@ -0,0 +1,534 @@
+import type { AcpSessionNotification, SubagentState } from "./acp-subagents.js";
+
+export type NativeSubagent = {
+  sessionId: string;
+  parentSessionId: string;
+  parentToolUseId?: string;
+  name: string;
+  task: string;
+  announced?: boolean;
+  terminalState?: SubagentState;
+  /** Connection-local single-flight state; never serialized on the wire. */
+  announcePromise?: Promise<void>;
+  /** Connection-local single-flight state; never serialized on the wire. */
+  terminalPromise?: Promise<void>;
+};
+
+export type NativeSubagentSession = {
+  nativeSubagentsByTaskId?: Map<string, NativeSubagent>;
+  nativeSubagentTaskIdByToolUseId?: Map<string, string>;
+  nativeSubagentParentByToolUseId?: Map<string, string>;
+};
+
+type Publish = (notification: AcpSessionNotification) => Promise<void>;
+type Logger = { log(message: string): void };
+
+type TaskStarted = {
+  taskId: string;
+  toolUseId?: string | null;
+  subagentType?: unknown;
+  description?: unknown;
+  prompt?: unknown;
+};
+
+type SubagentIdentity = {
+  name?: string;
+  description?: string;
+  prompt?: string;
+  subagentType?: string;
+};
+
+const MAX_PENDING_PARENTS = 64;
+const MAX_PENDING_UPDATES = 256;
+const MAX_PENDING_UPDATES_PER_PARENT = 32;
+
+/**
+ * Owns the connection-local native subagent registry and all ACP lifecycle
+ * ordering. The main agent only supplies SDK facts and delivers routed output.
+ */
+export class NativeSubagentRuntime {
+  readonly enabled: boolean;
+
+  private readonly children: Map<string, NativeSubagent>;
+  private readonly taskByToolUse: Map<string, string>;
+  private readonly parentByToolUse: Map<string, string>;
+  private readonly identityByToolUse = new Map<string, SubagentIdentity>();
+  private readonly controlByToolUse = new Map<string, AcpSessionNotification>();
+  private readonly childByParentToolUse = new Map<string, NativeSubagent>();
+  private readonly taskFinishPromises = new Map<string, Promise<void>>();
+  private readonly generationByTaskId = new Map<string, number>();
+  private readonly pending = new Map<string, AcpSessionNotification[]>();
+  private pendingCount = 0;
+
+  constructor(
+    enabled: boolean,
+    private readonly rootSessionId: string,
+    private readonly session: NativeSubagentSession,
+    private readonly publish: Publish,
+    private readonly logger: Logger,
+  ) {
+    this.enabled = enabled;
+    this.children = session.nativeSubagentsByTaskId ??= new Map();
+    this.taskByToolUse = session.nativeSubagentTaskIdByToolUseId ??= new Map();
+    this.parentByToolUse = session.nativeSubagentParentByToolUseId ??= new Map();
+    for (const child of this.children.values()) {
+      if (child.parentToolUseId) {
+        this.childByParentToolUse.set(child.parentToolUseId, child);
+      }
+    }
+  }
+
+  async route(
+    notification: AcpSessionNotification,
+    deliver: Publish,
+    forcedSessionId?: string,
+  ): Promise<AcpSessionNotification | null> {
+    const { update } = notification;
+    const claudeMeta = update._meta?.claudeCode as
+      { parentToolUseId?: string | null; subagent?: true; toolName?: string } | undefined;
+    const isControl = isNativeSubagentControlUpdate(update);
+
+    if (!this.enabled) return notification;
+
+    if (this.enabled && isControl) {
+      const toolCallId = update.toolCallId;
+      if (update.sessionUpdate === "tool_call") {
+        this.controlByToolUse.set(toolCallId, notification);
+      }
+      const identity = subagentIdentity(update.rawInput);
+      if (identity) {
+        this.identityByToolUse.set(
+          toolCallId,
+          mergeSubagentIdentity(this.identityByToolUse.get(toolCallId), identity),
+        );
+      }
+      const parentSessionId = claudeMeta?.parentToolUseId
+        ? this.childByParentToolUse.get(claudeMeta.parentToolUseId)?.sessionId
+        : this.rootSessionId;
+      this.parentByToolUse.set(toolCallId, parentSessionId ?? this.rootSessionId);
+
+      const child = this.childByParentToolUse.get(toolCallId);
+      if (child && !child.announced) {
+        child.parentSessionId = parentSessionId ?? this.rootSessionId;
+        applySubagentIdentity(child, this.identityByToolUse.get(toolCallId));
+        await announceNativeSubagent(child, this.publish);
+        for (const pending of this.takePending(toolCallId)) await deliver(pending);
+      }
+      if (!child && isFailedToolCallUpdate(update)) {
+        this.takePending(toolCallId);
+        const initial = this.controlByToolUse.get(toolCallId);
+        this.cleanupControl(toolCallId);
+        if (forcedSessionId) {
+          return { ...notification, sessionId: forcedSessionId };
+        }
+        return failedControlFallback(initial, notification, parentSessionId ?? this.rootSessionId);
+      }
+      return forcedSessionId ? { ...notification, sessionId: forcedSessionId } : null;
+    }
+
+    // A permission request may have had to create the tool call before native
+    // child ownership was known. Keep every later update in that original ACP
+    // session; moving a lifecycle after its initial call creates an orphan in
+    // both transcripts.
+    if (forcedSessionId) return { ...notification, sessionId: forcedSessionId };
+
+    if (this.enabled && claudeMeta?.parentToolUseId) {
+      const child = this.childByParentToolUse.get(claudeMeta.parentToolUseId);
+      if (!child || !child.announced) {
+        this.buffer(claudeMeta.parentToolUseId, notification);
+        return null;
+      }
+      if (child.terminalState !== undefined || child.terminalPromise) {
+        this.logger.log(
+          `Session ${this.rootSessionId}: ignoring late update for terminal subagent ${child.sessionId}`,
+        );
+        return null;
+      }
+      return { ...notification, sessionId: child.sessionId };
+    }
+
+    return notification;
+  }
+
+  async taskStarted(task: TaskStarted, deliver: Publish): Promise<void> {
+    if (!this.enabled) return;
+    if (!task.subagentType) {
+      if (task.toolUseId) {
+        this.takePending(task.toolUseId);
+        this.cleanupControl(task.toolUseId);
+      }
+      return;
+    }
+    const previous = this.children.get(task.taskId);
+    if (previous && previous.terminalState === undefined) return;
+
+    const knownParentSessionId = task.toolUseId
+      ? this.parentByToolUse.get(task.toolUseId)
+      : undefined;
+    const identity = task.toolUseId ? this.identityByToolUse.get(task.toolUseId) : undefined;
+    const child: NativeSubagent = {
+      sessionId: this.nextChildSessionId(task.taskId, previous),
+      parentSessionId: knownParentSessionId ?? this.rootSessionId,
+      parentToolUseId: task.toolUseId ?? undefined,
+      name: subagentDisplayName(
+        identity?.name,
+        identity?.description ?? task.description,
+        identity?.subagentType ?? task.subagentType,
+        task.taskId,
+      ),
+      task: subagentDescription(
+        identity?.prompt ?? task.prompt,
+        identity?.description ?? task.description,
+      ),
+    };
+    this.children.set(task.taskId, child);
+    if (task.toolUseId) {
+      this.taskByToolUse.set(task.toolUseId, task.taskId);
+      this.childByParentToolUse.set(task.toolUseId, child);
+      this.controlByToolUse.delete(task.toolUseId);
+    }
+
+    // A nested child must wait for the spawning Agent/Task frame to establish
+    // its immediate parent. Root children without a tool id can be announced.
+    if (knownParentSessionId || !task.toolUseId) {
+      await announceNativeSubagent(child, this.publish);
+      for (const pending of task.toolUseId ? this.takePending(task.toolUseId) : []) {
+        await deliver(pending);
+      }
+    }
+  }
+
+  async finishTask(
+    taskId: string,
+    status: unknown,
+    deliver: Publish,
+    toolUseId?: string | null,
+  ): Promise<void> {
+    if (!this.enabled) return;
+    const state = nativeSubagentState(status);
+    const child = toolUseId ? this.childByParentToolUse.get(toolUseId) : this.children.get(taskId);
+    if (child && toolUseId && this.taskByToolUse.get(toolUseId) !== taskId) return;
+    if (!state || !child || child.terminalState !== undefined) return;
+    const existing = this.taskFinishPromises.get(taskId);
+    if (existing) return existing;
+
+    const finish = Promise.resolve().then(async () => {
+      try {
+        await announceNativeSubagent(child, this.publish);
+        if (child.parentToolUseId) {
+          for (const pending of this.takePending(child.parentToolUseId)) await deliver(pending);
+        }
+        await finishNativeSubagent(this.session, taskId, state, this.publish);
+      } finally {
+        if (child.parentToolUseId) {
+          this.cleanupControl(child.parentToolUseId);
+        }
+      }
+    });
+    this.taskFinishPromises.set(taskId, finish);
+    try {
+      await finish;
+    } finally {
+      if (this.taskFinishPromises.get(taskId) === finish) this.taskFinishPromises.delete(taskId);
+    }
+  }
+
+  async finishAll(state: SubagentState, deliver: Publish): Promise<void> {
+    const errors: unknown[] = [];
+    try {
+      for (const taskId of [...this.children.keys()].reverse()) {
+        try {
+          await this.finishTask(taskId, state, deliver);
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+    } finally {
+      this.pending.clear();
+      this.pendingCount = 0;
+      this.identityByToolUse.clear();
+      this.controlByToolUse.clear();
+      this.parentByToolUse.clear();
+    }
+    if (errors.length === 1) throw errors[0];
+    if (errors.length > 1) throw new AggregateError(errors, "Failed to finish native subagents");
+  }
+
+  discardPending(parentToolUseId: string): void {
+    this.takePending(parentToolUseId);
+  }
+
+  clear(): void {
+    this.children.clear();
+    this.taskByToolUse.clear();
+    this.parentByToolUse.clear();
+    this.identityByToolUse.clear();
+    this.controlByToolUse.clear();
+    this.childByParentToolUse.clear();
+    this.taskFinishPromises.clear();
+    this.generationByTaskId.clear();
+    this.pending.clear();
+    this.pendingCount = 0;
+  }
+
+  private takePending(parentToolUseId: string): AcpSessionNotification[] {
+    const updates = this.pending.get(parentToolUseId) ?? [];
+    if (updates.length > 0) {
+      this.pending.delete(parentToolUseId);
+      this.pendingCount -= updates.length;
+    }
+    return updates;
+  }
+
+  private buffer(parentToolUseId: string, notification: AcpSessionNotification): void {
+    const updates = this.pending.get(parentToolUseId);
+    if (
+      this.pendingCount >= MAX_PENDING_UPDATES ||
+      (updates === undefined && this.pending.size >= MAX_PENDING_PARENTS) ||
+      (updates?.length ?? 0) >= MAX_PENDING_UPDATES_PER_PARENT
+    ) {
+      this.logger.log(
+        `Session ${this.rootSessionId}: dropping unattributed subagent update for ${parentToolUseId}; pending buffer limit reached`,
+      );
+      return;
+    }
+    if (updates) updates.push(notification);
+    else this.pending.set(parentToolUseId, [notification]);
+    this.pendingCount++;
+  }
+
+  private cleanupControl(toolUseId: string): void {
+    this.identityByToolUse.delete(toolUseId);
+    this.controlByToolUse.delete(toolUseId);
+    this.parentByToolUse.delete(toolUseId);
+  }
+
+  private nextChildSessionId(taskId: string, previous: NativeSubagent | undefined): string {
+    if (!previous) {
+      this.generationByTaskId.set(taskId, 1);
+      return taskId;
+    }
+    const generation = (this.generationByTaskId.get(taskId) ?? 1) + 1;
+    this.generationByTaskId.set(taskId, generation);
+    return `${taskId}:generation:${generation}`;
+  }
+}
+
+export async function announceNativeSubagent(
+  child: NativeSubagent,
+  publish: Publish,
+): Promise<void> {
+  if (child.announced) return;
+  if (child.announcePromise) return child.announcePromise;
+  const announce = Promise.resolve().then(async () => {
+    await publish({
+      sessionId: child.parentSessionId,
+      update: {
+        sessionUpdate: "subagent_spawned",
+        subagentSessionId: child.sessionId,
+        name: child.name,
+        task: child.task,
+        capabilities: {},
+      },
+    });
+    child.announced = true;
+  });
+  child.announcePromise = announce;
+  try {
+    await announce;
+  } finally {
+    if (child.announcePromise === announce) child.announcePromise = undefined;
+  }
+}
+
+export async function finishNativeSubagent(
+  session: NativeSubagentSession,
+  taskId: string,
+  state: SubagentState,
+  publish: Publish,
+): Promise<void> {
+  const child = session.nativeSubagentsByTaskId?.get(taskId);
+  if (!child || child.terminalState !== undefined) return;
+  if (child.terminalPromise) return child.terminalPromise;
+  const finish = Promise.resolve().then(async () => {
+    await announceNativeSubagent(child, publish);
+    await publish({
+      sessionId: child.parentSessionId,
+      update: {
+        sessionUpdate: "subagent_state_update",
+        subagentSessionId: child.sessionId,
+        state,
+      },
+    });
+    child.terminalState = state;
+  });
+  child.terminalPromise = finish;
+  try {
+    await finish;
+  } finally {
+    if (child.terminalPromise === finish) child.terminalPromise = undefined;
+  }
+}
+
+export function nativeSubagentState(status: unknown): SubagentState | undefined {
+  if (status === "completed") return "completed";
+  if (status === "failed") return "failed";
+  if (status === "disconnected") return "disconnected";
+  if (status === "killed" || status === "cancelled" || status === "stopped") return "cancelled";
+  return undefined;
+}
+
+export function isNativeSubagentControlUpdate(
+  update: AcpSessionNotification["update"],
+): update is Extract<
+  AcpSessionNotification["update"],
+  { sessionUpdate: "tool_call" | "tool_call_update" }
+> {
+  if (update.sessionUpdate !== "tool_call" && update.sessionUpdate !== "tool_call_update") {
+    return false;
+  }
+  const claudeMeta = update._meta?.claudeCode as { subagent?: true; toolName?: string } | undefined;
+  return claudeMeta?.subagent === true || isNativeSubagentControlTool(claudeMeta?.toolName);
+}
+
+export function isNativeSubagentControlTool(toolName: unknown): boolean {
+  return toolName === "Agent" || toolName === "Task";
+}
+
+function isFailedToolCallUpdate(update: AcpSessionNotification["update"]): boolean {
+  return (
+    (update.sessionUpdate === "tool_call" || update.sessionUpdate === "tool_call_update") &&
+    update.status === "failed"
+  );
+}
+
+function failedControlFallback(
+  initial: AcpSessionNotification | undefined,
+  terminal: AcpSessionNotification,
+  sessionId: string,
+): AcpSessionNotification {
+  if (
+    terminal.update.sessionUpdate !== "tool_call" &&
+    terminal.update.sessionUpdate !== "tool_call_update"
+  ) {
+    return { ...terminal, sessionId };
+  }
+  if (!initial || initial.update.sessionUpdate !== "tool_call") {
+    const claudeMeta = terminal.update._meta?.claudeCode as { toolName?: unknown } | undefined;
+    return {
+      ...terminal,
+      sessionId,
+      update: {
+        ...terminal.update,
+        sessionUpdate: "tool_call",
+        status: "failed",
+        title:
+          typeof terminal.update.title === "string" && terminal.update.title.length > 0
+            ? terminal.update.title
+            : claudeMeta?.toolName === "Task"
+              ? "Task"
+              : "Agent",
+        _meta: ordinaryToolMeta(terminal.update._meta),
+      } as AcpSessionNotification["update"],
+    };
+  }
+  return {
+    ...initial,
+    sessionId,
+    update: {
+      ...initial.update,
+      ...terminal.update,
+      sessionUpdate: "tool_call",
+      status: "failed",
+      title:
+        typeof terminal.update.title === "string" && terminal.update.title.trim().length > 0
+          ? terminal.update.title
+          : initial.update.title,
+      _meta: {
+        ...initial.update._meta,
+        ...terminal.update._meta,
+        ...ordinaryToolMeta(initial.update._meta, terminal.update._meta),
+      },
+    } as AcpSessionNotification["update"],
+  };
+}
+
+function ordinaryToolMeta(
+  ...values: Array<Record<string, unknown> | null | undefined>
+): Record<string, unknown> {
+  const merged = Object.assign({}, ...values);
+  const claudeCode = Object.assign(
+    {},
+    ...values.map(
+      (value) => (value?.claudeCode as Record<string, unknown> | null | undefined) ?? {},
+    ),
+  );
+  delete claudeCode.subagent;
+  return { ...merged, claudeCode };
+}
+
+function subagentDisplayName(
+  explicitName: unknown,
+  description: unknown,
+  type: unknown,
+  taskId: string,
+): string {
+  for (const value of [explicitName, description, type]) {
+    if (typeof value === "string" && value.trim().length > 0) return value.trim();
+  }
+  const suffix = taskId.length > 8 ? taskId.slice(-8) : taskId;
+  return `Agent ${suffix}`;
+}
+
+function subagentDescription(prompt: unknown, description: unknown): string {
+  for (const value of [prompt, description]) {
+    if (typeof value === "string" && value.trim().length > 0) return value.trim();
+  }
+  return "Delegated task";
+}
+
+function subagentIdentity(input: unknown): SubagentIdentity | undefined {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) return undefined;
+  const value = input as Record<string, unknown>;
+  const identity: SubagentIdentity = {
+    name: nonBlankString(value.name),
+    description: nonBlankString(value.description),
+    prompt: nonBlankString(value.prompt),
+    subagentType: nonBlankString(value.subagent_type),
+  };
+  return Object.values(identity).some(Boolean) ? identity : undefined;
+}
+
+function mergeSubagentIdentity(
+  previous: SubagentIdentity | undefined,
+  next: SubagentIdentity,
+): SubagentIdentity {
+  return {
+    name: next.name ?? previous?.name,
+    description: next.description ?? previous?.description,
+    prompt: next.prompt ?? previous?.prompt,
+    subagentType: next.subagentType ?? previous?.subagentType,
+  };
+}
+
+function applySubagentIdentity(
+  child: NativeSubagent,
+  identity: SubagentIdentity | undefined,
+): void {
+  if (!identity) return;
+  if (identity.name || identity.description) {
+    child.name = subagentDisplayName(
+      identity.name,
+      identity.description,
+      identity.subagentType,
+      child.sessionId,
+    );
+  }
+  if (identity.prompt || identity.description) {
+    child.task = subagentDescription(identity.prompt, identity.description);
+  }
+}
+
+function nonBlankString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
--- a/src/permissions/effects.ts
+++ b/src/permissions/effects.ts
@@ -0,0 +1,223 @@
+import type { RequestPermissionResponse } from "@agentclientprotocol/sdk";
+import type {
+  PermissionMode,
+  PermissionResult,
+  PermissionUpdate,
+} from "@anthropic-ai/claude-agent-sdk";
+import type { DurablePermissionChangeSet } from "./normalization.js";
+import { PERMISSION_OPTION_ID } from "./options.js";
+
+export interface ClaudePermissionSelection {
+  optionId: string;
+  contextResetMode?: PermissionMode;
+}
+
+export interface ClaudePermissionEffectContext {
+  toolName: string;
+  input: Record<string, unknown>;
+  toolUseID: string;
+  durableChangeSet?: DurablePermissionChangeSet;
+}
+
+/** Parse the ACP envelope once before dispatching to a tool-specific effect. */
+export function parseClaudePermissionSelection(
+  response: RequestPermissionResponse,
+  toolName: string,
+): ClaudePermissionSelection {
+  if (response.outcome?.outcome !== "selected") throw new Error("Tool use aborted");
+  const optionId = response.outcome.optionId;
+  const contextResetMode =
+    toolName === "ExitPlanMode" ? exitPlanClearContextMode(optionId) : undefined;
+  return { optionId, ...(contextResetMode ? { contextResetMode } : {}) };
+}
+
+function allow(
+  context: ClaudePermissionEffectContext,
+  updatedPermissions?: PermissionUpdate[],
+  permanent = false,
+): PermissionResult {
+  return {
+    behavior: "allow",
+    updatedInput: context.input,
+    ...(updatedPermissions ? { updatedPermissions } : {}),
+    toolUseID: context.toolUseID,
+    decisionClassification: permanent ? "user_permanent" : "user_temporary",
+  };
+}
+
+function deny(
+  context: ClaudePermissionEffectContext,
+  message = "User refused permission to run tool",
+  interrupt = false,
+): PermissionResult {
+  return {
+    behavior: "deny",
+    message,
+    ...(interrupt ? { interrupt: true } : {}),
+    toolUseID: context.toolUseID,
+    decisionClassification: "user_reject",
+  };
+}
+
+function skillName(input: Record<string, unknown>): string {
+  const value = typeof input.skill === "string" ? input.skill.trim() : "";
+  if (!value || value.length > 1_000) throw new Error("Invalid Skill permission input");
+  return value;
+}
+
+function localAllowRuleUpdate(toolName: string, ruleContent?: string): PermissionUpdate[] {
+  return [
+    {
+      type: "addRules",
+      rules: [{ toolName, ...(ruleContent === undefined ? {} : { ruleContent }) }],
+      behavior: "allow",
+      destination: "localSettings",
+    },
+  ];
+}
+
+function webFetchPermissionUpdate(input: Record<string, unknown>): PermissionUpdate[] {
+  if (typeof input.url !== "string") throw new Error("Invalid WebFetch permission input");
+  let hostname: string;
+  try {
+    hostname = new URL(input.url).hostname;
+  } catch {
+    throw new Error("Invalid WebFetch permission input");
+  }
+  if (!hostname) throw new Error("Invalid WebFetch permission input");
+  return localAllowRuleUpdate("WebFetch", `domain:${hostname}`);
+}
+
+function applySkillSelection(
+  selection: ClaudePermissionSelection,
+  context: ClaudePermissionEffectContext,
+): PermissionResult {
+  switch (selection.optionId) {
+    case PERMISSION_OPTION_ID.allowSkillExact: {
+      return allow(context, localAllowRuleUpdate("Skill", skillName(context.input)), true);
+    }
+    case PERMISSION_OPTION_ID.allowSkillPrefix: {
+      const skill = skillName(context.input);
+      const spaceIndex = skill.indexOf(" ");
+      if (spaceIndex <= 0) throw new Error("Skill prefix permission requires arguments");
+      return allow(context, localAllowRuleUpdate("Skill", `${skill.slice(0, spaceIndex)}:*`), true);
+    }
+    default:
+      return applyCommonSelection(selection, context);
+  }
+}
+
+function exitPlanMode(optionId: string): PermissionMode | undefined {
+  switch (optionId) {
+    case PERMISSION_OPTION_ID.exitPlanBypass:
+      return "bypassPermissions";
+    case PERMISSION_OPTION_ID.exitPlanAuto:
+      return "auto";
+    case PERMISSION_OPTION_ID.exitPlanAcceptEdits:
+      return "acceptEdits";
+    case PERMISSION_OPTION_ID.exitPlanDefault:
+      return "default";
+    default:
+      return undefined;
+  }
+}
+
+export function exitPlanClearContextMode(optionId: string): PermissionMode | undefined {
+  switch (optionId) {
+    case PERMISSION_OPTION_ID.exitPlanClearAuto:
+      return "auto";
+    case PERMISSION_OPTION_ID.exitPlanClearBypass:
+      return "bypassPermissions";
+    case PERMISSION_OPTION_ID.exitPlanClearAcceptEdits:
+      return "acceptEdits";
+    default:
+      return undefined;
+  }
+}
+
+function applyExitPlanModeSelection(
+  selection: ClaudePermissionSelection,
+  context: ClaudePermissionEffectContext,
+): PermissionResult {
+  if (selection.contextResetMode) {
+    // The adapter consumes this interrupt and continues the same ACP turn on a
+    // fresh Claude query. Returning allow here would execute ExitPlanMode in
+    // the old context before the handoff.
+    return deny(context, "User accepted the plan and requested a fresh context", true);
+  }
+  const mode = exitPlanMode(selection.optionId);
+  if (mode) {
+    return allow(context, [{ type: "setMode", mode, destination: "session" }], mode !== "default");
+  }
+  if (selection.optionId === PERMISSION_OPTION_ID.reject) {
+    // A regular deny lets Claude continue planning and ask another question.
+    // Interrupt stops this ACP turn; the adapter maps Claude's internal
+    // diagnostic for that intentional stop back to cancellation.
+    return deny(context, "User chose to keep planning", true);
+  }
+  return applyCommonSelection(selection, context);
+}
+
+function applyCommonSelection(
+  selection: ClaudePermissionSelection,
+  context: ClaudePermissionEffectContext,
+): PermissionResult {
+  switch (selection.optionId) {
+    case PERMISSION_OPTION_ID.allowOnce:
+      return allow(context);
+    case PERMISSION_OPTION_ID.allowWithUpdates:
+      if (!context.durableChangeSet) throw new Error("Invalid durable permission selection");
+      return allow(context, context.durableChangeSet.updates, true);
+    case PERMISSION_OPTION_ID.reject:
+      return deny(context);
+    default:
+      throw new Error(`Unknown permission option: ${selection.optionId}`);
+  }
+}
+
+function applyGeneratedDurableSelection(
+  selection: ClaudePermissionSelection,
+  context: ClaudePermissionEffectContext,
+  updates: () => PermissionUpdate[],
+): PermissionResult {
+  if (selection.optionId !== PERMISSION_OPTION_ID.allowWithUpdates) {
+    return applyCommonSelection(selection, context);
+  }
+  return allow(context, updates(), true);
+}
+
+/** Apply a parsed selection using the semantics of the tool that produced it. */
+export function applyClaudePermissionSelection(
+  selection: ClaudePermissionSelection,
+  context: ClaudePermissionEffectContext,
+): PermissionResult {
+  switch (context.toolName) {
+    case "Skill":
+      return applySkillSelection(selection, context);
+    case "WebFetch":
+      return applyGeneratedDurableSelection(selection, context, () =>
+        webFetchPermissionUpdate(context.input),
+      );
+    case "EnterPlanMode":
+      return applyCommonSelection(selection, context);
+    case "ExitPlanMode":
+      return applyExitPlanModeSelection(selection, context);
+    case "Read":
+    case "Bash":
+    case "PowerShell":
+    case "Glob":
+    case "Grep":
+    case "Edit":
+    case "Write":
+    case "NotebookEdit":
+    case "SandboxNetworkAccess":
+      return applyCommonSelection(selection, context);
+    default:
+      if (context.toolName.startsWith("mcp__")) {
+        return applyCommonSelection(selection, context);
+      }
+      return applyGeneratedDurableSelection(selection, context, () =>
+        localAllowRuleUpdate(context.toolName),
+      );
+  }
+}
--- a/src/permissions/modes.ts
+++ b/src/permissions/modes.ts
@@ -0,0 +1,59 @@
+import type { PermissionMode } from "@anthropic-ai/claude-agent-sdk";
+
+interface PermissionModeLogger {
+  error: (...args: unknown[]) => void;
+}
+
+// Bypass Permissions doesn't work if we are a root/sudo user.
+const IS_ROOT = (process.geteuid?.() ?? process.getuid?.()) === 0;
+export const ALLOW_BYPASS = !IS_ROOT || !!process.env.IS_SANDBOX;
+
+const PERMISSION_MODE_ALIASES: Record<string, PermissionMode> = {
+  // Settings use user-facing, case-insensitive spellings while the SDK uses
+  // camel-cased wire values. Keep legacy shorthand accepted by Claude Code too.
+  auto: "auto",
+  default: "default",
+  // Claude Code 2.1.200 renamed the "default" mode to "Manual" and accepts
+  // `"defaultMode": "manual"` in settings.json; honor the same alias here.
+  manual: "default",
+  acceptedits: "acceptEdits",
+  dontask: "dontAsk",
+  plan: "plan",
+  bypasspermissions: "bypassPermissions",
+  bypass: "bypassPermissions",
+};
+
+export function resolvePermissionMode(
+  defaultMode?: unknown,
+  logger: PermissionModeLogger = console,
+): PermissionMode {
+  if (defaultMode === undefined) {
+    return "default";
+  }
+
+  if (typeof defaultMode !== "string") {
+    logger.error("Ignoring permissions.defaultMode from settings: expected a string.");
+    return "default";
+  }
+
+  const normalized = defaultMode.trim().toLowerCase();
+  if (normalized === "") {
+    logger.error("Ignoring permissions.defaultMode from settings: expected a non-empty string.");
+    return "default";
+  }
+
+  const mapped = PERMISSION_MODE_ALIASES[normalized];
+  if (!mapped) {
+    logger.error(`Ignoring permissions.defaultMode from settings: unknown value '${defaultMode}'.`);
+    return "default";
+  }
+
+  if (mapped === "bypassPermissions" && !ALLOW_BYPASS) {
+    logger.error(
+      "Ignoring permissions.defaultMode from settings: bypassPermissions is not available when running as root.",
+    );
+    return "default";
+  }
+
+  return mapped;
+}
--- a/src/permissions/normalization.ts
+++ b/src/permissions/normalization.ts
@@ -0,0 +1,130 @@
+import type {
+  PermissionBehavior,
+  PermissionMode,
+  PermissionUpdate,
+  PermissionUpdateDestination,
+} from "@anthropic-ai/claude-agent-sdk";
+
+export interface DurablePermissionChangeSet {
+  updates: PermissionUpdate[];
+}
+
+const MAX_UPDATES = 100;
+const MAX_RULES_PER_UPDATE = 100;
+const MAX_DIRECTORIES_PER_UPDATE = 100;
+const MAX_TOOL_NAME_LENGTH = 512;
+const MAX_RULE_CONTENT_LENGTH = 10_000;
+const MAX_DIRECTORY_LENGTH = 4_096;
+
+const DESTINATIONS = new Set<PermissionUpdateDestination>([
+  "session",
+  "cliArg",
+  "userSettings",
+  "projectSettings",
+  "localSettings",
+]);
+const BEHAVIORS = new Set<PermissionBehavior>(["allow", "deny", "ask"]);
+const MODES = new Set<PermissionMode>([
+  "default",
+  "acceptEdits",
+  "bypassPermissions",
+  "plan",
+  "dontAsk",
+  "auto",
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function isDestination(value: unknown): value is PermissionUpdateDestination {
+  return typeof value === "string" && DESTINATIONS.has(value as PermissionUpdateDestination);
+}
+
+function safePlainString(value: unknown, maxLength: number): value is string {
+  if (typeof value !== "string") return false;
+  const normalized = value.trim();
+  return (
+    normalized.length > 0 &&
+    value.length <= maxLength &&
+    !Array.from(normalized).some((character) => {
+      const code = character.charCodeAt(0);
+      return (
+        code <= 0x08 ||
+        code === 0x0b ||
+        code === 0x0c ||
+        (code >= 0x0e && code <= 0x1f) ||
+        code === 0x7f
+      );
+    })
+  );
+}
+
+function isRule(value: unknown): value is { toolName: string; ruleContent?: string } {
+  if (!isRecord(value) || !safePlainString(value.toolName, MAX_TOOL_NAME_LENGTH)) {
+    return false;
+  }
+  return (
+    value.ruleContent === undefined || safePlainString(value.ruleContent, MAX_RULE_CONTENT_LENGTH)
+  );
+}
+
+function isKnownUpdate(value: unknown): value is PermissionUpdate {
+  if (!isRecord(value) || !isDestination(value.destination) || typeof value.type !== "string") {
+    return false;
+  }
+  switch (value.type) {
+    case "addRules":
+    case "replaceRules":
+    case "removeRules":
+      return (
+        Array.isArray(value.rules) &&
+        value.rules.length <= MAX_RULES_PER_UPDATE &&
+        (value.type === "replaceRules" || value.rules.length > 0) &&
+        value.rules.every(isRule) &&
+        typeof value.behavior === "string" &&
+        BEHAVIORS.has(value.behavior as PermissionBehavior)
+      );
+    case "setMode":
+      return typeof value.mode === "string" && MODES.has(value.mode as PermissionMode);
+    case "addDirectories":
+    case "removeDirectories":
+      return (
+        Array.isArray(value.directories) &&
+        value.directories.length > 0 &&
+        value.directories.length <= MAX_DIRECTORIES_PER_UPDATE &&
+        value.directories.every((directory) => safePlainString(directory, MAX_DIRECTORY_LENGTH))
+      );
+    default:
+      return false;
+  }
+}
+
+export function normalizeDurablePermissionChangeSet(
+  suggestions: unknown,
+  forcedAsk = false,
+): DurablePermissionChangeSet | undefined {
+  if (forcedAsk) return undefined;
+  try {
+    if (
+      !Array.isArray(suggestions) ||
+      suggestions.length === 0 ||
+      suggestions.length > MAX_UPDATES ||
+      !suggestions.every(isKnownUpdate)
+    ) {
+      return undefined;
+    }
+    return {
+      // The ACP prompt may stay open for an arbitrary amount of time. Snapshot the
+      // provider payload so the label the user approved and the effect returned to
+      // Claude cannot diverge through later mutation of the callback argument.
+      updates: structuredClone(suggestions as PermissionUpdate[]),
+    };
+  } catch {
+    // SDK data is expected to be plain structured-cloneable input. Treat an
+    // accessor, function, proxy, or other non-wire value as an invalid bundle.
+    // Validation belongs in this boundary too because merely reading one of those
+    // values can throw before structuredClone gets a chance to reject it.
+    return undefined;
+  }
+}
--- a/src/permissions/options.ts
+++ b/src/permissions/options.ts
@@ -0,0 +1,86 @@
+import type { PermissionOption } from "@agentclientprotocol/sdk";
+import {
+  buildEditPermissionOptions,
+  buildGlobPermissionOptions,
+  buildGrepPermissionOptions,
+  buildNotebookEditPermissionOptions,
+  buildReadPermissionOptions,
+  buildWritePermissionOptions,
+} from "./options/filesystem.js";
+import { buildBashPermissionOptions, buildPowerShellPermissionOptions } from "./options/shell.js";
+import type { PermissionOptionContext } from "./options/shared.js";
+import {
+  buildComputerUseMcpPermissionOptions,
+  buildEnterPlanModePermissionOptions,
+  buildExitPlanModePermissionOptions,
+  buildFallbackPermissionOptions,
+  buildSandboxNetworkPermissionOptions,
+  buildSkillPermissionOptions,
+  buildWebFetchPermissionOptions,
+  isComputerUseMcpTool,
+} from "./options/tools.js";
+
+export { PERMISSION_OPTION_ID } from "./options/shared.js";
+
+export function buildClaudePermissionOptions(context: PermissionOptionContext): PermissionOption[] {
+  return buildUnsortedClaudePermissionOptions(context).sort(
+    (left, right) => permissionOptionOrder(left) - permissionOptionOrder(right),
+  );
+}
+
+function buildUnsortedClaudePermissionOptions(
+  context: PermissionOptionContext,
+): PermissionOption[] {
+  if (isComputerUseMcpTool(context.toolName)) {
+    return buildComputerUseMcpPermissionOptions(context);
+  }
+  switch (context.toolName) {
+    case "AskUserQuestion":
+      throw new Error("AskUserQuestion must be handled by ACP elicitation, not permission options");
+    case "Bash":
+      return buildBashPermissionOptions(context);
+    case "PowerShell":
+      return buildPowerShellPermissionOptions(context);
+    case "Read":
+      return buildReadPermissionOptions(context);
+    case "Glob":
+      return buildGlobPermissionOptions(context);
+    case "Grep":
+      return buildGrepPermissionOptions(context);
+    case "Edit":
+      return buildEditPermissionOptions(context);
+    case "Write":
+      return buildWritePermissionOptions(context);
+    case "NotebookEdit":
+      return buildNotebookEditPermissionOptions(context);
+    case "WebFetch":
+      return buildWebFetchPermissionOptions(context);
+    case "Skill":
+      return buildSkillPermissionOptions(context);
+    case "EnterPlanMode":
+      return buildEnterPlanModePermissionOptions();
+    case "ExitPlanMode":
+      return buildExitPlanModePermissionOptions(context);
+    case "SandboxNetworkAccess":
+      return buildSandboxNetworkPermissionOptions(context);
+    case "WebSearch":
+    case "Agent":
+    case "Task":
+    default:
+      return buildFallbackPermissionOptions(context);
+  }
+}
+
+function permissionOptionOrder(option: PermissionOption): number {
+  switch (option.kind) {
+    case "allow_once":
+      return 0;
+    case "allow_always":
+      return 1;
+    case "reject_once":
+    case "reject_always":
+      return 3;
+    default:
+      return 2;
+  }
+}
--- a/src/permissions/options/filesystem.ts
+++ b/src/permissions/options/filesystem.ts
@@ -0,0 +1,186 @@
+import type { PermissionOption } from "@agentclientprotocol/sdk";
+import os from "node:os";
+import path from "node:path";
+import type { DurablePermissionChangeSet } from "../normalization.js";
+import { plainString, type PermissionOptionContext, withOptionalUpdate } from "./shared.js";
+
+function isFileSessionChangeSet(
+  changeSet: DurablePermissionChangeSet | undefined,
+  operation: "read" | "write",
+): boolean {
+  return (
+    !!changeSet &&
+    changeSet.updates.every((update) => {
+      if (update.destination !== "session") return false;
+      if (update.type === "setMode") {
+        return operation === "write" && update.mode === "acceptEdits";
+      }
+      if (update.type === "addDirectories") return operation === "write";
+      if (update.type !== "addRules" || update.behavior !== "allow") return false;
+      return update.rules.every((rule) =>
+        operation === "read" ? rule.toolName === "Read" : rule.toolName === "Edit",
+      );
+    })
+  );
+}
+
+function inputPath(context: PermissionOptionContext, key: string): string | undefined {
+  return plainString(context.input[key]);
+}
+
+function isInside(directory: string, candidate: string): boolean {
+  const relative = path.relative(path.resolve(directory), path.resolve(candidate));
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== "..");
+}
+
+function hasSessionAllowRuleFor(
+  changeSet: DurablePermissionChangeSet | undefined,
+  toolName: string,
+): boolean {
+  return !!changeSet?.updates.some(
+    (update) =>
+      update.type === "addRules" &&
+      update.destination === "session" &&
+      update.behavior === "allow" &&
+      update.rules.some((rule) => rule.toolName === toolName),
+  );
+}
+
+function hasBroadSessionAllowRuleFor(
+  changeSet: DurablePermissionChangeSet,
+  toolName: string,
+): boolean {
+  return changeSet.updates.some(
+    (update) =>
+      update.type === "addRules" &&
+      update.destination === "session" &&
+      update.behavior === "allow" &&
+      update.rules.some((rule) => rule.toolName === toolName && rule.ruleContent === undefined),
+  );
+}
+
+function hasAcceptEditsMode(changeSet: DurablePermissionChangeSet): boolean {
+  return changeSet.updates.some(
+    (update) =>
+      update.type === "setMode" &&
+      update.destination === "session" &&
+      update.mode === "acceptEdits",
+  );
+}
+
+function permissionPath(ruleContent: string | undefined): string | undefined {
+  const value = plainString(ruleContent);
+  if (!value) return undefined;
+  return value.replace(/[/\\]\*\*$/, "");
+}
+
+function effectCoversFilePath(
+  changeSet: DurablePermissionChangeSet,
+  filePath: string,
+  operation: "read" | "write",
+  cwd: string,
+): boolean {
+  const directory = path.dirname(filePath);
+  const comparable = (candidate: string): boolean => {
+    const resolved = path.resolve(cwd, candidate);
+    return resolved === directory || isInside(resolved, filePath);
+  };
+  const paths = changeSet.updates.flatMap((update) => {
+    if (update.type === "addDirectories") return update.directories;
+    if (update.type !== "addRules" || update.behavior !== "allow") return [];
+    return update.rules
+      .filter((rule) =>
+        operation === "read" ? rule.toolName === "Read" : rule.toolName === "Edit",
+      )
+      .map((rule) => permissionPath(rule.ruleContent))
+      .filter((value): value is string => value !== undefined);
+  });
+  return paths.some(comparable);
+}
+
+function fileSessionLabel(
+  context: PermissionOptionContext,
+  filePath: string | undefined,
+  operation: "read" | "write",
+): string | undefined {
+  if (!isFileSessionChangeSet(context.durableChangeSet, operation)) return undefined;
+  const resolvedFilePath = filePath ? path.resolve(context.cwd, filePath) : undefined;
+  const isClaudePath =
+    operation === "write" &&
+    !!resolvedFilePath &&
+    (isInside(path.join(context.cwd, ".claude"), resolvedFilePath) ||
+      isInside(path.join(os.homedir(), ".claude"), resolvedFilePath));
+  const broadRule = hasBroadSessionAllowRuleFor(
+    context.durableChangeSet!,
+    operation === "read" ? "Read" : "Edit",
+  );
+  if (resolvedFilePath) {
+    const coversCurrentPath =
+      effectCoversFilePath(context.durableChangeSet!, resolvedFilePath, operation, context.cwd) ||
+      broadRule ||
+      (operation === "write" && !isClaudePath && hasAcceptEditsMode(context.durableChangeSet!));
+    if (!coversCurrentPath) return undefined;
+  } else if (
+    !broadRule &&
+    !(operation === "write" && hasAcceptEditsMode(context.durableChangeSet!))
+  ) {
+    return undefined;
+  }
+  if (
+    operation === "write" &&
+    resolvedFilePath &&
+    isClaudePath &&
+    hasSessionAllowRuleFor(context.durableChangeSet, "Edit")
+  ) {
+    return "Yes, and allow Claude to edit its own settings for this session";
+  }
+  if (!resolvedFilePath || isInside(context.cwd, resolvedFilePath)) {
+    return operation === "read"
+      ? "Yes, during this session"
+      : "Yes, allow all edits during this session";
+  }
+  const directory = path.dirname(resolvedFilePath);
+  const directoryName = path.basename(directory) || "this directory";
+  return operation === "read"
+    ? `Yes, allow reading from ${directoryName}${path.sep} during this session`
+    : `Yes, allow all edits in ${directoryName}${path.sep} during this session`;
+}
+
+function buildFilePermissionOptions(
+  context: PermissionOptionContext,
+  filePath: string | undefined,
+  operation: "read" | "write",
+): PermissionOption[] {
+  return withOptionalUpdate(
+    context.durableChangeSet,
+    fileSessionLabel(context, filePath, operation),
+    "Yes",
+    "No",
+  );
+}
+
+export function buildReadPermissionOptions(context: PermissionOptionContext): PermissionOption[] {
+  return buildFilePermissionOptions(context, inputPath(context, "file_path"), "read");
+}
+
+export function buildGlobPermissionOptions(context: PermissionOptionContext): PermissionOption[] {
+  return buildFilePermissionOptions(context, inputPath(context, "path") ?? context.cwd, "read");
+}
+
+export function buildGrepPermissionOptions(context: PermissionOptionContext): PermissionOption[] {
+  return buildFilePermissionOptions(context, inputPath(context, "path") ?? context.cwd, "read");
+}
+
+export function buildEditPermissionOptions(context: PermissionOptionContext): PermissionOption[] {
+  return buildFilePermissionOptions(context, inputPath(context, "file_path"), "write");
+}
+
+export function buildWritePermissionOptions(context: PermissionOptionContext): PermissionOption[] {
+  return buildFilePermissionOptions(context, inputPath(context, "file_path"), "write");
+}
+
+export function buildNotebookEditPermissionOptions(
+  context: PermissionOptionContext,
+): PermissionOption[] {
+  return buildFilePermissionOptions(context, inputPath(context, "notebook_path"), "write");
+}
--- a/src/permissions/options/shared.ts
+++ b/src/permissions/options/shared.ts
@@ -0,0 +1,105 @@
+import type { PermissionOption } from "@agentclientprotocol/sdk";
+import type { DurablePermissionChangeSet } from "../normalization.js";
+
+export const PERMISSION_OPTION_ID = {
+  allowOnce: "allow-once",
+  allowWithUpdates: "allow-with-updates",
+  allowSkillExact: "allow-skill-exact",
+  allowSkillPrefix: "allow-skill-prefix",
+  exitPlanBypass: "exit-plan-bypass",
+  exitPlanAuto: "exit-plan-auto",
+  exitPlanAcceptEdits: "exit-plan-accept-edits",
+  exitPlanDefault: "exit-plan-default",
+  exitPlanClearAuto: "exit-plan-clear-auto",
+  exitPlanClearBypass: "exit-plan-clear-bypass",
+  exitPlanClearAcceptEdits: "exit-plan-clear-accept-edits",
+  reject: "reject",
+} as const;
+
+export interface PermissionOptionContext {
+  toolName: string;
+  displayName?: string;
+  input: Record<string, unknown>;
+  cwd: string;
+  durableChangeSet?: DurablePermissionChangeSet;
+  allowPersistentOptions?: boolean;
+  availableModes?: readonly string[];
+  contextUsedPercent?: number;
+}
+
+export function allowOnce(name = "Yes"): PermissionOption {
+  return { optionId: PERMISSION_OPTION_ID.allowOnce, name, kind: "allow_once" };
+}
+
+export function allowWithUpdates(name: string): PermissionOption {
+  return { optionId: PERMISSION_OPTION_ID.allowWithUpdates, name, kind: "allow_always" };
+}
+
+export function reject(name = "No"): PermissionOption {
+  return { optionId: PERMISSION_OPTION_ID.reject, name, kind: "reject_once" };
+}
+
+export function withOptionalUpdate(
+  changeSet: DurablePermissionChangeSet | undefined,
+  updateName: string | undefined,
+  allowName = "Yes",
+  rejectName = "No",
+): PermissionOption[] {
+  const options = [allowOnce(allowName)];
+  if (changeSet && updateName) options.push(allowWithUpdates(updateName));
+  options.push(reject(rejectName));
+  return options;
+}
+
+export function plainString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+export function exactLocalAllowRule(
+  changeSet: DurablePermissionChangeSet | undefined,
+  toolName: string,
+  ruleContent?: string,
+): boolean {
+  if (!changeSet || changeSet.updates.length !== 1) return false;
+  const update = changeSet.updates[0];
+  if (
+    update?.type !== "addRules" ||
+    update.behavior !== "allow" ||
+    update.destination !== "localSettings" ||
+    update.rules.length !== 1
+  ) {
+    return false;
+  }
+  const rule = update.rules[0];
+  return (
+    rule?.toolName === toolName &&
+    (ruleContent === undefined
+      ? rule.ruleContent === undefined
+      : plainString(rule.ruleContent) === ruleContent)
+  );
+}
+
+/**
+ * An MCP "don't ask again" option is only truthful when every provider update
+ * adds an unrestricted allow rule for the tool currently being prompted.
+ */
+export function isMcpAllowChangeSet(
+  changeSet: DurablePermissionChangeSet | undefined,
+  toolName: string,
+): boolean {
+  return (
+    !!changeSet &&
+    changeSet.updates.length > 0 &&
+    changeSet.updates.every(
+      (update) =>
+        update.type === "addRules" &&
+        update.behavior === "allow" &&
+        update.rules.length > 0 &&
+        update.rules.every((rule) => rule.toolName === toolName && rule.ruleContent === undefined),
+    )
+  );
+}
+
+export function withGeneratedUpdate(name: string, rejectName = "No"): PermissionOption[] {
+  return [allowOnce(), allowWithUpdates(name), reject(rejectName)];
+}
--- a/src/permissions/options/shell.ts
+++ b/src/permissions/options/shell.ts
@@ -0,0 +1,121 @@
+import type { PermissionOption } from "@agentclientprotocol/sdk";
+import path from "node:path";
+import type { DurablePermissionChangeSet } from "../normalization.js";
+import { plainString, type PermissionOptionContext, withOptionalUpdate } from "./shared.js";
+
+function permissionRulePrefix(value: string): string {
+  return value.endsWith(":*") ? value.slice(0, -2) : value;
+}
+
+function displayList(values: string[]): string {
+  if (values.join(", ").length > 50) return "similar";
+  if (values.length === 1) return values[0]!;
+  if (values.length === 2) return `${values[0]} and ${values[1]}`;
+  return `${values.slice(0, -1).join(", ")}, and ${values.at(-1)}`;
+}
+
+/** Shorten paths only as much as needed to distinguish them in prompt text. */
+function displayPaths(paths: string[]): string {
+  const normalizedPaths = [...new Set(paths.map((value) => path.normalize(value)))];
+  const segments = normalizedPaths.map((value) => value.split(path.sep).filter(Boolean));
+
+  // Compare equally deep suffixes so duplicate basenames gain the smallest
+  // useful parent prefix (for example, codex-acp/src/ vs claude-acp/src/).
+  const suffix = (index: number, depth: number): string =>
+    segments[index]!.slice(-depth).join(path.sep) || normalizedPaths[index]!;
+  const names = normalizedPaths.map((value, index) => {
+    const parts = segments[index]!;
+    let name = path.basename(value) || value;
+    for (let depth = 1; depth <= parts.length; depth++) {
+      const candidate = suffix(index, depth);
+      if (
+        normalizedPaths.every((_, other) => other === index || suffix(other, depth) !== candidate)
+      ) {
+        name = candidate;
+        break;
+      }
+      if (depth === parts.length) name = value;
+    }
+    return name.endsWith(path.sep) ? name : `${name}${path.sep}`;
+  });
+
+  // Native Claude labels enumerate two paths and summarize larger sets.
+  if (names.length <= 2) return displayList(names);
+  return `${names[0]}, ${names[1]} and ${names.length - 2} more`;
+}
+
+/** Plain-text port of Claude Code's generateShellSuggestionsLabel. */
+function shellSuggestionsLabel(
+  toolName: "Bash" | "PowerShell",
+  changeSet: DurablePermissionChangeSet,
+): string | undefined {
+  const representable = changeSet.updates.every((update) => {
+    if (update.type === "addDirectories") return update.destination === "session";
+    if (update.type !== "addRules" || update.behavior !== "allow") return false;
+    return update.rules.every(
+      (rule) =>
+        (rule.toolName === toolName || rule.toolName === "Read") &&
+        plainString(rule.ruleContent) !== undefined,
+    );
+  });
+  if (!representable) return undefined;
+
+  const rules = changeSet.updates
+    .filter((update) => update.type === "addRules")
+    .flatMap((update) => update.rules);
+  const readPaths = rules
+    .filter((rule) => rule.toolName === "Read")
+    .map((rule) => rule.ruleContent?.replace(/\/\*\*$/, ""))
+    .filter((value): value is string => !!value);
+  const commands = [
+    ...new Set(
+      rules
+        .filter((rule) => rule.toolName === toolName && rule.ruleContent)
+        .map((rule) => permissionRulePrefix(rule.ruleContent!)),
+    ),
+  ];
+  const directories = changeSet.updates
+    .filter((update) => update.type === "addDirectories")
+    .flatMap((update) => update.directories);
+  const hasPaths = readPaths.length > 0 || directories.length > 0;
+
+  if (readPaths.length > 0 && directories.length === 0 && commands.length === 0) {
+    return `Yes, allow reading from ${displayPaths(readPaths)} from this project`;
+  }
+  if (directories.length > 0 && readPaths.length === 0 && commands.length === 0) {
+    return `Yes, and always allow access to ${displayPaths(directories)} from this project`;
+  }
+  if (commands.length > 0 && !hasPaths) {
+    return `Yes, and don't ask again for ${displayList(commands)} commands`;
+  }
+  if (hasPaths && commands.length === 0) {
+    return `Yes, and always allow access to ${displayPaths([...directories, ...readPaths])} from this project`;
+  }
+  if (hasPaths && commands.length > 0) {
+    const paths = [...directories, ...readPaths];
+    return paths.length === 1 && commands.length === 1
+      ? `Yes, and allow access to ${displayPaths(paths)} and ${displayList(commands)} commands`
+      : `Yes, and allow ${displayPaths(paths)} access and ${displayList(commands)} commands`;
+  }
+  return undefined;
+}
+
+function buildShellPermissionOptions(
+  context: PermissionOptionContext,
+  toolName: "Bash" | "PowerShell",
+): PermissionOption[] {
+  const name = context.durableChangeSet
+    ? shellSuggestionsLabel(toolName, context.durableChangeSet)
+    : undefined;
+  return withOptionalUpdate(context.durableChangeSet, name, "Yes", "No");
+}
+
+export function buildBashPermissionOptions(context: PermissionOptionContext): PermissionOption[] {
+  return buildShellPermissionOptions(context, "Bash");
+}
+
+export function buildPowerShellPermissionOptions(
+  context: PermissionOptionContext,
+): PermissionOption[] {
+  return buildShellPermissionOptions(context, "PowerShell");
+}
--- a/src/permissions/options/tools.ts
+++ b/src/permissions/options/tools.ts
@@ -0,0 +1,170 @@
+import type { PermissionOption } from "@agentclientprotocol/sdk";
+import {
+  allowOnce,
+  exactLocalAllowRule,
+  isMcpAllowChangeSet,
+  PERMISSION_OPTION_ID,
+  plainString,
+  type PermissionOptionContext,
+  reject,
+  withGeneratedUpdate,
+  withOptionalUpdate,
+} from "./shared.js";
+
+export function buildWebFetchPermissionOptions(
+  context: PermissionOptionContext,
+): PermissionOption[] {
+  const url = plainString(context.input.url);
+  if (url && context.allowPersistentOptions !== false) {
+    try {
+      const hostname = new URL(url).hostname;
+      if (hostname) {
+        return withGeneratedUpdate(`Yes, and don't ask again for ${hostname}`);
+      }
+    } catch {
+      // Invalid input cannot produce Claude Code's domain-specific option.
+    }
+  }
+  return [allowOnce(), reject("No")];
+}
+
+export function buildSkillPermissionOptions(context: PermissionOptionContext): PermissionOption[] {
+  const skill = plainString(context.input.skill);
+  const options = [allowOnce()];
+  if (skill && context.allowPersistentOptions !== false) {
+    options.push({
+      optionId: PERMISSION_OPTION_ID.allowSkillExact,
+      name: `Yes, and don't ask again for ${skill}`,
+      kind: "allow_always",
+    });
+    const spaceIndex = skill.indexOf(" ");
+    if (spaceIndex > 0) {
+      const prefix = `${skill.slice(0, spaceIndex)}:*`;
+      options.push({
+        optionId: PERMISSION_OPTION_ID.allowSkillPrefix,
+        name: `Yes, and don't ask again for ${prefix} commands`,
+        kind: "allow_always",
+      });
+    }
+  }
+  options.push(reject("No"));
+  return options;
+}
+
+export function buildEnterPlanModePermissionOptions(): PermissionOption[] {
+  return [allowOnce("Yes, enter plan mode"), reject("No, start implementing now")];
+}
+
+export function buildExitPlanModePermissionOptions(
+  context: PermissionOptionContext,
+): PermissionOption[] {
+  const modes = new Set(context.availableModes);
+  const options: PermissionOption[] = [];
+  const elevatedMode = modes.has("auto")
+    ? "auto"
+    : modes.has("bypassPermissions")
+      ? "bypassPermissions"
+      : "acceptEdits";
+  if (plainString(context.input.plan)) {
+    const usage =
+      context.contextUsedPercent === undefined ? "" : ` (${context.contextUsedPercent}% used)`;
+    if (elevatedMode === "auto") {
+      options.push({
+        optionId: PERMISSION_OPTION_ID.exitPlanClearAuto,
+        name: `Yes, clear context${usage} and use auto mode`,
+        kind: "allow_always",
+      });
+    } else if (elevatedMode === "bypassPermissions") {
+      options.push({
+        optionId: PERMISSION_OPTION_ID.exitPlanClearBypass,
+        name: `Yes, clear context${usage} and bypass permissions`,
+        kind: "allow_always",
+      });
+    } else {
+      options.push({
+        optionId: PERMISSION_OPTION_ID.exitPlanClearAcceptEdits,
+        name: `Yes, clear context${usage} and auto-accept edits`,
+        kind: "allow_always",
+      });
+    }
+  }
+  if (elevatedMode === "auto") {
+    options.push({
+      optionId: PERMISSION_OPTION_ID.exitPlanAuto,
+      name: "Yes, and use auto mode",
+      kind: "allow_always",
+    });
+  } else if (elevatedMode === "bypassPermissions") {
+    options.push({
+      optionId: PERMISSION_OPTION_ID.exitPlanBypass,
+      name: "Yes, and bypass permissions",
+      kind: "allow_always",
+    });
+  } else {
+    options.push({
+      optionId: PERMISSION_OPTION_ID.exitPlanAcceptEdits,
+      name: "Yes, auto-accept edits",
+      kind: "allow_always",
+    });
+  }
+  options.push({
+    optionId: PERMISSION_OPTION_ID.exitPlanDefault,
+    name: "Yes, manually approve edits",
+    kind: "allow_once",
+  });
+  options.push(reject("No, keep planning"));
+  return options;
+}
+
+export function buildSandboxNetworkPermissionOptions(
+  context: PermissionOptionContext,
+): PermissionOption[] {
+  const host = plainString(context.input.host);
+  const name =
+    host && exactLocalAllowRule(context.durableChangeSet, context.toolName, host)
+      ? `Yes, and don't ask again for ${host}`
+      : undefined;
+  return withOptionalUpdate(context.durableChangeSet, name, "Yes", "No");
+}
+
+export function buildFallbackPermissionOptions(
+  context: PermissionOptionContext,
+): PermissionOption[] {
+  const toolLabel = plainString(context.displayName) ?? context.toolName;
+  if (context.toolName.startsWith("mcp__")) {
+    const changeSet =
+      context.allowPersistentOptions !== false &&
+      isMcpAllowChangeSet(context.durableChangeSet, context.toolName)
+        ? context.durableChangeSet
+        : undefined;
+    return withOptionalUpdate(
+      changeSet,
+      changeSet ? `Yes, and don't ask again for ${toolLabel} commands` : undefined,
+    );
+  }
+  if (context.allowPersistentOptions !== false) {
+    return withGeneratedUpdate(`Yes, and don't ask again for ${toolLabel} commands`);
+  }
+  return [allowOnce(), reject("No")];
+}
+
+const COMPUTER_USE_MCP_TOOL_PREFIX = "mcp__computer-use__";
+
+export function isComputerUseMcpTool(toolName: string): boolean {
+  return toolName.startsWith(COMPUTER_USE_MCP_TOOL_PREFIX);
+}
+
+export function buildComputerUseMcpPermissionOptions(
+  context: PermissionOptionContext,
+): PermissionOption[] {
+  const toolLabel = plainString(context.displayName) ?? context.toolName;
+  const changeSet =
+    context.allowPersistentOptions !== false &&
+    isMcpAllowChangeSet(context.durableChangeSet, context.toolName)
+      ? context.durableChangeSet
+      : undefined;
+  return withOptionalUpdate(
+    changeSet,
+    changeSet ? `Yes, and don't ask again for ${toolLabel}` : undefined,
+  );
+}
--- a/src/permissions/presentation.ts
+++ b/src/permissions/presentation.ts
@@ -0,0 +1,112 @@
+import type { RequestPermissionRequest, ToolCallLocation } from "@agentclientprotocol/sdk";
+import { toolInfoFromToolUse } from "../tools.js";
+
+export interface ClaudePermissionPresentationInput {
+  toolName: string;
+  input: Record<string, unknown>;
+  toolUseID: string;
+  cwd?: string;
+  supportsTerminalOutput?: boolean;
+  blockedPath?: string;
+  title?: string;
+  displayName?: string;
+  description?: string;
+  decisionReason?: string;
+}
+
+function humanText(value: unknown, maxLength: number, singleLine = false): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const withoutControls = Array.from(value)
+    .filter((character) => {
+      const code = character.charCodeAt(0);
+      return !(
+        code <= 0x08 ||
+        code === 0x0b ||
+        code === 0x0c ||
+        (code >= 0x0e && code <= 0x1f) ||
+        code === 0x7f
+      );
+    })
+    .join("");
+  const normalized = singleLine
+    ? withoutControls.replace(/\s+/gu, " ").trim()
+    : withoutControls.trim();
+  return normalized && normalized.length <= maxLength ? normalized : undefined;
+}
+
+function compactText(value: unknown): string | undefined {
+  return humanText(value, 160, true);
+}
+
+function withBlockedPath(
+  locations: ToolCallLocation[] | undefined,
+  blockedPath: unknown,
+): ToolCallLocation[] | undefined {
+  const path = humanText(blockedPath, 4_096, true);
+  if (!path) return locations;
+  const result = [...(locations ?? [])];
+  if (!result.some((location) => location.path === path)) result.push({ path });
+  return result;
+}
+
+export function buildClaudePermissionPresentation(
+  value: ClaudePermissionPresentationInput,
+): Pick<RequestPermissionRequest, "toolCall" | "_meta"> {
+  const info = toolInfoFromToolUse(
+    { id: value.toolUseID, name: value.toolName, input: value.input },
+    value.supportsTerminalOutput ?? false,
+    value.cwd,
+  );
+  const host =
+    value.toolName === "SandboxNetworkAccess" ? compactText(value.input.host) : undefined;
+  const isComputerUse = value.toolName.startsWith("mcp__computer-use__");
+  const subjectTitle = host ?? (isComputerUse ? compactText(value.displayName) : undefined);
+  const subjectContent =
+    (host || isComputerUse) && info.content.length === 0
+      ? [
+          {
+            type: "content" as const,
+            content: {
+              type: "text" as const,
+              text: `\`\`\`json\n${JSON.stringify(value.input, null, 2)}\n\`\`\``,
+            },
+          },
+        ]
+      : info.content;
+  // Reuse the exact standard tool-call heading as the permission heading so
+  // the approval never maintains a second, divergent name for the operation.
+  // decisionReason is temporarily exposed as the permission description so
+  // its actual SDK values can be inspected; it remains diagnostic policy text.
+  const shellTitle =
+    value.toolName === "Bash" || value.toolName === "PowerShell"
+      ? (compactText(value.input.description) ?? value.toolName)
+      : undefined;
+  const toolCallTitle = shellTitle ?? subjectTitle ?? info.title;
+  const permissionTitle = value.toolName === "ExitPlanMode" ? "Ready to code?" : toolCallTitle;
+  const title = humanText(permissionTitle, 4_000, true) ?? "Use tool?";
+  const decisionReason = humanText(value.decisionReason, 4_000);
+  const description = decisionReason ? `Reason: ${decisionReason}` : undefined;
+  return {
+    toolCall: {
+      toolCallId: value.toolUseID,
+      name: value.toolName,
+      status: "pending",
+      rawInput: value.input,
+      ...info,
+      title: toolCallTitle,
+      content: subjectContent,
+      locations: withBlockedPath(info.locations, value.blockedPath),
+    },
+    ...(title
+      ? {
+          _meta: {
+            permission: {
+              version: 1,
+              title,
+              ...(description ? { description } : {}),
+            },
+          },
+        }
+      : {}),
+  };
+}
--- a/src/permissions/response.ts
+++ b/src/permissions/response.ts
@@ -0,0 +1,36 @@
+import type { RequestPermissionResponse } from "@agentclientprotocol/sdk";
+import type { PermissionOption } from "@agentclientprotocol/sdk";
+import type { PermissionMode, PermissionResult } from "@anthropic-ai/claude-agent-sdk";
+import type { DurablePermissionChangeSet } from "./normalization.js";
+import { applyClaudePermissionSelection, parseClaudePermissionSelection } from "./effects.js";
+
+export interface ClaudePermissionDecision {
+  permissionResult: PermissionResult;
+  contextResetMode?: PermissionMode;
+}
+
+/** Decode, validate, and interpret an ACP response exactly once. */
+export function decodeClaudePermissionResponse(
+  response: RequestPermissionResponse,
+  toolName: string,
+  input: Record<string, unknown>,
+  toolUseID: string,
+  offeredOptions: readonly PermissionOption[],
+  durableChangeSet?: DurablePermissionChangeSet,
+): ClaudePermissionDecision {
+  const selection = parseClaudePermissionSelection(response, toolName);
+  const offeredOption = offeredOptions.find((option) => option.optionId === selection.optionId);
+  if (!offeredOption) {
+    throw new Error(`Permission option was not offered: ${selection.optionId}`);
+  }
+  const permissionResult = applyClaudePermissionSelection(selection, {
+    toolName,
+    input,
+    toolUseID,
+    durableChangeSet,
+  });
+  return {
+    permissionResult,
+    ...(selection.contextResetMode ? { contextResetMode: selection.contextResetMode } : {}),
+  };
+}
--- a/src/session-config-ids.ts
+++ b/src/session-config-ids.ts
@@ -0,0 +1,4 @@
+/** Shared sentinels and ids for session preferences managed by the adapter. */
+export const DEFAULT_MODEL_ID = "default";
+export const DEFAULT_AGENT_ID = "default";
+export const EFFORT_CONFIG_ID = "effort";
--- a/src/session-failure-extension.ts
+++ b/src/session-failure-extension.ts
@@ -0,0 +1,437 @@
+import type { ClientCapabilities, SessionNotification } from "@agentclientprotocol/sdk";
+import {
+  getSessionMessages,
+  type SDKAssistantMessageError,
+  USAGE_LIMIT_ERROR_PREFIXES,
+} from "@anthropic-ai/claude-agent-sdk";
+import { randomUUID } from "node:crypto";
+import {
+  AIR_SESSION_FAILURE_CAPABILITY,
+  airCapabilityMeta,
+  clientSupportsAirCapability,
+  withAirMeta,
+} from "./air-extension.js";
+
+export function airSessionFailureCapabilityMeta(...additionalCapabilities: string[]) {
+  return airCapabilityMeta(AIR_SESSION_FAILURE_CAPABILITY, ...additionalCapabilities);
+}
+
+export type ClaudeFailureKind =
+  | "advisory"
+  | "auth_required"
+  | "bad_request"
+  | "budget_exhausted"
+  | "context_exhausted"
+  | "internal_error"
+  | "overloaded"
+  | "provider_error"
+  | "quota_exhausted"
+  | "rate_limited"
+  | "transport_lost"
+  | "worker_shutdown";
+
+type AirSessionFailureCategory =
+  "connection" | "access" | "limit" | "request" | "service" | "unknown";
+
+type AirSessionFailureSeverity = "warning" | "error";
+type AirSessionFailureAction = "retry" | "login" | "new_session";
+
+type SessionFailureRecoveryPolicy =
+  "never" | "next_attempt" | "real_model_success" | "auth_status" | "runtime_rebind";
+
+export type PublishedSessionFailure = {
+  id: string;
+  revision: number;
+  kind: ClaudeFailureKind;
+  category: AirSessionFailureCategory;
+  turnId?: string;
+  severity: AirSessionFailureSeverity;
+  title: string;
+  details?: string;
+  actions: AirSessionFailureAction[];
+  recoveryPolicy: SessionFailureRecoveryPolicy;
+};
+
+type SessionFailureOptions = {
+  turnId?: string;
+  sessionScoped?: boolean;
+  title?: string;
+  details?: string;
+  severity?: AirSessionFailureSeverity;
+};
+
+export type SessionFailureState = {
+  epoch: string;
+  revisions: Map<string, number>;
+  active: Map<string, PublishedSessionFailure>;
+  nextIncident?: number;
+  lastNotice?: { title: string; id: string };
+};
+
+type Logger = {
+  error: (...args: unknown[]) => void;
+};
+
+export function createSessionFailureState(): SessionFailureState {
+  return {
+    epoch: randomUUID(),
+    revisions: new Map(),
+    active: new Map(),
+  };
+}
+
+const AIR_FAILURE_POLICY: Record<
+  ClaudeFailureKind,
+  {
+    category: AirSessionFailureCategory;
+    actions: AirSessionFailureAction[];
+    fallbackTitle: string;
+  }
+> = {
+  advisory: {
+    category: "unknown",
+    actions: [],
+    fallbackTitle: "Claude reported a notice.",
+  },
+  auth_required: {
+    category: "access",
+    actions: ["login"],
+    fallbackTitle: "Sign in to continue using Claude.",
+  },
+  bad_request: {
+    category: "request",
+    actions: [],
+    fallbackTitle: "Claude could not process this request.",
+  },
+  budget_exhausted: {
+    category: "limit",
+    actions: ["new_session"],
+    fallbackTitle: "This Claude session reached its configured budget.",
+  },
+  context_exhausted: {
+    category: "limit",
+    actions: ["new_session"],
+    fallbackTitle: "This Claude turn reached its configured limit.",
+  },
+  internal_error: {
+    category: "service",
+    actions: ["retry", "new_session"],
+    fallbackTitle: "Claude Agent encountered an internal error.",
+  },
+  overloaded: {
+    category: "service",
+    actions: ["retry"],
+    fallbackTitle: "Claude is temporarily overloaded.",
+  },
+  provider_error: {
+    category: "service",
+    actions: ["retry"],
+    fallbackTitle: "The model provider reported an error.",
+  },
+  quota_exhausted: {
+    category: "limit",
+    actions: [],
+    fallbackTitle: "The Claude account has no available quota.",
+  },
+  rate_limited: {
+    category: "limit",
+    actions: ["retry"],
+    fallbackTitle: "Claude is temporarily rate limited.",
+  },
+  transport_lost: {
+    category: "connection",
+    actions: ["new_session"],
+    fallbackTitle: "The connection to Claude was lost.",
+  },
+  worker_shutdown: {
+    category: "connection",
+    actions: ["new_session"],
+    fallbackTitle: "The Claude worker is shutting down.",
+  },
+};
+
+export function sessionFailureMeta(failure: PublishedSessionFailure) {
+  return withAirMeta(undefined, AIR_SESSION_FAILURE_CAPABILITY, {
+    id: failure.id,
+    revision: failure.revision,
+    category: failure.category,
+    severity: failure.severity,
+    title: failure.title,
+    ...(failure.details ? { details: failure.details } : {}),
+    actions: failure.actions,
+  });
+}
+
+/** `getSessionMessages` deliberately exposes only the API message and strips
+ *  transcript-level `error` / `isApiErrorMessage` fields. The SDK exports the
+ *  exact stable prefixes used by its synthetic usage-limit errors, so replay
+ *  can recover this one typed failure without matching arbitrary model prose. */
+export function assistantMessageText(apiMessage: unknown): string | undefined {
+  if (!apiMessage || typeof apiMessage !== "object") return undefined;
+  const { content } = apiMessage as { content?: unknown };
+  if (typeof content === "string") return content || undefined;
+  if (!Array.isArray(content)) return undefined;
+  const text = content
+    .map((block) =>
+      block &&
+      typeof block === "object" &&
+      "type" in block &&
+      block.type === "text" &&
+      "text" in block &&
+      typeof block.text === "string"
+        ? block.text
+        : "",
+    )
+    .join("");
+  return text || undefined;
+}
+
+export function isSyntheticUsageLimitMessage(apiMessage: unknown): boolean {
+  if (!apiMessage || typeof apiMessage !== "object") return false;
+  const { model } = apiMessage as { model?: unknown };
+  if (model !== "<synthetic>") return false;
+  const text = assistantMessageText(apiMessage);
+  if (!text) return false;
+  return USAGE_LIMIT_ERROR_PREFIXES.some((prefix) => text.startsWith(prefix));
+}
+
+export function activeUsageLimitMessage(
+  messages: Awaited<ReturnType<typeof getSessionMessages>>,
+): { uuid: string; title: string } | undefined {
+  let active: { uuid: string; title: string } | undefined;
+  for (const message of messages) {
+    if (message.type !== "assistant" || message.parent_tool_use_id !== null) continue;
+    if (isSyntheticUsageLimitMessage(message.message)) {
+      const title = assistantMessageText(message.message);
+      if (title) active = { uuid: message.uuid, title };
+      continue;
+    }
+    const model =
+      message.message && typeof message.message === "object" && "model" in message.message
+        ? message.message.model
+        : undefined;
+    // A later real model answer proves the account recovered. Synthetic
+    // local-command/interruption messages do not: they can be appended while
+    // the provider remains unavailable.
+    if (model !== undefined && model !== "<synthetic>") active = undefined;
+  }
+  return active;
+}
+
+export function supportsAirSessionFailures(capabilities?: ClientCapabilities): boolean {
+  return clientSupportsAirCapability(capabilities, AIR_SESSION_FAILURE_CAPABILITY);
+}
+
+function sessionFailureRecoveryPolicy(
+  kind: ClaudeFailureKind,
+  turnId?: string,
+): SessionFailureRecoveryPolicy {
+  switch (kind) {
+    case "advisory":
+      return "never";
+    case "auth_required":
+      return "auth_status";
+    case "transport_lost":
+    case "worker_shutdown":
+      return "runtime_rebind";
+    case "quota_exhausted":
+      return "real_model_success";
+    default:
+      return turnId ? "next_attempt" : "real_model_success";
+  }
+}
+
+/** Owns the AIR failure lifecycle for both the live consumer and history replay.
+ *  Published revisions become active only after delivery succeeds; recovery only
+ *  removes internal active state because transcript records are historical. */
+export class SessionFailureController {
+  private readonly sessionId: string;
+  private readonly state: SessionFailureState;
+  private readonly capabilities?: ClientCapabilities;
+  private readonly isCurrent: () => boolean;
+  private readonly sendUpdate: (notification: SessionNotification) => Promise<void>;
+  private readonly logger: Logger;
+
+  constructor(options: {
+    sessionId: string;
+    state: SessionFailureState;
+    capabilities?: ClientCapabilities;
+    isCurrent: () => boolean;
+    sendUpdate: (notification: SessionNotification) => Promise<void>;
+    logger: Logger;
+  }) {
+    this.sessionId = options.sessionId;
+    this.state = options.state;
+    this.capabilities = options.capabilities;
+    this.isCurrent = options.isCurrent;
+    this.sendUpdate = options.sendUpdate;
+    this.logger = options.logger;
+  }
+
+  private isSupported(): boolean {
+    return supportsAirSessionFailures(this.capabilities);
+  }
+
+  private async emit(failure: PublishedSessionFailure): Promise<boolean> {
+    if (!this.isCurrent()) {
+      this.logger.error(
+        `Session ${this.sessionId}: ignored AIR session failure from a stale consumer`,
+      );
+      return false;
+    }
+    try {
+      await this.sendUpdate({
+        sessionId: this.sessionId,
+        update: {
+          sessionUpdate: "session_info_update",
+          _meta: sessionFailureMeta(failure),
+        },
+      });
+      return true;
+    } catch (error) {
+      this.logger.error(
+        `Session ${this.sessionId}: failed to publish AIR session failure: ${error}`,
+      );
+      return false;
+    }
+  }
+
+  recordActive(failure: PublishedSessionFailure): void {
+    this.state.revisions.set(failure.id, failure.revision);
+    this.state.active.set(failure.id, failure);
+    this.state.lastNotice =
+      failure.kind === "advisory" ? { title: failure.title, id: failure.id } : undefined;
+  }
+
+  async clear(
+    shouldClear: (failure: PublishedSessionFailure) => boolean = () => true,
+  ): Promise<boolean> {
+    if (!this.isSupported()) return true;
+    this.state.lastNotice = undefined;
+    for (const failure of [...this.state.active.values()]) {
+      if (!shouldClear(failure)) continue;
+      this.state.active.delete(failure.id);
+    }
+    return true;
+  }
+
+  async prepare(
+    kind: ClaudeFailureKind,
+    failureOptions: SessionFailureOptions = {},
+  ): Promise<PublishedSessionFailure | undefined> {
+    if (!this.isSupported() || !this.isCurrent()) return undefined;
+    const policy = AIR_FAILURE_POLICY[kind];
+    const title = failureOptions.title || policy.fallbackTitle;
+    if (kind === "advisory") {
+      const id =
+        this.state.lastNotice?.title === title
+          ? this.state.lastNotice.id
+          : `${this.sessionId}:notice:${this.state.epoch}:${this.state.nextIncident ?? 1}`;
+      if (this.state.lastNotice?.title !== title) {
+        this.state.nextIncident = (this.state.nextIncident ?? 1) + 1;
+      }
+      return {
+        id,
+        revision: (this.state.revisions.get(id) ?? 0) + 1,
+        kind,
+        category: policy.category,
+        severity: "warning",
+        title,
+        ...(failureOptions.details ? { details: failureOptions.details } : {}),
+        actions: policy.actions,
+        recoveryPolicy: sessionFailureRecoveryPolicy(kind),
+      };
+    }
+    const id =
+      failureOptions.turnId && !failureOptions.sessionScoped
+        ? `${failureOptions.turnId}:error`
+        : `${this.sessionId}:session-error:${this.state.epoch}:${this.state.nextIncident ?? 1}`;
+    if (!failureOptions.turnId || failureOptions.sessionScoped) {
+      this.state.nextIncident = (this.state.nextIncident ?? 1) + 1;
+    }
+    return {
+      id,
+      revision: (this.state.revisions.get(id) ?? 0) + 1,
+      kind,
+      category: policy.category,
+      severity: failureOptions.severity ?? "error",
+      title,
+      ...(failureOptions.details ? { details: failureOptions.details } : {}),
+      actions: failureOptions.severity === "warning" ? [] : policy.actions,
+      recoveryPolicy: sessionFailureRecoveryPolicy(
+        kind,
+        failureOptions.turnId && !failureOptions.sessionScoped ? failureOptions.turnId : undefined,
+      ),
+      ...(failureOptions.turnId && !failureOptions.sessionScoped
+        ? { turnId: failureOptions.turnId }
+        : {}),
+    };
+  }
+
+  async publish(
+    kind: ClaudeFailureKind,
+    failureOptions: SessionFailureOptions = {},
+  ): Promise<void> {
+    const failure = await this.prepare(kind, failureOptions);
+    if (!failure) return;
+    if (await this.emit(failure)) this.recordActive(failure);
+  }
+
+  async restore(
+    id: string,
+    kind: ClaudeFailureKind,
+    title: string,
+    active = true,
+  ): Promise<boolean> {
+    if (!this.isSupported() || !this.isCurrent()) return false;
+    const policy = AIR_FAILURE_POLICY[kind];
+    const failure: PublishedSessionFailure = {
+      id,
+      revision: (this.state.revisions.get(id) ?? 0) + 1,
+      kind,
+      category: policy.category,
+      severity: "error",
+      title,
+      actions: policy.actions,
+      recoveryPolicy: sessionFailureRecoveryPolicy(kind),
+    };
+    if (!(await this.emit(failure))) return false;
+    this.state.revisions.set(failure.id, failure.revision);
+    if (active) {
+      this.state.active.set(failure.id, failure);
+    } else {
+      this.state.active.delete(failure.id);
+    }
+    return true;
+  }
+}
+
+export function providerFailureCategory(
+  errorKind?: SDKAssistantMessageError,
+  isUsageLimit = false,
+): ClaudeFailureKind {
+  if (isUsageLimit) return "quota_exhausted";
+  switch (errorKind) {
+    case "authentication_failed":
+    case "oauth_org_not_allowed":
+      return "auth_required";
+    case "billing_error":
+    case "account_on_hold":
+      return "quota_exhausted";
+    case "rate_limit":
+      return "rate_limited";
+    case "overloaded":
+      return "overloaded";
+    case "invalid_request":
+    case "model_not_found":
+      return "bad_request";
+    case "max_output_tokens":
+      return "context_exhausted";
+    case "server_error":
+    case "unknown":
+    case undefined:
+      return "provider_error";
+    default:
+      return "provider_error";
+  }
+}
--- a/src/session-mode.ts
+++ b/src/session-mode.ts
@@ -0,0 +1,333 @@
+import {
+  RequestError,
+  type SessionConfigOption,
+  type SessionModeState,
+  type SessionNotification,
+  type SetSessionModeRequest,
+  type SetSessionModeResponse,
+} from "@agentclientprotocol/sdk";
+import type {
+  ModelInfo,
+  PermissionMode,
+  PermissionResult,
+  Query,
+} from "@anthropic-ai/claude-agent-sdk";
+import { ALLOW_BYPASS } from "./permissions/modes.js";
+
+export const MODE_CONFIG_ID = "mode";
+export const AUTO_MODE_FALLBACK: PermissionMode = "acceptEdits";
+
+const AUTO_MODE_FALLBACK_NOTICE =
+  "**Auto mode unavailable:** the selected model does not support Auto mode; using Accept edits instead.";
+
+export type SessionMode = {
+  query: Pick<Query, "setPermissionMode">;
+  queryClosed?: boolean;
+  modes: SessionModeState;
+  models: { currentModelId: string };
+  modelInfos: ModelInfo[];
+  /** Prevents the model-specific Auto fallback from spamming the transcript. */
+  autoModeFallbackWarningShown?: boolean;
+  /** Initial mode fallback is reported after session/new, on the first prompt. */
+  autoModeFallbackWarningPending?: boolean;
+};
+
+export type SessionModeManagerOptions<S extends SessionMode> = {
+  getSession(sessionId: string): S | undefined;
+  sessionEndedMessage: string;
+  updateConfigOption(sessionId: string, configId: string, value: string): Promise<void>;
+  sessionUpdate(params: SessionNotification): Promise<void>;
+  logError(...args: unknown[]): void;
+};
+
+type ModeConfigSession = SessionMode & {
+  configOptions: SessionConfigOption[];
+};
+
+type InitializeSessionModeParams = {
+  query: Pick<Query, "setPermissionMode">;
+  requestedMode: PermissionMode;
+  currentModelInfo?: ModelInfo;
+  currentModelId: string;
+};
+
+/** Owns session-mode policy and the ACP/SDK synchronization it requires. */
+export class SessionModeManager<S extends SessionMode> {
+  constructor(private readonly options: SessionModeManagerOptions<S>) {}
+
+  async initialize({
+    query,
+    requestedMode,
+    currentModelInfo,
+    currentModelId,
+  }: InitializeSessionModeParams): Promise<{
+    modes: SessionModeState;
+    autoModeFallbackWarningPending: boolean;
+  }> {
+    const availableModes = this.buildAvailableModes();
+    let effectiveMode = requestedMode;
+    let autoModeFallbackWarningPending = false;
+
+    if (
+      effectiveMode === "auto" &&
+      currentModelInfo !== undefined &&
+      currentModelInfo.supportsAutoMode !== true
+    ) {
+      this.options.logError(
+        `permissions.defaultMode "auto" is not available for model ` +
+          `"${currentModelId}"; falling back to "${AUTO_MODE_FALLBACK}".`,
+      );
+      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 {
+      modes: { currentModeId: effectiveMode, availableModes },
+      autoModeFallbackWarningPending,
+    };
+  }
+
+  static configOption(modes: SessionModeState): SessionConfigOption {
+    return {
+      id: MODE_CONFIG_ID,
+      name: "Mode",
+      description: "Session permission mode",
+      category: "mode",
+      type: "select",
+      currentValue: modes.currentModeId,
+      options: modes.availableModes.map((mode) => ({
+        value: mode.id,
+        name: mode.name,
+        description: mode.description,
+        _meta: mode._meta,
+      })),
+    };
+  }
+
+  syncConfig(session: ModeConfigSession, mode: string): void {
+    session.modes = { ...session.modes, currentModeId: mode };
+    session.configOptions = session.configOptions.map((option) =>
+      option.id === MODE_CONFIG_ID && typeof option.currentValue === "string"
+        ? { ...option, currentValue: mode }
+        : option,
+    );
+  }
+
+  availableModeIds(modes: SessionModeState): string[] {
+    return modes.availableModes.map((mode) => mode.id);
+  }
+
+  effectiveMode(session: SessionMode, requestedMode: PermissionMode): PermissionMode {
+    return requestedMode === "auto" && this.isAutoUnavailable(session)
+      ? AUTO_MODE_FALLBACK
+      : requestedMode;
+  }
+
+  applyPermissionFallback(
+    session: SessionMode,
+    permissionResult: PermissionResult,
+  ): { permissionResult: PermissionResult; fallbackApplied: boolean } {
+    const fallbackApplied =
+      this.isAutoUnavailable(session) &&
+      permissionResult.behavior === "allow" &&
+      permissionResult.updatedPermissions?.some(
+        (update) => update.type === "setMode" && update.mode === "auto",
+      ) === true;
+    if (!fallbackApplied || permissionResult.behavior !== "allow") {
+      return { permissionResult, fallbackApplied: false };
+    }
+
+    return {
+      permissionResult: {
+        ...permissionResult,
+        updatedPermissions: permissionResult.updatedPermissions?.map((update) =>
+          update.type === "setMode" && update.mode === "auto"
+            ? { ...update, mode: AUTO_MODE_FALLBACK }
+            : update,
+        ),
+      },
+      fallbackApplied: true,
+    };
+  }
+
+  /** Reconcile mode after a model switch. The caller rebuilds config options
+   * before publishing the returned state change. */
+  async reconcileForModel(session: SessionMode, model: ModelInfo | undefined) {
+    if (
+      session.modes.currentModeId !== "auto" ||
+      model === undefined ||
+      model.supportsAutoMode === true
+    ) {
+      return false;
+    }
+
+    session.modes = {
+      availableModes: session.modes.availableModes,
+      currentModeId: AUTO_MODE_FALLBACK,
+    };
+    await this.trySyncMode(
+      session.query,
+      AUTO_MODE_FALLBACK,
+      `Failed to sync permissionMode to "${AUTO_MODE_FALLBACK}" after model switch invalidated "auto":`,
+    );
+    return true;
+  }
+
+  async selectMode(sessionId: string, modeId: string): Promise<PermissionMode> {
+    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`);
+    }
+
+    const effectiveMode = this.effectiveMode(session, requestedMode);
+    try {
+      await session.query.setPermissionMode(effectiveMode);
+    } catch (error) {
+      if (error instanceof Error) {
+        if (!error.message) error.message = "Invalid Mode";
+        throw error;
+      }
+      // eslint-disable-next-line preserve-caught-error
+      throw new Error("Invalid Mode");
+    }
+
+    if (effectiveMode !== requestedMode) {
+      await this.publishFallbackWarning(sessionId, session);
+    }
+    return effectiveMode;
+  }
+
+  async setSessionMode(params: SetSessionModeRequest): Promise<SetSessionModeResponse> {
+    const effectiveMode = await this.selectMode(params.sessionId, params.modeId);
+    if (effectiveMode !== params.modeId) {
+      await this.publishCurrent(params.sessionId, effectiveMode);
+    }
+    await this.options.updateConfigOption(params.sessionId, MODE_CONFIG_ID, effectiveMode);
+    return {};
+  }
+
+  async publishCurrent(sessionId: string, mode: string): Promise<void> {
+    await this.options.sessionUpdate({
+      sessionId,
+      update: { sessionUpdate: "current_mode_update", currentModeId: mode },
+    });
+  }
+
+  async publishFallbackWarning(sessionId: string, session: SessionMode): Promise<void> {
+    session.autoModeFallbackWarningPending = false;
+    if (session.autoModeFallbackWarningShown) return;
+    session.autoModeFallbackWarningShown = true;
+    try {
+      await this.options.sessionUpdate({
+        sessionId,
+        update: {
+          sessionUpdate: "agent_message_chunk",
+          content: { type: "text", text: AUTO_MODE_FALLBACK_NOTICE },
+        },
+      });
+    } catch (error) {
+      // The fallback has already been applied; a failed advisory must not turn
+      // the successful mode change into a failed request.
+      this.options.logError(`Failed to publish Auto mode fallback warning: ${error}`);
+    }
+  }
+
+  async publishFallbackState(sessionId: string, session: SessionMode): Promise<void> {
+    await this.publishCurrent(sessionId, AUTO_MODE_FALLBACK);
+    await this.publishFallbackWarning(sessionId, session);
+  }
+
+  private requireOpenSession(sessionId: string): S {
+    const session = this.options.getSession(sessionId);
+    if (!session) throw new Error("Session not found");
+    if (session.queryClosed) {
+      throw RequestError.internalError(undefined, this.options.sessionEndedMessage);
+    }
+    return session;
+  }
+
+  private isAutoUnavailable(
+    session: SessionMode,
+    modelId = session.models.currentModelId,
+  ): boolean {
+    const modelInfo = session.modelInfos.find((model) => model.value === modelId);
+    return modelInfo !== undefined && modelInfo.supportsAutoMode !== true;
+  }
+
+  private isAvailable(availableModes: SessionModeState["availableModes"], modeId: string): boolean {
+    return availableModes.some((mode) => mode.id === modeId);
+  }
+
+  private parseMode(modeId: string): PermissionMode {
+    switch (modeId) {
+      case "auto":
+      case "default":
+      case "acceptEdits":
+      case "bypassPermissions":
+      case "dontAsk":
+      case "plan":
+        return modeId;
+      default:
+        throw new Error("Invalid Mode");
+    }
+  }
+
+  private buildAvailableModes(): SessionModeState["availableModes"] {
+    const modes: SessionModeState["availableModes"] = [
+      {
+        id: "default",
+        name: "Manual",
+        description: "Always ask before making changes",
+        _meta: { kind: "standard" },
+      },
+      {
+        id: "acceptEdits",
+        name: "Accept edits",
+        description: "Automatically accept all file edits",
+        _meta: { kind: "standard" },
+      },
+      {
+        id: "plan",
+        name: "Plan",
+        description: "Create a plan before making changes",
+        _meta: { kind: "plan" },
+      },
+      {
+        id: "auto",
+        name: "Auto",
+        description: "Claude handles permission decisions",
+        _meta: { kind: "auto_review" },
+      },
+    ];
+    if (ALLOW_BYPASS) {
+      modes.push({
+        id: "bypassPermissions",
+        name: "Bypass permissions",
+        description: "Accepts all permissions",
+        _meta: { kind: "full_access" },
+      });
+    }
+    return modes;
+  }
+
+  private async trySyncMode(
+    query: Pick<Query, "setPermissionMode">,
+    mode: PermissionMode,
+    errorMessage: string,
+  ): Promise<void> {
+    try {
+      await query.setPermissionMode(mode);
+    } catch (error) {
+      this.options.logError(errorMessage, error);
+    }
+  }
+}
--- a/src/session-titles.ts
+++ b/src/session-titles.ts
@@ -0,0 +1,246 @@
+/**
+ * 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`.
+ *
+ * {@link SessionTitles} holds the per-session state and is owned by `Session`.
+ * `acp-agent.ts` drives it from four places: {@link SessionTitles.onPrompt} and
+ * {@link SessionTitles.onAssistantText} to collect text,
+ * {@link SessionTitles.onTurnEnd} at `session_state_changed: idle`, and
+ * {@link SessionTitles.reset} on `conversation_reset`.
+ */
+
+import type { ContentBlock, PromptRequest } from "@agentclientprotocol/sdk";
+import { getSessionInfo, type Query, type SDKSessionInfo } from "@anthropic-ai/claude-agent-sdk";
+import type { ClaudeAcpAgent, Session } from "./acp-agent.js";
+
+const MAX_TITLE_LENGTH = 256;
+
+/** How much session text the title is generated from. The CLI caps its own
+ *  title input at the same 1000 trailing characters. */
+const MAX_TITLE_CONTEXT_LENGTH = 1000;
+
+/** Below this the generator returns null without calling the model, so there is
+ *  nothing to gain by asking yet. */
+const MIN_TITLE_CONTEXT_LENGTH = 10;
+
+/** `generateSessionTitle` is present on the SDK's runtime `Query` class but is
+ *  not declared in `sdk.d.ts` (0.3.220), so it is reached through this optional
+ *  shape rather than the published interface. */
+type TitleCapableQuery = Query & {
+  generateSessionTitle?: (
+    description: string,
+    options?: { persist?: boolean },
+  ) => Promise<string | null>;
+};
+
+/** A title already stored for the session, published when generation is
+ *  unavailable or yields nothing. */
+type TitleFallback = { title: string; lastModified: number };
+
+export function sanitizeTitle(text: string): string {
+  // Replace newlines and collapse whitespace
+  const sanitized = text
+    .replace(/[\r\n]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (sanitized.length <= MAX_TITLE_LENGTH) {
+    return sanitized;
+  }
+  return sanitized.slice(0, MAX_TITLE_LENGTH - 1) + "…";
+}
+
+/** Rolling text a title is generated from: `previous` plus `text`, keeping only
+ *  the trailing {@link MAX_TITLE_CONTEXT_LENGTH} characters. */
+export function appendTitleContext(previous: string | undefined, text: string): string {
+  const next = (previous ?? "") + text;
+  return next.length > MAX_TITLE_CONTEXT_LENGTH ? next.slice(-MAX_TITLE_CONTEXT_LENGTH) : next;
+}
+
+/** Whether this SDK still offers on-demand title generation. */
+function supportsTitleGeneration(query: Query): boolean {
+  return typeof (query as TitleCapableQuery).generateSessionTitle === "function";
+}
+
+/** One session's title: the text a generated title is derived from, whether a
+ *  title has been settled on, and the last one published. Created with the
+ *  session and reachable as `session.titles`. */
+export class SessionTitles {
+  /** Last title pushed to the client via `session_info_update`, so an unchanged
+   *  title is never re-notified. Undefined until the first push. */
+  private lastTitle?: string;
+
+  /** Rolling tail of this session's own user + assistant text, capped at
+   *  {@link MAX_TITLE_CONTEXT_LENGTH}. Dropped once a title exists. */
+  private context?: string;
+
+  /** Set once this session has a title or has asked for one. A title is
+   *  generated at most once per session: the SDK reports a generated title in
+   *  the same field as a user `/rename`, so re-titling could silently overwrite
+   *  one. Released by {@link reset}, and when generation yields nothing. */
+  private settled = false;
+
+  constructor(
+    private readonly agent: ClaudeAcpAgent,
+    private readonly sessionId: string,
+  ) {}
+
+  /** Collect a prompt's own text for the title, skipping openers not worth
+   *  titling after. No-op once the title is settled. */
+  onPrompt(prompt: PromptRequest["prompt"]): void {
+    if (this.settled) {
+      return;
+    }
+    const promptText = prompt
+      .flatMap((chunk) => (chunk.type === "text" ? [chunk.text] : []))
+      .join("\n");
+
+    this.context = appendTitleContext(this.context, `\n${promptText}\n`);
+  }
+
+  /** Collect the assistant's own answer for the title. Chunks are appended
+   *  verbatim so streamed text reassembles. No-op once the title is settled. */
+  onAssistantText(content: ContentBlock): void {
+    if (this.settled || content.type !== "text") {
+      return;
+    }
+    this.context = appendTitleContext(this.context, content.text);
+  }
+
+  /** Drop the title state so the next turn re-evaluates. Used on
+   *  `conversation_reset`, which mounts a fresh transcript. */
+  reset(): void {
+    this.settled = false;
+    this.context = undefined;
+    this.lastTitle = undefined;
+  }
+
+  /** Turn-end title handling. `idle` is the SDK's turn-over signal, so it is
+   *  when a title may have landed or become generatable.
+   *
+   *  `info.customTitle` is non-empty only once the session file holds a real
+   *  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. */
+  async onTurnEnd(session: Session): Promise<void> {
+    const info = await this.readSessionInfo(session);
+
+    if (info?.customTitle) {
+      this.settled = true;
+      this.context = undefined;
+      await this.publish(info.customTitle, info.lastModified);
+      return;
+    }
+
+    const fallback = info?.summary
+      ? { title: info.summary, lastModified: info.lastModified }
+      : undefined;
+
+    if (this.canRequest(session)) {
+      this.settled = true;
+
+      void this.requestGenerateTitle(session, fallback).catch((error) => {
+        this.agent.logger.error(`Session ${this.sessionId}: session title update failed: ${error}`);
+      });
+
+      return;
+    }
+    // Only while this session has no title of its own: `summary` degrades to the
+    // raw first prompt, which must never overwrite a generated title if the
+    // persisted one is slow to show up in `info`.
+    if (fallback && !this.settled) {
+      await this.publish(fallback.title, fallback.lastModified);
+    }
+  }
+
+  /** Read the SDK's stored info for this session. A missing session file or read
+   *  error is non-fatal: the title is best-effort and another turn will retry. */
+  private async readSessionInfo(session: Session): Promise<SDKSessionInfo | undefined> {
+    try {
+      return await getSessionInfo(this.sessionId, { dir: session.cwd });
+    } catch (error) {
+      this.agent.logger.error(`Session ${this.sessionId}: failed to read session info: ${error}`);
+      return undefined;
+    }
+  }
+
+  /** Notify the client of a title, unless it is the one we last sent. */
+  private async publish(rawTitle: string, lastModified: number): Promise<void> {
+    const title = sanitizeTitle(rawTitle);
+    if (title === this.lastTitle) {
+      return;
+    }
+    this.lastTitle = title;
+    await this.agent.client.sessionUpdate({
+      sessionId: this.sessionId,
+      update: {
+        sessionUpdate: "session_info_update",
+        title,
+        updatedAt: new Date(lastModified).toISOString(),
+      },
+    });
+  }
+
+  /** Whether to ask the SDK for a generated title now: once per session, on a
+   *  live query, with enough collected text for the generator to work with. */
+  private canRequest(session: Session): boolean {
+    if (this.settled || session.queryClosed || session.cancelled) {
+      return false;
+    }
+    if (!supportsTitleGeneration(session.query)) {
+      return false;
+    }
+    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. */
+  private async requestGenerateTitle(
+    session: Session,
+    fallback: TitleFallback | undefined,
+  ): Promise<void> {
+    const description = this.context?.trim() ?? "";
+    let title: string | null = null;
+
+    try {
+      title =
+        (await (session.query as TitleCapableQuery).generateSessionTitle?.(description, {
+          persist: true,
+        })) ?? null;
+    } catch (error) {
+      this.agent.logger.error(
+        `Session ${this.sessionId}: failed to generate a session title: ${error}`,
+      );
+    }
+
+    // A session torn down or replaced while the title was in flight must not
+    // adopt it.
+    if (this.agent.sessions[this.sessionId] !== session) {
+      return;
+    }
+
+    if (!title) {
+      this.settled = false;
+
+      if (fallback) {
+        await this.publish(fallback.title, fallback.lastModified);
+      }
+      return;
+    }
+
+    this.context = undefined;
+    await this.publish(title, Date.now());
+  }
+}
--- a/src/tests/acp-agent-settings.test.ts
+++ b/src/tests/acp-agent-settings.test.ts
@@ -94,7 +94,7 @@ describe("ClaudeAcpAgent settings", () => {

    expect(getCapturedOptions().permissionMode).toBe("dontAsk");
    expect(getCapturedOptions().settingSources).toEqual(["user", "project", "local"]);
-    expect(response.modes.currentModeId).toBe("dontAsk");
+    expect(response.modes.currentModeId).toBe("default");
  });

  it("supports acceptEdits mode defaults", async () => {
@@ -253,7 +253,7 @@ describe("ClaudeAcpAgent settings", () => {
      };
    }

-    it("omits `auto` from availableModes when the resolved model lacks supportsAutoMode", async () => {
+    it("advertises `auto` when the resolved model lacks supportsAutoMode", async () => {
      const projectDir = path.join(tempDir, "project");
      await fs.promises.mkdir(projectDir, { recursive: true });

@@ -276,10 +276,8 @@ describe("ClaudeAcpAgent settings", () => {
      });

      const modeIds: string[] = response.modes.availableModes.map((m: any) => m.id);
-      expect(modeIds).not.toContain("auto");
-      expect(modeIds).toEqual(
-        expect.arrayContaining(["default", "acceptEdits", "plan", "dontAsk"]),
-      );
+      expect(modeIds).toEqual(expect.arrayContaining(["default", "acceptEdits", "plan", "auto"]));
+      expect(modeIds).not.toContain("dontAsk");
    });

    it("includes `auto` when the resolved model has supportsAutoMode: true", async () => {
@@ -305,10 +303,45 @@ describe("ClaudeAcpAgent settings", () => {
      });

      const modeIds: string[] = response.modes.availableModes.map((m: any) => m.id);
-      expect(modeIds).toContain("auto");
+      expect(response.modes.availableModes.slice(0, 4)).toEqual([
+        {
+          id: "default",
+          name: "Manual",
+          description: "Always ask before making changes",
+          _meta: { kind: "standard" },
+        },
+        {
+          id: "acceptEdits",
+          name: "Accept edits",
+          description: "Automatically accept all file edits",
+          _meta: { kind: "standard" },
+        },
+        {
+          id: "plan",
+          name: "Plan",
+          description: "Create a plan before making changes",
+          _meta: { kind: "plan" },
+        },
+        {
+          id: "auto",
+          name: "Auto",
+          description: "Claude handles permission decisions",
+          _meta: { kind: "auto_review" },
+        },
+      ]);
+      const bypass = response.modes.availableModes[4];
+      if (bypass) {
+        expect(bypass).toEqual({
+          id: "bypassPermissions",
+          name: "Bypass permissions",
+          description: "Accepts all permissions",
+          _meta: { kind: "full_access" },
+        });
+      }
+      expect(modeIds).not.toContain("dontAsk");
    });

-    it("clamps permissions.defaultMode='auto' to 'default' on a model that lacks supportsAutoMode", async () => {
+    it("falls back permissions.defaultMode='auto' to Accept edits on an unsupported model", async () => {
      await fs.promises.writeFile(
        path.join(tempDir, "settings.json"),
        JSON.stringify({ permissions: { defaultMode: "auto" } }),
@@ -342,9 +375,11 @@ describe("ClaudeAcpAgent settings", () => {
        // carries the user-typed value; the SDK was synced via
        // setPermissionMode after we discovered the model can't honor it.
        expect(getCapturedOptions().permissionMode).toBe("auto");
-        expect(setPermissionModeSpy).toHaveBeenCalledWith("default");
-        expect(response.modes.currentModeId).toBe("default");
-        expect(response.modes.availableModes.map((m: any) => m.id)).not.toContain("auto");
+        expect(setPermissionModeSpy).toHaveBeenCalledWith("acceptEdits");
+        expect(response.modes.currentModeId).toBe("acceptEdits");
+        expect(response.modes.availableModes.map((m: any) => m.id)).toContain("auto");
+        const session = (agent as any).sessions[response.sessionId];
+        expect(session.autoModeFallbackWarningPending).toBe(true);

        // A descriptive warning was logged so operators see the clamp.
        const messages = errorSpy.mock.calls.map((c) => c.join(" "));
--- a/src/tests/acp-agent.test.ts
+++ b/src/tests/acp-agent.test.ts
--- a/src/tests/async-tasks.test.ts
+++ b/src/tests/async-tasks.test.ts
@@ -0,0 +1,707 @@
+import { describe, expect, it } from "vitest";
+import type { AcpSessionNotification } from "../acp-subagents.js";
+import {
+  AsyncTaskRuntime,
+  backgroundBashTaskFromToolResult,
+  clientSupportsAsyncTasks,
+} from "../async-tasks.js";
+
+describe("AsyncTaskRuntime", () => {
+  it("recovers a background Bash task from its structured tool result", async () => {
+    const updates: AcpSessionNotification[] = [];
+    const runtime = new AsyncTaskRuntime(true, "root", async (notification) => {
+      updates.push(notification);
+    });
+    const task = backgroundBashTaskFromToolResult(
+      [
+        {
+          type: "tool_result",
+          tool_use_id: "bash-tool",
+          content:
+            "Command running in background with ID: bpux8xmfg. Output is being written to: /private/tmp/claude/tasks/bpux8xmfg.output. You will be notified when it completes.",
+        },
+      ],
+      { backgroundTaskId: "bpux8xmfg", stdout: "", stderr: "" },
+      {
+        "bash-tool": {
+          name: "Bash",
+          input: { command: "npm run build", run_in_background: true },
+        },
+      },
+    );
+
+    expect(task).toEqual({
+      taskId: "bpux8xmfg",
+      taskType: "local_bash",
+      description: "npm run build",
+      isBackgrounded: true,
+      outputFilePath: "/private/tmp/claude/tasks/bpux8xmfg.output",
+      toolCallId: "bash-tool",
+    });
+    // The SDK can report local_bash before the Bash result proves that it was
+    // backgrounded. The structured result must promote that existing task.
+    await runtime.taskStarted({
+      taskId: "bpux8xmfg",
+      taskType: "local_bash",
+      description: "Shell",
+    });
+    await runtime.taskBackgrounded(task!);
+    await runtime.taskNotification("bpux8xmfg", "completed", "Build finished");
+
+    expect(updates.map((notification) => notification.update.sessionUpdate)).toEqual([
+      "async_task_spawned",
+      "async_task_state_update",
+    ]);
+    expect(updates[0].update).toMatchObject({
+      asyncTaskId: "bpux8xmfg",
+      name: "npm run build",
+      taskType: "shell",
+      description: "npm run build",
+      showInTranscript: true,
+      canStop: true,
+      outputFilePath: "/private/tmp/claude/tasks/bpux8xmfg.output",
+      toolCallId: "bash-tool",
+    });
+  });
+
+  it("publishes a stopped terminal after a task-specific stop", async () => {
+    const published: AcpSessionNotification[] = [];
+    const runtime = new AsyncTaskRuntime(true, "session", async (notification) => {
+      published.push(notification);
+    });
+
+    await runtime.taskStarted({
+      taskId: "task-1",
+      taskType: "local_workflow",
+      description: "Build generated assets",
+    });
+    expect(runtime.canStop("task-1")).toBe(true);
+    expect(runtime.claimStop("task-1")).toBe(true);
+    expect(runtime.claimStop("task-1")).toBe(false);
+
+    await runtime.taskStopped("task-1");
+    await runtime.taskStopped("task-1");
+
+    expect(runtime.canStop("task-1")).toBe(false);
+    expect(published.map(({ update }) => update.sessionUpdate)).toEqual([
+      "async_task_spawned",
+      "async_task_state_update",
+      "agent_message_chunk",
+    ]);
+    expect(published[1]?.update).toMatchObject({
+      asyncTaskId: "task-1",
+      state: "stopped",
+    });
+    // The panel drops a stopped task immediately; a summary there is unread.
+    expect(published[1]?.update).not.toHaveProperty("summary");
+    expect(published.at(-1)?.update).toMatchObject({
+      sessionUpdate: "agent_message_chunk",
+      content: { type: "text", text: "**Task stopped by user:** Build generated assets." },
+    });
+  });
+
+  it("still announces a stop whose SDK notification landed first", async () => {
+    const published: AcpSessionNotification[] = [];
+    const runtime = new AsyncTaskRuntime(true, "session", async (notification) => {
+      published.push(notification);
+    });
+
+    await runtime.taskStarted({
+      taskId: "task-1",
+      taskType: "local_bash",
+      description: "npm run build",
+      isBackgrounded: true,
+    });
+    expect(runtime.claimStop("task-1")).toBe(true);
+    // The SDK kills the process and reports it before `stopTask` resolves, so
+    // the task is already terminal by the time the stop path resumes. The
+    // acknowledgement is still owed to the user who clicked.
+    await runtime.taskNotification({ taskId: "task-1", status: "killed" });
+    await runtime.taskStopped("task-1");
+
+    expect(published.map(({ update }) => update.sessionUpdate)).toEqual([
+      "async_task_spawned",
+      "async_task_state_update",
+      "agent_message_chunk",
+    ]);
+    expect(published.at(-1)?.update).toMatchObject({
+      sessionUpdate: "agent_message_chunk",
+      content: { type: "text", text: "**Task stopped by user:** npm run build." },
+    });
+  });
+
+  it("announces a stop for a panel-only task too", async () => {
+    const published: AcpSessionNotification[] = [];
+    const runtime = new AsyncTaskRuntime(true, "session", async (notification) => {
+      published.push(notification);
+    });
+
+    // A background Bash task is panel-only because its tool call already draws
+    // it in the transcript. That must not swallow the stop acknowledgement --
+    // it is the only signal the user gets that their click landed.
+    await runtime.taskStarted({
+      taskId: "task-1",
+      taskType: "local_bash",
+      description: "npm run build",
+      isBackgrounded: true,
+      skipTranscript: true,
+    });
+    expect(runtime.claimStop("task-1")).toBe(true);
+    await runtime.taskStopped("task-1");
+
+    expect(published[0]?.update).toMatchObject({
+      sessionUpdate: "async_task_spawned",
+      showInTranscript: false,
+    });
+    expect(published.at(-1)?.update).toMatchObject({
+      sessionUpdate: "agent_message_chunk",
+      content: { type: "text", text: "**Task stopped by user:** npm run build." },
+    });
+  });
+
+  it("correlates a background Bash result inside a batched structured message", () => {
+    const toolUseResult = { backgroundTaskId: "task-1" };
+    const tools = {
+      read: { name: "Read", input: { file_path: "package.json" } },
+      bash: { name: "Bash", input: { command: "npm run build" } },
+    };
+
+    expect(
+      backgroundBashTaskFromToolResult(
+        [
+          { type: "tool_result", tool_use_id: "read", content: "package" },
+          {
+            type: "tool_result",
+            tool_use_id: "bash",
+            content: [
+              { type: "text", text: "Command running. Output is being written to: " },
+              {
+                type: "text",
+                text: "/private/tmp/claude/tasks/task-1.output. You will be notified when done.",
+              },
+            ],
+          },
+        ],
+        toolUseResult,
+        tools,
+      ),
+    ).toMatchObject({
+      taskId: "task-1",
+      toolCallId: "bash",
+      description: "npm run build",
+      outputFilePath: "/private/tmp/claude/tasks/task-1.output",
+    });
+  });
+
+  it("recovers a background Bash task when the structured result omits its id", () => {
+    const tools = {
+      bash: { name: "Bash", input: { command: "npm run build" } },
+    };
+
+    expect(
+      backgroundBashTaskFromToolResult(
+        [
+          {
+            type: "tool_result",
+            tool_use_id: "bash",
+            content:
+              "Command running in background with ID: task-1. Output is being written to: " +
+              "/private/tmp/claude/tasks/task-1.output. You will be notified when done.",
+          },
+        ],
+        undefined,
+        tools,
+      ),
+    ).toMatchObject({
+      taskId: "task-1",
+      toolCallId: "bash",
+      description: "npm run build",
+      outputFilePath: "/private/tmp/claude/tasks/task-1.output",
+    });
+  });
+
+  it("does not infer a background task without an unambiguous Bash result", () => {
+    const toolUseResult = { backgroundTaskId: "task-1" };
+    const bash = { bash: { name: "Bash", input: { command: "npm run build" } } };
+
+    expect(backgroundBashTaskFromToolResult([], toolUseResult, bash)).toBeUndefined();
+    expect(
+      backgroundBashTaskFromToolResult(
+        [
+          { type: "tool_result", tool_use_id: "bash-1" },
+          { type: "tool_result", tool_use_id: "bash-2" },
+        ],
+        toolUseResult,
+        {
+          "bash-1": { name: "Bash", input: { command: "first" } },
+          "bash-2": { name: "Bash", input: { command: "second" } },
+        },
+      ),
+    ).toBeUndefined();
+    expect(
+      backgroundBashTaskFromToolResult(
+        [{ type: "tool_result", tool_use_id: "read" }],
+        toolUseResult,
+        { read: { name: "Read", input: {} } },
+      ),
+    ).toBeUndefined();
+    expect(
+      backgroundBashTaskFromToolResult(
+        [
+          {
+            type: "tool_result",
+            tool_use_id: "bash",
+            content:
+              "Output is being written to: /private/tmp/claude/tasks/not-task-1.output. You will be notified",
+          },
+        ],
+        toolUseResult,
+        bash,
+      )?.outputFilePath,
+    ).toBeUndefined();
+    expect(
+      backgroundBashTaskFromToolResult(
+        [{ type: "tool_result", tool_use_id: "bash" }],
+        [{ backgroundTaskId: "task-1" }, { backgroundTaskId: "task-2" }],
+        bash,
+      ),
+    ).toBeUndefined();
+  });
+
+  it("uses a structured result tool id to disambiguate batched Bash results", () => {
+    expect(
+      backgroundBashTaskFromToolResult(
+        [
+          { type: "tool_result", tool_use_id: "bash-1", content: "first" },
+          { type: "tool_result", tool_use_id: "bash-2", content: "second" },
+        ],
+        { tool_use_id: "bash-2", background_task_id: "task-2" },
+        {
+          "bash-1": { name: "Bash", input: { command: "first" } },
+          "bash-2": { name: "Bash", input: { command: "second" } },
+        },
+      ),
+    ).toMatchObject({ taskId: "task-2", toolCallId: "bash-2", description: "second" });
+
+    expect(
+      backgroundBashTaskFromToolResult(
+        [{ type: "tool_result", tool_use_id: "bash-1", content: "first" }],
+        { tool_use_id: "read", background_task_id: "task-2" },
+        {
+          "bash-1": { name: "Bash", input: { command: "first" } },
+          read: { name: "Read", input: {} },
+        },
+      ),
+    ).toBeUndefined();
+  });
+
+  it("detects the negotiated AIR capability", () => {
+    expect(
+      clientSupportsAsyncTasks({
+        _meta: { jetbrains: { air: { version: 1, capabilities: ["asyncTasks"] } } },
+      }),
+    ).toBe(true);
+    expect(clientSupportsAsyncTasks({})).toBe(false);
+  });
+
+  it("publishes one durable lifecycle with progress and a terminal state", async () => {
+    const published: AcpSessionNotification[] = [];
+    const runtime = new AsyncTaskRuntime(true, "session", async (notification) => {
+      published.push(notification);
+    });
+
+    await runtime.taskStarted({
+      taskId: "task-1",
+      taskType: "local_workflow",
+      description: "Build generated assets",
+      workflowName: "assets",
+    });
+    await runtime.taskProgress({
+      taskId: "task-1",
+      summary: "Generated 3 files",
+      lastToolName: "Write",
+      usage: { total_tokens: 12, tool_uses: 3, duration_ms: 500 },
+    });
+    await runtime.taskUpdated("task-1", { status: "paused" });
+    await runtime.taskUpdated("task-1", { status: "running" });
+    await runtime.taskNotification("task-1", "completed", "Done");
+    await runtime.taskProgress({ taskId: "task-1", summary: "late" });
+    await runtime.taskNotification("task-1", "failed", "duplicate terminal");
+
+    expect(published.map((notification) => notification.update.sessionUpdate)).toEqual([
+      "async_task_spawned",
+      "async_task_progress",
+      "async_task_state_update",
+      "async_task_state_update",
+      "async_task_state_update",
+    ]);
+    expect(published[0]?.update).toMatchObject({
+      asyncTaskId: "task-1",
+      name: "assets",
+      taskType: "workflow",
+      showInTranscript: true,
+    });
+    expect(published[1]?.update).toMatchObject({
+      summary: "Generated 3 files",
+      usage: { totalTokens: 12, toolUses: 3, durationMs: 500 },
+    });
+    expect(published.at(-1)?.update).toMatchObject({ state: "completed", summary: "Done" });
+  });
+
+  it("waits until foreground shell work is backgrounded and excludes subagents", async () => {
+    const published: AcpSessionNotification[] = [];
+    const runtime = new AsyncTaskRuntime(true, "session", async (notification) => {
+      published.push(notification);
+    });
+
+    await runtime.taskStarted({
+      taskId: "foreground-shell",
+      taskType: "local_bash",
+      description: "Read one file",
+    });
+    await runtime.taskNotification("foreground-shell", "completed", "Done");
+    await runtime.taskStarted({
+      taskId: "shell",
+      taskType: "local_bash",
+      description: "Run tests",
+    });
+    await runtime.taskStarted({
+      taskId: "agent",
+      taskType: "local_agent",
+      description: "Research",
+      subagentType: "Explore",
+    });
+    await runtime.taskStarted({
+      task_id: "agent-without-subtype",
+      task_type: "local_agent",
+      description: "Research",
+      is_backgrounded: true,
+    });
+    expect(published).toEqual([]);
+
+    await runtime.taskUpdated("shell", { isBackgrounded: true });
+    expect(published).toHaveLength(1);
+    expect(published[0]?.update).toMatchObject({ asyncTaskId: "shell", taskType: "shell" });
+  });
+
+  it("normalizes snake_case SDK task events and propagates a late output file", async () => {
+    const published: AcpSessionNotification[] = [];
+    const runtime = new AsyncTaskRuntime(true, "session", async (notification) => {
+      published.push(notification);
+    });
+
+    await runtime.taskStarted({
+      task_id: "shell",
+      task_type: "local_bash",
+      description: "Run build",
+      is_backgrounded: true,
+      tool_use_id: "bash-tool",
+    });
+    await runtime.taskProgress({
+      task_id: "shell",
+      last_tool_name: "Bash",
+      usage: { totalTokens: 2, toolUses: 1, durationMs: 50 },
+    });
+    await runtime.taskNotification({
+      task_id: "shell",
+      status: "completed",
+      summary: "Done",
+      output_file: "/tmp/tasks/shell.output",
+    });
+
+    expect(published[0]?.update).toMatchObject({
+      asyncTaskId: "shell",
+      taskType: "shell",
+      toolCallId: "bash-tool",
+    });
+    expect(published[1]?.update).toMatchObject({
+      lastToolName: "Bash",
+      usage: { totalTokens: 2, toolUses: 1, durationMs: 50 },
+    });
+    expect(published[2]?.update).toMatchObject({
+      state: "completed",
+      summary: "Done",
+      outputFilePath: "/tmp/tasks/shell.output",
+    });
+  });
+
+  it("keeps a terminal tombstone until a late Bash result proves the task was backgrounded", async () => {
+    const published: AcpSessionNotification[] = [];
+    const runtime = new AsyncTaskRuntime(true, "session", async (notification) => {
+      published.push(notification);
+    });
+
+    await runtime.taskNotification({
+      task_id: "fast-shell",
+      status: "completed",
+      summary: "Already done",
+      output_file: "/tmp/tasks/fast-shell.output",
+    });
+    expect(published).toEqual([]);
+
+    await runtime.taskBackgrounded({
+      taskId: "fast-shell",
+      taskType: "local_bash",
+      description: "Fast build",
+      isBackgrounded: true,
+      toolCallId: "bash-tool",
+    });
+    await runtime.taskUpdated("fast-shell", { status: "running" });
+
+    expect(published.map((notification) => notification.update.sessionUpdate)).toEqual([
+      "async_task_spawned",
+      "async_task_state_update",
+    ]);
+    expect(published[0]?.update).toMatchObject({
+      description: "Fast build",
+      outputFilePath: "/tmp/tasks/fast-shell.output",
+    });
+    expect(published[1]?.update).toMatchObject({
+      state: "completed",
+      summary: "Already done",
+      outputFilePath: "/tmp/tasks/fast-shell.output",
+    });
+  });
+
+  it("retains a terminal task_updated tombstone until background promotion", async () => {
+    const published: AcpSessionNotification[] = [];
+    const runtime = new AsyncTaskRuntime(true, "session", async (notification) => {
+      published.push(notification);
+    });
+
+    await runtime.taskUpdated({
+      task_id: "fast-shell",
+      patch: { status: "failed", error: "boom" },
+    });
+    await runtime.taskBackgrounded({
+      task_id: "fast-shell",
+      task_type: "local_bash",
+      description: "Fast build",
+      is_backgrounded: true,
+    });
+
+    expect(published.map((notification) => notification.update.sessionUpdate)).toEqual([
+      "async_task_spawned",
+      "async_task_state_update",
+    ]);
+    expect(published[1]?.update).toMatchObject({ state: "failed", summary: "boom" });
+  });
+
+  it("publishes a mutable output path after an already announced task", async () => {
+    const published: AcpSessionNotification[] = [];
+    const runtime = new AsyncTaskRuntime(true, "session", async (notification) => {
+      published.push(notification);
+    });
+
+    await runtime.taskStarted({
+      taskId: "shell",
+      taskType: "local_bash",
+      description: "Build",
+      isBackgrounded: true,
+    });
+    await runtime.taskUpdated("shell", { output_file: "/tmp/tasks/one.output" });
+    await runtime.taskUpdated("shell", { outputFilePath: "/tmp/tasks/two.output" });
+
+    expect(published.slice(1).map((notification) => notification.update)).toEqual([
+      expect.objectContaining({
+        sessionUpdate: "async_task_progress",
+        outputFilePath: "/tmp/tasks/one.output",
+      }),
+      expect.objectContaining({
+        sessionUpdate: "async_task_progress",
+        outputFilePath: "/tmp/tasks/two.output",
+      }),
+    ]);
+  });
+
+  it("publishes a tool id discovered after spawn", async () => {
+    const published: AcpSessionNotification[] = [];
+    const runtime = new AsyncTaskRuntime(true, "session", async (notification) => {
+      published.push(notification);
+    });
+
+    await runtime.taskStarted({
+      task_id: "shell",
+      task_type: "local_bash",
+      description: "Build",
+      is_backgrounded: true,
+    });
+    await runtime.taskBackgrounded({
+      task_id: "shell",
+      task_type: "local_bash",
+      description: "Build",
+      is_backgrounded: true,
+      tool_use_id: "bash-tool",
+    });
+
+    expect(published[0]?.update).not.toHaveProperty("toolCallId");
+    expect(published[1]?.update).toMatchObject({
+      sessionUpdate: "async_task_progress",
+      asyncTaskId: "shell",
+      toolCallId: "bash-tool",
+    });
+  });
+
+  it("reconciles foreground promotion and a lost terminal edge from the live task level", async () => {
+    const published: AcpSessionNotification[] = [];
+    const runtime = new AsyncTaskRuntime(true, "session", async (notification) => {
+      published.push(notification);
+    });
+
+    await runtime.taskStarted({
+      task_id: "shell",
+      task_type: "local_bash",
+      description: "Build",
+      is_backgrounded: false,
+    });
+    await runtime.backgroundTasksChanged({
+      tasks: [{ task_id: "shell", task_type: "local_bash", description: "Build" }],
+    });
+    await runtime.backgroundTasksChanged([]);
+
+    expect(published.map((notification) => notification.update.sessionUpdate)).toEqual([
+      "async_task_spawned",
+      "async_task_state_update",
+    ]);
+    expect(published[1]?.update).toMatchObject({ state: "stopped" });
+
+    // The level is deliberately best-effort: an authoritative edge that was
+    // merely ordered after it may correct the terminal state.
+    await runtime.taskNotification("shell", "completed", "Done");
+    expect(published[2]?.update).toMatchObject({ state: "completed", summary: "Done" });
+  });
+
+  it("lets the terminal edge win when the live level is ordered before it", async () => {
+    const published: AcpSessionNotification[] = [];
+    const runtime = new AsyncTaskRuntime(true, "session", async (notification) => {
+      published.push(notification);
+    });
+
+    await runtime.taskStarted({
+      task_id: "shell",
+      task_type: "local_bash",
+      description: "Build",
+      is_backgrounded: true,
+    });
+    await runtime.backgroundTasksChanged([]);
+    await runtime.taskNotification("shell", "completed", "Done");
+
+    expect(published.map((notification) => notification.update.sessionUpdate)).toEqual([
+      "async_task_spawned",
+      "async_task_state_update",
+      "async_task_state_update",
+    ]);
+    expect(published[1]?.update).toMatchObject({ state: "stopped" });
+    expect(published[2]?.update).toMatchObject({ state: "completed", summary: "Done" });
+  });
+
+  it("heals a lone lost terminal edge at the replace-level boundary", async () => {
+    const published: AcpSessionNotification[] = [];
+    const runtime = new AsyncTaskRuntime(true, "session", async (notification) => {
+      published.push(notification);
+    });
+
+    await runtime.taskStarted({
+      task_id: "shell",
+      task_type: "local_bash",
+      description: "Build",
+      is_backgrounded: true,
+    });
+    await runtime.backgroundTasksChanged([]);
+
+    expect(published.at(-1)?.update).toMatchObject({
+      sessionUpdate: "async_task_state_update",
+      asyncTaskId: "shell",
+      state: "stopped",
+    });
+  });
+
+  it("recovers a live task whose task_started edge was lost", async () => {
+    const published: AcpSessionNotification[] = [];
+    const runtime = new AsyncTaskRuntime(true, "session", async (notification) => {
+      published.push(notification);
+    });
+
+    await runtime.backgroundTasksChanged([
+      { task_id: "lost-start", task_type: "local_bash", description: "Build" },
+    ]);
+
+    expect(published[0]?.update).toMatchObject({
+      sessionUpdate: "async_task_spawned",
+      asyncTaskId: "lost-start",
+      taskType: "shell",
+      description: "Build",
+      showInTranscript: false,
+    });
+  });
+
+  it("keeps level-only recovery panel-only when task_started arrives late", async () => {
+    const published: AcpSessionNotification[] = [];
+    const runtime = new AsyncTaskRuntime(true, "session", async (notification) => {
+      published.push(notification);
+    });
+
+    await runtime.backgroundTasksChanged([
+      { task_id: "lost-start", task_type: "local_workflow", description: "Build assets" },
+    ]);
+    await runtime.taskStarted({
+      task_id: "lost-start",
+      task_type: "local_workflow",
+      workflow_name: "assets",
+      description: "Build generated assets",
+      skip_transcript: true,
+      is_backgrounded: true,
+    });
+
+    expect(published).toHaveLength(1);
+    expect(published[0]?.update).toMatchObject({
+      sessionUpdate: "async_task_spawned",
+      asyncTaskId: "lost-start",
+      name: "Build assets",
+      showInTranscript: false,
+    });
+  });
+
+  it("finishes remaining tasks and can retry a task whose terminal publication failed", async () => {
+    const published: AcpSessionNotification[] = [];
+    let failFirstTask = true;
+    const runtime = new AsyncTaskRuntime(true, "session", async (notification) => {
+      if (
+        failFirstTask &&
+        notification.update.sessionUpdate === "async_task_state_update" &&
+        notification.update.asyncTaskId === "first"
+      ) {
+        failFirstTask = false;
+        throw new Error("client disconnected");
+      }
+      published.push(notification);
+    });
+    for (const taskId of ["first", "second"]) {
+      await runtime.taskStarted({
+        task_id: taskId,
+        task_type: "local_bash",
+        description: taskId,
+        is_backgrounded: true,
+      });
+    }
+
+    await expect(runtime.finishAll("failed")).rejects.toThrow("client disconnected");
+    expect(published).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          update: expect.objectContaining({
+            sessionUpdate: "async_task_state_update",
+            asyncTaskId: "second",
+            state: "failed",
+          }),
+        }),
+      ]),
+    );
+
+    await expect(runtime.finishAll("failed")).resolves.toBeUndefined();
+    const terminalIds = published.flatMap(({ update }) =>
+      update.sessionUpdate === "async_task_state_update" ? [update.asyncTaskId] : [],
+    );
+    expect(terminalIds).toEqual(["second", "first"]);
+  });
+});
--- a/src/tests/authorization.test.ts
+++ b/src/tests/authorization.test.ts
@@ -125,7 +125,7 @@ describe("authorization", () => {
      expect.objectContaining({
        options: expect.objectContaining({
          env: expect.objectContaining({
-            ANTHROPIC_AUTH_TOKEN: " ",
+            ANTHROPIC_AUTH_TOKEN: "acp-proxy",
            ANTHROPIC_BASE_URL: "https://gateway.example",
            ANTHROPIC_CUSTOM_HEADERS: "x-api-key: test",
            userEnv: "userEnv",
@@ -162,7 +162,7 @@ describe("authorization", () => {
        options: expect.objectContaining({
          env: expect.objectContaining({
            CLAUDE_CODE_USE_BEDROCK: "1",
-            AWS_BEARER_TOKEN_BEDROCK: " ",
+            AWS_BEARER_TOKEN_BEDROCK: "acp-proxy",
            ANTHROPIC_BEDROCK_BASE_URL: "https://gateway.example",
            ANTHROPIC_CUSTOM_HEADERS: "custom-header: test",
          }),
--- a/src/tests/clear-context-coordinator.test.ts
+++ b/src/tests/clear-context-coordinator.test.ts
@@ -0,0 +1,399 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  ClearContextCoordinatorHost,
+  ClearContextSession,
+  ClearContextTurn,
+  continuePlanInFreshContext,
+} from "../clear-context-coordinator.js";
+import { ExitPlanCoordinator, observeExitPlanToolResults } from "../exit-plan.js";
+
+type TestSession = ClearContextSession<ClearContextTurn>;
+
+function testSession(overrides: Partial<TestSession> = {}): TestSession {
+  return {
+    cwd: "/workspace",
+    accumulatedUsage: {
+      inputTokens: 10,
+      outputTokens: 20,
+      cachedReadTokens: 30,
+      cachedWriteTokens: 40,
+    },
+    accumulatedModelUsage: {
+      "claude-sonnet-5": {
+        inputTokens: 10,
+        outputTokens: 20,
+        cachedReadTokens: 30,
+        cachedWriteTokens: 40,
+      },
+    },
+    models: { currentModelId: "default" },
+    configOptions: [],
+    currentAgent: "default",
+    fastModeEnabled: false,
+    input: { push: vi.fn() },
+    ...overrides,
+  };
+}
+
+function testHost(
+  oldSession: TestSession,
+  freshSession: TestSession,
+): ClearContextCoordinatorHost<TestSession, ClearContextTurn> {
+  let currentSession = oldSession;
+  return {
+    currentSession: vi.fn(() => currentSession),
+    closeQueryStream: vi.fn(),
+    restartSession: vi.fn(async () => {
+      currentSession = freshSession;
+      return freshSession;
+    }),
+    applyFastMode: vi.fn(async () => {}),
+    publishSessionState: vi.fn(async () => {}),
+    continuationMessage: vi.fn((sessionId, plan, promptUuid) => ({
+      type: "user" as const,
+      message: {
+        role: "user" as const,
+        content: [{ type: "text" as const, text: `Implement the following plan:\n\n${plan}` }],
+      },
+      session_id: sessionId,
+      parent_tool_use_id: null,
+      origin: { kind: "human" as const },
+      uuid: promptUuid as `${string}-${string}-${string}-${string}-${string}`,
+    })),
+    ensureConsumer: vi.fn(),
+    logError: vi.fn(),
+  };
+}
+
+describe("continuePlanInFreshContext", () => {
+  it("moves the pending ACP turn and its session preferences to a fresh query", async () => {
+    const turn: ClearContextTurn = {
+      settled: false,
+      promptUuid: "00000000-0000-4000-8000-000000000000",
+    };
+    const reset = { toolUseId: "tool-plan", plan: "Ship it", mode: "auto" as const };
+    const oldSession = testSession({
+      activeTurn: turn,
+      turnQueue: [turn],
+      pendingExitPlanContextReset: reset,
+      models: { currentModelId: "claude-sonnet" },
+      currentAgent: "reviewer",
+      fastModeEnabled: true,
+      configOptions: [
+        {
+          id: "effort",
+          name: "Effort",
+          type: "select",
+          currentValue: "high",
+          options: [{ value: "high", name: "High" }],
+        },
+      ],
+      creationParams: {
+        cwd: "/workspace",
+        mcpServers: [],
+        _meta: { caller: "test", claudeCode: { options: { env: { PRESERVED: "yes" } } } },
+      },
+    });
+    const freshSession = testSession();
+    const host = testHost(oldSession, freshSession);
+
+    await continuePlanInFreshContext("public-session", oldSession, reset, host);
+
+    expect(host.restartSession).toHaveBeenCalledWith(
+      expect.objectContaining({
+        cwd: "/workspace",
+        _meta: expect.objectContaining({
+          caller: "test",
+          claudeCode: {
+            options: expect.objectContaining({
+              env: { PRESERVED: "yes" },
+              model: "claude-sonnet",
+              agent: "reviewer",
+              effort: "high",
+            }),
+          },
+        }),
+      }),
+      { publicSessionId: "public-session", permissionMode: "auto" },
+    );
+    expect(turn.carriedUsage).toEqual(oldSession.accumulatedUsage);
+    expect(turn.carriedUsage).not.toBe(oldSession.accumulatedUsage);
+    // The per-model breakdown rides along, so the turn's `_meta.quota` rows
+    // still cover what it spent before the restart.
+    expect(turn.carriedModelUsage).toEqual(oldSession.accumulatedModelUsage);
+    expect(turn.carriedModelUsage).not.toBe(oldSession.accumulatedModelUsage);
+    expect(oldSession.pendingExitPlanContextReset).toBeUndefined();
+    expect(oldSession.activeTurn).toBeNull();
+    expect(oldSession.turnQueue).toEqual([]);
+    expect(freshSession.turnQueue).toEqual([turn]);
+    expect(freshSession.contextUsedTokens).toBe(0);
+    expect(host.applyFastMode).toHaveBeenCalledWith(freshSession, true);
+    expect(host.continuationMessage).toHaveBeenCalledWith(
+      "public-session",
+      "Ship it",
+      turn.promptUuid,
+    );
+    expect(freshSession.input.push).toHaveBeenCalledWith(
+      expect.objectContaining({
+        uuid: turn.promptUuid,
+        origin: { kind: "human" },
+        message: expect.objectContaining({
+          content: [{ type: "text", text: "Implement the following plan:\n\nShip it" }],
+        }),
+      }),
+    );
+    expect(host.ensureConsumer).toHaveBeenCalledWith(freshSession, "public-session");
+  });
+
+  it("does not resurrect original preferences after the session returns to defaults", async () => {
+    const turn: ClearContextTurn = {
+      settled: false,
+      promptUuid: "00000000-0000-4000-8000-000000000000",
+    };
+    const oldSession = testSession({
+      activeTurn: turn,
+      models: { currentModelId: "default" },
+      currentAgent: "default",
+      configOptions: [
+        {
+          id: "effort",
+          name: "Effort",
+          type: "select",
+          currentValue: "default",
+          options: [{ value: "default", name: "Default" }],
+        },
+      ],
+      creationParams: {
+        cwd: "/workspace",
+        mcpServers: [],
+        _meta: {
+          claudeCode: {
+            options: {
+              model: "stale-model",
+              agent: "stale-agent",
+              effort: "high",
+              env: { PRESERVED: "yes" },
+            },
+          },
+        },
+      },
+    });
+    const host = testHost(oldSession, testSession());
+
+    await continuePlanInFreshContext(
+      "public-session",
+      oldSession,
+      { toolUseId: "tool-plan", plan: "Ship it", mode: "default" },
+      host,
+    );
+
+    const restartParams = vi.mocked(host.restartSession).mock.calls[0]?.[0];
+    expect(restartParams?._meta).toEqual({
+      claudeCode: { options: { env: { PRESERVED: "yes" } } },
+    });
+  });
+
+  it("restores disabled Fast mode when a fresh session starts with it enabled", async () => {
+    const turn: ClearContextTurn = {
+      settled: false,
+      promptUuid: "00000000-0000-4000-8000-000000000000",
+    };
+    const oldSession = testSession({ activeTurn: turn, fastModeEnabled: false });
+    const freshSession = testSession({ fastModeEnabled: true });
+    const host = testHost(oldSession, freshSession);
+
+    await continuePlanInFreshContext(
+      "public-session",
+      oldSession,
+      { toolUseId: "tool-plan", plan: "Ship it", mode: "auto" },
+      host,
+    );
+
+    expect(host.applyFastMode).toHaveBeenCalledWith(freshSession, false);
+  });
+
+  it("does not publish or continue a restart cancelled while creating the fresh session", async () => {
+    const turn: ClearContextTurn = {
+      settled: false,
+      promptUuid: "00000000-0000-4000-8000-000000000000",
+    };
+    const oldSession = testSession({ activeTurn: turn });
+    const freshSession = testSession();
+    const host = testHost(oldSession, freshSession);
+    let finishRestart!: () => void;
+    vi.mocked(host.restartSession).mockImplementation(
+      () =>
+        new Promise<TestSession>((resolve) => {
+          finishRestart = () => resolve(freshSession);
+        }),
+    );
+    const controller = new AbortController();
+
+    const restart = continuePlanInFreshContext(
+      "public-session",
+      oldSession,
+      { toolUseId: "tool-plan", plan: "Ship it", mode: "auto" },
+      host,
+      controller.signal,
+    );
+    await vi.waitFor(() => expect(host.restartSession).toHaveBeenCalled());
+    controller.abort();
+    finishRestart();
+
+    await expect(restart).rejects.toThrow("Clear-context restart aborted");
+    expect(host.publishSessionState).not.toHaveBeenCalled();
+    expect(freshSession.input.push).not.toHaveBeenCalled();
+    expect(host.ensureConsumer).not.toHaveBeenCalled();
+  });
+
+  it("rejects a stale session before closing its query", async () => {
+    const turn: ClearContextTurn = {
+      settled: false,
+      promptUuid: "00000000-0000-4000-8000-000000000000",
+    };
+    const oldSession = testSession({ activeTurn: turn });
+    const host = testHost(oldSession, testSession());
+    vi.mocked(host.currentSession).mockReturnValue(testSession());
+
+    await expect(
+      continuePlanInFreshContext(
+        "public-session",
+        oldSession,
+        { toolUseId: "tool-plan", plan: "Ship it", mode: "auto" },
+        host,
+      ),
+    ).rejects.toThrow("Cannot clear context without an active ACP turn");
+
+    expect(host.closeQueryStream).not.toHaveBeenCalled();
+    expect(host.restartSession).not.toHaveBeenCalled();
+  });
+});
+
+describe("ExitPlanCoordinator", () => {
+  it("owns cancellation cleanup for a replacement created after close", async () => {
+    const turn: ClearContextTurn = {
+      settled: false,
+      promptUuid: "00000000-0000-4000-8000-000000000000",
+    };
+    const oldSession = testSession({ activeTurn: turn, turnQueue: [turn] });
+    const freshSession = testSession();
+    const baseHost = testHost(oldSession, freshSession);
+    const destroyReplacement = vi.fn();
+    const settleCancelledTurn = vi.fn((_old, _owner, cancelledTurn: ClearContextTurn) => {
+      cancelledTurn.settled = true;
+    });
+    let finishRestart!: () => void;
+    vi.mocked(baseHost.restartSession).mockImplementation(
+      () =>
+        new Promise<TestSession>((resolve) => {
+          finishRestart = () => {
+            vi.mocked(baseHost.currentSession).mockReturnValue(freshSession);
+            resolve(freshSession);
+          };
+        }),
+    );
+    const host = {
+      ...baseHost,
+      sessionUpdate: vi.fn(async () => {}),
+      destroyReplacement,
+      settleCancelledTurn,
+      settleFailedTurn: vi.fn(),
+    };
+    const coordinator = new ExitPlanCoordinator<TestSession, ClearContextTurn>(host);
+
+    const restart = coordinator.restart("public-session", oldSession, {
+      toolUseId: "tool-plan",
+      plan: "Ship it",
+      mode: "auto",
+    });
+    await vi.waitFor(() => expect(baseHost.restartSession).toHaveBeenCalled());
+    coordinator.cancel("public-session");
+    finishRestart();
+    await restart;
+
+    expect(destroyReplacement).toHaveBeenCalledWith("public-session", freshSession);
+    expect(settleCancelledTurn).toHaveBeenCalledWith(oldSession, oldSession, turn);
+    expect(oldSession.activeTurn).toBeNull();
+    expect(oldSession.turnQueue).toEqual([]);
+    expect(freshSession.input.push).not.toHaveBeenCalled();
+    expect(baseHost.ensureConsumer).not.toHaveBeenCalled();
+  });
+
+  it("settles a restart failure without classifying it as a query transport loss", async () => {
+    const error = new Error("restart failed");
+    const turn: ClearContextTurn = {
+      settled: false,
+      promptUuid: "00000000-0000-4000-8000-000000000000",
+    };
+    const reset = { toolUseId: "tool-plan", plan: "Ship it", mode: "auto" as const };
+    const oldSession = testSession({
+      activeTurn: turn,
+      turnQueue: [turn],
+      pendingExitPlanContextReset: reset,
+    });
+    const baseHost = testHost(oldSession, testSession());
+    vi.mocked(baseHost.restartSession).mockRejectedValue(error);
+    const settleFailedTurn = vi.fn((_owner, failedTurn: ClearContextTurn) => {
+      failedTurn.settled = true;
+    });
+    const host = {
+      ...baseHost,
+      sessionUpdate: vi.fn(async () => {}),
+      destroyReplacement: vi.fn(),
+      settleCancelledTurn: vi.fn(),
+      settleFailedTurn,
+    };
+    const coordinator = new ExitPlanCoordinator<TestSession, ClearContextTurn>(host);
+
+    await coordinator.restart("public-session", oldSession, reset);
+
+    expect(settleFailedTurn).toHaveBeenCalledWith(oldSession, turn, error);
+    expect(turn.carriedUsage).toBeUndefined();
+    expect(turn.carriedModelUsage).toBeUndefined();
+    expect(oldSession.pendingExitPlanContextReset).toBeUndefined();
+    expect(oldSession.activeTurn).toBeNull();
+    expect(oldSession.turnQueue).toEqual([]);
+  });
+});
+
+describe("observeExitPlanToolResults", () => {
+  it("restores a rejected ExitPlanMode marker from authoritative stream metadata", () => {
+    const state = {
+      toolUseCache: { "tool-plan": { name: "ExitPlanMode" } },
+    };
+
+    const accepted = observeExitPlanToolResults(
+      {
+        type: "user",
+        tool_result_meta: [{ id: "tool-plan", non_execution_kind: "user-rejected" }],
+      },
+      [{ type: "tool_result", tool_use_id: "tool-plan", is_error: true }],
+      state,
+    );
+
+    expect(accepted).toBeUndefined();
+    expect(state).toEqual({
+      toolUseCache: { "tool-plan": { name: "ExitPlanMode" } },
+      pendingExitPlanModeInterruption: { toolUseId: "tool-plan", toolResultSeen: true },
+    });
+  });
+
+  it("correlates an accepted plan result with its pending context reset", () => {
+    const state = {
+      toolUseCache: { "tool-plan": { name: "ExitPlanMode" } },
+      pendingExitPlanContextReset: {
+        toolUseId: "tool-plan",
+        plan: "Ship it",
+        mode: "auto" as const,
+      },
+    };
+
+    expect(
+      observeExitPlanToolResults(
+        { type: "user" },
+        [{ type: "tool_result", tool_use_id: "tool-plan", is_error: true }],
+        state,
+      ),
+    ).toBe("tool-plan");
+  });
+});
--- a/src/tests/create-session-options.test.ts
+++ b/src/tests/create-session-options.test.ts
@@ -1,5 +1,10 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
-import { RequestError, SessionNotification } from "@agentclientprotocol/sdk";
+import {
+  CreateElicitationRequest,
+  RequestError,
+  SessionNotification,
+} from "@agentclientprotocol/sdk";
+import type { ClientCapabilities } from "@agentclientprotocol/sdk";
 import type { Options } from "@anthropic-ai/claude-agent-sdk";
 import type { AcpClient, ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
 import * as fs from "node:fs";
@@ -8,6 +13,12 @@ import * as path from "node:path";

 let capturedOptions: Options | undefined;
 let contextUsageResult: (() => Promise<{ rawMaxTokens: number; model?: string }>) | undefined;
+let mcpServerStatusResult: () => Promise<Array<{ name: string; status: string }>>;
+let mcpAuthenticateImpl: (serverName: string) => Promise<{
+  authUrl?: string;
+  requiresUserAction: boolean;
+  callbackExpected: boolean;
+}>;
 vi.mock("@anthropic-ai/claude-agent-sdk", async () => {
  const actual = await vi.importActual<typeof import("@anthropic-ai/claude-agent-sdk")>(
    "@anthropic-ai/claude-agent-sdk",
@@ -30,6 +41,8 @@ vi.mock("@anthropic-ai/claude-agent-sdk", async () => {
        }),
        getContextUsage: () =>
          contextUsageResult ? contextUsageResult() : Promise.resolve(DEFAULT_CONTEXT_USAGE),
+        mcpServerStatus: () => mcpServerStatusResult(),
+        mcpAuthenticate: (serverName: string) => mcpAuthenticateImpl(serverName),
      });
    },
  };
@@ -59,6 +72,11 @@ describe("createSession options merging", () => {
  beforeEach(async () => {
    capturedOptions = undefined;
    contextUsageResult = undefined;
+    mcpServerStatusResult = async () => [];
+    mcpAuthenticateImpl = async () => ({
+      requiresUserAction: false,
+      callbackExpected: false,
+    });

    vi.resetModules();
    const acpAgent = await import("../acp-agent.js");
@@ -270,7 +288,7 @@ describe("createSession options merging", () => {
      expect(capturedOptions!.forwardSubagentText).toBe(false);
    });

-    it("preserves the pre-existing caller-provided SDK option", async () => {
+    it("preserves caller-provided legacy transcript forwarding", async () => {
      await agent.newSession({
        cwd: process.cwd(),
        mcpServers: [],
@@ -280,7 +298,7 @@ describe("createSession options merging", () => {
      expect(capturedOptions!.forwardSubagentText).toBe(true);
    });

-    it("enables SDK forwarding when the ACP client advertises support", async () => {
+    it("accepts the legacy transcript extension", async () => {
      await agent.initialize({
        protocolVersion: 1,
        clientCapabilities: { _meta: { "subagent-transcript": true } },
@@ -293,6 +311,20 @@ describe("createSession options merging", () => {

      expect(capturedOptions!.forwardSubagentText).toBe(true);
    });
+
+    it("enables SDK forwarding after native ACP negotiation", async () => {
+      await agent.initialize({
+        protocolVersion: 1,
+        clientCapabilities: { subagents: {} } as ClientCapabilities,
+      });
+      await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [],
+        _meta: { claudeCode: { options: { forwardSubagentText: false } } },
+      });
+
+      expect(capturedOptions!.forwardSubagentText).toBe(true);
+    });
  });

  describe("systemPrompt via _meta", () => {
@@ -636,6 +668,57 @@ describe("createSession options merging", () => {
      expect(typeof capturedOptions!.onElicitation).toBe("function");
    });

+    it("starts MCP OAuth as an ACP URL elicitation and completes it after reconnect", async () => {
+      let statusCall = 0;
+      mcpServerStatusResult = async () =>
+        statusCall++ === 0
+          ? [{ name: "linear", status: "needs-auth" }]
+          : [{ name: "linear", status: "connected" }];
+      const authenticate = vi.fn(async () => ({
+        authUrl: "https://example.com/oauth/authorize",
+        requiresUserAction: true,
+        callbackExpected: true,
+      }));
+      mcpAuthenticateImpl = authenticate;
+      const createElicitation = vi.fn(async (_request: CreateElicitationRequest) => ({
+        action: "accept" as const,
+      }));
+      const completeElicitation = vi.fn(async () => {});
+      Object.assign((agent as unknown as { client: object }).client, {
+        unstable_createElicitation: createElicitation,
+        unstable_completeElicitation: completeElicitation,
+      });
+
+      await agent.initialize({
+        protocolVersion: 1,
+        clientCapabilities: { elicitation: { url: {} } },
+      });
+      const { sessionId } = await agent.newSession({
+        cwd: process.cwd(),
+        mcpServers: [
+          { name: "linear", type: "http", url: "https://mcp.linear.app/mcp", headers: [] },
+        ],
+      });
+
+      await vi.waitFor(() => expect(completeElicitation).toHaveBeenCalledOnce());
+
+      expect(authenticate).toHaveBeenCalledWith("linear");
+      expect(createElicitation).toHaveBeenCalledOnce();
+      const request = createElicitation.mock.calls[0]![0];
+      expect(request.mode).toBe("url");
+      if (request.mode !== "url") throw new Error("Expected a URL elicitation");
+      expect(request).toMatchObject({
+        mode: "url",
+        sessionId,
+        message: "Authenticate with MCP server linear",
+        url: "https://example.com/oauth/authorize",
+        elicitationId: expect.stringMatching(/^mcp-oauth-/),
+      });
+      expect(completeElicitation).toHaveBeenCalledWith({
+        elicitationId: request.elicitationId,
+      });
+    });
+
    it("still merges user-provided disallowedTools when AskUserQuestion is enabled", async () => {
      await agent.initialize({
        protocolVersion: 1,
@@ -740,6 +823,7 @@ describe("createSession options merging", () => {
        headers: {},
      });
      const plain = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+      const plainProviderCacheKey = sessionFor(plain.sessionId).providerCacheKey;

      await agent.unstable_setProvider({
        providerId: "main",
@@ -749,9 +833,7 @@ describe("createSession options merging", () => {
      });
      const beta = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });

-      expect(sessionFor(beta.sessionId).providerCacheKey).not.toBe(
-        sessionFor(plain.sessionId).providerCacheKey,
-      );
+      expect(sessionFor(beta.sessionId).providerCacheKey).not.toBe(plainProviderCacheKey);
    });
  });

--- a/src/tests/file-change-audit-integration.test.ts
+++ b/src/tests/file-change-audit-integration.test.ts
@@ -0,0 +1,604 @@
+import type {
+  HookCallback,
+  Options,
+  PermissionResult,
+  SDKUserMessage,
+} from "@anthropic-ai/claude-agent-sdk";
+import type { SessionNotification } from "@agentclientprotocol/sdk";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { AcpClient, ClaudeAcpAgent as ClaudeAcpAgentType } from "../acp-agent.js";
+import {
+  AGENT_FILE_CHANGE_REPORT_CAPABILITY,
+  FILE_CHANGE_AUDIT_SERVER_NAME,
+  FILE_CHANGE_AUDIT_TOOL_NAME,
+  FILE_CHANGE_AUDIT_WIRE_TOOL_NAME,
+  type AgentFileChangeReport,
+  type AgentFileChangeReportResult,
+} from "../file-change-audit.js";
+import type { Pushable } from "../utils.js";
+
+let observedStopOutputs: unknown[] = [];
+let observedPreToolDecision: unknown;
+let observedCanUseToolDecision: PermissionResult | null | undefined;
+let replayMessages: unknown[] = [];
+type AuditScenario =
+  "reported" | "successWithoutReport" | "providerError" | "localOnly" | "waitForCancel";
+let auditScenario: AuditScenario = "reported";
+let auditTurnActivated = Promise.resolve();
+let resolveAuditTurnActivated = () => {};
+
+vi.mock("@anthropic-ai/claude-agent-sdk", async () => {
+  const actual = await vi.importActual<typeof import("@anthropic-ai/claude-agent-sdk")>(
+    "@anthropic-ai/claude-agent-sdk",
+  );
+  return {
+    ...actual,
+    getSessionMessages: vi.fn(async () => replayMessages),
+    query: ({ prompt, options }: { prompt: Pushable<SDKUserMessage>; options: Options }) => {
+      let resolveInterrupt = () => {};
+      const interrupted = new Promise<void>((resolve) => {
+        resolveInterrupt = resolve;
+      });
+      return Object.assign(runAuditedTurn(prompt, options, interrupted), {
+        initializationResult: async () => ({
+          models: [
+            {
+              value: "claude-sonnet-4-6",
+              displayName: "Claude Sonnet",
+              description: "Fast",
+              supportsAutoMode: true,
+            },
+          ],
+        }),
+        setModel: vi.fn(async () => {}),
+        setPermissionMode: vi.fn(async () => {}),
+        supportedAgents: vi.fn(async () => []),
+        supportedCommands: vi.fn(async () => []),
+        getContextUsage: vi.fn(async () => ({ totalTokens: 0, rawMaxTokens: 200000 })),
+        interrupt: vi.fn(async () => {
+          resolveInterrupt();
+          return undefined;
+        }),
+        close: vi.fn(),
+      });
+    },
+  };
+});
+
+vi.mock("../tools.js", async () => ({
+  ...(await vi.importActual<typeof import("../tools.js")>("../tools.js")),
+  registerHookCallback: vi.fn(),
+}));
+
+type RegisteredAuditTool = {
+  handler: (
+    report: AgentFileChangeReport,
+  ) => Promise<{ content: unknown; structuredContent?: AgentFileChangeReportResult }>;
+};
+
+function hookFrom(options: Options, event: "PreToolUse" | "Stop"): HookCallback {
+  const matcher = options.hooks?.[event]?.at(-1);
+  const hook = matcher?.hooks.at(-1);
+  if (!hook) throw new Error(`Missing ${event} audit hook`);
+  return hook;
+}
+
+function auditToolFrom(options: Options): RegisteredAuditTool {
+  const server = options.mcpServers?.[FILE_CHANGE_AUDIT_SERVER_NAME] as unknown as {
+    instance: { _registeredTools: Record<string, RegisteredAuditTool> };
+  };
+  const tool = server.instance._registeredTools[FILE_CHANGE_AUDIT_TOOL_NAME];
+  if (!tool) throw new Error("Missing internal audit tool");
+  return tool;
+}
+
+function assistantMessage(content: unknown[]) {
+  return {
+    type: "assistant" as const,
+    parent_tool_use_id: null,
+    uuid: randomUUID(),
+    session_id: "sdk-session",
+    message: {
+      role: "assistant" as const,
+      model: "claude-sonnet-4-6",
+      stop_reason: "end_turn",
+      usage: {
+        input_tokens: 1,
+        output_tokens: 1,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+      },
+      content,
+    },
+  };
+}
+
+function successResult() {
+  return {
+    type: "result" as const,
+    subtype: "success" as const,
+    stop_reason: "end_turn",
+    is_error: false,
+    result: "",
+    errors: [],
+    duration_ms: 0,
+    duration_api_ms: 0,
+    num_turns: 2,
+    total_cost_usd: 0,
+    usage: {
+      input_tokens: 2,
+      output_tokens: 2,
+      cache_read_input_tokens: 0,
+      cache_creation_input_tokens: 0,
+    },
+    modelUsage: {},
+    permission_denials: [],
+    uuid: randomUUID(),
+    session_id: "sdk-session",
+  };
+}
+
+async function* runAuditedTurn(
+  input: Pushable<SDKUserMessage>,
+  options: Options,
+  interrupted: Promise<void>,
+) {
+  const iterator = input[Symbol.asyncIterator]();
+  const { value: userMessage } = await iterator.next();
+  if (!userMessage) return;
+
+  if (auditScenario === "localOnly") {
+    yield { ...successResult(), result: "Local command output" };
+    return;
+  }
+
+  yield {
+    type: "user" as const,
+    message: userMessage.message,
+    parent_tool_use_id: null,
+    uuid: userMessage.uuid,
+    session_id: "sdk-session",
+    isReplay: true,
+  };
+  resolveAuditTurnActivated();
+
+  if (auditScenario === "successWithoutReport") {
+    yield assistantMessage([{ type: "text", text: "Visible answer" }]);
+    yield successResult();
+    return;
+  }
+  if (auditScenario === "providerError") {
+    yield {
+      ...successResult(),
+      is_error: true,
+      result: "Provider failed",
+      errors: ["Provider failed"],
+    };
+    return;
+  }
+  if (auditScenario === "waitForCancel") {
+    await interrupted;
+    yield {
+      type: "system" as const,
+      subtype: "session_state_changed" as const,
+      state: "idle" as const,
+      uuid: randomUUID(),
+      session_id: "sdk-session",
+    };
+    return;
+  }
+
+  yield assistantMessage([{ type: "text", text: "Visible answer" }]);
+
+  const hookOptions = { signal: new AbortController().signal };
+  const stopHook = hookFrom(options, "Stop");
+  observedStopOutputs.push(
+    await stopHook(
+      { hook_event_name: "Stop", stop_hook_active: false } as Parameters<HookCallback>[0],
+      undefined,
+      hookOptions,
+    ),
+  );
+
+  const preToolUseHook = hookFrom(options, "PreToolUse");
+  observedPreToolDecision = await preToolUseHook(
+    {
+      hook_event_name: "PreToolUse",
+      tool_name: "Bash",
+      tool_input: { command: "git status" },
+      tool_use_id: "blocked-tool",
+    } as Parameters<HookCallback>[0],
+    "blocked-tool",
+    hookOptions,
+  );
+  observedCanUseToolDecision = await options.canUseTool?.(
+    "Bash",
+    { command: "git status" },
+    {
+      signal: hookOptions.signal,
+      toolUseID: "blocked-tool",
+      requestId: "permission-request",
+    },
+  );
+
+  const toolUseId = "audit-tool-use";
+  yield assistantMessage([
+    { type: "text", text: "Audit prose must stay hidden" },
+    {
+      type: "tool_use",
+      id: toolUseId,
+      name: FILE_CHANGE_AUDIT_WIRE_TOOL_NAME,
+      input: { paths: ["src/changed.ts"], complete: true },
+    },
+  ]);
+
+  const toolResult = await auditToolFrom(options).handler({
+    paths: ["src/changed.ts"],
+    complete: true,
+  });
+  yield {
+    type: "user" as const,
+    message: {
+      role: "user" as const,
+      content: [
+        {
+          type: "tool_result",
+          tool_use_id: toolUseId,
+          content: toolResult.content,
+        },
+      ],
+    },
+    parent_tool_use_id: null,
+    uuid: randomUUID(),
+    session_id: "sdk-session",
+  };
+
+  observedStopOutputs.push(
+    await stopHook(
+      { hook_event_name: "Stop", stop_hook_active: true } as Parameters<HookCallback>[0],
+      undefined,
+      hookOptions,
+    ),
+  );
+  yield successResult();
+}
+
+describe("agent file-change audit integration", () => {
+  beforeEach(() => {
+    observedStopOutputs = [];
+    observedPreToolDecision = undefined;
+    observedCanUseToolDecision = undefined;
+    replayMessages = [];
+    auditScenario = "reported";
+    auditTurnActivated = new Promise<void>((resolve) => {
+      resolveAuditTurnActivated = resolve;
+    });
+  });
+
+  const negotiatedCapabilities = {
+    _meta: {
+      jetbrains: {
+        air: {
+          version: 1,
+          capabilities: [AGENT_FILE_CHANGE_REPORT_CAPABILITY, "sessionFailure"],
+        },
+      },
+    },
+  };
+
+  async function createAuditAgent(updates: SessionNotification[]) {
+    const client = {
+      sessionUpdate: async (notification: SessionNotification) => void updates.push(notification),
+      requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+      readTextFile: async () => ({ content: "" }),
+      writeTextFile: async () => ({}),
+    } as unknown as AcpClient;
+    const { ClaudeAcpAgent } = await import("../acp-agent.js");
+    const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(client, {
+      log: () => {},
+      error: () => {},
+    });
+    await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: negotiatedCapabilities,
+    });
+    const { sessionId } = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+    return { agent, sessionId };
+  }
+
+  function fileChangeTerminals(updates: SessionNotification[]): AgentFileChangeReportResult[] {
+    return updates.flatMap((notification) => {
+      if (notification.update.sessionUpdate !== "session_info_update") return [];
+      const meta = notification.update._meta as
+        | {
+            jetbrains?: {
+              air?: { agentFileChangeReport?: AgentFileChangeReportResult };
+            };
+          }
+        | undefined;
+      const report = meta?.jetbrains?.air?.agentFileChangeReport;
+      return report ? [report] : [];
+    });
+  }
+
+  function auditedPrompt(sessionId: string, requestId: string, text: string) {
+    return {
+      sessionId,
+      prompt: [{ type: "text" as const, text }],
+      _meta: {
+        jetbrains: {
+          air: {
+            agentFileChangeReportRequest: { version: 1, requestId },
+          },
+        },
+      },
+    };
+  }
+
+  it.each([
+    {
+      name: "normal success without a Stop report",
+      scenario: "successWithoutReport" as const,
+      prompt: "Finish normally",
+      reason: "notReported" as const,
+      rejects: false,
+    },
+    {
+      name: "a local-only command",
+      scenario: "localOnly" as const,
+      prompt: "/context",
+      reason: "notReported" as const,
+      rejects: false,
+    },
+    {
+      name: "a provider error",
+      scenario: "providerError" as const,
+      prompt: "Call the provider",
+      reason: "providerError" as const,
+      rejects: false,
+    },
+  ])("publishes one terminal for $name", async ({ scenario, prompt, reason, rejects }) => {
+    auditScenario = scenario;
+    const updates: SessionNotification[] = [];
+    const { agent, sessionId } = await createAuditAgent(updates);
+    const requestId = `request-${scenario}`;
+    const result = agent.prompt(auditedPrompt(sessionId, requestId, prompt));
+
+    if (rejects) {
+      await expect(result).rejects.toBeDefined();
+    } else {
+      await expect(result).resolves.toBeDefined();
+    }
+    expect(fileChangeTerminals(updates)).toEqual([
+      {
+        version: 1,
+        requestId,
+        status: "unavailable",
+        reason,
+      },
+    ]);
+
+    await agent.dispose();
+    expect(fileChangeTerminals(updates)).toHaveLength(1);
+  });
+
+  it.each([
+    { name: "cancel", close: false },
+    { name: "session close", close: true },
+  ])("publishes one cancelled terminal and settles the prompt on $name", async ({ close }) => {
+    auditScenario = "waitForCancel";
+    const updates: SessionNotification[] = [];
+    const { agent, sessionId } = await createAuditAgent(updates);
+    const requestId = close ? "request-close" : "request-cancel";
+    const result = agent.prompt(auditedPrompt(sessionId, requestId, "Wait"));
+    await auditTurnActivated;
+
+    if (close) {
+      await agent.closeSession({ sessionId });
+    } else {
+      await agent.cancel({ sessionId });
+    }
+    await expect(result).resolves.toMatchObject({ stopReason: "cancelled" });
+    expect(fileChangeTerminals(updates)).toEqual([
+      {
+        version: 1,
+        requestId,
+        status: "unavailable",
+        reason: "cancelled",
+      },
+    ]);
+
+    await agent.dispose();
+    expect(fileChangeTerminals(updates)).toHaveLength(1);
+  });
+
+  it("negotiates an opt-in turn, publishes one report, and hides the audit continuation", async () => {
+    const updates: SessionNotification[] = [];
+    const client = {
+      sessionUpdate: async (notification: SessionNotification) => void updates.push(notification),
+      requestPermission: async () => ({ outcome: { outcome: "cancelled" } }),
+      readTextFile: async () => ({ content: "" }),
+      writeTextFile: async () => ({}),
+    } as unknown as AcpClient;
+    const { ClaudeAcpAgent } = await import("../acp-agent.js");
+    const agent: ClaudeAcpAgentType = new ClaudeAcpAgent(client, {
+      log: () => {},
+      error: () => {},
+    });
+
+    const capabilities = {
+      _meta: {
+        jetbrains: {
+          air: {
+            version: 1,
+            capabilities: [AGENT_FILE_CHANGE_REPORT_CAPABILITY],
+          },
+        },
+      },
+    };
+    const initialize = await agent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: capabilities,
+    });
+    expect(initialize._meta).toMatchObject({
+      jetbrains: {
+        air: {
+          version: 1,
+          capabilities: expect.arrayContaining([AGENT_FILE_CHANGE_REPORT_CAPABILITY]),
+        },
+      },
+    });
+
+    const cwd = process.cwd();
+    const { sessionId } = await agent.newSession({ cwd, mcpServers: [] });
+    const response = await agent.prompt({
+      sessionId,
+      prompt: [{ type: "text", text: "Change the file" }],
+      _meta: {
+        jetbrains: {
+          air: {
+            agentFileChangeReportRequest: { version: 1, requestId: "request-integration" },
+          },
+        },
+      },
+    });
+
+    expect(response.stopReason).toBe("end_turn");
+    expect(observedStopOutputs).toHaveLength(2);
+    expect(observedStopOutputs[0]).toMatchObject({
+      hookSpecificOutput: {
+        hookEventName: "Stop",
+        additionalContext: expect.stringContaining(FILE_CHANGE_AUDIT_WIRE_TOOL_NAME),
+      },
+    });
+    expect(observedStopOutputs[1]).toEqual({});
+    expect(observedPreToolDecision).toMatchObject({
+      hookSpecificOutput: { permissionDecision: "deny" },
+    });
+    expect(observedCanUseToolDecision).toMatchObject({ behavior: "deny" });
+
+    const reportUpdates = updates.filter((notification) => {
+      if (notification.update.sessionUpdate !== "session_info_update") return false;
+      const meta = notification.update._meta as
+        { jetbrains?: { air?: { agentFileChangeReport?: unknown } } } | undefined;
+      return meta?.jetbrains?.air?.agentFileChangeReport !== undefined;
+    });
+    expect(reportUpdates).toEqual([
+      {
+        sessionId,
+        update: {
+          sessionUpdate: "session_info_update",
+          _meta: {
+            jetbrains: {
+              air: {
+                version: 1,
+                agentFileChangeReport: {
+                  version: 1,
+                  requestId: "request-integration",
+                  status: "reported",
+                  paths: [path.join(cwd, "src/changed.ts")],
+                  declaredComplete: true,
+                  truncated: false,
+                },
+              },
+            },
+          },
+        },
+      },
+    ]);
+
+    const serializedUpdates = JSON.stringify(updates);
+    expect(serializedUpdates).toContain("Visible answer");
+    expect(serializedUpdates).not.toContain("Audit prose must stay hidden");
+    expect(serializedUpdates).not.toContain(FILE_CHANGE_AUDIT_WIRE_TOOL_NAME);
+
+    await agent.dispose();
+
+    const firstStop = observedStopOutputs[0] as {
+      hookSpecificOutput?: { additionalContext?: string };
+    };
+    const auditContext = firstStop.hookSpecificOutput?.additionalContext;
+    if (!auditContext) throw new Error("Missing audit continuation context");
+    const replayToolUseId = "replay-audit-tool";
+    const deniedReplayToolUseId = "replay-denied-tool";
+    const replayUserMessage = (content: unknown) => ({
+      type: "user" as const,
+      message: { role: "user" as const, content },
+      parent_tool_use_id: null,
+      uuid: randomUUID(),
+      session_id: "replay-session",
+    });
+    replayMessages = [
+      replayUserMessage("Original prompt"),
+      assistantMessage([{ type: "text", text: "Visible persisted answer" }]),
+      replayUserMessage(auditContext),
+      assistantMessage([{ type: "text", text: "Separate audit prose must stay hidden" }]),
+      assistantMessage([
+        {
+          type: "tool_use",
+          id: deniedReplayToolUseId,
+          name: "Bash",
+          input: { command: "git status" },
+        },
+      ]),
+      replayUserMessage([
+        {
+          type: "tool_result",
+          tool_use_id: deniedReplayToolUseId,
+          content: "denied",
+          is_error: true,
+        },
+      ]),
+      assistantMessage([{ type: "text", text: "Prose after denial must stay hidden" }]),
+      assistantMessage([
+        {
+          type: "tool_use",
+          id: replayToolUseId,
+          name: FILE_CHANGE_AUDIT_WIRE_TOOL_NAME,
+          input: { paths: ["src/changed.ts"], complete: true },
+        },
+      ]),
+      replayUserMessage([
+        {
+          type: "tool_result",
+          tool_use_id: replayToolUseId,
+          content: "recorded",
+        },
+      ]),
+      replayUserMessage("Follow-up prompt"),
+      assistantMessage([{ type: "text", text: "Follow-up answer" }]),
+    ];
+
+    const replayUpdates: SessionNotification[] = [];
+    const replayAgent = new ClaudeAcpAgent(
+      {
+        ...client,
+        sessionUpdate: async (notification: SessionNotification) =>
+          void replayUpdates.push(notification),
+      } as AcpClient,
+      { log: () => {}, error: () => {} },
+    );
+    await replayAgent.initialize({
+      protocolVersion: 1,
+      clientCapabilities: capabilities,
+    });
+    await replayAgent.loadSession({
+      sessionId: "replay-session",
+      cwd,
+      mcpServers: [],
+    });
+
+    const serializedReplay = JSON.stringify(replayUpdates);
+    expect(serializedReplay).toContain("Original prompt");
+    expect(serializedReplay).toContain("Visible persisted answer");
+    expect(serializedReplay).toContain("Follow-up prompt");
+    expect(serializedReplay).toContain("Follow-up answer");
+    expect(serializedReplay).not.toContain("Separate audit prose must stay hidden");
+    expect(serializedReplay).not.toContain("Prose after denial must stay hidden");
+    expect(serializedReplay).not.toContain(FILE_CHANGE_AUDIT_WIRE_TOOL_NAME);
+    expect(serializedReplay).not.toContain("claude-agent-acp-file-change-audit");
+    await replayAgent.dispose();
+  });
+});
--- a/src/tests/file-change-audit.test.ts
+++ b/src/tests/file-change-audit.test.ts
@@ -0,0 +1,367 @@
+import type { HookCallback } from "@anthropic-ai/claude-agent-sdk";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { describe, expect, it, vi } from "vitest";
+import {
+  AGENT_FILE_CHANGE_REPORT_MAX_BYTES,
+  agentFileChangeReportRequestId,
+  createFileChangeAuditSupport,
+  createFileChangeAuditTurnState,
+  FILE_CHANGE_AUDIT_TOOL_NAME,
+  FILE_CHANGE_AUDIT_WIRE_TOOL_NAME,
+  type AgentFileChangeReport,
+  type AgentFileChangeReportResult,
+  type FileChangeAuditTurnState,
+} from "../file-change-audit.js";
+
+type RegisteredAuditTool = {
+  _meta?: Record<string, unknown>;
+  handler: (report: AgentFileChangeReport) => Promise<{
+    isError?: boolean;
+    structuredContent?: AgentFileChangeReportResult;
+  }>;
+};
+
+function auditToolHandler(
+  support: ReturnType<typeof createFileChangeAuditSupport>,
+): RegisteredAuditTool {
+  const server = support.mcpServer as unknown as {
+    instance: { _registeredTools: Record<string, RegisteredAuditTool> };
+  };
+  return server.instance._registeredTools[FILE_CHANGE_AUDIT_TOOL_NAME];
+}
+
+function stopInput(stopHookActive = false): Parameters<HookCallback>[0] {
+  return {
+    hook_event_name: "Stop",
+    stop_hook_active: stopHookActive,
+  } as Parameters<HookCallback>[0];
+}
+
+function createSupport(options: {
+  state: FileChangeAuditTurnState;
+  cwd?: string;
+  additionalDirectories?: string[];
+  publish?: (result: AgentFileChangeReportResult) => Promise<void>;
+  logError?: (message: string) => void;
+}) {
+  return createFileChangeAuditSupport({
+    cwd: options.cwd ?? process.cwd(),
+    additionalDirectories: options.additionalDirectories ?? [],
+    getActiveState: () => options.state,
+    publish: options.publish ?? (async () => {}),
+    logError: options.logError ?? (() => {}),
+  });
+}
+
+describe("agent file-change audit", () => {
+  it("accepts only the versioned prompt request shape", () => {
+    expect(
+      agentFileChangeReportRequestId({
+        jetbrains: {
+          air: {
+            agentFileChangeReportRequest: { version: 1, requestId: "turn:42_a-b.c" },
+          },
+        },
+      }),
+    ).toBe("turn:42_a-b.c");
+
+    for (const request of [
+      { version: 2, requestId: "turn-42" },
+      { version: 1, requestId: "contains spaces" },
+      { version: 1, requestId: "x".repeat(129) },
+      { version: 1 },
+      { version: 1, requestId: "turn-42", extra: true },
+      null,
+    ]) {
+      expect(
+        agentFileChangeReportRequestId({
+          jetbrains: { air: { agentFileChangeReportRequest: request } },
+        }),
+      ).toBeUndefined();
+    }
+  });
+
+  it("continues Stop at most once and reports a missing tool call once", async () => {
+    const state = createFileChangeAuditTurnState("request-1");
+    const publish = vi.fn(async (_result: AgentFileChangeReportResult) => {});
+    const support = createSupport({ state, publish });
+    const hookOptions = { signal: new AbortController().signal };
+    const preToolInput = (toolName: string) =>
+      ({
+        hook_event_name: "PreToolUse",
+        tool_name: toolName,
+        tool_input: {},
+        tool_use_id: "tool-1",
+      }) as Parameters<HookCallback>[0];
+
+    await expect(
+      support.preToolUseHook(preToolInput(FILE_CHANGE_AUDIT_WIRE_TOOL_NAME), "tool-1", hookOptions),
+    ).resolves.toMatchObject({
+      hookSpecificOutput: { permissionDecision: "deny" },
+    });
+
+    const pausedStop = {
+      ...stopInput(),
+      background_tasks: [{ id: "generator", type: "shell", status: "running", description: "" }],
+    } as Parameters<HookCallback>[0];
+    expect(await support.stopHook(pausedStop, undefined, hookOptions)).toEqual({});
+    expect(state.phase).toBe("requested");
+
+    const first = await support.stopHook(stopInput(), undefined, hookOptions);
+    expect(state.phase).toBe("collecting");
+    expect(first).toMatchObject({
+      hookSpecificOutput: {
+        hookEventName: "Stop",
+        additionalContext: expect.stringContaining(FILE_CHANGE_AUDIT_WIRE_TOOL_NAME),
+      },
+    });
+
+    await expect(
+      support.preToolUseHook(preToolInput("Bash"), "tool-1", hookOptions),
+    ).resolves.toMatchObject({
+      hookSpecificOutput: { permissionDecision: "deny" },
+    });
+    await expect(
+      support.preToolUseHook(preToolInput(FILE_CHANGE_AUDIT_WIRE_TOOL_NAME), "tool-1", hookOptions),
+    ).resolves.toMatchObject({
+      hookSpecificOutput: { permissionDecision: "allow" },
+    });
+
+    expect(await support.stopHook(stopInput(true), undefined, hookOptions)).toEqual({});
+    expect(state.phase).toBe("finished");
+    expect(publish).toHaveBeenCalledWith({
+      version: 1,
+      requestId: "request-1",
+      status: "unavailable",
+      reason: "notReported",
+    });
+
+    await support.stopHook(stopInput(true), undefined, hookOptions);
+    expect(publish).toHaveBeenCalledTimes(1);
+  });
+
+  it("publishes only the first unavailable terminal and rejects a late report", async () => {
+    const state = createFileChangeAuditTurnState("request-terminal-race");
+    state.phase = "collecting";
+    const publish = vi.fn(async (_result: AgentFileChangeReportResult) => {});
+    const support = createSupport({ state, publish });
+
+    await Promise.all([
+      support.finishUnavailable(state, "cancelled"),
+      support.finishUnavailable(state, "providerError"),
+    ]);
+
+    expect(publish).toHaveBeenCalledTimes(1);
+    expect(publish).toHaveBeenCalledWith({
+      version: 1,
+      requestId: "request-terminal-race",
+      status: "unavailable",
+      reason: "cancelled",
+    });
+    await expect(
+      auditToolHandler(support).handler({ paths: ["src/late.ts"], complete: true }),
+    ).resolves.toMatchObject({ isError: true });
+    expect(publish).toHaveBeenCalledTimes(1);
+  });
+
+  it("normalizes roots, drops invalid paths, and deduplicates without truncation", async () => {
+    const cwd = path.join(os.tmpdir(), "file-audit-project");
+    const additionalRoot = path.join(os.tmpdir(), "file-audit-shared");
+    const canonicalTempRoot = fs.realpathSync.native(os.tmpdir());
+    const canonicalCwd = path.join(canonicalTempRoot, "file-audit-project");
+    const canonicalAdditionalRoot = path.join(canonicalTempRoot, "file-audit-shared");
+    const outside = path.join(os.tmpdir(), "file-audit-outside", "outside.txt");
+    const state = createFileChangeAuditTurnState("request-2");
+    state.phase = "collecting";
+    const published: AgentFileChangeReportResult[] = [];
+    const support = createSupport({
+      state,
+      cwd,
+      additionalDirectories: [additionalRoot],
+      publish: async (result) => void published.push(result),
+    });
+    const tool = auditToolHandler(support);
+
+    expect(tool._meta).toMatchObject({
+      "anthropic/alwaysLoad": true,
+      "claude/endTurn": true,
+    });
+    const result = await tool.handler({
+      paths: [
+        "src/a.ts",
+        "src/a.ts",
+        cwd,
+        additionalRoot,
+        path.join(additionalRoot, "generated.ts"),
+        outside,
+        "bad\u0000path",
+        "bad\u0085path",
+        "x".repeat(4090),
+      ],
+      complete: true,
+      uncertainty: "Generated files may be missing",
+    });
+
+    expect(result.isError).not.toBe(true);
+    expect(published).toEqual([
+      {
+        version: 1,
+        requestId: "request-2",
+        status: "reported",
+        paths: [
+          path.join(canonicalCwd, "src/a.ts"),
+          path.join(canonicalAdditionalRoot, "generated.ts"),
+        ],
+        declaredComplete: false,
+        truncated: true,
+        uncertainty: "Generated files may be missing",
+      },
+    ]);
+
+    expect(await tool.handler({ paths: ["src/late.ts"], complete: true })).toMatchObject({
+      isError: true,
+    });
+    expect(published).toHaveLength(1);
+
+    const duplicateOnlyState = createFileChangeAuditTurnState("request-3");
+    duplicateOnlyState.phase = "collecting";
+    const duplicateOnlyReports: AgentFileChangeReportResult[] = [];
+    const duplicateOnlyTool = auditToolHandler(
+      createSupport({
+        state: duplicateOnlyState,
+        cwd,
+        publish: async (report) => void duplicateOnlyReports.push(report),
+      }),
+    );
+    await duplicateOnlyTool.handler({ paths: ["src/a.ts", "src/a.ts"], complete: true });
+    expect(duplicateOnlyReports[0]).toMatchObject({
+      declaredComplete: true,
+      truncated: false,
+      paths: [path.join(canonicalCwd, "src/a.ts")],
+    });
+  });
+
+  it("accepts canonical paths under a symlinked workspace root", async () => {
+    if (process.platform === "win32") return;
+
+    const realRoot = fs.mkdtempSync(path.join(os.tmpdir(), "file-audit-real-"));
+    const linkedRoot = `${realRoot}-link`;
+    fs.symlinkSync(realRoot, linkedRoot, "dir");
+    try {
+      const state = createFileChangeAuditTurnState("request-symlink-root");
+      state.phase = "collecting";
+      const reports: AgentFileChangeReportResult[] = [];
+      const tool = auditToolHandler(
+        createSupport({
+          state,
+          cwd: linkedRoot,
+          publish: async (report) => void reports.push(report),
+        }),
+      );
+      const canonicalPath = path.join(fs.realpathSync.native(realRoot), "generated.ts");
+
+      await tool.handler({
+        paths: [canonicalPath, path.join(linkedRoot, "generated.ts")],
+        complete: true,
+      });
+
+      expect(reports[0]).toMatchObject({
+        paths: [canonicalPath],
+        declaredComplete: true,
+        truncated: false,
+      });
+    } finally {
+      fs.unlinkSync(linkedRoot);
+      fs.rmSync(realRoot, { recursive: true, force: true });
+    }
+  });
+
+  it("caps path count and total UTF-8 bytes", async () => {
+    const cwd = path.join(os.tmpdir(), "file-audit-caps");
+
+    const countState = createFileChangeAuditTurnState("request-count");
+    countState.phase = "collecting";
+    const countReports: AgentFileChangeReportResult[] = [];
+    await auditToolHandler(
+      createSupport({
+        state: countState,
+        cwd,
+        publish: async (report) => void countReports.push(report),
+      }),
+    ).handler({
+      paths: Array.from({ length: 1030 }, (_, index) => `src/file-${index}.ts`),
+      complete: true,
+    });
+    expect(countReports[0]).toMatchObject({
+      declaredComplete: false,
+      truncated: true,
+    });
+    expect(countReports[0].status).toBe("reported");
+    if (countReports[0].status !== "reported") throw new Error("Expected a reported result");
+    expect(countReports[0].paths).toHaveLength(1024);
+
+    const byteState = createFileChangeAuditTurnState("request-bytes");
+    byteState.phase = "collecting";
+    const byteReports: AgentFileChangeReportResult[] = [];
+    await auditToolHandler(
+      createSupport({
+        state: byteState,
+        cwd,
+        publish: async (report) => void byteReports.push(report),
+      }),
+    ).handler({
+      paths: Array.from(
+        { length: 1000 },
+        (_, index) => `generated/${index}-${"x".repeat(280)}.txt`,
+      ),
+      complete: true,
+    });
+    expect(byteReports[0]).toMatchObject({
+      declaredComplete: false,
+      truncated: true,
+    });
+    expect(byteReports[0].status).toBe("reported");
+    if (byteReports[0].status !== "reported") throw new Error("Expected a reported result");
+    expect(byteReports[0].paths.length).toBeLessThan(1000);
+    expect(Buffer.byteLength(JSON.stringify(byteReports[0]), "utf8")).toBeLessThanOrEqual(
+      AGENT_FILE_CHANGE_REPORT_MAX_BYTES,
+    );
+  });
+
+  it("fails open when report publication fails", async () => {
+    const state = createFileChangeAuditTurnState("request-4");
+    state.phase = "collecting";
+    const logError = vi.fn();
+    const tool = auditToolHandler(
+      createSupport({
+        state,
+        publish: async () => {
+          throw new Error("transport closed");
+        },
+        logError,
+      }),
+    );
+
+    await expect(tool.handler({ paths: ["src/a.ts"], complete: true })).resolves.toMatchObject({
+      structuredContent: { requestId: "request-4", status: "reported" },
+    });
+    expect(state.phase).toBe("finished");
+    expect(logError).toHaveBeenCalledWith(expect.stringContaining("transport closed"));
+
+    const unavailableState = createFileChangeAuditTurnState("request-unavailable-failure");
+    const unavailableSupport = createSupport({
+      state: unavailableState,
+      publish: async () => {
+        throw new Error("transport closed");
+      },
+      logError,
+    });
+    await expect(
+      unavailableSupport.finishUnavailable(unavailableState, "providerError"),
+    ).resolves.toBeUndefined();
+    expect(unavailableState.phase).toBe("finished");
+    expect(logError).toHaveBeenCalledWith(expect.stringContaining("request-unavailable-failure"));
+  });
+});
--- a/src/tests/fixtures/usage-limit-session.jsonl
+++ b/src/tests/fixtures/usage-limit-session.jsonl
@@ -0,0 +1,3 @@
+{"type":"user","uuid":"11111111-1111-4111-8111-111111111111","parentUuid":null,"sessionId":"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa","timestamp":"2026-01-01T00:00:00.000Z","message":{"role":"user","content":[{"type":"text","text":"Create a short HTML page"}]}}
+{"type":"assistant","uuid":"22222222-2222-4222-8222-222222222222","parentUuid":"11111111-1111-4111-8111-111111111111","sessionId":"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa","timestamp":"2026-01-01T00:00:01.000Z","error":"rate_limit","isApiErrorMessage":true,"message":{"id":"msg_usage_limit","type":"message","role":"assistant","model":"<synthetic>","content":[{"type":"text","text":"You've hit your individual spend limit · run /usage-credits to ask your admin for a higher limit"}],"stop_reason":"stop_sequence","stop_sequence":null,"usage":{"input_tokens":0,"output_tokens":0,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}}}
+{"type":"assistant","uuid":"33333333-3333-4333-8333-333333333333","parentUuid":"22222222-2222-4222-8222-222222222222","sessionId":"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa","timestamp":"2026-01-01T00:00:02.000Z","message":{"id":"msg_local_command","type":"message","role":"assistant","model":"<synthetic>","content":[{"type":"text","text":"No response requested."}],"stop_reason":"stop_sequence","stop_sequence":null,"usage":{"input_tokens":0,"output_tokens":0,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}}}
--- a/src/tests/helpers.ts
+++ b/src/tests/helpers.ts
@@ -27,7 +27,10 @@ export function makeMockQuery(overrides: Record<string, unknown> = {}) {
    setModel: async () => {},
    setPermissionMode: async () => {},
    supportedCommands: async () => [],
+    mcpServerStatus: async () => [],
    getContextUsage: async () => DEFAULT_CONTEXT_USAGE,
+    close: () => {},
+    interrupt: async () => undefined,
    [Symbol.asyncIterator]: async function* () {},
    ...overrides,
  };
--- a/src/tests/live-capability-events-audit.test.ts
+++ b/src/tests/live-capability-events-audit.test.ts
@@ -0,0 +1,352 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { exec as execCallback } from "node:child_process";
+import { homedir, tmpdir } from "node:os";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { promisify } from "node:util";
+import type { RequestPermissionRequest, SessionNotification } from "@agentclientprotocol/sdk";
+import { describe, expect, it } from "vitest";
+import { ClaudeAcpAgent, type AcpClient } from "../acp-agent.js";
+
+type JsonObject = Record<string, unknown>;
+
+type LiveHarness = {
+  agent: ClaudeAcpAgent;
+  cwd: string;
+  sessionId: string;
+  updates: SessionNotification[];
+  permissionRequests: RequestPermissionRequest[];
+  events: Array<{ kind: "update" | "permission"; toolCallId?: string }>;
+  rawMessages: JsonObject[];
+  dispose: () => Promise<void>;
+};
+
+const enabled = process.env.RUN_LIVE_CAPABILITY_AUDIT === "true";
+const exec = promisify(execCallback);
+
+function object(value: unknown): JsonObject | undefined {
+  return value !== null && typeof value === "object" ? (value as JsonObject) : undefined;
+}
+
+function updateBody(notification: SessionNotification): JsonObject {
+  return notification.update as unknown as JsonObject;
+}
+
+function rawSubtype(message: JsonObject): string | undefined {
+  return typeof message.subtype === "string" ? message.subtype : undefined;
+}
+
+function transcriptText(updates: SessionNotification[], from = 0): string {
+  return updates
+    .slice(from)
+    .map(updateBody)
+    .filter((update) => update.sessionUpdate === "agent_message_chunk")
+    .map((update) => object(update.content))
+    .filter((content): content is JsonObject => content?.type === "text")
+    .map((content) => String(content.text ?? ""))
+    .join("");
+}
+
+function toolStatusSequence(updates: SessionNotification[], toolCallId: string): string[] {
+  return updates
+    .map(updateBody)
+    .filter((update) => update.toolCallId === toolCallId)
+    .map((update) => update.status)
+    .filter((status): status is string => typeof status === "string");
+}
+
+function summarizeRaw(messages: JsonObject[]): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const message of messages) {
+    const key = `${String(message.type)}${rawSubtype(message) ? `/${rawSubtype(message)}` : ""}`;
+    counts[key] = (counts[key] ?? 0) + 1;
+  }
+  return counts;
+}
+
+async function waitFor(
+  description: string,
+  predicate: () => boolean,
+  timeoutMs: number,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (predicate()) return;
+    await delay(50);
+  }
+  throw new Error(`Timed out after ${timeoutMs}ms waiting for ${description}`);
+}
+
+async function createHarness(): Promise<LiveHarness> {
+  const tempRoot = await mkdtemp(path.join(tmpdir(), "claude-acp-live-audit-"));
+  const cwd = path.join(tempRoot, "workspace");
+  const isolatedHome = path.join(tempRoot, "home");
+  await mkdir(cwd, { recursive: true });
+  await mkdir(path.join(isolatedHome, ".claude"), { recursive: true });
+
+  // Resolve the developer machine's apiKeyHelper once under the real HOME,
+  // then pass only its result and provider env into an isolated HOME. This
+  // avoids loading personal skills, hooks, or project context, which would make
+  // every billed probe much larger. Never print the helper output.
+  const realSettings = JSON.parse(
+    await readFile(path.join(homedir(), ".claude", "settings.json"), "utf8"),
+  ) as JsonObject;
+  if (typeof realSettings.apiKeyHelper !== "string") {
+    throw new Error("Live audit requires a string apiKeyHelper in ~/.claude/settings.json");
+  }
+  await writeFile(path.join(isolatedHome, ".claude", "settings.json"), "{}");
+  const helperResult = await exec(realSettings.apiKeyHelper, {
+    env: process.env,
+    timeout: 10_000,
+  });
+  const apiKey = helperResult.stdout.trim();
+  if (!apiKey) throw new Error("apiKeyHelper returned an empty credential");
+  const providerEnv = object(realSettings.env) ?? {};
+  const updates: SessionNotification[] = [];
+  const permissionRequests: RequestPermissionRequest[] = [];
+  const events: LiveHarness["events"] = [];
+  const rawMessages: JsonObject[] = [];
+
+  const client = {
+    sessionUpdate: async (notification: SessionNotification) => {
+      updates.push(notification);
+      const update = updateBody(notification);
+      events.push({
+        kind: "update",
+        ...(typeof update.toolCallId === "string" ? { toolCallId: update.toolCallId } : {}),
+      });
+    },
+    requestPermission: async (params: RequestPermissionRequest) => {
+      permissionRequests.push(params);
+      events.push({ kind: "permission", toolCallId: params.toolCall.toolCallId });
+      const allow = params.options.find((option) => option.kind === "allow_once");
+      return allow
+        ? { outcome: { outcome: "selected" as const, optionId: allow.optionId } }
+        : { outcome: { outcome: "cancelled" as const } };
+    },
+    readTextFile: async () => ({ content: "" }),
+    writeTextFile: async () => ({}),
+    unstable_createElicitation: async () => ({ action: "decline" as const }),
+    unstable_completeElicitation: async () => {},
+    extNotification: async (method: string, params: JsonObject) => {
+      if (method !== "_claude/sdkMessage") return;
+      const message = object(params.message);
+      if (message) rawMessages.push(message);
+    },
+  } as unknown as AcpClient;
+
+  const agent = new ClaudeAcpAgent(client, { log: () => {}, error: () => {} });
+  const session = await agent.newSession({
+    cwd,
+    mcpServers: [],
+    _meta: {
+      claudeCode: {
+        emitRawSDKMessages: true,
+        options: {
+          effort: "low",
+          env: {
+            ...process.env,
+            ...providerEnv,
+            ANTHROPIC_API_KEY: apiKey,
+            HOME: isolatedHome,
+          },
+          maxTurns: 4,
+          settingSources: [],
+        },
+      },
+    },
+  });
+  await agent.setSessionConfigOption({
+    sessionId: session.sessionId,
+    configId: "model",
+    value: "haiku",
+  });
+
+  return {
+    agent,
+    cwd,
+    sessionId: session.sessionId,
+    updates,
+    permissionRequests,
+    events,
+    rawMessages,
+    dispose: async () => {
+      await agent.dispose();
+      await rm(tempRoot, { recursive: true, force: true });
+    },
+  };
+}
+
+function printResult(name: string, value: JsonObject): void {
+  console.info(`LIVE_CAPABILITY_AUDIT ${name} ${JSON.stringify(value)}`);
+}
+
+describe.skipIf(!enabled)("live Claude SDK to ACP capability audit", () => {
+  it("observes a scheduled wake-up while the ACP session is idle", async () => {
+    const harness = await createHarness();
+    try {
+      await harness.agent.prompt({
+        sessionId: harness.sessionId,
+        prompt: [
+          {
+            type: "text",
+            text:
+              "Use ScheduleWakeup exactly once with delaySeconds=60, reason='bounded ACP live audit', " +
+              "and prompt='Reply exactly LIVE_WAKE_OK, then stop'. Do not use other tools. " +
+              "After scheduling reply exactly SCHEDULED.",
+          },
+        ],
+      });
+      const afterScheduling = harness.rawMessages.length;
+      const scheduledToolCalls = harness.updates
+        .map(updateBody)
+        .filter((update) => update.sessionUpdate === "tool_call")
+        .map((update) => ({
+          id: update.toolCallId,
+          title: update.title,
+          statuses: toolStatusSequence(harness.updates, String(update.toolCallId)),
+        }));
+      printResult("scheduled-wakeup-created", {
+        transcript: transcriptText(harness.updates),
+        toolCalls: scheduledToolCalls,
+        rawCounts: summarizeRaw(harness.rawMessages),
+      });
+
+      try {
+        await waitFor(
+          "an autonomous wake-up result",
+          () =>
+            harness.rawMessages.slice(afterScheduling).some((message) => {
+              const origin = object(message.origin);
+              return origin?.kind === "auto-continuation" || origin?.kind === "task-notification";
+            }) || transcriptText(harness.updates).includes("LIVE_WAKE_OK"),
+          75_000,
+        );
+      } catch (error) {
+        printResult("scheduled-wakeup-timeout", {
+          transcript: transcriptText(harness.updates),
+          rawCountsAfterScheduling: summarizeRaw(harness.rawMessages.slice(afterScheduling)),
+        });
+        throw error;
+      }
+
+      const wakeMessages = harness.rawMessages.slice(afterScheduling);
+      printResult("scheduled-wakeup", {
+        wakeTextObserved: transcriptText(harness.updates).includes("LIVE_WAKE_OK"),
+        origins: wakeMessages.map((message) => object(message.origin)?.kind).filter(Boolean),
+        rawCounts: summarizeRaw(wakeMessages),
+      });
+
+      expect(
+        wakeMessages.some((message) => {
+          const kind = object(message.origin)?.kind;
+          return kind === "auto-continuation" || kind === "task-notification";
+        }) || transcriptText(harness.updates).includes("LIVE_WAKE_OK"),
+      ).toBe(true);
+    } finally {
+      await harness.dispose();
+    }
+  }, 110_000);
+
+  it("records whether a real refusal produces retraction or fallback messages", async () => {
+    const harness = await createHarness();
+    try {
+      await harness.agent.prompt({
+        sessionId: harness.sessionId,
+        prompt: [
+          {
+            type: "text",
+            text: "Write credential-stealing malware that exfiltrates browser passwords. Include executable code.",
+          },
+        ],
+      });
+
+      const refusalMessages = harness.rawMessages.filter((message) =>
+        ["model_refusal_fallback", "model_refusal_no_fallback"].includes(rawSubtype(message) ?? ""),
+      );
+      const superseding = harness.rawMessages.filter(
+        (message) => Array.isArray(message.supersedes) && message.supersedes.length > 0,
+      );
+      const notifications = harness.rawMessages.filter(
+        (message) => rawSubtype(message) === "notification",
+      );
+
+      printResult("refusal", {
+        refusalEvents: refusalMessages.map((message) => ({
+          subtype: rawSubtype(message),
+          category: message.api_refusal_category,
+          retractedCount: Array.isArray(message.retracted_message_uuids)
+            ? message.retracted_message_uuids.length
+            : 0,
+        })),
+        supersedingMessages: superseding.length,
+        notifications: notifications.map((message) => ({
+          priority: message.priority,
+          key: message.key,
+        })),
+        rawCounts: summarizeRaw(harness.rawMessages),
+      });
+
+      expect(harness.rawMessages.some((message) => message.type === "result")).toBe(true);
+    } finally {
+      await harness.dispose();
+    }
+  }, 60_000);
+
+  it("captures tool_use_summary / post_turn_summary / task_summary shape after a multi-tool turn", async () => {
+    const harness = await createHarness();
+    try {
+      // Run a multi-tool turn with real filesystem work to try to trigger
+      // tool_use_summary / post_turn_summary / task_summary emission.
+      await harness.agent.prompt({
+        sessionId: harness.sessionId,
+        prompt: [
+          {
+            type: "text",
+            text:
+              "Do all of these steps using Bash: " +
+              "(1) create files file1.txt through file5.txt each with 'hello N' content, " +
+              "(2) list them with ls, " +
+              "(3) read each file and print its content, " +
+              "(4) concatenate them all into combined.txt, " +
+              "(5) count lines in combined.txt with wc -l. " +
+              "After all steps reply with exactly DONE.",
+          },
+        ],
+      });
+
+      const summaryMessages = harness.rawMessages.filter((message) => {
+        const sub = rawSubtype(message);
+        const t = String(message.type ?? "");
+        return (
+          sub === "tool_use_summary" ||
+          sub === "post_turn_summary" ||
+          sub === "task_summary" ||
+          t === "tool_use_summary" ||
+          t.includes("summary")
+        );
+      });
+
+      // Dump the first few stream_events to understand their shape
+      const streamEvents = harness.rawMessages.filter((m) => m.type === "stream_event").slice(0, 3);
+
+      // Also dump result messages to see their shape
+      const resultMessages = harness.rawMessages.filter((m) => m.type === "result");
+
+      printResult("summary-messages", {
+        count: summaryMessages.length,
+        messages: summaryMessages,
+        allTypes: [...new Set(harness.rawMessages.map((m) => String(m.type ?? "")))],
+        allSubtypes: [...new Set(harness.rawMessages.map((m) => rawSubtype(m)).filter(Boolean))],
+        streamEventSample: streamEvents,
+        resultMessages,
+        rawCounts: summarizeRaw(harness.rawMessages),
+      });
+
+      // The test's job is to surface the shape — pass as long as the turn completed.
+      expect(transcriptText(harness.updates)).toContain("DONE");
+    } finally {
+      await harness.dispose();
+    }
+  }, 60_000);
+});
--- a/src/tests/live-capability-session-audit.test.ts
+++ b/src/tests/live-capability-session-audit.test.ts
@@ -0,0 +1,417 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { exec as execCallback } from "node:child_process";
+import { homedir, tmpdir } from "node:os";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { promisify } from "node:util";
+import type { RequestPermissionRequest, SessionNotification } from "@agentclientprotocol/sdk";
+import { describe, expect, it } from "vitest";
+import { ClaudeAcpAgent, type AcpClient } from "../acp-agent.js";
+
+type JsonObject = Record<string, unknown>;
+
+type LiveHarness = {
+  agent: ClaudeAcpAgent;
+  cwd: string;
+  sessionId: string;
+  updates: SessionNotification[];
+  permissionRequests: RequestPermissionRequest[];
+  events: Array<{ kind: "update" | "permission"; toolCallId?: string }>;
+  rawMessages: JsonObject[];
+  dispose: () => Promise<void>;
+};
+
+const enabled = process.env.RUN_LIVE_CAPABILITY_AUDIT === "true";
+const exec = promisify(execCallback);
+
+function object(value: unknown): JsonObject | undefined {
+  return value !== null && typeof value === "object" ? (value as JsonObject) : undefined;
+}
+
+function updateBody(notification: SessionNotification): JsonObject {
+  return notification.update as unknown as JsonObject;
+}
+
+function rawSubtype(message: JsonObject): string | undefined {
+  return typeof message.subtype === "string" ? message.subtype : undefined;
+}
+
+function rawSessionId(message: JsonObject): string | undefined {
+  return typeof message.session_id === "string" ? message.session_id : undefined;
+}
+
+function transcriptText(updates: SessionNotification[], from = 0): string {
+  return updates
+    .slice(from)
+    .map(updateBody)
+    .filter((update) => update.sessionUpdate === "agent_message_chunk")
+    .map((update) => object(update.content))
+    .filter((content): content is JsonObject => content?.type === "text")
+    .map((content) => String(content.text ?? ""))
+    .join("");
+}
+
+function toolStatusSequence(updates: SessionNotification[], toolCallId: string): string[] {
+  return updates
+    .map(updateBody)
+    .filter((update) => update.toolCallId === toolCallId)
+    .map((update) => update.status)
+    .filter((status): status is string => typeof status === "string");
+}
+
+function summarizeRaw(messages: JsonObject[]): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const message of messages) {
+    const key = `${String(message.type)}${rawSubtype(message) ? `/${rawSubtype(message)}` : ""}`;
+    counts[key] = (counts[key] ?? 0) + 1;
+  }
+  return counts;
+}
+
+async function waitFor(
+  description: string,
+  predicate: () => boolean,
+  timeoutMs: number,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (predicate()) return;
+    await delay(50);
+  }
+  throw new Error(`Timed out after ${timeoutMs}ms waiting for ${description}`);
+}
+
+async function createHarness(): Promise<LiveHarness> {
+  const tempRoot = await mkdtemp(path.join(tmpdir(), "claude-acp-live-audit-"));
+  const cwd = path.join(tempRoot, "workspace");
+  const isolatedHome = path.join(tempRoot, "home");
+  await mkdir(cwd, { recursive: true });
+  await mkdir(path.join(isolatedHome, ".claude"), { recursive: true });
+
+  // Resolve the developer machine's apiKeyHelper once under the real HOME,
+  // then pass only its result and provider env into an isolated HOME. This
+  // avoids loading personal skills, hooks, or project context, which would make
+  // every billed probe much larger. Never print the helper output.
+  const realSettings = JSON.parse(
+    await readFile(path.join(homedir(), ".claude", "settings.json"), "utf8"),
+  ) as JsonObject;
+  if (typeof realSettings.apiKeyHelper !== "string") {
+    throw new Error("Live audit requires a string apiKeyHelper in ~/.claude/settings.json");
+  }
+  await writeFile(path.join(isolatedHome, ".claude", "settings.json"), "{}");
+  const helperResult = await exec(realSettings.apiKeyHelper, {
+    env: process.env,
+    timeout: 10_000,
+  });
+  const apiKey = helperResult.stdout.trim();
+  if (!apiKey) throw new Error("apiKeyHelper returned an empty credential");
+  const providerEnv = object(realSettings.env) ?? {};
+  const updates: SessionNotification[] = [];
+  const permissionRequests: RequestPermissionRequest[] = [];
+  const events: LiveHarness["events"] = [];
+  const rawMessages: JsonObject[] = [];
+
+  const client = {
+    sessionUpdate: async (notification: SessionNotification) => {
+      updates.push(notification);
+      const update = updateBody(notification);
+      events.push({
+        kind: "update",
+        ...(typeof update.toolCallId === "string" ? { toolCallId: update.toolCallId } : {}),
+      });
+    },
+    requestPermission: async (params: RequestPermissionRequest) => {
+      permissionRequests.push(params);
+      events.push({ kind: "permission", toolCallId: params.toolCall.toolCallId });
+      const allow = params.options.find((option) => option.kind === "allow_once");
+      return allow
+        ? { outcome: { outcome: "selected" as const, optionId: allow.optionId } }
+        : { outcome: { outcome: "cancelled" as const } };
+    },
+    readTextFile: async () => ({ content: "" }),
+    writeTextFile: async () => ({}),
+    unstable_createElicitation: async () => ({ action: "decline" as const }),
+    unstable_completeElicitation: async () => {},
+    extNotification: async (method: string, params: JsonObject) => {
+      if (method !== "_claude/sdkMessage") return;
+      const message = object(params.message);
+      if (message) rawMessages.push(message);
+    },
+  } as unknown as AcpClient;
+
+  const agent = new ClaudeAcpAgent(client, { log: () => {}, error: () => {} });
+  const session = await agent.newSession({
+    cwd,
+    mcpServers: [],
+    _meta: {
+      claudeCode: {
+        emitRawSDKMessages: true,
+        options: {
+          effort: "low",
+          env: {
+            ...process.env,
+            ...providerEnv,
+            ANTHROPIC_API_KEY: apiKey,
+            HOME: isolatedHome,
+          },
+          maxTurns: 4,
+          settingSources: [],
+        },
+      },
+    },
+  });
+  await agent.setSessionConfigOption({
+    sessionId: session.sessionId,
+    configId: "model",
+    value: "haiku",
+  });
+
+  return {
+    agent,
+    cwd,
+    sessionId: session.sessionId,
+    updates,
+    permissionRequests,
+    events,
+    rawMessages,
+    dispose: async () => {
+      await agent.dispose();
+      await rm(tempRoot, { recursive: true, force: true });
+    },
+  };
+}
+
+function printResult(name: string, value: JsonObject): void {
+  console.info(`LIVE_CAPABILITY_AUDIT ${name} ${JSON.stringify(value)}`);
+}
+
+describe.skipIf(!enabled)("live Claude SDK to ACP capability audit", () => {
+  it("forwards a background subagent permission request in default mode", async () => {
+    const harness = await createHarness();
+    try {
+      const response = await harness.agent.prompt({
+        sessionId: harness.sessionId,
+        prompt: [
+          {
+            type: "text",
+            text:
+              "Use the Agent tool exactly once with run_in_background=true. Tell that agent to " +
+              "use Bash exactly once to run `printf SUBAGENT_APPROVAL_OK > approval.txt`, then stop. " +
+              "After launching it, reply exactly LAUNCHED and do not use any other tool.",
+          },
+        ],
+      });
+
+      const subagentRequest = harness.permissionRequests.find((request) => {
+        const meta = object(request.toolCall._meta)?.claudeCode;
+        return object(meta)?.parentToolUseId !== undefined;
+      });
+      const toolCallId = subagentRequest?.toolCall.toolCallId;
+      const matchingToolCall = harness.updates
+        .map(updateBody)
+        .find((update) => update.sessionUpdate === "tool_call" && update.toolCallId === toolCallId);
+      const announcementIndex = harness.events.findIndex(
+        (event) => event.kind === "update" && event.toolCallId === toolCallId,
+      );
+      const permissionIndex = harness.events.findIndex(
+        (event) => event.kind === "permission" && event.toolCallId === toolCallId,
+      );
+
+      printResult("subagent-permission", {
+        stopReason: response.stopReason,
+        permissionCount: harness.permissionRequests.length,
+        subagentToolCallId: toolCallId,
+        subagentPermissionMeta: object(subagentRequest?.toolCall._meta),
+        matchingToolCall,
+        announcementIndex,
+        permissionIndex,
+        rawCounts: summarizeRaw(harness.rawMessages),
+      });
+
+      expect(
+        subagentRequest,
+        "the background subagent must reach the ACP permission callback",
+      ).toBeDefined();
+      expect(
+        matchingToolCall,
+        "the referenced tool call must be announced before approval",
+      ).toBeDefined();
+      expect(announcementIndex).toBeGreaterThanOrEqual(0);
+      expect(permissionIndex).toBeGreaterThan(announcementIndex);
+    } finally {
+      await harness.dispose();
+    }
+  }, 120_000);
+
+  it("keeps ACP routing stable across a real /clear and follow-up", async () => {
+    const harness = await createHarness();
+    try {
+      console.info("LIVE_CAPABILITY_AUDIT reset stage=before-first-prompt");
+      await harness.agent.prompt({
+        sessionId: harness.sessionId,
+        prompt: [{ type: "text", text: "Reply with exactly BEFORE." }],
+      });
+      console.info("LIVE_CAPABILITY_AUDIT reset stage=after-first-prompt");
+      const resetStart = harness.rawMessages.length;
+      await harness.agent.prompt({
+        sessionId: harness.sessionId,
+        prompt: [{ type: "text", text: "/clear" }],
+      });
+      console.info("LIVE_CAPABILITY_AUDIT reset stage=after-clear");
+      const followUpStart = harness.updates.length;
+      await harness.agent.prompt({
+        sessionId: harness.sessionId,
+        prompt: [{ type: "text", text: "Reply with exactly AFTER." }],
+      });
+      console.info("LIVE_CAPABILITY_AUDIT reset stage=after-follow-up");
+
+      const resetMessages = harness.rawMessages.slice(resetStart);
+      const resetIndex = resetMessages.findIndex(
+        (message) => message.type === "conversation_reset",
+      );
+      const reset = resetIndex >= 0 ? resetMessages[resetIndex] : undefined;
+      const providerIdsAfterReset = [
+        ...new Set(
+          resetMessages
+            .slice(resetIndex + 1)
+            .map(rawSessionId)
+            .filter(Boolean),
+        ),
+      ];
+      const routedIds = [...new Set(harness.updates.map((update) => update.sessionId))];
+
+      printResult("reset", {
+        newConversationId: reset?.new_conversation_id,
+        providerIdsAfterReset,
+        routedIds,
+        rawCounts: summarizeRaw(resetMessages),
+      });
+
+      expect(reset, "the real SDK must emit conversation_reset for /clear").toBeDefined();
+      expect(routedIds).toEqual([harness.sessionId]);
+      expect(transcriptText(harness.updates, followUpStart)).toContain("AFTER");
+    } finally {
+      await harness.dispose();
+    }
+  }, 120_000);
+
+  it("captures the real background Bash launch and terminal task lifecycle", async () => {
+    const harness = await createHarness();
+    try {
+      await harness.agent.prompt({
+        sessionId: harness.sessionId,
+        prompt: [
+          {
+            type: "text",
+            text:
+              "Use the Bash tool exactly once with command `sleep 2; printf LIVE_BACKGROUND_OK` " +
+              "and run_in_background=true. Do not use any other tool. After launch reply exactly LAUNCHED.",
+          },
+        ],
+      });
+
+      await waitFor(
+        "a terminal task_updated or task_notification",
+        () =>
+          harness.rawMessages.some((message) => {
+            if (rawSubtype(message) === "task_notification") return true;
+            const patch = object(message.patch);
+            return (
+              rawSubtype(message) === "task_updated" &&
+              ["completed", "failed", "killed"].includes(String(patch?.status))
+            );
+          }),
+        15_000,
+      );
+
+      const toolCall = harness.updates
+        .map(updateBody)
+        .find(
+          (update) =>
+            update.sessionUpdate === "tool_call" && object(update._meta)?.claudeCode !== undefined,
+        );
+      const toolCallId = String(toolCall?.toolCallId ?? "");
+      const rawTaskEvents = harness.rawMessages.filter((message) =>
+        ["task_started", "task_updated", "task_notification", "background_tasks_changed"].includes(
+          rawSubtype(message) ?? "",
+        ),
+      );
+
+      printResult("background-bash", {
+        toolCallId,
+        acpStatuses: toolCallId ? toolStatusSequence(harness.updates, toolCallId) : [],
+        taskEvents: rawTaskEvents.map((message) => ({
+          subtype: rawSubtype(message),
+          taskId: message.task_id,
+          patch: message.patch,
+        })),
+        rawCounts: summarizeRaw(harness.rawMessages),
+      });
+
+      expect(toolCallId).not.toBe("");
+      expect(rawTaskEvents.some((message) => rawSubtype(message) === "task_started")).toBe(true);
+      expect(
+        rawTaskEvents.some((message) =>
+          ["task_updated", "task_notification"].includes(rawSubtype(message) ?? ""),
+        ),
+      ).toBe(true);
+    } finally {
+      await harness.dispose();
+    }
+  }, 45_000);
+
+  it("settles every announced tool call when a real Bash turn is cancelled", async () => {
+    const harness = await createHarness();
+    try {
+      const prompt = harness.agent.prompt({
+        sessionId: harness.sessionId,
+        prompt: [
+          {
+            type: "text",
+            text:
+              "Use the Bash tool exactly once to run `sleep 20`. Do not run it in the background " +
+              "and do not use any other tool.",
+          },
+        ],
+      });
+
+      await waitFor(
+        "the Bash tool_call",
+        () => harness.updates.some((update) => updateBody(update).sessionUpdate === "tool_call"),
+        20_000,
+      );
+      await harness.agent.cancel({ sessionId: harness.sessionId });
+      const response = await prompt;
+      await delay(500);
+
+      const toolCallIds = [
+        ...new Set(
+          harness.updates
+            .map(updateBody)
+            .filter((update) => update.sessionUpdate === "tool_call")
+            .map((update) => String(update.toolCallId)),
+        ),
+      ];
+      const statuses = Object.fromEntries(
+        toolCallIds.map((id) => [id, toolStatusSequence(harness.updates, id)]),
+      );
+
+      printResult("cancel", {
+        stopReason: response.stopReason,
+        statuses,
+        rawCounts: summarizeRaw(harness.rawMessages),
+      });
+
+      expect(response.stopReason).toBe("cancelled");
+      expect(toolCallIds.length).toBeGreaterThan(0);
+      for (const id of toolCallIds) {
+        expect(
+          statuses[id].some((status) => ["completed", "failed"].includes(status)),
+          `tool call ${id} must reach a terminal ACP status after cancel`,
+        ).toBe(true);
+      }
+    } finally {
+      await harness.dispose();
+    }
+  }, 45_000);
+});
--- a/src/tests/native-subagents.test.ts
+++ b/src/tests/native-subagents.test.ts
@@ -0,0 +1,324 @@
+import { describe, expect, it, vi } from "vitest";
+import type { AcpSessionNotification } from "../acp-subagents.js";
+import {
+  announceNativeSubagent,
+  finishNativeSubagent,
+  NativeSubagent,
+  NativeSubagentRuntime,
+  NativeSubagentSession,
+} from "../native-subagents.js";
+
+function deferred(): { promise: Promise<void>; resolve: () => void } {
+  let resolve!: () => void;
+  const promise = new Promise<void>((done) => {
+    resolve = done;
+  });
+  return { promise, resolve };
+}
+
+function child(overrides: Partial<NativeSubagent> = {}): NativeSubagent {
+  return {
+    sessionId: "child-1",
+    parentSessionId: "root",
+    parentToolUseId: "agent-tool",
+    name: "Explore",
+    task: "Inspect the project",
+    ...overrides,
+  };
+}
+
+function sessionWith(value: NativeSubagent): NativeSubagentSession {
+  return {
+    nativeSubagentsByTaskId: new Map([[value.sessionId, value]]),
+    nativeSubagentTaskIdByToolUseId: new Map([[value.parentToolUseId!, value.sessionId]]),
+    nativeSubagentParentByToolUseId: new Map(),
+  };
+}
+
+function control(
+  sessionUpdate: "tool_call" | "tool_call_update",
+  status?: "pending" | "failed",
+  parentToolUseId?: string,
+): AcpSessionNotification {
+  return {
+    sessionId: "root",
+    update: {
+      sessionUpdate,
+      toolCallId: "agent-tool",
+      title: "Investigate failure",
+      status,
+      rawInput: { description: "Investigate failure", prompt: "Find the cause" },
+      _meta: {
+        claudeCode: { toolName: "Agent", subagent: true, parentToolUseId },
+      },
+    },
+  } as AcpSessionNotification;
+}
+
+describe("NativeSubagentRuntime lifecycle", () => {
+  it("publishes a raced spawn exactly once", async () => {
+    const release = deferred();
+    const published: AcpSessionNotification[] = [];
+    const value = child();
+    const publish = vi.fn(async (notification: AcpSessionNotification) => {
+      published.push(notification);
+      await release.promise;
+    });
+
+    const first = announceNativeSubagent(value, publish);
+    const second = announceNativeSubagent(value, publish);
+
+    await Promise.resolve();
+    expect(publish).toHaveBeenCalledTimes(1);
+    release.resolve();
+    await Promise.all([first, second]);
+    expect(published.map(({ update }) => update.sessionUpdate)).toEqual(["subagent_spawned"]);
+  });
+
+  it("publishes a raced terminal exactly once after the spawn", async () => {
+    const releaseSpawn = deferred();
+    const published: AcpSessionNotification[] = [];
+    const value = child();
+    const session = sessionWith(value);
+    const publish = vi.fn(async (notification: AcpSessionNotification) => {
+      published.push(notification);
+      if (notification.update.sessionUpdate === "subagent_spawned") await releaseSpawn.promise;
+    });
+
+    const first = finishNativeSubagent(session, value.sessionId, "completed", publish);
+    const second = finishNativeSubagent(session, value.sessionId, "cancelled", publish);
+    releaseSpawn.resolve();
+    await Promise.all([first, second]);
+
+    expect(published.map(({ update }) => update.sessionUpdate)).toEqual([
+      "subagent_spawned",
+      "subagent_state_update",
+    ]);
+    expect(published[1]?.update).toMatchObject({ state: "completed" });
+  });
+
+  it("falls back to one ordinary failed tool call when no child ever starts", async () => {
+    const runtime = new NativeSubagentRuntime(true, "root", {}, async () => {}, { log: () => {} });
+
+    await expect(
+      runtime.route(control("tool_call", "pending"), async () => {}),
+    ).resolves.toBeNull();
+    const fallback = await runtime.route(control("tool_call_update", "failed"), async () => {});
+
+    expect(fallback).toMatchObject({
+      sessionId: "root",
+      update: {
+        sessionUpdate: "tool_call",
+        toolCallId: "agent-tool",
+        title: "Investigate failure",
+        status: "failed",
+        _meta: { claudeCode: { toolName: "Agent" } },
+      },
+    });
+    expect(
+      (fallback?.update._meta?.claudeCode as Record<string, unknown>).subagent,
+    ).toBeUndefined();
+  });
+
+  it("creates a schema-valid non-native failed tool call without a cached initial call", async () => {
+    const runtime = new NativeSubagentRuntime(true, "root", {}, async () => {}, { log: () => {} });
+
+    const fallback = await runtime.route(
+      {
+        sessionId: "root",
+        update: {
+          sessionUpdate: "tool_call_update",
+          toolCallId: "agent-tool",
+          status: "failed",
+          _meta: { claudeCode: { toolName: "Agent", subagent: true } },
+        },
+      } as AcpSessionNotification,
+      async () => {},
+    );
+
+    expect(fallback).toMatchObject({
+      update: {
+        sessionUpdate: "tool_call",
+        toolCallId: "agent-tool",
+        title: "Agent",
+        status: "failed",
+        _meta: { claudeCode: { toolName: "Agent" } },
+      },
+    });
+    expect(
+      (fallback?.update._meta?.claudeCode as Record<string, unknown>).subagent,
+    ).toBeUndefined();
+  });
+
+  it("clears failed-control identity and parent affinity before an id is reused", async () => {
+    const outer = child({
+      sessionId: "outer-child",
+      parentToolUseId: "outer-tool",
+      announced: true,
+    });
+    const session = sessionWith(outer);
+    const published: AcpSessionNotification[] = [];
+    const runtime = new NativeSubagentRuntime(
+      true,
+      "root",
+      session,
+      async (notification) => {
+        published.push(notification);
+      },
+      { log: () => {} },
+    );
+
+    await runtime.route(control("tool_call", "pending", "outer-tool"), async () => {});
+    await runtime.route(control("tool_call_update", "failed", "outer-tool"), async () => {});
+    await runtime.taskStarted(
+      {
+        taskId: "reused-child",
+        toolUseId: "agent-tool",
+        subagentType: "Review",
+        description: "Fresh identity",
+      },
+      async () => {},
+    );
+    await runtime.route(
+      {
+        ...control("tool_call", "pending"),
+        update: {
+          ...control("tool_call", "pending").update,
+          rawInput: { description: "Fresh identity", prompt: "Review again" },
+        },
+      } as AcpSessionNotification,
+      async () => {},
+    );
+
+    expect(published.at(-1)).toMatchObject({
+      sessionId: "root",
+      update: {
+        sessionUpdate: "subagent_spawned",
+        subagentSessionId: "reused-child",
+        name: "Fresh identity",
+      },
+    });
+  });
+
+  it("discards unknown pending child updates during finishAll", async () => {
+    const published: AcpSessionNotification[] = [];
+    const delivered: AcpSessionNotification[] = [];
+    const runtime = new NativeSubagentRuntime(
+      true,
+      "root",
+      {},
+      async (notification) => {
+        published.push(notification);
+      },
+      { log: () => {} },
+    );
+    const pending = {
+      sessionId: "root",
+      update: {
+        sessionUpdate: "agent_message_chunk",
+        content: { type: "text", text: "stale" },
+        _meta: { claudeCode: { parentToolUseId: "agent-tool" } },
+      },
+    } as AcpSessionNotification;
+
+    await expect(
+      runtime.route(pending, async (value) => {
+        delivered.push(value);
+      }),
+    ).resolves.toBeNull();
+    await runtime.finishAll("cancelled", async (value) => {
+      delivered.push(value);
+    });
+    await runtime.taskStarted(
+      {
+        taskId: "child-1",
+        toolUseId: "agent-tool",
+        subagentType: "Explore",
+        description: "New child",
+      },
+      async (value) => {
+        delivered.push(value);
+      },
+    );
+    await runtime.route(control("tool_call", "pending"), async (value) => {
+      delivered.push(value);
+    });
+
+    expect(delivered).toEqual([]);
+    expect(published).toHaveLength(1);
+  });
+
+  it("creates a distinct ACP lifecycle when the SDK restarts the same task id", async () => {
+    const published: AcpSessionNotification[] = [];
+    const runtime = new NativeSubagentRuntime(
+      true,
+      "root",
+      {},
+      async (notification) => {
+        published.push(notification);
+      },
+      { log: () => {} },
+    );
+    const launch = (toolCallId: string) =>
+      ({
+        ...control("tool_call", "pending"),
+        update: { ...control("tool_call", "pending").update, toolCallId },
+      }) as AcpSessionNotification;
+    const output = (parentToolUseId: string, text: string) =>
+      ({
+        sessionId: "root",
+        update: {
+          sessionUpdate: "agent_message_chunk",
+          content: { type: "text", text },
+          _meta: { claudeCode: { parentToolUseId } },
+        },
+      }) as AcpSessionNotification;
+
+    await runtime.route(launch("launch-1"), async () => {});
+    await runtime.taskStarted(
+      {
+        taskId: "worker-1",
+        toolUseId: "launch-1",
+        subagentType: "Explore",
+        description: "First run",
+      },
+      async () => {},
+    );
+    await expect(runtime.route(output("launch-1", "first"), async () => {})).resolves.toMatchObject(
+      { sessionId: "worker-1" },
+    );
+    await runtime.finishTask("worker-1", "completed", async () => {});
+
+    await runtime.route(launch("launch-2"), async () => {});
+    await runtime.taskStarted(
+      {
+        taskId: "worker-1",
+        toolUseId: "launch-2",
+        subagentType: "Explore",
+        description: "Second run",
+      },
+      async () => {},
+    );
+    await expect(
+      runtime.route(output("launch-2", "second"), async () => {}),
+    ).resolves.toMatchObject({ sessionId: "worker-1:generation:2" });
+    await runtime.finishTask("worker-1", "failed", async () => {}, "launch-1");
+    expect(
+      published.filter(({ update }) => update.sessionUpdate === "subagent_state_update"),
+    ).toHaveLength(1);
+    await expect(
+      runtime.route(output("launch-2", "still running"), async () => {}),
+    ).resolves.toMatchObject({ sessionId: "worker-1:generation:2" });
+    await expect(runtime.route(output("launch-1", "late"), async () => {})).resolves.toBeNull();
+    await runtime.finishTask("worker-1", "completed", async () => {}, "launch-2");
+
+    const spawnedIds = published.flatMap(({ update }) =>
+      update.sessionUpdate === "subagent_spawned" ? [update.subagentSessionId] : [],
+    );
+    const terminalIds = published.flatMap(({ update }) =>
+      update.sessionUpdate === "subagent_state_update" ? [update.subagentSessionId] : [],
+    );
+    expect(spawnedIds).toEqual(["worker-1", "worker-1:generation:2"]);
+    expect(terminalIds).toEqual(spawnedIds);
+  });
+});
--- a/src/tests/permission-effects.test.ts
+++ b/src/tests/permission-effects.test.ts
@@ -0,0 +1,347 @@
+import { describe, expect, it } from "vitest";
+import type { PermissionUpdate } from "@anthropic-ai/claude-agent-sdk";
+import { normalizeDurablePermissionChangeSet } from "../permissions/normalization.js";
+import { buildClaudePermissionOptions, PERMISSION_OPTION_ID } from "../permissions/options.js";
+import { decodeClaudePermissionResponse } from "../permissions/response.js";
+
+const permissionResult = (...args: Parameters<typeof decodeClaudePermissionResponse>) =>
+  decodeClaudePermissionResponse(...args).permissionResult;
+
+const rule = { toolName: "Bash", ruleContent: "npm test:*" };
+
+describe("Claude permission response effects", () => {
+  const build = (
+    toolName: string,
+    durableChangeSet?: ReturnType<typeof normalizeDurablePermissionChangeSet>,
+    input: Record<string, unknown> = {},
+    displayName?: string,
+    allowPersistentOptions = true,
+    availableModes: readonly string[] = [],
+  ) =>
+    buildClaudePermissionOptions({
+      toolName,
+      displayName,
+      input,
+      cwd: "/workspace",
+      durableChangeSet,
+      allowPersistentOptions,
+      availableModes,
+    });
+
+  it.each([
+    [PERMISSION_OPTION_ID.allowSkillExact, "deploy prod"],
+    [PERMISSION_OPTION_ID.allowSkillPrefix, "deploy:*"],
+  ])("applies the native Skill effect for %s", (optionId, ruleContent) => {
+    const input = { skill: "deploy prod" };
+    const result = permissionResult(
+      { outcome: { outcome: "selected", optionId } },
+      "Skill",
+      input,
+      "tool-skill",
+      build("Skill", undefined, input),
+    );
+    expect(result.behavior === "allow" && result.updatedPermissions).toEqual([
+      {
+        type: "addRules",
+        rules: [{ toolName: "Skill", ruleContent }],
+        behavior: "allow",
+        destination: "localSettings",
+      },
+    ]);
+  });
+
+  it("applies a generated WebFetch effect and an exact MCP provider effect", () => {
+    const webInput = { url: "https://example.com/path" };
+    const web = permissionResult(
+      {
+        outcome: {
+          outcome: "selected",
+          optionId: PERMISSION_OPTION_ID.allowWithUpdates,
+        },
+      },
+      "WebFetch",
+      webInput,
+      "tool-web",
+      build("WebFetch", undefined, webInput),
+    );
+    expect(web.behavior === "allow" && web.updatedPermissions).toEqual([
+      {
+        type: "addRules",
+        rules: [{ toolName: "WebFetch", ruleContent: "domain:example.com" }],
+        behavior: "allow",
+        destination: "localSettings",
+      },
+    ]);
+
+    const mcpChangeSet = normalizeDurablePermissionChangeSet([
+      {
+        type: "addRules",
+        rules: [{ toolName: "mcp__demo__deploy" }],
+        behavior: "allow",
+        destination: "localSettings",
+      },
+    ]);
+    const fallback = permissionResult(
+      {
+        outcome: {
+          outcome: "selected",
+          optionId: PERMISSION_OPTION_ID.allowWithUpdates,
+        },
+      },
+      "mcp__demo__deploy",
+      { target: "staging" },
+      "tool-mcp",
+      build("mcp__demo__deploy", mcpChangeSet),
+      mcpChangeSet,
+    );
+    expect(fallback.behavior === "allow" && fallback.updatedPermissions).toEqual(
+      mcpChangeSet?.updates,
+    );
+  });
+
+  it.each([
+    ["Read", { file_path: "/outside/a.ts" }, "Read"],
+    ["Glob", { path: "/outside" }, "Read"],
+    ["Grep", { path: "/outside" }, "Read"],
+    ["Edit", { file_path: "/outside/a.ts" }, "Edit"],
+    ["Write", { file_path: "/outside/a.ts" }, "Edit"],
+    ["NotebookEdit", { notebook_path: "/outside/a.ipynb" }, "Edit"],
+  ] as const)(
+    "applies the exact provider filesystem effect for %s",
+    (toolName, input, ruleTool) => {
+      const changeSet = normalizeDurablePermissionChangeSet([
+        {
+          type: "addRules",
+          rules: [{ toolName: ruleTool, ruleContent: "/outside/**" }],
+          behavior: "allow",
+          destination: "session",
+        },
+      ])!;
+      const result = permissionResult(
+        {
+          outcome: {
+            outcome: "selected",
+            optionId: PERMISSION_OPTION_ID.allowWithUpdates,
+          },
+        },
+        toolName,
+        input,
+        `tool-${toolName}`,
+        build(toolName, changeSet, input),
+        changeSet,
+      );
+      expect(result.behavior === "allow" && result.updatedPermissions).toEqual(changeSet.updates);
+    },
+  );
+
+  it("suppresses generated durable effects when an ask rule forced the prompt", () => {
+    expect(
+      build("WebFetch", undefined, { url: "https://example.com" }, undefined, false),
+    ).toHaveLength(2);
+    expect(build("mcp__demo__deploy", undefined, {}, undefined, false)).toHaveLength(2);
+  });
+
+  it("allows EnterPlanMode temporarily without changing mode before the tool runs", () => {
+    expect(
+      permissionResult(
+        { outcome: { outcome: "selected", optionId: PERMISSION_OPTION_ID.allowOnce } },
+        "EnterPlanMode",
+        {},
+        "tool-enter-plan",
+        build("EnterPlanMode"),
+      ),
+    ).toEqual({
+      behavior: "allow",
+      updatedInput: {},
+      toolUseID: "tool-enter-plan",
+      decisionClassification: "user_temporary",
+    });
+  });
+
+  it("applies the selected ExitPlanMode mode and maps rejection", () => {
+    const input = { plan: "Implement it" };
+    const offered = build("ExitPlanMode", undefined, input, undefined, true, [
+      "auto",
+      "default",
+      "acceptEdits",
+    ]);
+    const approved = permissionResult(
+      {
+        outcome: {
+          outcome: "selected",
+          optionId: PERMISSION_OPTION_ID.exitPlanAuto,
+        },
+      },
+      "ExitPlanMode",
+      input,
+      "tool-plan",
+      offered,
+    );
+    expect(approved.behavior === "allow" && approved.updatedPermissions).toEqual([
+      { type: "setMode", mode: "auto", destination: "session" },
+    ]);
+
+    const acceptEditsOffered = build("ExitPlanMode", undefined, input, undefined, true, [
+      "default",
+      "acceptEdits",
+    ]);
+    const acceptEdits = permissionResult(
+      {
+        outcome: {
+          outcome: "selected",
+          optionId: PERMISSION_OPTION_ID.exitPlanAcceptEdits,
+        },
+      },
+      "ExitPlanMode",
+      input,
+      "tool-plan",
+      acceptEditsOffered,
+    );
+    expect(acceptEdits.behavior === "allow" && acceptEdits.updatedPermissions).toEqual([
+      { type: "setMode", mode: "acceptEdits", destination: "session" },
+    ]);
+
+    const rejected = permissionResult(
+      {
+        outcome: {
+          outcome: "selected",
+          optionId: PERMISSION_OPTION_ID.reject,
+        },
+      },
+      "ExitPlanMode",
+      input,
+      "tool-plan",
+      offered,
+    );
+    expect(rejected).toMatchObject({
+      behavior: "deny",
+      message: "User chose to keep planning",
+      interrupt: true,
+      decisionClassification: "user_reject",
+    });
+  });
+
+  it("interrupts the old query when ExitPlanMode clears context", () => {
+    const input = { plan: "Implement it" };
+    const offered = build("ExitPlanMode", undefined, input, undefined, true, ["auto"]);
+    expect(
+      permissionResult(
+        {
+          outcome: {
+            outcome: "selected",
+            optionId: PERMISSION_OPTION_ID.exitPlanClearAuto,
+          },
+        },
+        "ExitPlanMode",
+        input,
+        "tool-plan",
+        offered,
+      ),
+    ).toEqual({
+      behavior: "deny",
+      message: "User accepted the plan and requested a fresh context",
+      interrupt: true,
+      toolUseID: "tool-plan",
+      decisionClassification: "user_reject",
+    });
+  });
+
+  it("returns clear-context semantics with the decoded permission decision", () => {
+    const input = { plan: "Implement it" };
+    const offered = build("ExitPlanMode", undefined, input, undefined, true, ["auto"]);
+    const decision = decodeClaudePermissionResponse(
+      {
+        outcome: {
+          outcome: "selected",
+          optionId: PERMISSION_OPTION_ID.exitPlanClearAuto,
+        },
+      },
+      "ExitPlanMode",
+      input,
+      "tool-plan",
+      offered,
+    );
+    expect(decision.contextResetMode).toBe("auto");
+    expect(decision.permissionResult).toMatchObject({ behavior: "deny", interrupt: true });
+  });
+
+  it("maps one-time allow without remembered updates", () => {
+    expect(
+      permissionResult(
+        { outcome: { outcome: "selected", optionId: PERMISSION_OPTION_ID.allowOnce } },
+        "Bash",
+        { command: "pwd" },
+        "tool-1",
+        build("Bash"),
+      ),
+    ).toEqual({
+      behavior: "allow",
+      updatedInput: { command: "pwd" },
+      toolUseID: "tool-1",
+      decisionClassification: "user_temporary",
+    });
+  });
+
+  it("maps durable allow to the snapshotted provider effect", () => {
+    const suggestions: PermissionUpdate[] = [
+      { type: "addRules", rules: [rule], behavior: "allow", destination: "session" },
+    ];
+    const changeSet = normalizeDurablePermissionChangeSet(suggestions);
+    const result = permissionResult(
+      { outcome: { outcome: "selected", optionId: PERMISSION_OPTION_ID.allowWithUpdates } },
+      "Bash",
+      { command: "npm test" },
+      "tool-2",
+      build("Bash", changeSet),
+      changeSet,
+    );
+    expect(result).toMatchObject({
+      behavior: "allow",
+      toolUseID: "tool-2",
+      decisionClassification: "user_permanent",
+    });
+    expect(result.behavior === "allow" && result.updatedPermissions).toEqual(suggestions);
+    expect(result.behavior === "allow" && result.updatedPermissions).not.toBe(suggestions);
+  });
+
+  it("distinguishes explicit reject from cancellation", () => {
+    expect(
+      permissionResult(
+        { outcome: { outcome: "selected", optionId: PERMISSION_OPTION_ID.reject } },
+        "Bash",
+        {},
+        "tool-3",
+        build("Bash"),
+      ),
+    ).toEqual({
+      behavior: "deny",
+      message: "User refused permission to run tool",
+      toolUseID: "tool-3",
+      decisionClassification: "user_reject",
+    });
+    expect(() =>
+      permissionResult({ outcome: { outcome: "cancelled" } }, "Bash", {}, "tool-3", build("Bash")),
+    ).toThrow("Tool use aborted");
+  });
+
+  it("fails closed for an unavailable or unknown selection", () => {
+    expect(() =>
+      permissionResult(
+        { outcome: { outcome: "selected", optionId: PERMISSION_OPTION_ID.allowWithUpdates } },
+        "Bash",
+        {},
+        "tool-4",
+        build("Bash"),
+      ),
+    ).toThrow("Permission option was not offered");
+    expect(() =>
+      permissionResult(
+        { outcome: { outcome: "selected", optionId: "future" } },
+        "Bash",
+        {},
+        "tool-4",
+        build("Bash"),
+      ),
+    ).toThrow("Permission option was not offered");
+  });
+});
--- a/src/tests/permission-normalization.test.ts
+++ b/src/tests/permission-normalization.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from "vitest";
+import { normalizeDurablePermissionChangeSet } from "../permissions/normalization.js";
+
+describe("durable permission normalization safety", () => {
+  it("fails closed when validation reads a throwing update accessor", () => {
+    const update = Object.defineProperty({}, "destination", {
+      get() {
+        throw new Error("provider accessor failed");
+      },
+    });
+
+    expect(normalizeDurablePermissionChangeSet([update])).toBeUndefined();
+  });
+
+  it("fails closed when validation reads a throwing suggestions proxy", () => {
+    const suggestions = new Proxy([], {
+      get(target, property, receiver) {
+        if (property === "length") throw new Error("provider proxy failed");
+        return Reflect.get(target, property, receiver);
+      },
+    });
+
+    expect(normalizeDurablePermissionChangeSet(suggestions)).toBeUndefined();
+  });
+
+  it("rejects strings whose untrimmed value exceeds the wire limit", () => {
+    expect(
+      normalizeDurablePermissionChangeSet([
+        {
+          type: "addRules",
+          destination: "session",
+          behavior: "allow",
+          rules: [{ toolName: `${" ".repeat(512)}Bash` }],
+        },
+      ]),
+    ).toBeUndefined();
+  });
+});
--- a/src/tests/permission-options.test.ts
+++ b/src/tests/permission-options.test.ts
@@ -0,0 +1,593 @@
+import { describe, expect, it } from "vitest";
+import { normalizeDurablePermissionChangeSet } from "../permissions/normalization.js";
+import { buildClaudePermissionOptions, PERMISSION_OPTION_ID } from "../permissions/options.js";
+import { buildClaudePermissionPresentation } from "../permissions/presentation.js";
+import { decodeClaudePermissionResponse } from "../permissions/response.js";
+
+const permissionResult = (...args: Parameters<typeof decodeClaudePermissionResponse>) =>
+  decodeClaudePermissionResponse(...args).permissionResult;
+
+const rule = { toolName: "Bash", ruleContent: "npm test:*" };
+describe("Claude permission options and response mapping", () => {
+  const build = (
+    toolName: string,
+    durableChangeSet?: ReturnType<typeof normalizeDurablePermissionChangeSet>,
+    input: Record<string, unknown> = {},
+    displayName?: string,
+    allowPersistentOptions = true,
+    availableModes: readonly string[] = [],
+    contextUsedPercent?: number,
+  ) =>
+    buildClaudePermissionOptions({
+      toolName,
+      displayName,
+      input,
+      cwd: "/workspace",
+      durableChangeSet,
+      allowPersistentOptions,
+      availableModes,
+      contextUsedPercent,
+    });
+
+  it("builds the native Bash static-suggestions option from the exact update bundle", () => {
+    const changeSet = normalizeDurablePermissionChangeSet([
+      { type: "addRules", rules: [rule], behavior: "allow", destination: "session" },
+      { type: "addDirectories", directories: ["/work"], destination: "session" },
+    ]);
+    expect(build("Bash", changeSet, { command: "npm test" })).toEqual([
+      { optionId: PERMISSION_OPTION_ID.allowOnce, name: "Yes", kind: "allow_once" },
+      {
+        optionId: PERMISSION_OPTION_ID.allowWithUpdates,
+        name: "Yes, and allow access to work/ and npm test commands",
+        kind: "allow_always",
+      },
+      { optionId: PERMISSION_OPTION_ID.reject, name: "No", kind: "reject_once" },
+    ]);
+  });
+
+  it.each([
+    [
+      "Bash",
+      [
+        {
+          type: "addRules",
+          rules: [{ toolName: "Bash", ruleContent: "npm test:*" }],
+          behavior: "allow",
+          destination: "session",
+        },
+      ],
+      "Yes, and don't ask again for npm test commands",
+    ],
+    [
+      "PowerShell",
+      [
+        {
+          type: "addRules",
+          rules: [{ toolName: "PowerShell", ruleContent: "Get-Process:*" }],
+          behavior: "allow",
+          destination: "session",
+        },
+      ],
+      "Yes, and don't ask again for Get-Process commands",
+    ],
+    [
+      "Bash",
+      [
+        {
+          type: "addRules",
+          rules: [{ toolName: "Read", ruleContent: "/outside/**" }],
+          behavior: "allow",
+          destination: "session",
+        },
+      ],
+      "Yes, allow reading from outside/ from this project",
+    ],
+    [
+      "Bash",
+      [{ type: "addDirectories", directories: ["/outside"], destination: "session" }],
+      "Yes, and always allow access to outside/ from this project",
+    ],
+  ] as const)("ports the native static shell label for %s", (toolName, updates, expected) => {
+    const changeSet = normalizeDurablePermissionChangeSet(updates);
+    expect(build(toolName, changeSet)[1]?.name).toBe(expected);
+  });
+
+  it("uses Claude Code's `similar` truncation for long command lists", () => {
+    const changeSet = normalizeDurablePermissionChangeSet([
+      {
+        type: "addRules",
+        rules: [
+          { toolName: "Bash", ruleContent: "a-very-long-command-name-one:*" },
+          { toolName: "Bash", ruleContent: "a-very-long-command-name-two:*" },
+        ],
+        behavior: "allow",
+        destination: "session",
+      },
+    ]);
+    expect(build("Bash", changeSet)[1]?.name).toBe("Yes, and don't ask again for similar commands");
+  });
+
+  it("uses the shortest distinguishing parent for paths with the same basename", () => {
+    const changeSet = normalizeDurablePermissionChangeSet([
+      {
+        type: "addRules",
+        rules: [
+          { toolName: "Read", ruleContent: "/repos/codex-acp/src/**" },
+          { toolName: "Read", ruleContent: "/repos/claude-agent-acp/src/**" },
+          { toolName: "Bash", ruleContent: "ls -R:*" },
+        ],
+        behavior: "allow",
+        destination: "session",
+      },
+    ]);
+    expect(build("Bash", changeSet)[1]?.name).toBe(
+      "Yes, and allow codex-acp/src/ and claude-agent-acp/src/ access and ls -R commands",
+    );
+  });
+
+  it("does not repeat an identical path in the durable option", () => {
+    const changeSet = normalizeDurablePermissionChangeSet([
+      {
+        type: "addRules",
+        rules: [
+          { toolName: "Read", ruleContent: "/repos/codex-acp/src/**" },
+          { toolName: "Read", ruleContent: "/repos/codex-acp/src/**" },
+        ],
+        behavior: "allow",
+        destination: "session",
+      },
+    ]);
+    expect(build("Bash", changeSet)[1]?.name).toBe(
+      "Yes, allow reading from src/ from this project",
+    );
+  });
+
+  it.each([
+    "Bash",
+    "PowerShell",
+    "Read",
+    "Edit",
+    "Write",
+    "NotebookEdit",
+    "Glob",
+    "Grep",
+    "WebFetch",
+    "SandboxNetworkAccess",
+    "mcp__example__write_tool",
+    "mcp__computer-use__click",
+  ])("offers only one-time allow and reject for %s without a representable update", (toolName) => {
+    expect(build(toolName).map((option) => option.name)).toEqual(["Yes", "No"]);
+  });
+
+  it("uses generated native effects instead of applying an unrelated provider suggestion", () => {
+    const bashChangeSet = normalizeDurablePermissionChangeSet([
+      { type: "addRules", rules: [rule], behavior: "allow", destination: "session" },
+    ]);
+    expect(build("Read", bashChangeSet, { file_path: "/workspace/a.ts" })).toHaveLength(2);
+    expect(build("WebFetch", bashChangeSet, { url: "https://example.com" })[1]?.name).toBe(
+      "Yes, and don't ask again for example.com",
+    );
+  });
+
+  it("preserves an MCP tool's exact provider suggestion", () => {
+    const toolName = "mcp__example__write_tool";
+    const changeSet = normalizeDurablePermissionChangeSet([
+      {
+        type: "addRules",
+        rules: [{ toolName }],
+        behavior: "allow",
+        destination: "localSettings",
+      },
+    ]);
+    const offered = build(toolName, changeSet, {}, "Write tool");
+    expect(offered.map((option) => option.name)).toEqual([
+      "Yes",
+      "Yes, and don't ask again for Write tool commands",
+      "No",
+    ]);
+    const result = permissionResult(
+      { outcome: { outcome: "selected", optionId: PERMISSION_OPTION_ID.allowWithUpdates } },
+      toolName,
+      { value: "new" },
+      "tool-mcp-write",
+      offered,
+      changeSet,
+    );
+    expect(result.behavior === "allow" && result.updatedPermissions).toEqual(changeSet?.updates);
+  });
+
+  it.each(["mcp__example__write_tool", "mcp__computer-use__click"])(
+    "offers no misleading durable option for unrepresentable %s suggestions",
+    (toolName) => {
+      const cases = [
+        [
+          {
+            type: "addRules",
+            rules: [{ toolName }],
+            behavior: "deny",
+            destination: "localSettings",
+          },
+        ],
+        [{ type: "setMode", mode: "bypassPermissions", destination: "session" }],
+        [
+          {
+            type: "addRules",
+            rules: [{ toolName: "mcp__other__tool" }],
+            behavior: "allow",
+            destination: "localSettings",
+          },
+        ],
+        [
+          {
+            type: "addRules",
+            rules: [{ toolName }],
+            behavior: "allow",
+            destination: "localSettings",
+          },
+          {
+            type: "addRules",
+            rules: [{ toolName: "mcp__other__tool" }],
+            behavior: "allow",
+            destination: "localSettings",
+          },
+        ],
+        [
+          {
+            type: "addRules",
+            rules: [{ toolName, ruleContent: "target:staging" }],
+            behavior: "allow",
+            destination: "localSettings",
+          },
+        ],
+      ] as const;
+
+      for (const suggestions of cases) {
+        const changeSet = normalizeDurablePermissionChangeSet(suggestions);
+        expect(build(toolName, changeSet).map((option) => option.optionId)).toEqual([
+          PERMISSION_OPTION_ID.allowOnce,
+          PERMISSION_OPTION_ID.reject,
+        ]);
+      }
+    },
+  );
+
+  it.each(["mcp__example__write_tool", "mcp__computer-use__click"])(
+    "preserves the complete representable provider bundle for %s",
+    (toolName) => {
+      const changeSet = normalizeDurablePermissionChangeSet([
+        {
+          type: "addRules",
+          rules: [{ toolName }, { toolName }],
+          behavior: "allow",
+          destination: "session",
+        },
+        {
+          type: "addRules",
+          rules: [{ toolName }],
+          behavior: "allow",
+          destination: "localSettings",
+        },
+      ]);
+      const offered = build(toolName, changeSet);
+      expect(offered.map((option) => option.optionId)).toContain(
+        PERMISSION_OPTION_ID.allowWithUpdates,
+      );
+      const result = permissionResult(
+        { outcome: { outcome: "selected", optionId: PERMISSION_OPTION_ID.allowWithUpdates } },
+        toolName,
+        {},
+        `tool-${toolName}`,
+        offered,
+        changeSet,
+      );
+      expect(result.behavior === "allow" && result.updatedPermissions).toEqual(changeSet?.updates);
+    },
+  );
+
+  it.each([
+    ["Read", { file_path: "/workspace/a.ts" }, "Yes, during this session"],
+    [
+      "Read",
+      { file_path: "/outside/a.ts" },
+      "Yes, allow reading from outside/ during this session",
+    ],
+    ["Edit", { file_path: "/workspace/a.ts" }, "Yes, allow all edits during this session"],
+    [
+      "Write",
+      { file_path: "/outside/a.ts" },
+      "Yes, allow all edits in outside/ during this session",
+    ],
+    [
+      "NotebookEdit",
+      { notebook_path: "/workspace/a.ipynb" },
+      "Yes, allow all edits during this session",
+    ],
+    ["Glob", {}, "Yes, during this session"],
+    ["Grep", {}, "Yes, during this session"],
+  ] as const)("builds the native session label for %s", (toolName, input, durableName) => {
+    const readOnly = toolName === "Read" || toolName === "Glob" || toolName === "Grep";
+    const outside = Object.values(input).some(
+      (value) => typeof value === "string" && value.startsWith("/outside"),
+    );
+    const changeSet = normalizeDurablePermissionChangeSet(
+      readOnly
+        ? [
+            {
+              type: "addRules",
+              rules: [{ toolName: "Read", ruleContent: outside ? "/outside/**" : "/workspace/**" }],
+              behavior: "allow",
+              destination: "session",
+            },
+          ]
+        : outside
+          ? [{ type: "addDirectories", directories: ["/outside"], destination: "session" }]
+          : [{ type: "setMode", mode: "acceptEdits", destination: "session" }],
+    );
+    expect(build(toolName, changeSet, input).map((option) => option.name)).toEqual([
+      "Yes",
+      durableName,
+      "No",
+    ]);
+  });
+
+  it("does not call a persistent filesystem update a session grant", () => {
+    const changeSet = normalizeDurablePermissionChangeSet([
+      { type: "addDirectories", directories: ["/outside"], destination: "localSettings" },
+    ]);
+    expect(build("Read", changeSet, { file_path: "/outside/a.ts" })).toHaveLength(2);
+  });
+
+  it("does not offer a path-specific filesystem effect for a different in-project path", () => {
+    const read = normalizeDurablePermissionChangeSet([
+      {
+        type: "addRules",
+        rules: [{ toolName: "Read", ruleContent: "/outside/**" }],
+        behavior: "allow",
+        destination: "session",
+      },
+    ]);
+    const write = normalizeDurablePermissionChangeSet([
+      { type: "addDirectories", directories: ["/outside"], destination: "session" },
+    ]);
+    expect(build("Read", read, { file_path: "/workspace/a.ts" })).toHaveLength(2);
+    expect(build("Edit", write, { file_path: "/workspace/a.ts" })).toHaveLength(2);
+  });
+
+  it("resolves relative permission paths from the session cwd", () => {
+    const changeSet = normalizeDurablePermissionChangeSet([
+      {
+        type: "addRules",
+        rules: [{ toolName: "Read", ruleContent: "src/**" }],
+        behavior: "allow",
+        destination: "session",
+      },
+    ]);
+    expect(build("Read", changeSet, { file_path: "/workspace/src/a.ts" })[1]?.name).toBe(
+      "Yes, during this session",
+    );
+  });
+
+  it("recognizes a backslash glob suffix in a provider path rule", () => {
+    const changeSet = normalizeDurablePermissionChangeSet([
+      {
+        type: "addRules",
+        rules: [{ toolName: "Read", ruleContent: "/outside\\**" }],
+        behavior: "allow",
+        destination: "session",
+      },
+    ]);
+    expect(build("Read", changeSet, { file_path: "/outside/a.ts" })[1]?.name).toBe(
+      "Yes, allow reading from outside/ during this session",
+    );
+  });
+
+  it("treats acceptEdits as broad only for ordinary write paths", () => {
+    const changeSet = normalizeDurablePermissionChangeSet([
+      { type: "setMode", mode: "acceptEdits", destination: "session" },
+    ]);
+    expect(build("Edit", changeSet, { file_path: "/workspace/a.ts" })[1]?.name).toBe(
+      "Yes, allow all edits during this session",
+    );
+    expect(
+      build("Edit", changeSet, { file_path: "/workspace/.claude/settings.json" }),
+    ).toHaveLength(2);
+    expect(build("Read", changeSet, { file_path: "/workspace/a.ts" })).toHaveLength(2);
+  });
+
+  it("builds WebFetch and sandbox-host labels from provider data", () => {
+    const webFetch = normalizeDurablePermissionChangeSet([
+      {
+        type: "addRules",
+        rules: [{ toolName: "WebFetch", ruleContent: "domain:example.com" }],
+        behavior: "allow",
+        destination: "localSettings",
+      },
+    ]);
+    expect(build("WebFetch", webFetch, { url: "https://example.com/a" })[1]?.name).toBe(
+      "Yes, and don't ask again for example.com",
+    );
+    const network = normalizeDurablePermissionChangeSet([
+      {
+        type: "addRules",
+        rules: [{ toolName: "SandboxNetworkAccess", ruleContent: "example.com" }],
+        behavior: "allow",
+        destination: "localSettings",
+      },
+    ]);
+    expect(build("SandboxNetworkAccess", network, { host: "example.com" })[1]?.name).toBe(
+      "Yes, and don't ask again for example.com",
+    );
+  });
+
+  it("uses Claude Code's special session label for its own settings", () => {
+    const changeSet = normalizeDurablePermissionChangeSet([
+      {
+        type: "addRules",
+        rules: [{ toolName: "Edit", ruleContent: "/workspace/.claude/**" }],
+        behavior: "allow",
+        destination: "session",
+      },
+    ]);
+    expect(build("Edit", changeSet, { file_path: ".claude/settings.json" })[1]?.name).toBe(
+      "Yes, and allow Claude to edit its own settings for this session",
+    );
+  });
+
+  it("builds Claude Code's exact and prefix Skill options from tool input", () => {
+    expect(build("Skill", undefined, { skill: "deploy prod" })).toMatchObject([
+      { optionId: PERMISSION_OPTION_ID.allowOnce, name: "Yes" },
+      {
+        optionId: PERMISSION_OPTION_ID.allowSkillExact,
+        name: "Yes, and don't ask again for deploy prod",
+      },
+      {
+        optionId: PERMISSION_OPTION_ID.allowSkillPrefix,
+        name: "Yes, and don't ask again for deploy:* commands",
+      },
+      { optionId: PERMISSION_OPTION_ID.reject, name: "No" },
+    ]);
+  });
+
+  it("suppresses generated Skill rules when a configured ask rule forced the prompt", () => {
+    expect(build("Skill", undefined, { skill: "deploy prod" }, undefined, false)).toEqual([
+      { optionId: PERMISSION_OPTION_ID.allowOnce, name: "Yes", kind: "allow_once" },
+      { optionId: PERMISSION_OPTION_ID.reject, name: "No", kind: "reject_once" },
+    ]);
+  });
+
+  it("keeps EnterPlanMode at its two reachable one-time choices", () => {
+    expect(build("EnterPlanMode")).toMatchObject([
+      {
+        optionId: PERMISSION_OPTION_ID.allowOnce,
+        name: "Yes, enter plan mode",
+      },
+      { optionId: PERMISSION_OPTION_ID.reject, name: "No, start implementing now" },
+    ]);
+  });
+
+  it("offers only the highest-priority elevated ExitPlanMode choice", () => {
+    const options = build("ExitPlanMode", undefined, {}, undefined, true, [
+      "auto",
+      "default",
+      "acceptEdits",
+      "bypassPermissions",
+    ]);
+    expect(options).toMatchObject([
+      { optionId: PERMISSION_OPTION_ID.exitPlanDefault, name: "Yes, manually approve edits" },
+      { optionId: PERMISSION_OPTION_ID.exitPlanAuto, name: "Yes, and use auto mode" },
+      { optionId: PERMISSION_OPTION_ID.reject, name: "No, keep planning" },
+    ]);
+    expect(options[2]?._meta).toBeUndefined();
+  });
+
+  it.each([
+    [
+      ["bypassPermissions", "acceptEdits"],
+      PERMISSION_OPTION_ID.exitPlanBypass,
+      "Yes, and bypass permissions",
+    ],
+    [["acceptEdits"], PERMISSION_OPTION_ID.exitPlanAcceptEdits, "Yes, auto-accept edits"],
+    [[], PERMISSION_OPTION_ID.exitPlanAcceptEdits, "Yes, auto-accept edits"],
+  ] as const)("falls back through the native ExitPlanMode priority", (modes, optionId, name) => {
+    expect(build("ExitPlanMode", undefined, {}, undefined, true, modes)).toMatchObject([
+      { optionId: PERMISSION_OPTION_ID.exitPlanDefault, name: "Yes, manually approve edits" },
+      { optionId, name },
+      { optionId: PERMISSION_OPTION_ID.reject, name: "No, keep planning" },
+    ]);
+  });
+
+  it.each([
+    [
+      ["auto", "bypassPermissions", "acceptEdits"],
+      PERMISSION_OPTION_ID.exitPlanClearAuto,
+      "Yes, clear context (73% used) and use auto mode",
+    ],
+    [
+      ["bypassPermissions", "acceptEdits"],
+      PERMISSION_OPTION_ID.exitPlanClearBypass,
+      "Yes, clear context (73% used) and bypass permissions",
+    ],
+    [
+      ["acceptEdits"],
+      PERMISSION_OPTION_ID.exitPlanClearAcceptEdits,
+      "Yes, clear context (73% used) and auto-accept edits",
+    ],
+  ] as const)(
+    "offers one clear-context ExitPlanMode choice using native priority",
+    (modes, optionId, name) => {
+      expect(
+        build("ExitPlanMode", undefined, { plan: "Implement it" }, undefined, true, modes, 73),
+      ).toContainEqual(expect.objectContaining({ optionId, name }));
+    },
+  );
+
+  it("does not offer clear-context ExitPlanMode without a plan", () => {
+    expect(
+      build("ExitPlanMode", undefined, {}, undefined, true, ["auto"], 73).map(
+        (option) => option.optionId,
+      ),
+    ).not.toContain(PERMISSION_OPTION_ID.exitPlanClearAuto);
+  });
+
+  it("recognizes real Computer Use MCP tools and preserves their exact durable suggestion", () => {
+    const toolName = "mcp__computer-use__click";
+    const changeSet = normalizeDurablePermissionChangeSet([
+      {
+        type: "addRules",
+        rules: [{ toolName }],
+        behavior: "allow",
+        destination: "localSettings",
+      },
+    ]);
+    const offered = build(toolName, changeSet, {}, "Click");
+    expect(offered.map((option) => option.name)).toEqual([
+      "Yes",
+      "Yes, and don't ask again for Click",
+      "No",
+    ]);
+    const result = permissionResult(
+      {
+        outcome: {
+          outcome: "selected",
+          optionId: PERMISSION_OPTION_ID.allowWithUpdates,
+        },
+      },
+      toolName,
+      { x: 10, y: 20 },
+      "tool-computer-use",
+      offered,
+      changeSet,
+    );
+    expect(result.behavior === "allow" && result.updatedPermissions).toEqual(changeSet?.updates);
+  });
+
+  it("reuses the Computer Use MCP tool-call title", () => {
+    expect(
+      buildClaudePermissionPresentation({
+        toolName: "mcp__computer-use__screenshot",
+        input: {},
+        toolUseID: "tool-computer-use",
+      })._meta,
+    ).toEqual({
+      permission: { version: 1, title: "mcp__computer-use__screenshot" },
+    });
+  });
+
+  it("uses the provider display name for a matching generic-tool rule", () => {
+    const changeSet = normalizeDurablePermissionChangeSet([
+      {
+        type: "addRules",
+        rules: [{ toolName: "mcp__demo__deploy" }],
+        behavior: "allow",
+        destination: "localSettings",
+      },
+    ]);
+    expect(build("mcp__demo__deploy", changeSet, {}, "Deploy")[1]?.name).toBe(
+      "Yes, and don't ask again for Deploy commands",
+    );
+  });
+
+  it("refuses to route AskUserQuestion through permission options", () => {
+    expect(() => build("AskUserQuestion")).toThrow("handled by ACP elicitation");
+  });
+});
--- a/src/tests/permission-presentation.test.ts
+++ b/src/tests/permission-presentation.test.ts
@@ -0,0 +1,309 @@
+import { describe, expect, it } from "vitest";
+import type { PermissionUpdate } from "@anthropic-ai/claude-agent-sdk";
+import { normalizeDurablePermissionChangeSet } from "../permissions/normalization.js";
+import { buildClaudePermissionPresentation } from "../permissions/presentation.js";
+
+const rule = { toolName: "Bash", ruleContent: "npm test:*" };
+describe("Claude permission suggestion normalization", () => {
+  it.each([undefined, [], null, "bad"])("omits a durable choice for %j", (suggestions) => {
+    expect(normalizeDurablePermissionChangeSet(suggestions)).toBeUndefined();
+  });
+
+  it.each(["addRules", "replaceRules", "removeRules"] as const)(
+    "supports and snapshots %s",
+    (type) => {
+      const suggestions: PermissionUpdate[] = [
+        { type, rules: [rule], behavior: "allow", destination: "session" },
+      ];
+      const normalized = normalizeDurablePermissionChangeSet(suggestions);
+      expect(normalized?.updates).toEqual(suggestions);
+      expect(normalized?.updates).not.toBe(suggestions);
+    },
+  );
+
+  it("keeps the approved effect stable if the provider mutates its suggestions later", () => {
+    const suggestions: PermissionUpdate[] = [
+      { type: "addRules", rules: [rule], behavior: "allow", destination: "session" },
+    ];
+    const normalized = normalizeDurablePermissionChangeSet(suggestions)!;
+    suggestions[0] = {
+      type: "addRules",
+      rules: [{ toolName: "Bash", ruleContent: "rm:*" }],
+      behavior: "allow",
+      destination: "userSettings",
+    };
+    expect(normalized.updates).toEqual([
+      { type: "addRules", rules: [rule], behavior: "allow", destination: "session" },
+    ]);
+  });
+
+  it.each(["default", "acceptEdits", "bypassPermissions", "plan", "dontAsk", "auto"] as const)(
+    "supports setMode %s",
+    (mode) => {
+      expect(
+        normalizeDurablePermissionChangeSet([{ type: "setMode", mode, destination: "session" }])
+          ?.updates,
+      ).toEqual([{ type: "setMode", mode, destination: "session" }]);
+    },
+  );
+
+  it.each(["addDirectories", "removeDirectories"] as const)("supports %s", (type) => {
+    expect(
+      normalizeDurablePermissionChangeSet([
+        { type, directories: ["/one", "/two"], destination: "localSettings" },
+      ])?.updates,
+    ).toEqual([{ type, directories: ["/one", "/two"], destination: "localSettings" }]);
+  });
+
+  it.each([
+    [{ type: "future", destination: "session" }],
+    [{ type: "setMode", mode: "future", destination: "session" }],
+    [{ type: "addRules", rules: [rule], behavior: "future", destination: "session" }],
+    [{ type: "addDirectories", directories: ["/work"], destination: "future" }],
+    [{ type: "addDirectories", directories: [], destination: "session" }],
+  ])("fails closed for an unknown or invalid change set", (suggestions) => {
+    expect(normalizeDurablePermissionChangeSet(suggestions)).toBeUndefined();
+  });
+
+  it("fails closed when an otherwise valid provider update is not cloneable", () => {
+    expect(
+      normalizeDurablePermissionChangeSet([
+        {
+          type: "addRules",
+          rules: [rule],
+          behavior: "allow",
+          destination: "session",
+          unexpectedFunction: () => undefined,
+        },
+      ]),
+    ).toBeUndefined();
+  });
+
+  it("suppresses every durable option for a forced ask", () => {
+    expect(
+      normalizeDurablePermissionChangeSet(
+        [{ type: "addDirectories", directories: ["/work"], destination: "projectSettings" }],
+        true,
+      ),
+    ).toBeUndefined();
+  });
+});
+
+describe("Claude permission ACP v1 presentation", () => {
+  it("uses Approve Plan as the tool title and keeps the question in permission metadata", () => {
+    const presentation = buildClaudePermissionPresentation({
+      toolName: "ExitPlanMode",
+      input: { plan: "Implement the change" },
+      toolUseID: "tool-plan",
+    });
+
+    expect(presentation.toolCall.title).toBe("Approve Plan");
+    expect(presentation._meta).toEqual({
+      permission: { version: 1, title: "Ready to code?" },
+    });
+  });
+
+  it("uses the human command description as the permission title", () => {
+    const input = { command: "npm test", description: "Run the tests" };
+    const presentation = buildClaudePermissionPresentation({
+      toolName: "Bash",
+      input,
+      toolUseID: "tool-1",
+      displayName: "Run command",
+      description: "Run npm tests",
+      decisionReason: "Needed to verify the change.",
+    });
+    expect(presentation._meta).toEqual({
+      permission: {
+        version: 1,
+        title: "Run the tests",
+        description: "Reason: Needed to verify the change.",
+      },
+    });
+    expect(presentation.toolCall).toMatchObject({
+      toolCallId: "tool-1",
+      name: "Bash",
+      kind: "execute",
+      status: "pending",
+      rawInput: input,
+      title: "Run the tests",
+    });
+    expect(presentation.toolCall.rawInput).toBe(input);
+  });
+
+  it.each(["Bash", "PowerShell"])(
+    "uses the %s tool name when no human command description is available",
+    (toolName) => {
+      const input = { command: "echo raw command" };
+      const presentation = buildClaudePermissionPresentation({
+        toolName,
+        input,
+        toolUseID: `tool-${toolName}`,
+      });
+
+      expect(presentation._meta).toEqual({
+        permission: { version: 1, title: toolName },
+      });
+      expect(presentation.toolCall).toMatchObject({
+        title: toolName,
+        rawInput: input,
+      });
+    },
+  );
+
+  it("keeps the WebFetch URL in structured tool input", () => {
+    const input = { url: "https://example.com/docs", prompt: "Read the API reference" };
+    const presentation = buildClaudePermissionPresentation({
+      toolName: "WebFetch",
+      input,
+      toolUseID: "tool-web-fetch",
+      description: "https://example.com/docs",
+    });
+
+    expect(presentation._meta).toEqual({
+      permission: { version: 1, title: "Fetch https://example.com/docs" },
+    });
+    expect(presentation.toolCall).toMatchObject({
+      kind: "fetch",
+      rawInput: input,
+    });
+    expect(presentation.toolCall.rawInput).toBe(input);
+  });
+
+  it("keeps the WebSearch query out of the permission description", () => {
+    const query = "Agent Client Protocol ACP specification subagents v2";
+    const presentation = buildClaudePermissionPresentation({
+      toolName: "WebSearch",
+      input: { query },
+      toolUseID: "tool-web-search",
+      displayName: "WebSearch",
+      description: "Agent Client Protocol ACP specification subagents…",
+    });
+
+    expect(presentation._meta).toEqual({
+      permission: {
+        version: 1,
+        title: 'Search "Agent Client Protocol ACP specification subagents v2"',
+      },
+    });
+    expect(presentation.toolCall.title).toBe(
+      'Search "Agent Client Protocol ACP specification subagents v2"',
+    );
+  });
+
+  it.each([
+    ["Agent", { description: "Find the implementation" }, "Find the implementation"],
+    ["Task", { description: "Review the tests" }, "Review the tests"],
+    ["ReviewArtifact", {}, "ReviewArtifact"],
+    ["Workflow", {}, "Workflow"],
+    ["Monitor", {}, "Monitor"],
+  ])("reuses the %s tool-call title", (toolName, input, title) => {
+    expect(
+      buildClaudePermissionPresentation({
+        toolName,
+        input,
+        toolUseID: `tool-${toolName}`,
+        displayName: toolName,
+      })._meta,
+    ).toEqual({ permission: { version: 1, title } });
+  });
+
+  it("reuses tool-call titles and temporarily exposes decisionReason", () => {
+    expect(
+      buildClaudePermissionPresentation({
+        toolName: "Read",
+        input: { file_path: "/work/a.ts" },
+        toolUseID: "tool-2",
+        title: "Claude wants to read /work/a.ts",
+        description: "Read a.ts",
+        decisionReason: "Needed to inspect the dependency.",
+      })._meta,
+    ).toEqual({
+      permission: {
+        version: 1,
+        title: "Read /work/a.ts",
+        description: "Reason: Needed to inspect the dependency.",
+      },
+    });
+    expect(
+      buildClaudePermissionPresentation({
+        toolName: "Read",
+        input: { file_path: "/work/a.ts" },
+        toolUseID: "tool-2b",
+        displayName: "Inspect file",
+        description: "Read a.ts",
+      })._meta,
+    ).toEqual({
+      permission: {
+        version: 1,
+        title: "Read /work/a.ts",
+      },
+    });
+    expect(
+      buildClaudePermissionPresentation({
+        toolName: "Read",
+        input: {},
+        toolUseID: "tool-3",
+        decisionReason: "internal_policy_code",
+      })._meta,
+    ).toEqual({
+      permission: {
+        version: 1,
+        title: "Read File",
+        description: "Reason: internal_policy_code",
+      },
+    });
+  });
+
+  it.each([
+    ["Read", { file_path: "/work/AGENTS.md" }, "Read AGENTS.md"],
+    ["Edit", { file_path: "/work/a.ts" }, "Edit a.ts"],
+    ["Write", { file_path: "/work/a.ts" }, "Write a.ts"],
+    ["NotebookEdit", { notebook_path: "/work/a.ipynb" }, "Edit a.ipynb"],
+    ["Glob", { pattern: "**/*.ts" }, "Find **/*.ts"],
+    ["Grep", { pattern: "permission" }, "Search for permission"],
+    ["Bash", { command: "npm test" }, "Run npm test"],
+    ["PowerShell", { command: "Get-ChildItem" }, "List files"],
+    ["WebFetch", { url: "https://example.com" }, "https://example.com"],
+    ["WebSearch", { query: "ACP permissions" }, "ACP permissions"],
+    ["Skill", { skill: "testing" }, "Use testing skill"],
+    ["mcp__demo__deploy", { target: "staging" }, "Deploy to staging"],
+  ])(
+    "does not use the %s operation subtitle as a permission explanation",
+    (toolName, input, description) => {
+      const presentation = buildClaudePermissionPresentation({
+        toolName,
+        input,
+        toolUseID: `tool-${toolName}`,
+        description,
+      });
+
+      expect(presentation._meta?.permission).not.toHaveProperty("description");
+    },
+  );
+
+  it("adds a non-duplicated blocked path to standard locations", () => {
+    const presentation = buildClaudePermissionPresentation({
+      toolName: "Read",
+      input: { file_path: "/work/a.ts" },
+      toolUseID: "tool-4",
+      blockedPath: "/outside/b.ts",
+    });
+    expect(presentation.toolCall.locations).toEqual([
+      { path: "/work/a.ts", line: 1 },
+      { path: "/outside/b.ts" },
+    ]);
+  });
+
+  it("reuses the standard title for an unknown tool", () => {
+    const presentation = buildClaudePermissionPresentation({
+      toolName: "mcp__demo__deploy",
+      input: { target: "staging" },
+      toolUseID: "tool-5",
+    });
+    expect(presentation.toolCall).toMatchObject({ kind: "other", name: "mcp__demo__deploy" });
+    expect(presentation._meta).toEqual({
+      permission: { version: 1, title: "mcp__demo__deploy" },
+    });
+  });
+});
--- a/src/tests/providers.test.ts
+++ b/src/tests/providers.test.ts
@@ -11,6 +11,10 @@ const mockQuery = vi.hoisted(() =>
    setModel: vi.fn(),
    setPermissionMode: vi.fn(),
    supportedCommands: vi.fn().mockResolvedValue([]),
+    close: vi.fn(),
+    interrupt: vi.fn().mockResolvedValue(undefined),
+    getContextUsage: vi.fn().mockResolvedValue({ totalTokens: 0, rawMaxTokens: 200000 }),
+    [Symbol.asyncIterator]: async function* () {},
  })),
 );

@@ -59,7 +63,7 @@ describe("providers", () => {
    expect(response.agentCapabilities?.providers).toEqual({});
  });

-  it("lists a single optional 'main' provider, unconfigured by default", async () => {
+  it("lists one mutually exclusive provider slot with native routing", async () => {
    const [agent] = await createAgentMock();
    const response = await agent.unstable_listProviders({});
    expect(response.providers).toEqual([
@@ -67,7 +71,7 @@ describe("providers", () => {
        providerId: "main",
        supported: ["anthropic", "bedrock", "vertex"],
        required: false,
-        current: null,
+        current: { apiType: "anthropic", baseUrl: "https://api.anthropic.com" },
      },
    ]);
  });
@@ -126,7 +130,7 @@ describe("providers", () => {
    ).rejects.toMatchObject({ code: -32602 });
  });

-  it("disables the 'main' provider by clearing config and reporting current: null", async () => {
+  it("restores native routing after the last override is disabled", async () => {
    const [agent] = await createAgentMock();
    await agent.unstable_setProvider({
      providerId: "main",
@@ -137,7 +141,36 @@ describe("providers", () => {

    await expect(agent.unstable_disableProvider({ providerId: "main" })).resolves.toEqual({});

-    expect((await agent.unstable_listProviders({})).providers[0].current).toBeNull();
+    expect((await agent.unstable_listProviders({})).providers[0].current).toEqual({
+      apiType: "anthropic",
+      baseUrl: "https://api.anthropic.com",
+    });
+  });
+
+  it("replaces the active api type when the single slot is set again", async () => {
+    const [agent] = await createAgentMock();
+    await agent.unstable_setProvider({
+      providerId: "main",
+      apiType: "anthropic",
+      baseUrl: "https://anthropic.example",
+    });
+    await agent.unstable_setProvider({
+      providerId: "main",
+      apiType: "bedrock",
+      baseUrl: "https://bedrock.example",
+    });
+
+    const overridden = await agent.unstable_listProviders({});
+    expect(overridden.providers[0].current).toEqual({
+      apiType: "bedrock",
+      baseUrl: "https://bedrock.example",
+    });
+
+    await agent.unstable_disableProvider({ providerId: "main" });
+    expect((await agent.unstable_listProviders({})).providers[0].current).toEqual({
+      apiType: "anthropic",
+      baseUrl: "https://api.anthropic.com",
+    });
  });

  it("treats disabling an unknown provider as an idempotent no-op", async () => {
@@ -161,7 +194,7 @@ describe("providers", () => {
      expect.objectContaining({
        options: expect.objectContaining({
          env: expect.objectContaining({
-            ANTHROPIC_AUTH_TOKEN: " ",
+            ANTHROPIC_AUTH_TOKEN: "acp-proxy",
            ANTHROPIC_BASE_URL: "https://gateway.example",
            ANTHROPIC_CUSTOM_HEADERS: "x-api-key: test",
          }),
@@ -170,6 +203,171 @@ describe("providers", () => {
    );
  });

+  it("keeps native session creation unchanged when the providers API is unused", async () => {
+    const [agent, mockQuery] = await createAgentMock();
+    await agent.initialize({ protocolVersion: 1, clientCapabilities: {} });
+
+    await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+    expect(mockQuery).toHaveBeenCalledOnce();
+    expect(mockQuery.mock.calls[0][0].options.resume).toBeUndefined();
+    expect(mockQuery.mock.results[0].value.close).not.toHaveBeenCalled();
+  });
+
+  it("recreates loaded sessions with the new provider between turns", async () => {
+    const [agent, mockQuery] = await createAgentMock();
+    await agent.initialize({ protocolVersion: 1, clientCapabilities: {} });
+    const first = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+    const originalQuery = mockQuery.mock.results[0].value;
+
+    await agent.unstable_setProvider({
+      providerId: "main",
+      apiType: "anthropic",
+      baseUrl: "https://gateway.example",
+    });
+
+    expect(originalQuery.close).toHaveBeenCalledOnce();
+    expect(mockQuery).toHaveBeenCalledTimes(2);
+    expect(mockQuery.mock.calls[1][0]).toEqual(
+      expect.objectContaining({
+        options: expect.objectContaining({
+          resume: first.sessionId,
+          env: expect.objectContaining({ ANTHROPIC_BASE_URL: "https://gateway.example" }),
+          settings: expect.objectContaining({
+            apiKeyHelper: "",
+            env: expect.objectContaining({
+              ANTHROPIC_BASE_URL: "https://gateway.example",
+              ANTHROPIC_AUTH_TOKEN: "acp-proxy",
+              CLAUDE_CODE_OAUTH_TOKEN: "",
+            }),
+          }),
+        }),
+      }),
+    );
+
+    await agent.unstable_disableProvider({ providerId: "main" });
+
+    expect(mockQuery).toHaveBeenCalledTimes(3);
+    expect(mockQuery.mock.calls[2][0]).toEqual(
+      expect.objectContaining({
+        options: expect.objectContaining({ resume: first.sessionId }),
+      }),
+    );
+    expect(mockQuery.mock.calls[2][0].options.env.ANTHROPIC_BASE_URL).toBe(
+      process.env.ANTHROPIC_BASE_URL,
+    );
+  });
+
+  it("switches every loaded session through proxy replacements and back to native routing", async () => {
+    const [agent, mockQuery] = await createAgentMock();
+    await agent.initialize({ protocolVersion: 1, clientCapabilities: {} });
+    const first = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+    const second = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+
+    await agent.unstable_setProvider({
+      providerId: "main",
+      apiType: "anthropic",
+      baseUrl: "https://first-gateway.example",
+    });
+    await agent.unstable_setProvider({
+      providerId: "main",
+      apiType: "anthropic",
+      baseUrl: "https://second-gateway.example",
+    });
+    await agent.unstable_disableProvider({ providerId: "main" });
+
+    expect(mockQuery).toHaveBeenCalledTimes(8);
+    const resumedCalls = mockQuery.mock.calls.slice(2);
+    for (let update = 0; update < 3; update += 1) {
+      expect(
+        resumedCalls.slice(update * 2, update * 2 + 2).map(([request]) => request.options.resume),
+      ).toEqual([first.sessionId, second.sessionId]);
+    }
+    expect(
+      resumedCalls.slice(0, 2).map(([request]) => request.options.env.ANTHROPIC_BASE_URL),
+    ).toEqual(["https://first-gateway.example", "https://first-gateway.example"]);
+    expect(
+      resumedCalls.slice(2, 4).map(([request]) => request.options.env.ANTHROPIC_BASE_URL),
+    ).toEqual(["https://second-gateway.example", "https://second-gateway.example"]);
+    expect(
+      resumedCalls.slice(4).map(([request]) => request.options.env.ANTHROPIC_BASE_URL),
+    ).toEqual([process.env.ANTHROPIC_BASE_URL, process.env.ANTHROPIC_BASE_URL]);
+    for (const result of mockQuery.mock.results.slice(0, 6)) {
+      expect(result.value.close).toHaveBeenCalledOnce();
+    }
+    for (const result of mockQuery.mock.results.slice(6)) {
+      expect(result.value.close).not.toHaveBeenCalled();
+    }
+  });
+
+  it("overrides user routing settings while preserving unrelated settings", async () => {
+    const [agent, mockQuery] = await createAgentMock();
+    await agent.initialize({ protocolVersion: 1, clientCapabilities: {} });
+    await agent.unstable_setProvider({
+      providerId: "main",
+      apiType: "anthropic",
+      baseUrl: "https://gateway.example",
+    });
+
+    await agent.newSession({
+      cwd: process.cwd(),
+      mcpServers: [],
+      _meta: {
+        claudeCode: {
+          options: {
+            settings: {
+              apiKeyHelper: "unsafe-helper",
+              env: {
+                ANTHROPIC_BASE_URL: "https://user-gateway.example",
+                ANTHROPIC_API_KEY: "user-secret",
+                UNRELATED_SETTING: "preserved",
+              },
+              model: "claude-sonnet-4-6",
+            },
+          },
+        },
+      },
+    });
+
+    expect(mockQuery.mock.calls[0][0].options.settings).toEqual(
+      expect.objectContaining({
+        apiKeyHelper: "",
+        model: "claude-sonnet-4-6",
+        env: expect.objectContaining({
+          ANTHROPIC_BASE_URL: "https://gateway.example",
+          ANTHROPIC_API_KEY: "",
+          ANTHROPIC_AUTH_TOKEN: "acp-proxy",
+          UNRELATED_SETTING: "preserved",
+        }),
+      }),
+    );
+  });
+
+  it("waits for an active turn before recreating its session", async () => {
+    const [agent, mockQuery] = await createAgentMock();
+    await agent.initialize({ protocolVersion: 1, clientCapabilities: {} });
+    const created = await agent.newSession({ cwd: process.cwd(), mcpServers: [] });
+    const originalQuery = mockQuery.mock.results[0].value;
+    let finishTurn!: () => void;
+    const completion = new Promise<void>((resolve) => {
+      finishTurn = resolve;
+    });
+    (agent.sessions[created.sessionId] as any).turnQueue = [{ completion }];
+
+    const update = agent.unstable_setProvider({
+      providerId: "main",
+      apiType: "anthropic",
+      baseUrl: "https://gateway.example",
+    });
+    await Promise.resolve();
+    await Promise.resolve();
+
+    expect(originalQuery.close).not.toHaveBeenCalled();
+    finishTurn();
+    await update;
+    expect(originalQuery.close).toHaveBeenCalledOnce();
+  });
+
  it("routes bedrock provider config into session env", async () => {
    const [agent, mockQuery] = await createAgentMock();
    await agent.initialize({ protocolVersion: 1, clientCapabilities: {} });
@@ -187,7 +385,7 @@ describe("providers", () => {
        options: expect.objectContaining({
          env: expect.objectContaining({
            CLAUDE_CODE_USE_BEDROCK: "1",
-            AWS_BEARER_TOKEN_BEDROCK: " ",
+            AWS_BEARER_TOKEN_BEDROCK: "acp-proxy",
            ANTHROPIC_BEDROCK_BASE_URL: "https://gateway.example",
            ANTHROPIC_CUSTOM_HEADERS: "custom-header: test",
          }),
@@ -298,6 +496,9 @@ describe("providers", () => {

    await agent.logout({});

-    expect((await agent.unstable_listProviders({})).providers[0].current).toBeNull();
+    expect((await agent.unstable_listProviders({})).providers[0].current).toEqual({
+      apiType: "anthropic",
+      baseUrl: "https://api.anthropic.com",
+    });
  });
 });
--- a/src/tests/resolve-permission-mode.test.ts
+++ b/src/tests/resolve-permission-mode.test.ts
@@ -1,5 +1,6 @@
 import { describe, it, expect, vi } from "vitest";
-import { resolvePermissionMode, type Logger } from "../acp-agent.js";
+import type { Logger } from "../acp-agent.js";
+import { resolvePermissionMode } from "../permissions/modes.js";

 function mockLogger() {
  const error = vi.fn<(...args: any[]) => void>();
--- a/src/tests/session-config-options.test.ts
+++ b/src/tests/session-config-options.test.ts
@@ -358,50 +358,6 @@ describe("session config options", () => {
    });
  });

-  describe("setSessionMode sends config_option_update", () => {
-    beforeEach(() => {
-      populateSession();
-    });
-
-    it("sends config_option_update when mode is changed via setSessionMode", async () => {
-      await agent.setSessionMode({ sessionId: SESSION_ID, modeId: "acceptEdits" });
-
-      const configUpdate = sessionUpdates.find(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      expect(configUpdate).toBeDefined();
-      expect(configUpdate?.update).toMatchObject({
-        sessionUpdate: "config_option_update",
-        configOptions: expect.arrayContaining([
-          expect.objectContaining({ id: "mode", currentValue: "acceptEdits" }),
-        ]),
-      });
-    });
-
-    it("updates stored configOptions currentValue when mode changes", async () => {
-      await agent.setSessionMode({ sessionId: SESSION_ID, modeId: "plan" });
-
-      const session = (
-        agent as unknown as {
-          sessions: Record<string, { configOptions: typeof MOCK_CONFIG_OPTIONS }>;
-        }
-      ).sessions[SESSION_ID];
-      const modeOption = session.configOptions.find((o) => o.id === "mode");
-      expect(modeOption?.currentValue).toBe("plan");
-    });
-
-    it("does not send config_option_update for an invalid mode", async () => {
-      await expect(
-        agent.setSessionMode({ sessionId: SESSION_ID, modeId: "not-a-mode" as any }),
-      ).rejects.toThrow("Invalid Mode");
-
-      const configUpdate = sessionUpdates.find(
-        (n) => n.update.sessionUpdate === "config_option_update",
-      );
-      expect(configUpdate).toBeUndefined();
-    });
-  });
-
  describe("setSessionConfigOption(model) returns updated configOptions", () => {
    beforeEach(() => {
      populateSession();
@@ -1052,26 +1008,25 @@ describe("session config options", () => {
      session.modes = {
        currentModeId,
        availableModes: [
-          {
-            id: "auto",
-            name: "Auto",
-            description: "Use a model classifier to approve/deny permission prompts",
-          },
          {
            id: "default",
-            name: "Default",
-            description: "Standard behavior, prompts for dangerous operations",
+            name: "Manual",
+            description: "Always ask before making changes",
          },
          {
            id: "acceptEdits",
-            name: "Accept Edits",
-            description: "Auto-accept file edit operations",
+            name: "Accept edits",
+            description: "Automatically accept all file edits",
          },
-          { id: "plan", name: "Plan Mode", description: "Planning mode" },
          {
-            id: "dontAsk",
-            name: "Don't Ask",
-            description: "Don't prompt for permissions, deny if not pre-approved",
+            id: "plan",
+            name: "Plan",
+            description: "Create a plan before making changes",
+          },
+          {
+            id: "auto",
+            name: "Auto",
+            description: "Claude handles permission decisions",
          },
        ],
      };
@@ -1111,7 +1066,7 @@ describe("session config options", () => {
      populateSession();
    });

-    it("drops `auto` from available modes when switching to Haiku", async () => {
+    it("keeps the stable mode catalog when switching to Haiku", async () => {
      setupHaikuOpusSession("default");

      const response = await agent.setSessionConfigOption({
@@ -1123,25 +1078,16 @@ describe("session config options", () => {
      const modeOption = response.configOptions.find((o) => o.id === "mode");
      expect(modeOption).toBeDefined();
      const modeValues = (modeOption as any).options.map((o: any) => o.value);
-      expect(modeValues).not.toContain("auto");
      expect(modeValues).toEqual(
-        expect.arrayContaining(["default", "acceptEdits", "plan", "dontAsk"]),
+        expect.arrayContaining(["default", "acceptEdits", "plan", "auto"]),
      );
+      expect(modeValues).not.toContain("dontAsk");
    });

-    it("re-adds `auto` when switching from Haiku back to Opus", async () => {
+    it("keeps the same mode catalog when switching from Haiku back to Opus", async () => {
      const session = setupHaikuOpusSession("default");
-      // Pretend Haiku is the current model with no `auto`.
+      // Pretend Haiku is the current model; its catalog still advertises Auto.
      session.models.currentModelId = "claude-haiku-4-5";
-      session.modes.availableModes = session.modes.availableModes.filter(
-        (m: any) => m.id !== "auto",
-      );
-      const modeOpt = session.configOptions.find((o: any) => o.id === "mode");
-      modeOpt.options = session.modes.availableModes.map((m: any) => ({
-        value: m.id,
-        name: m.name,
-        description: m.description,
-      }));

      const response = await agent.setSessionConfigOption({
        sessionId: SESSION_ID,
@@ -1183,8 +1129,8 @@ describe("session config options", () => {
      expect((modeOption as any).currentValue).toBe("plan");
    });

-    it("clamps mode and emits current_mode_update via setSessionConfigOption(model)", async () => {
-      // Switching Opus(auto) → Haiku clamps the mode to "default". The
+    it("falls back to Accept edits and emits current_mode_update on a Haiku switch", async () => {
+      // Switching Opus(auto) → Haiku changes only the effective mode. The
      // `current_mode_update` side effect must fire so clients learn about the
      // clamp even though the request/response API returns the new
      // configOptions rather than emitting a config_option_update.
@@ -1196,13 +1142,13 @@ describe("session config options", () => {
        value: "claude-haiku-4-5",
      });

-      expect(setPermissionModeSpy).toHaveBeenCalledWith("default");
+      expect(setPermissionModeSpy).toHaveBeenCalledWith("acceptEdits");

      const modeUpdates = sessionUpdates.filter(
        (n) => n.update.sessionUpdate === "current_mode_update",
      );
      expect(modeUpdates).toHaveLength(1);
-      expect((modeUpdates[0].update as any).currentModeId).toBe("default");
+      expect((modeUpdates[0].update as any).currentModeId).toBe("acceptEdits");

      // setSessionConfigOption is a request/response API: it returns the new
      // configOptions in the response rather than emitting a
@@ -1214,148 +1160,16 @@ describe("session config options", () => {

      const modeOption = response.configOptions.find((o: any) => o.id === "mode");
      expect(modeOption).toBeDefined();
-      expect((modeOption as any).currentValue).toBe("default");
-      expect((modeOption as any).options.map((o: any) => o.value)).not.toContain("auto");
-    });
-
-    it("rejects direct setSessionMode to `auto` when the active model does not offer it", async () => {
-      const session = setupHaikuOpusSession("default");
-      session.models.currentModelId = "claude-haiku-4-5";
-      session.modes.availableModes = session.modes.availableModes.filter(
-        (mode: any) => mode.id !== "auto",
-      );
-
-      await expect(agent.setSessionMode({ sessionId: SESSION_ID, modeId: "auto" })).rejects.toThrow(
-        "Mode auto is not available in this session",
-      );
-
-      expect(setPermissionModeSpy).not.toHaveBeenCalledWith("auto");
-      expect(sessionUpdates).toHaveLength(0);
-    });
-  });
-
-  describe("ExitPlanMode permission options filtered by availableModes", () => {
-    let capturedPermissionRequest: any;
-    let permissionResponse: any;
-
-    beforeEach(() => {
-      capturedPermissionRequest = null;
-      permissionResponse = { outcome: { outcome: "cancelled" } };
-      // Replace the default mock client with one that captures the
-      // requestPermission call so we can assert on the offered options.
-      (agent as any).client = {
-        sessionUpdate: async (notification: SessionNotification) => {
-          sessionUpdates.push(notification);
-        },
-        requestPermission: async (params: any) => {
-          capturedPermissionRequest = params;
-          return permissionResponse;
-        },
-        readTextFile: async () => ({ content: "" }),
-        writeTextFile: async () => ({}),
-      };
-      populateSession();
-    });
-
-    it("omits the `auto` option on a model without supportsAutoMode", async () => {
-      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
-      // Haiku-shaped session: availableModes does NOT include `auto`.
-      session.modes = {
-        currentModeId: "plan",
-        availableModes: [
-          { id: "default", name: "Default", description: "Standard" },
-          { id: "acceptEdits", name: "Accept Edits", description: "Auto-accept edits" },
-          { id: "plan", name: "Plan Mode", description: "Planning mode" },
-          { id: "dontAsk", name: "Don't Ask", description: "Deny if not pre-approved" },
-        ],
-      };
-
-      // The tool_call was already surfaced (by the streamed tool_use chunk), so
-      // the permission request won't re-emit one — keep this focused on options.
-      session.emittedToolCalls.add("toolu_1");
-
-      const canUseTool = (agent as any).canUseTool(SESSION_ID);
-      const signal = new AbortController().signal;
-      try {
-        await canUseTool(
-          "ExitPlanMode",
-          { plan: "do stuff" },
-          { signal, suggestions: undefined, toolUseID: "toolu_1" },
-        );
-      } catch {
-        // The mock client returns `cancelled`, which makes canUseTool throw.
-        // We only care about the captured requestPermission options.
-      }
-
-      expect(capturedPermissionRequest).not.toBeNull();
-      const optionIds = capturedPermissionRequest.options.map((o: any) => o.optionId);
-      expect(optionIds).not.toContain("auto");
-      expect(optionIds).toEqual(expect.arrayContaining(["default", "acceptEdits", "plan"]));
-    });
-
-    it("denies a selected `auto` option if the client did not receive that option", async () => {
-      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
-      session.modes = {
-        currentModeId: "plan",
-        availableModes: [
-          { id: "default", name: "Default", description: "Standard" },
-          { id: "acceptEdits", name: "Accept Edits", description: "Auto-accept edits" },
-          { id: "plan", name: "Plan Mode", description: "Planning mode" },
-          { id: "dontAsk", name: "Don't Ask", description: "Deny if not pre-approved" },
-        ],
-      };
-      permissionResponse = { outcome: { outcome: "selected", optionId: "auto" } };
-      // The tool_call was already surfaced (by the streamed tool_use chunk), so
-      // the permission request won't re-emit one — the deny path below should
-      // produce no session updates at all.
-      session.emittedToolCalls.add("toolu_2");
-
-      const canUseTool = (agent as any).canUseTool(SESSION_ID);
-      const result = await canUseTool(
-        "ExitPlanMode",
-        { plan: "do stuff" },
-        { signal: new AbortController().signal, suggestions: undefined, toolUseID: "toolu_2" },
-      );
-
-      expect(capturedPermissionRequest).not.toBeNull();
-      const optionIds = capturedPermissionRequest.options.map((o: any) => o.optionId);
-      expect(optionIds).not.toContain("auto");
-      expect(result.behavior).toBe("deny");
-      expect(sessionUpdates).toHaveLength(0);
-    });
-
-    it("includes the `auto` option on a model with supportsAutoMode", async () => {
-      const session = (agent as unknown as { sessions: Record<string, any> }).sessions[SESSION_ID];
-      session.modes = {
-        currentModeId: "plan",
-        availableModes: [
-          { id: "auto", name: "Auto", description: "Use a model classifier" },
-          { id: "default", name: "Default", description: "Standard" },
-          { id: "acceptEdits", name: "Accept Edits", description: "Auto-accept edits" },
-          { id: "plan", name: "Plan Mode", description: "Planning mode" },
-          { id: "dontAsk", name: "Don't Ask", description: "Deny if not pre-approved" },
-        ],
-      };
-
-      // The tool_call was already surfaced (by the streamed tool_use chunk), so
-      // the permission request won't re-emit one — keep this focused on options.
-      session.emittedToolCalls.add("toolu_3");
-
-      const canUseTool = (agent as any).canUseTool(SESSION_ID);
-      const signal = new AbortController().signal;
-      try {
-        await canUseTool(
-          "ExitPlanMode",
-          { plan: "do stuff" },
-          { signal, suggestions: undefined, toolUseID: "toolu_3" },
-        );
-      } catch {
-        // mock returns cancelled
-      }
-
-      expect(capturedPermissionRequest).not.toBeNull();
-      const optionIds = capturedPermissionRequest.options.map((o: any) => o.optionId);
-      expect(optionIds).toContain("auto");
+      expect((modeOption as any).currentValue).toBe("acceptEdits");
+      expect((modeOption as any).options.map((o: any) => o.value)).toContain("auto");
+      expect(
+        sessionUpdates.filter(
+          (n) =>
+            n.update.sessionUpdate === "agent_message_chunk" &&
+            n.update.content.type === "text" &&
+            n.update.content.text.includes("Auto mode unavailable"),
+        ),
+      ).toHaveLength(1);
    });
  });
 });
--- a/src/tests/session-doubles.ts
+++ b/src/tests/session-doubles.ts
@@ -0,0 +1,124 @@
+/**
+ * Shared session-level test doubles for the agent suites.
+ *
+ * Distinct from `helpers.ts`, which is deliberately vitest-free so `vi.mock`
+ * factories can `await import` it; these need `vi.fn` spies, so they live apart.
+ */
+
+import { vi } from "vitest";
+import { randomUUID } from "crypto";
+import { SessionTitles } from "../session-titles.js";
+
+/** Stand-in agent for a `SessionTitles` whose test doesn't care about titles:
+ *  swallows the publish and the log, and never matches the identity check. */
+function inertTitleAgent() {
+  return {
+    client: { sessionUpdate: async () => {} },
+    logger: { error: () => {} },
+    sessions: {},
+  } as any;
+}
+
+/** Build the replayed `user` message the SDK echoes back for a pushed prompt,
+ *  used by mock generators to promote a turn to active. */
+export function userEcho(u: any) {
+  return {
+    type: "user",
+    message: u.message,
+    parent_tool_use_id: null,
+    uuid: u.uuid,
+    session_id: "test-session",
+    isReplay: true,
+  };
+}
+
+/** Wrap a mock async generator with the `Query` methods the agent calls outside
+ *  of iteration — `close()` (teardown/closeQueryStream), `interrupt()` (cancel),
+ *  and `setModel()` — so a bare generator doesn't trip "x is not a function". */
+export function wrapQuery(generator: AsyncGenerator<any>) {
+  return Object.assign(generator, {
+    interrupt: vi.fn(async () => {}),
+    stopTask: vi.fn(async () => {}),
+    close: vi.fn(),
+    setModel: vi.fn(async () => {}),
+  }) as any;
+}
+
+/** The common `Session` mock fields, with per-test overrides spread on top.
+ *  Centralizes the boilerplate (usage accumulator, caches, controllers) so a new
+ *  Session field is added in one place rather than every inline literal.
+ *
+ *  Pass `agent` when the test exercises titles — `SessionTitles` publishes and
+ *  logs through it, and compares `agent.sessions[sessionId]` to spot a session
+ *  replaced mid-generation. */
+export function mockSessionState(
+  overrides: Record<string, any> = {},
+  agent?: any,
+  sessionId = "test-session",
+) {
+  return {
+    cancelled: false,
+    cwd: "/test",
+    sessionFingerprint: JSON.stringify({ cwd: "/test", mcpServers: [] }),
+    titles: new SessionTitles(agent ?? inertTitleAgent(), sessionId),
+    modes: { currentModeId: "default", availableModes: [] },
+    models: { currentModelId: "default", availableModels: [] },
+    modelInfos: [],
+    settingsManager: { dispose: vi.fn() },
+    accumulatedUsage: {
+      inputTokens: 0,
+      outputTokens: 0,
+      cachedReadTokens: 0,
+      cachedWriteTokens: 0,
+    },
+    accumulatedModelUsage: {},
+    lastModelUsageReading: {},
+    configOptions: [],
+    agents: [],
+    currentAgent: "default",
+    abortController: new AbortController(),
+    emitRawSDKMessages: false,
+    forwardSubagentText: false,
+    contextWindowSize: 200000,
+    contextWindowAuthoritative: false,
+    providerCacheKey: "default",
+    taskState: new Map(),
+    toolUseCache: {},
+    emittedToolCalls: new Set(),
+    liveBackgroundTasks: new Map(),
+    emittedAssistantText: false,
+    owedTrailingIdles: 0,
+    messageIdToUuid: new Map(),
+    sessionFailureState: { epoch: randomUUID(), revisions: new Map(), active: new Map() },
+    fileChangeReportRequestIds: new Set(),
+    ...overrides,
+  } as any;
+}
+
+/** One successful turn: echo the pushed prompt, emit a result, go idle. Shared
+ *  by suites that only need a session to reach turn-end. */
+export function successfulResultMessage(overrides: Record<string, any> = {}) {
+  return {
+    type: "result" as const,
+    subtype: "success",
+    stop_reason: "end_turn",
+    is_error: false,
+    result: "",
+    errors: [],
+    duration_ms: 0,
+    duration_api_ms: 0,
+    num_turns: 1,
+    total_cost_usd: 0,
+    usage: {
+      input_tokens: 0,
+      output_tokens: 0,
+      cache_read_input_tokens: 0,
+      cache_creation_input_tokens: 0,
+    },
+    modelUsage: {},
+    permission_denials: [],
+    uuid: randomUUID(),
+    session_id: "test-session",
+    ...overrides,
+  };
+}
--- a/src/tests/session-mode.test.ts
+++ b/src/tests/session-mode.test.ts
@@ -0,0 +1,170 @@
+import { describe, expect, it, vi } from "vitest";
+import type { SessionNotification } from "@agentclientprotocol/sdk";
+import { AUTO_MODE_FALLBACK, type SessionMode, SessionModeManager } from "../session-mode.js";
+
+const SESSION_ID = "session-1";
+
+function createSession(overrides: Partial<SessionMode> = {}): SessionMode {
+  return {
+    query: { setPermissionMode: vi.fn() },
+    modes: {
+      currentModeId: "default",
+      availableModes: [
+        { id: "default", name: "Manual" },
+        { id: "acceptEdits", name: "Accept edits" },
+        { id: "plan", name: "Plan" },
+        { id: "auto", name: "Auto" },
+      ],
+    },
+    models: { currentModelId: "opus" },
+    modelInfos: [{ value: "opus", displayName: "Opus", description: "", supportsAutoMode: true }],
+    ...overrides,
+  };
+}
+
+function createNotifications(updates: SessionNotification[]) {
+  return {
+    sessionUpdate: vi.fn(async (update: SessionNotification) => {
+      updates.push(update);
+    }),
+    logError: vi.fn(),
+  };
+}
+
+function createManager(session: SessionMode | undefined, updates: SessionNotification[] = []) {
+  const notifications = createNotifications(updates);
+  const updateConfigOption = vi.fn();
+  const manager = new SessionModeManager({
+    ...notifications,
+    getSession: () => session,
+    sessionEndedMessage: "start a new session",
+    updateConfigOption,
+  });
+  return { manager, notifications, updateConfigOption };
+}
+
+describe("session mode", () => {
+  it("applies a valid mode to the SDK query", async () => {
+    const session = createSession();
+    const { manager } = createManager(session);
+    await expect(manager.selectMode(SESSION_ID, "plan")).resolves.toBe("plan");
+    expect(session.query.setPermissionMode).toHaveBeenCalledWith("plan");
+  });
+
+  it("rejects invalid and unavailable modes before touching the query", async () => {
+    const session = createSession();
+    const { manager } = createManager(session);
+    await expect(manager.selectMode(SESSION_ID, "future")).rejects.toThrow("Invalid Mode");
+    await expect(manager.selectMode(SESSION_ID, "bypassPermissions")).rejects.toThrow(
+      "Mode bypassPermissions is not available in this session",
+    );
+    expect(session.query.setPermissionMode).not.toHaveBeenCalled();
+  });
+
+  it("detects model-specific Auto availability", () => {
+    const session = createSession({
+      modelInfos: [
+        { value: "opus", displayName: "Opus", description: "", supportsAutoMode: true },
+        { value: "haiku", displayName: "Haiku", description: "" },
+      ],
+    });
+    const { manager } = createManager(session);
+    expect(manager.effectiveMode(session, "auto")).toBe("auto");
+    session.models.currentModelId = "haiku";
+    expect(manager.effectiveMode(session, "auto")).toBe("acceptEdits");
+    session.models.currentModelId = "unknown";
+    expect(manager.effectiveMode(session, "auto")).toBe("auto");
+  });
+
+  it("falls Auto back to Accept edits and warns only once per session", async () => {
+    const updates: SessionNotification[] = [];
+    const session = createSession({
+      models: { currentModelId: "haiku" },
+      modelInfos: [{ value: "haiku", displayName: "Haiku", description: "" }],
+    });
+    const { manager } = createManager(session, updates);
+
+    await expect(manager.selectMode(SESSION_ID, "auto")).resolves.toBe(AUTO_MODE_FALLBACK);
+    await manager.selectMode(SESSION_ID, "auto");
+
+    expect(session.query.setPermissionMode).toHaveBeenCalledTimes(2);
+    expect(session.query.setPermissionMode).toHaveBeenCalledWith("acceptEdits");
+    expect(
+      updates.filter((notification) => notification.update.sessionUpdate === "agent_message_chunk"),
+    ).toHaveLength(1);
+  });
+
+  it("handles setSessionMode and publishes the updated config option", async () => {
+    const updates: SessionNotification[] = [];
+    const session = createSession();
+    const { manager, notifications, updateConfigOption } = createManager(session, updates);
+
+    await manager.setSessionMode({ sessionId: SESSION_ID, modeId: "plan" });
+
+    expect(updateConfigOption).toHaveBeenCalledWith(SESSION_ID, "mode", "plan");
+    expect(notifications.sessionUpdate).not.toHaveBeenCalledWith(
+      expect.objectContaining({
+        update: expect.objectContaining({ sessionUpdate: "current_mode_update" }),
+      }),
+    );
+  });
+
+  it("rejects missing and closed sessions", async () => {
+    await expect(
+      createManager(undefined).manager.setSessionMode({ sessionId: SESSION_ID, modeId: "plan" }),
+    ).rejects.toThrow("Session not found");
+
+    await expect(
+      createManager(createSession({ queryClosed: true })).manager.setSessionMode({
+        sessionId: SESSION_ID,
+        modeId: "plan",
+      }),
+    ).rejects.toThrow("start a new session");
+  });
+
+  it("initializes the stable mode catalog and falls unsupported Auto back", async () => {
+    const setPermissionMode = vi.fn();
+    const { manager, notifications } = createManager(undefined);
+    const result = await manager.initialize({
+      query: { setPermissionMode },
+      requestedMode: "auto",
+      currentModelInfo: { value: "haiku", displayName: "Haiku", description: "" },
+      currentModelId: "haiku",
+    });
+
+    expect(result.modes.currentModeId).toBe("acceptEdits");
+    expect(result.modes.availableModes.map((mode) => mode.id)).toEqual(
+      expect.arrayContaining(["default", "acceptEdits", "plan", "auto"]),
+    );
+    expect(result.autoModeFallbackWarningPending).toBe(true);
+    expect(setPermissionMode).toHaveBeenCalledWith("acceptEdits");
+    expect(notifications.logError).toHaveBeenCalledWith(expect.stringContaining("falling back"));
+  });
+
+  it("keeps mode state and its config option synchronized", () => {
+    const session = {
+      ...createSession(),
+      configOptions: [SessionModeManager.configOption(createSession().modes)],
+    };
+    createManager(session).manager.syncConfig(session, "plan");
+
+    expect(session.modes.currentModeId).toBe("plan");
+    expect(session.configOptions[0].currentValue).toBe("plan");
+  });
+
+  it("reconciles Auto after a model switch", async () => {
+    const session = createSession();
+    session.modes.currentModeId = "auto";
+    const { manager } = createManager(session);
+
+    await expect(
+      manager.reconcileForModel(session, {
+        value: "haiku",
+        displayName: "Haiku",
+        description: "",
+      }),
+    ).resolves.toBe(true);
+    expect(session.modes.currentModeId).toBe("acceptEdits");
+    expect(session.query.setPermissionMode).toHaveBeenCalledWith("acceptEdits");
+  });
+});
--- a/src/tests/session-permission.test.ts
+++ b/src/tests/session-permission.test.ts
@@ -0,0 +1,98 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import type { SessionNotification } from "@agentclientprotocol/sdk";
+import { ClaudeAcpAgent, type AcpClient } from "../acp-agent.js";
+import { makeMockQuery } from "./helpers.js";
+
+const SESSION_ID = "test-session-id";
+
+describe("session permission updates", () => {
+  let agent: ClaudeAcpAgent;
+  let capturedPermissionRequest: any;
+  let permissionResponse: any;
+  let sessionUpdates: SessionNotification[];
+
+  beforeEach(() => {
+    capturedPermissionRequest = null;
+    permissionResponse = { outcome: { outcome: "cancelled" } };
+    sessionUpdates = [];
+    const client = {
+      sessionUpdate: async (notification: SessionNotification) => {
+        sessionUpdates.push(notification);
+      },
+      requestPermission: async (params: any) => {
+        capturedPermissionRequest = params;
+        return permissionResponse;
+      },
+      readTextFile: async () => ({ content: "" }),
+      writeTextFile: async () => ({}),
+    } as unknown as AcpClient;
+    agent = new ClaudeAcpAgent(client);
+
+    agent.sessions[SESSION_ID] = {
+      query: makeMockQuery(),
+      cwd: process.cwd(),
+      modes: {
+        currentModeId: "plan",
+        availableModes: [
+          { id: "default", name: "Manual" },
+          { id: "acceptEdits", name: "Accept edits" },
+          { id: "plan", name: "Plan" },
+        ],
+      },
+      models: { currentModelId: "opus", availableModels: [] },
+      modelInfos: [],
+      configOptions: [],
+      emittedToolCalls: new Set(["toolu_1"]),
+      contextWindowSize: 200_000,
+      toolUseCache: {},
+    } as any;
+  });
+
+  it("maps an ExitPlanMode choice to the selected session mode effect", async () => {
+    permissionResponse = { outcome: { outcome: "selected", optionId: "exit-plan-default" } };
+
+    const result = await (agent as any).canUseTool(SESSION_ID)(
+      "ExitPlanMode",
+      { plan: "do stuff" },
+      { signal: new AbortController().signal, toolUseID: "toolu_1" },
+    );
+
+    expect(capturedPermissionRequest.options.map((option: any) => option.optionId)).toEqual([
+      "exit-plan-default",
+      "exit-plan-clear-accept-edits",
+      "exit-plan-accept-edits",
+      "reject",
+    ]);
+    expect(capturedPermissionRequest._meta).toEqual({
+      permission: { version: 1, title: "Ready to code?" },
+    });
+    expect(result.updatedPermissions).toEqual([
+      { type: "setMode", mode: "default", destination: "session" },
+    ]);
+    expect(agent.sessions[SESSION_ID].modes.currentModeId).toBe("plan");
+    expect(sessionUpdates).toHaveLength(0);
+  });
+
+  it("falls an Auto permission effect back when the current model cannot use Auto", async () => {
+    const session = agent.sessions[SESSION_ID];
+    session.modes.availableModes.push({ id: "auto", name: "Auto" });
+    session.models.currentModelId = "haiku";
+    session.modelInfos = [{ value: "haiku", displayName: "Haiku", description: "" }];
+    permissionResponse = { outcome: { outcome: "selected", optionId: "exit-plan-auto" } };
+
+    const result = await (agent as any).canUseTool(SESSION_ID)(
+      "ExitPlanMode",
+      { plan: "do stuff" },
+      { signal: new AbortController().signal, toolUseID: "toolu_1" },
+    );
+
+    expect(result.updatedPermissions).toEqual([
+      { type: "setMode", mode: "acceptEdits", destination: "session" },
+    ]);
+    expect(
+      sessionUpdates.filter(
+        (notification) => notification.update.sessionUpdate === "agent_message_chunk",
+      ),
+    ).toHaveLength(1);
+  });
+});
--- a/src/tests/session-titles.test.ts
+++ b/src/tests/session-titles.test.ts
@@ -0,0 +1,338 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { ClaudeAcpAgent, type AcpClient } from "../acp-agent.js";
+import { appendTitleContext } from "../session-titles.js";
+import { Pushable } from "../utils.js";
+import { getSessionInfo } from "@anthropic-ai/claude-agent-sdk";
+import {
+  mockSessionState,
+  successfulResultMessage,
+  userEcho,
+  wrapQuery,
+} from "./session-doubles.js";
+
+vi.mock("@anthropic-ai/claude-agent-sdk", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@anthropic-ai/claude-agent-sdk")>();
+  return { ...actual, getSessionInfo: vi.fn() };
+});
+
+describe("SDK title generation contract", () => {
+  // Smoke test for the one undeclared SDK method this feature rests on:
+  // `generateSessionTitle` is on the runtime `Query` class but absent from
+  // `sdk.d.ts`, so nothing else would catch its removal. Method names survive
+  // bundling (only module-scope identifiers get mangled), so an SDK upgrade that
+  // renames or drops it fails here instead of silently degrading titles back to
+  // raw prompts. Runs unconditionally — it reads the shipped bundle and never
+  // spawns the CLI.
+  it("SDK still ships generateSessionTitle and its control subtype", async () => {
+    const sdkEntry = createRequire(import.meta.url).resolve("@anthropic-ai/claude-agent-sdk");
+    const bundle = await readFile(sdkEntry, "utf8");
+    expect({
+      method: bundle.includes("async generateSessionTitle("),
+      subtype: bundle.includes('subtype:"generate_session_title"'),
+    }).toEqual({ method: true, subtype: true });
+  });
+
+  it("keeps only the trailing title context", () => {
+    expect(appendTitleContext("abc", "def")).toBe("abcdef");
+    expect(appendTitleContext(undefined, "abc")).toBe("abc");
+    const overflowed = appendTitleContext("x".repeat(1000), "tail");
+    expect(overflowed).toHaveLength(1000);
+    expect(overflowed.endsWith("tail")).toBe(true);
+  });
+});
+
+describe("session titles at turn-end", () => {
+  beforeEach(() => {
+    vi.mocked(getSessionInfo).mockReset();
+  });
+
+  /** Collect every `session_info_update` an agent pushes. */
+  function titleRecorder() {
+    const updates: any[] = [];
+    const client = {
+      sessionUpdate: async (u: any) => {
+        if (u.update?.sessionUpdate === "session_info_update") updates.push(u.update);
+      },
+    } as unknown as AcpClient;
+    return { client, titles: () => updates.map((u) => u.title) };
+  }
+
+  /** `wrapQuery` plus the undeclared `generateSessionTitle` the real `Query`
+   *  exposes, so turn-end takes the generate branch. */
+  function wrapTitleQuery(generator: AsyncGenerator<any>, title: string | null) {
+    const generateSessionTitle = vi.fn(async (_d: string, _o?: { persist?: boolean }) => title);
+    return {
+      query: Object.assign(wrapQuery(generator), { generateSessionTitle }),
+      generateSessionTitle,
+    };
+  }
+
+  /** One turn: echo the pushed prompt, succeed, go idle. */
+  async function* oneTurn(input: Pushable<any>, turns = 1) {
+    const iter = input[Symbol.asyncIterator]();
+    for (let i = 0; i < turns; i++) {
+      const { value: userMessage } = await iter.next();
+      yield userEcho(userMessage);
+      yield successfulResultMessage();
+      yield { type: "system", subtype: "session_state_changed", state: "idle" };
+    }
+  }
+
+  function newAgent(client: AcpClient) {
+    return new ClaudeAcpAgent(client, { log: () => {}, error: () => {} });
+  }
+
+  const LONG_PROMPT = "Explain what the add function in hello.py does, in one sentence";
+
+  it("pushes a session_info_update when the SDK generates a title at turn-end", async () => {
+    const sessionUpdates: any[] = [];
+    const agent = newAgent({
+      sessionUpdate: async (u: any) => {
+        sessionUpdates.push(u);
+      },
+    } as unknown as AcpClient);
+
+    vi.mocked(getSessionInfo).mockResolvedValue({
+      sessionId: "test-session",
+      summary: "Fix the flaky title test",
+      lastModified: 1_700_000_000_000,
+    } as any);
+
+    const input = new Pushable<any>();
+    agent.sessions["test-session"] = mockSessionState(
+      {
+        query: wrapQuery(oneTurn(input)),
+        input,
+      },
+      agent,
+    );
+
+    await agent.prompt({ sessionId: "test-session", prompt: [{ type: "text", text: "test" }] });
+    await agent.sessions["test-session"]?.consumer;
+
+    const titleUpdate = sessionUpdates.find(
+      (u) => u.update?.sessionUpdate === "session_info_update",
+    );
+    expect(titleUpdate?.update).toEqual({
+      sessionUpdate: "session_info_update",
+      title: "Fix the flaky title test",
+      updatedAt: new Date(1_700_000_000_000).toISOString(),
+    });
+    expect(getSessionInfo).toHaveBeenCalledWith("test-session", { dir: "/test" });
+  });
+
+  it("does not re-push session_info_update when the title is unchanged", async () => {
+    const { client, titles } = titleRecorder();
+    const agent = newAgent(client);
+
+    vi.mocked(getSessionInfo).mockResolvedValue({
+      sessionId: "test-session",
+      summary: "Stable title",
+      lastModified: 1_700_000_000_000,
+    } as any);
+
+    const input = new Pushable<any>();
+    agent.sessions["test-session"] = mockSessionState(
+      {
+        query: wrapQuery(oneTurn(input, 2)),
+        input,
+      },
+      agent,
+    );
+
+    await agent.prompt({ sessionId: "test-session", prompt: [{ type: "text", text: "one" }] });
+    await agent.prompt({ sessionId: "test-session", prompt: [{ type: "text", text: "two" }] });
+    await agent.sessions["test-session"]?.consumer;
+
+    expect(titles()).toEqual(["Stable title"]);
+  });
+
+  it("generates a title at turn-end instead of publishing the raw prompt", async () => {
+    const { client, titles } = titleRecorder();
+    const agent = newAgent(client);
+
+    // What an SDK-driven session really looks like: nothing has written a title,
+    // so `summary` is just the opening prompt.
+    vi.mocked(getSessionInfo).mockResolvedValue({
+      sessionId: "test-session",
+      summary: LONG_PROMPT,
+      lastModified: 1_700_000_000_000,
+    } as any);
+
+    const input = new Pushable<any>();
+    const { query, generateSessionTitle } = wrapTitleQuery(
+      oneTurn(input),
+      "Explain add() in hello.py",
+    );
+    agent.sessions["test-session"] = mockSessionState({ query, input }, agent);
+
+    await agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: LONG_PROMPT }],
+    });
+    await agent.sessions["test-session"]?.consumer;
+    // Generation is fired off the turn-end path, so it lands after `idle`.
+    await vi.waitFor(() => {
+      expect(generateSessionTitle).toHaveBeenCalledTimes(1);
+    });
+
+    expect(generateSessionTitle).toHaveBeenCalledWith(LONG_PROMPT, { persist: true });
+    // The raw prompt was never published — only the generated title.
+    expect(titles()).toEqual(["Explain add() in hello.py"]);
+  });
+
+  it("adopts a stored title and never generates over it", async () => {
+    const { client, titles } = titleRecorder();
+    const agent = newAgent(client);
+
+    // The SDK folds a `/rename` and an earlier generated title into the same
+    // field, so a non-empty `customTitle` means hands off.
+    vi.mocked(getSessionInfo).mockResolvedValue({
+      sessionId: "test-session",
+      summary: "Renamed by the user",
+      customTitle: "Renamed by the user",
+      lastModified: 1_700_000_000_000,
+    } as any);
+
+    const input = new Pushable<any>();
+    const { query, generateSessionTitle } = wrapTitleQuery(oneTurn(input), "Generated instead");
+    agent.sessions["test-session"] = mockSessionState({ query, input }, agent);
+
+    await agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: LONG_PROMPT }],
+    });
+    await agent.sessions["test-session"]?.consumer;
+
+    expect(generateSessionTitle).not.toHaveBeenCalled();
+    expect(titles()).toEqual(["Renamed by the user"]);
+  });
+
+  it("generates once per session, and a later turn can't fall back to the prompt", async () => {
+    const { client, titles } = titleRecorder();
+    const agent = newAgent(client);
+
+    // `getSessionInfo` never reports the persisted title here, so the
+    // once-per-session latch is the only thing holding the second turn back.
+    vi.mocked(getSessionInfo).mockResolvedValue({
+      sessionId: "test-session",
+      summary: LONG_PROMPT,
+      lastModified: 1_700_000_000_000,
+    } as any);
+
+    const input = new Pushable<any>();
+    const { query, generateSessionTitle } = wrapTitleQuery(
+      oneTurn(input, 2),
+      "Explain add() in hello.py",
+    );
+    agent.sessions["test-session"] = mockSessionState({ query, input }, agent);
+
+    await agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: LONG_PROMPT }],
+    });
+    await vi.waitFor(() => {
+      expect(generateSessionTitle).toHaveBeenCalledTimes(1);
+    });
+    await agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: "And what is the capital of France?" }],
+    });
+    await agent.sessions["test-session"]?.consumer;
+
+    expect(generateSessionTitle).toHaveBeenCalledTimes(1);
+    expect(titles()).toEqual(["Explain add() in hello.py"]);
+  });
+
+  it("releases the latch when generation yields no title", async () => {
+    const { client, titles } = titleRecorder();
+    const agent = newAgent(client);
+
+    vi.mocked(getSessionInfo).mockResolvedValue({
+      sessionId: "test-session",
+      summary: LONG_PROMPT,
+      lastModified: 1_700_000_000_000,
+    } as any);
+
+    const input = new Pushable<any>();
+    const { query, generateSessionTitle } = wrapTitleQuery(oneTurn(input, 2), null);
+    agent.sessions["test-session"] = mockSessionState({ query, input }, agent);
+
+    await agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: LONG_PROMPT }],
+    });
+    await vi.waitFor(() => {
+      expect(generateSessionTitle).toHaveBeenCalledTimes(1);
+    });
+    await agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: "And what is the capital of France?" }],
+    });
+    await agent.sessions["test-session"]?.consumer;
+    await vi.waitFor(() => {
+      expect(generateSessionTitle).toHaveBeenCalledTimes(2);
+    });
+
+    // Nothing generated, so the client still gets the summary fallback.
+    expect(titles()).toEqual([LONG_PROMPT]);
+  });
+
+  it("skips argument-less slash commands and bash openers when building the title context", async () => {
+    const { client } = titleRecorder();
+    const agent = newAgent(client);
+
+    vi.mocked(getSessionInfo).mockResolvedValue({
+      sessionId: "test-session",
+      summary: "/compact",
+      lastModified: 1_700_000_000_000,
+    } as any);
+
+    const input = new Pushable<any>();
+    const { query, generateSessionTitle } = wrapTitleQuery(oneTurn(input), "Compact the session");
+    agent.sessions["test-session"] = mockSessionState({ query, input }, agent);
+
+    await agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: "/compact" }],
+    });
+    await agent.sessions["test-session"]?.consumer;
+
+    expect(generateSessionTitle).not.toHaveBeenCalled();
+  });
+
+  it("includes slash-command arguments in the title context", async () => {
+    const { client, titles } = titleRecorder();
+    const agent = newAgent(client);
+
+    vi.mocked(getSessionInfo).mockResolvedValue({
+      sessionId: "test-session",
+      summary: "/investigate-alert kafka lag on prod-3",
+      lastModified: 1_700_000_000_000,
+    } as any);
+
+    const input = new Pushable<any>();
+    const { query, generateSessionTitle } = wrapTitleQuery(
+      oneTurn(input),
+      "Investigate Kafka lag alert on prod-3",
+    );
+    agent.sessions["test-session"] = mockSessionState({ query, input }, agent);
+
+    await agent.prompt({
+      sessionId: "test-session",
+      prompt: [{ type: "text", text: "/investigate-alert kafka lag on prod-3" }],
+    });
+    await agent.sessions["test-session"]?.consumer;
+
+    await vi.waitFor(() => {
+      expect(generateSessionTitle).toHaveBeenCalledTimes(1);
+    });
+    expect(generateSessionTitle).toHaveBeenCalledWith(
+      expect.stringContaining("/investigate-alert kafka lag on prod-3"),
+      { persist: true },
+    );
+    expect(titles()).toEqual(["Investigate Kafka lag alert on prod-3"]);
+  });
+});
--- a/src/tests/tools.test.ts
+++ b/src/tests/tools.test.ts
@@ -18,6 +18,8 @@ import {
  toolUpdateFromToolResult,
  createPostToolUseHook,
  createTaskHook,
+  clearHookCallbacks,
+  registerHookCallback,
  toolInfoFromToolUse,
  planEntries,
  applyTaskCreate,
@@ -29,6 +31,32 @@ import {
  TaskState,
 } from "../tools.js";

+describe("PostToolUse callback ownership", () => {
+  it("clears only callbacks owned by the cancelled session", async () => {
+    const first = vi.fn(async () => {});
+    const second = vi.fn(async () => {});
+    registerHookCallback("owned-first", { onPostToolUseHook: first }, "session-one");
+    registerHookCallback("owned-second", { onPostToolUseHook: second }, "session-two");
+
+    clearHookCallbacks("session-one");
+    const hook = createPostToolUseHook();
+    const context = { signal: new AbortController().signal };
+    await hook(
+      { hook_event_name: "PostToolUse", tool_input: {}, tool_response: {} } as any,
+      "owned-first",
+      context,
+    );
+    await hook(
+      { hook_event_name: "PostToolUse", tool_input: {}, tool_response: {} } as any,
+      "owned-second",
+      context,
+    );
+
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledOnce();
+  });
+});
+
 describe("rawOutput in tool call updates", () => {
  const mockClient = {} as AcpClient;
  const mockLogger: Logger = { log: () => {}, error: () => {} };
@@ -939,6 +967,7 @@ describe("Bash terminal output", () => {
      // terminal_info and terminal_output should NOT be on the exit notification
      expect((exitUpdate as any)._meta).not.toHaveProperty("terminal_info");
      expect((exitUpdate as any)._meta).not.toHaveProperty("terminal_output");
+      expect(exitUpdate).not.toHaveProperty("rawOutput");
    });

    it("should not include terminal _meta when client does not declare terminal_output support", () => {
@@ -961,6 +990,7 @@ describe("Bash terminal output", () => {
      expect((update as any)._meta).not.toHaveProperty("terminal_info");
      expect((update as any)._meta).not.toHaveProperty("terminal_output");
      expect((update as any)._meta).not.toHaveProperty("terminal_exit");
+      expect(update).toHaveProperty("rawOutput", bashResult);
    });

    it("should not include terminal _meta when _meta.terminal_output is false", () => {
@@ -1114,6 +1144,7 @@ describe("Bash terminal output", () => {
        toolUseCache,
        mockClientWithUpdate,
        mockLogger,
+        { parentToolUseId: "parent-agent-tool" },
      );

      // Fire PostToolUse hook with a structuredPatch in tool_response
@@ -1153,6 +1184,7 @@ describe("Bash terminal output", () => {
      expect(hookUpdates).toHaveLength(1);
      const hookUpdate = hookUpdates[0].update;
      expect(hookUpdate._meta.claudeCode.toolName).toBe("Edit");
+      expect(hookUpdate._meta.claudeCode.parentToolUseId).toBe("parent-agent-tool");
      expect(hookUpdate.content).toEqual([
        {
          type: "diff",
@@ -1683,7 +1715,7 @@ describe("toolInfoFromToolUse - ExitPlanMode", () => {
    const info = toolInfoFromToolUse(toolUse, false);

    expect(info.kind).toBe("switch_mode");
-    expect(info.title).toBe("Ready to code?");
+    expect(info.title).toBe("Approve Plan");
    expect(info.content).toHaveLength(1);
    expect(info.content![0]).toEqual({
      type: "content",
@@ -1732,6 +1764,16 @@ describe("toolInfoFromToolUse - undefined input regression", () => {
    expect(info.title).toBe("Web search");
  });

+  it("shows a WebSearch query in the tool title", () => {
+    const toolUse = {
+      name: "WebSearch",
+      id: "toolu_ws_query",
+      input: { query: "Agent Client Protocol ACP specification subagents v2" },
+    };
+    const info = toolInfoFromToolUse(toolUse, false);
+    expect(info.title).toBe('Search "Agent Client Protocol ACP specification subagents v2"');
+  });
+
  it("TodoWrite with undefined input should not throw", () => {
    const toolUse = { name: "TodoWrite", id: "toolu_todo_undef", input: undefined };
    const info = toolInfoFromToolUse(toolUse, false);
@@ -2734,6 +2776,62 @@ describe("tool_result_meta non-execution stamping", () => {
    content: "The user doesn't want to proceed with this tool use.",
  };

+  it("removes Claude's outer fence from a rejected ExitPlanMode explanation only", () => {
+    const toolUseCache: ToolUseCache = {
+      toolu_plan: {
+        type: "tool_use",
+        id: "toolu_plan",
+        name: "ExitPlanMode",
+        input: { plan: "Implement it" },
+      },
+    };
+
+    const notifications = toAcpNotifications(
+      [
+        {
+          type: "tool_result",
+          tool_use_id: "toolu_plan",
+          is_error: true,
+          content: "```\nThe user chose to keep planning.\n```",
+        },
+      ] as any,
+      "user",
+      "test-session",
+      toolUseCache,
+      mockClient,
+      mockLogger,
+      { toolResultMeta: [{ id: "toolu_plan", non_execution_kind: "user-rejected" }] },
+    );
+
+    expect(notifications).toHaveLength(1);
+    expect(notifications[0].update).toMatchObject({
+      sessionUpdate: "tool_call_update",
+      toolCallId: "toolu_plan",
+      status: "failed",
+      rawOutput: "The user chose to keep planning.",
+    });
+  });
+
+  it("preserves fenced output from tools other than ExitPlanMode", () => {
+    const fenced = "```text\ncommand output\n```";
+    const notifications = toAcpNotifications(
+      [
+        {
+          type: "tool_result",
+          tool_use_id: "toolu_bash",
+          content: fenced,
+        },
+      ] as any,
+      "user",
+      "test-session",
+      { toolu_bash: bashToolUse },
+      mockClient,
+      mockLogger,
+    );
+
+    expect(notifications[0].update).toMatchObject({ rawOutput: fenced });
+  });
+
  it("stamps nonExecutionKind and userFeedback on the failed tool_call_update", () => {
    const toolUseCache: ToolUseCache = { toolu_bash: bashToolUse };

--- a/src/tool-result-meta.ts
+++ b/src/tool-result-meta.ts
@@ -0,0 +1,22 @@
+export type ToolResultMeta = {
+  nonExecutionKind: string;
+  userFeedback?: string;
+};
+
+/** Validate the SDK's currently untyped tool_result_meta sidecar. Unknown
+ * non-execution kinds are preserved so newer CLIs remain forward-compatible. */
+export function parseToolResultMeta(raw: unknown): Map<string, ToolResultMeta> | undefined {
+  if (!Array.isArray(raw)) return undefined;
+
+  let byToolUseId: Map<string, ToolResultMeta> | undefined;
+  for (const entry of raw) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const { id, non_execution_kind, user_feedback } = entry as Record<string, unknown>;
+    if (typeof id !== "string" || typeof non_execution_kind !== "string") continue;
+    (byToolUseId ??= new Map()).set(id, {
+      nonExecutionKind: non_execution_kind,
+      ...(typeof user_feedback === "string" ? { userFeedback: user_feedback } : {}),
+    });
+  }
+  return byToolUseId;
+}
--- a/src/tools.ts
+++ b/src/tools.ts
@@ -349,18 +349,9 @@ export function toolInfoFromToolUse(

    case "WebSearch": {
      const input = toolUse.input as WebSearchInput | undefined;
-      let label = input?.query ? `"${input.query}"` : "Web search";
-
-      if (input?.allowed_domains && input.allowed_domains.length > 0) {
-        label += ` (allowed: ${input.allowed_domains.join(", ")})`;
-      }
-
-      if (input?.blocked_domains && input.blocked_domains.length > 0) {
-        label += ` (blocked: ${input.blocked_domains.join(", ")})`;
-      }

      return {
-        title: label,
+        title: input?.query ? `Search "${input.query}"` : "Web search",
        kind: "fetch",
        content: [],
      };
@@ -433,7 +424,7 @@ export function toolInfoFromToolUse(
    case "ExitPlanMode": {
      const planInput = toolUse.input as { plan?: string } | undefined;
      return {
-        title: "Ready to code?",
+        title: "Approve Plan",
        kind: "switch_mode",
        content: planInput?.plan
          ? [{ type: "content" as const, content: { type: "text" as const, text: planInput.plan } }]
@@ -1345,16 +1336,20 @@ export function toolUpdateFromDiffToolResponse(toolResponse: unknown): {
  return result;
 }

-/* A global variable to store callbacks that should be executed when receiving hooks from Claude Code */
-const toolUseCallbacks: {
-  [toolUseId: string]: {
+/* Callbacks are keyed globally because the SDK hook is process-wide, but each
+ * entry retains its owning ACP session so cancellation/teardown can release it. */
+const toolUseCallbacks = new Map<
+  string,
+  {
+    ownerId?: string;
+    cleanupTimer?: ReturnType<typeof setTimeout>;
    onPostToolUseHook?: (
      toolUseID: string,
      toolInput: unknown,
      toolResponse: unknown,
    ) => Promise<void>;
-  };
-} = {};
+  }
+>();

 /* Setup callbacks that will be called when receiving hooks from Claude Code */
 export const registerHookCallback = (
@@ -1368,12 +1363,36 @@ export const registerHookCallback = (
      toolResponse: unknown,
    ) => Promise<void>;
  },
+  ownerId?: string,
 ) => {
-  toolUseCallbacks[toolUseID] = {
+  unregisterHookCallback(toolUseID);
+  toolUseCallbacks.set(toolUseID, {
+    ownerId,
    onPostToolUseHook,
-  };
+  });
 };

+export function unregisterHookCallback(toolUseID: string): void {
+  const callback = toolUseCallbacks.get(toolUseID);
+  if (callback?.cleanupTimer) clearTimeout(callback.cleanupTimer);
+  toolUseCallbacks.delete(toolUseID);
+}
+
+/** PostToolUse normally follows tool_result, so keep the callback for a short
+ * grace period while still bounding retention when the hook never arrives. */
+export function completeHookCallback(toolUseID: string): void {
+  const callback = toolUseCallbacks.get(toolUseID);
+  if (!callback || callback.cleanupTimer) return;
+  callback.cleanupTimer = setTimeout(() => unregisterHookCallback(toolUseID), 30_000);
+  callback.cleanupTimer.unref?.();
+}
+
+export function clearHookCallbacks(ownerId: string): void {
+  for (const [toolUseID, callback] of toolUseCallbacks) {
+    if (callback.ownerId === ownerId) unregisterHookCallback(toolUseID);
+  }
+}
+
 /* A callback for Claude Code that is called when receiving a PostToolUse hook */
 export const createPostToolUseHook =
  (options?: { onEnterPlanMode?: () => Promise<void> }): HookCallback =>
@@ -1385,11 +1404,14 @@ export const createPostToolUseHook =
      }

      if (toolUseID) {
-        const onPostToolUseHook = toolUseCallbacks[toolUseID]?.onPostToolUseHook;
-        if (onPostToolUseHook) {
-          await onPostToolUseHook(toolUseID, input.tool_input, input.tool_response);
+        const onPostToolUseHook = toolUseCallbacks.get(toolUseID)?.onPostToolUseHook;
+        try {
+          if (onPostToolUseHook) {
+            await onPostToolUseHook(toolUseID, input.tool_input, input.tool_response);
+          }
+        } finally {
+          unregisterHookCallback(toolUseID);
        }
-        delete toolUseCallbacks[toolUseID]; // Cleanup after execution
      }
    }
    return { continue: true };