@agentclientprotocol/claude-agent-acp 0.70.0 → 0.71.0

package/dist/acp-agent.js

@@ -1,6 +1,11 @@
-import { agent as acpAgent, methods, ndJsonStream, RequestError, } from "@agentclientprotocol/sdk";
-import { deleteSession, getSessionInfo, getSessionMessages, listSessions, query, } from "@anthropic-ai/claude-agent-sdk";
+import { agent as acpAgent, CreateElicitationResponse, methods, ndJsonStream, RequestError, } from "@agentclientprotocol/sdk";
+import { deleteSession, getSessionMessages, listSessions, query, } from "@anthropic-ai/claude-agent-sdk";
 import { GOAL_ACTIONS, GOAL_CONTROL_METHOD, GOAL_EXTENSION_VERSION, goalUpdateFromPrompt, parseGoalRequest, toGoalSnapshot, } from "./goal-extension.js";
+import { sanitizeTitle, SessionTitles } from "./session-titles.js";
+import { AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY, asSdkSessionNotification, clientSupportsSubagents, } from "./acp-subagents.js";
+import { isNativeSubagentControlTool, isNativeSubagentControlUpdate, NativeSubagentRuntime, } from "./native-subagents.js";
+import { AIR_ASYNC_TASKS_CAPABILITY, withAirMeta } from "./air-extension.js";
+import { AsyncTaskRuntime, backgroundBashTaskFromToolResult, clientSupportsAsyncTasks, } from "./async-tasks.js";
 import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
@@ -10,25 +15,37 @@ import * as path from "node:path";
 import { promisify } from "node:util";
 import packageJson from "../package.json" with { type: "json" };
 import { applyAskElicitationResponse, askUserQuestionsToCreateRequest, createElicitationResponseToElicitResult, extractAskUserQuestions, extractRefusalFallbackPrompt, mcpElicitationToCreateRequest, REFUSAL_FALLBACK_DIALOG_KIND, refusalFallbackResultFromResponse, refusalFallbackToCreateRequest, } from "./elicitation.js";
+import { forkSession } from "./fork-session.js";
+import { ALLOW_BYPASS, resolvePermissionMode } from "./permissions/modes.js";
+import { normalizeDurablePermissionChangeSet } from "./permissions/normalization.js";
+import { buildClaudePermissionOptions } from "./permissions/options.js";
+import { buildClaudePermissionPresentation } from "./permissions/presentation.js";
+import { decodeClaudePermissionResponse } from "./permissions/response.js";
 import { SettingsManager } from "./settings.js";
 import { activeUsageLimitMessage, airSessionFailureCapabilityMeta, assistantMessageText, createSessionFailureState, isSyntheticUsageLimitMessage, providerFailureCategory, SessionFailureController, sessionFailureMeta, supportsAirSessionFailures, } from "./session-failure-extension.js";
 import { AGENT_FILE_CHANGE_REPORT_CAPABILITY, agentFileChangeReportMeta, agentFileChangeReportRequestId, containsFileChangeAuditMarker, createFileChangeAuditSupport, createFileChangeAuditTurnState, FILE_CHANGE_AUDIT_SERVER_NAME, isFileChangeAuditReportPhase, isFileChangeAuditTool, supportsAgentFileChangeReport, } from "./file-change-audit.js";
-import { applyTaskCreate, applyTaskList, applyTaskUpdate, createPostToolUseHook, createTaskHook, parseTaskCreateOutput, parseTaskListOutput, parseTaskUpdateOutput, planEntries, registerHookCallback, taskStateToPlanEntries, toolInfoFromToolUse, toolUpdateFromDiffToolResponse, toolUpdateFromToolResult, } from "./tools.js";
+import { applyTaskCreate, applyTaskList, applyTaskUpdate, clearHookCallbacks, completeHookCallback, createPostToolUseHook, createTaskHook, parseTaskCreateOutput, parseTaskListOutput, parseTaskUpdateOutput, planEntries, registerHookCallback, taskStateToPlanEntries, toolInfoFromToolUse, toolUpdateFromDiffToolResponse, toolUpdateFromToolResult, unregisterHookCallback, } from "./tools.js";
 import { nodeToWebReadable, nodeToWebWritable, Pushable, unreachable } from "./utils.js";
+import { acceptedPlanToolResult, ExitPlanCoordinator, executionDiagnostic, exitPlanModeRawOutput, observeExitPlanToolResults, } from "./exit-plan.js";
+import { DEFAULT_AGENT_ID, EFFORT_CONFIG_ID } from "./session-config-ids.js";
+import { parseToolResultMeta } from "./tool-result-meta.js";
+export { DEFAULT_AGENT_ID, EFFORT_CONFIG_ID } from "./session-config-ids.js";
+import { MODE_CONFIG_ID, SessionModeManager } from "./session-mode.js";
 export const CLAUDE_CONFIG_DIR = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
 const execFileAsync = promisify(execFile);
-const MAX_TITLE_LENGTH = 256;
 const MAX_INLINE_FAILURE_TITLE_LENGTH = 256;
-function sanitizeTitle(text) {
-    // 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) + "…";
+/** Claude CLI emits this synthetic result when an interrupted cycle ends on
+ *  queued user input before producing any assistant content. It is a hand-off
+ *  marker, not the outcome of the replacement prompt that may already be
+ *  active by the time the SDK stream delivers it. */
+function isEmptyUserInterruptionDiagnostic(message) {
+    const diagnostic = "result" in message
+        ? message.result
+        : message.errors.find((error) => error.startsWith("[ede_diagnostic]"));
+    return (diagnostic?.startsWith("[ede_diagnostic]") === true &&
+        /(?:^|\s)result_type=user(?:\s|$)/.test(diagnostic) &&
+        /(?:^|\s)last_content_type=n\/a(?:\s|$)/.test(diagnostic) &&
+        /(?:^|\s)stop_reason=null(?:\s|$)/.test(diagnostic));
 }
 const ZERO_USAGE = Object.freeze({
     input_tokens: 0,
@@ -47,6 +64,31 @@ const DEFAULT_CONTEXT_WINDOW = 200000;
  *  "obviously stuck" ceiling, not a guess at interrupt latency, so it can't
  *  pre-empt a slow-but-healthy interrupt. */
 const DEFAULT_FORCE_CANCEL_GRACE_MS = 30_000;
+/** Claude Code keeps the OAuth callback listener open in the background after
+ *  `mcpAuthenticate` returns the authorization URL. The SDK does not expose
+ *  that listener's completion promise, so watch the server status while the
+ *  ACP client has the URL elicitation open. */
+const MCP_OAUTH_STATUS_POLL_MS = 1_000;
+const MCP_OAUTH_TIMEOUT_MS = 10 * 60_000;
+function supportsMcpOAuth(query) {
+    return typeof query.mcpAuthenticate === "function";
+}
+/** Wait for a polling interval, resolving false when the session is aborted. */
+function waitUnlessAborted(milliseconds, signal) {
+    if (signal.aborted)
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(true);
+        }, milliseconds);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve(false);
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
 /** Error surfaced when the SDK declares a turn over (`session_state_changed:
  *  idle`, its authoritative turn-over signal) without ever emitting the turn's
  *  `result` — a model stream that dropped mid-turn, or an async agent that
@@ -59,13 +101,30 @@ const TURN_NO_RESULT_MESSAGE = "The turn ended without a result: the agent went
  *  agreed ACP steering wire protocol; advertised to clients via the top-level
  *  `InitializeResponse._meta.steering.supported`. */
 const STEER_METHOD = "_session/steering";
+/** Stops one Claude background task without cancelling the parent prompt turn. */
+const ASYNC_TASK_STOP_METHOD = "_session/async_task/stop";
+function parseAsyncTaskStopRequest(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw RequestError.invalidParams(undefined, "async task stop params must be an object");
+    }
+    const params = value;
+    const sessionId = typeof params.sessionId === "string" ? params.sessionId.trim() : "";
+    const asyncTaskId = typeof params.asyncTaskId === "string" ? params.asyncTaskId.trim() : "";
+    if (!sessionId) {
+        throw RequestError.invalidParams(undefined, "async task stop params require a non-empty sessionId");
+    }
+    if (!asyncTaskId) {
+        throw RequestError.invalidParams(undefined, "async task stop params require a non-empty asyncTaskId");
+    }
+    return { sessionId, asyncTaskId };
+}
 /** How urgently the SDK delivers a steered message relative to the running
  *  turn — an internal Claude implementation detail, not part of the wire
- *  contract. `now` pre-empts the current generation and handles the message
- *  immediately (interrupting a single-shot response, or slotting in between a
- *  multi-step turn's tool calls). Maps to `SDKUserMessage.priority`; injected
- *  steering always uses `now` so the running turn adapts as soon as possible. */
-const STEER_PRIORITY = "now";
+ *  contract. `now` pre-empts the current generation, while `later` waits for a
+ *  pending permission/elicitation callback to settle instead of cancelling its
+ *  ACP request and hiding the client's user-input card (IJAI-1191). */
+const STEER_PRIORITY_NOW = "now";
+const STEER_PRIORITY_LATER = "later";
 /** Validate raw JSON-RPC params into a {@link SteerRequest}. Kept minimal — the
  *  content blocks are handed to `promptToClaude`, which tolerates unknown block
  *  types — but `sessionId` and a non-empty `prompt` array are required. */
@@ -161,6 +220,28 @@ function parentToolUseIdOf(message) {
         return null;
     return typeof message.parent_tool_use_id === "string" ? message.parent_tool_use_id : null;
 }
+function replaySubagentTerminalState(block) {
+    if (block.is_error !== true)
+        return "completed";
+    const text = replayContentText(block.content).toLowerCase();
+    return /\b(?:cancelled|canceled|interrupted|stopped|killed)\b/.test(text)
+        ? "cancelled"
+        : "failed";
+}
+function replayContentText(value, seen = new Set()) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value !== "object" || value === null || seen.has(value))
+        return "";
+    seen.add(value);
+    if (Array.isArray(value))
+        return value.map((item) => replayContentText(item, seen)).join(" ");
+    const record = value;
+    return [record.text, record.content, record.message]
+        .map((item) => replayContentText(item, seen))
+        .filter(Boolean)
+        .join(" ");
+}
 function stripSubagentTextAndThinking(content) {
     if (!Array.isArray(content))
         return content;
@@ -280,9 +361,6 @@ function shouldHideClaudeAuth() {
  *  query stream has already ended (ran to `done` or died). The stream is not
  *  revivable, so the only recovery is a fresh session. */
 const SESSION_ENDED_MESSAGE = "The Claude Agent session has ended. Please start a new session.";
-// Bypass Permissions doesn't work if we are a root/sudo user
-const IS_ROOT = (process.geteuid?.() ?? process.getuid?.()) === 0;
-const ALLOW_BYPASS = !IS_ROOT || !!process.env.IS_SANDBOX;
 // Slash commands that the SDK handles locally without replaying the user
 // message and without invoking the model.
 const LOCAL_ONLY_COMMANDS = new Set(["/context", "/heapdump", "/extra-usage"]);
@@ -392,147 +470,6 @@ export function isSyntheticLoginMessage(apiMessage) {
         typeof block.text === "string" &&
         block.text.includes("Please run /login"));
 }
-const PERMISSION_MODE_ALIASES = {
-    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, logger = console) {
-    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;
-}
-function permissionLifetime(destination) {
-    switch (destination) {
-        case "session":
-            return { scope: "session" };
-        case "cliArg":
-            return { scope: "process", storage: "cli_argument" };
-        case "userSettings":
-            return { scope: "persistent", storage: "user" };
-        case "projectSettings":
-            return { scope: "persistent", storage: "project" };
-        case "localSettings":
-            return { scope: "persistent", storage: "project_local" };
-        default:
-            return { scope: "unknown" };
-    }
-}
-function permissionMetadataForAlwaysAllow(suggestions, toolName) {
-    const effectiveSuggestions = suggestions && suggestions.length > 0
-        ? suggestions
-        : [
-            {
-                type: "addRules",
-                rules: [{ toolName }],
-                behavior: "allow",
-                destination: "session",
-            },
-        ];
-    const changes = [];
-    for (const update of effectiveSuggestions) {
-        switch (update.type) {
-            case "addRules":
-            case "removeRules":
-            case "replaceRules": {
-                const operation = update.type === "addRules" ? "add" : update.type === "removeRules" ? "remove" : "replace";
-                const targets = update.rules.map((rule) => ({
-                    type: "tool",
-                    toolName: rule.toolName,
-                    ...(rule.ruleContent
-                        ? {
-                            matcher: {
-                                type: "provider_rule",
-                                provider: "claudeCode",
-                                value: rule.ruleContent,
-                            },
-                        }
-                        : {}),
-                }));
-                const renderedRules = update.rules
-                    .map((rule) => rule.ruleContent
-                    ? `${rule.toolName} calls matching ${rule.ruleContent}`
-                    : `all ${rule.toolName} calls`)
-                    .join(", ");
-                const verb = operation === "add"
-                    ? update.behavior === "allow"
-                        ? "Allow"
-                        : update.behavior === "deny"
-                            ? "Deny"
-                            : "Ask before"
-                    : operation === "remove"
-                        ? `Remove ${update.behavior} rules for`
-                        : `Replace ${update.behavior} rules with`;
-                changes.push({
-                    type: "policy_rule",
-                    operation,
-                    ruleBehavior: update.behavior,
-                    description: `${verb} ${renderedRules}`,
-                    lifetime: permissionLifetime(update.destination),
-                    targets,
-                });
-                break;
-            }
-            case "addDirectories":
-            case "removeDirectories": {
-                const operation = update.type === "addDirectories" ? "add" : "remove";
-                changes.push({
-                    type: "policy_rule",
-                    operation,
-                    ruleBehavior: "allow",
-                    description: operation === "add"
-                        ? `Allow filesystem access under ${update.directories.join(", ")}`
-                        : `Remove additional filesystem access under ${update.directories.join(", ")}`,
-                    lifetime: permissionLifetime(update.destination),
-                    targets: update.directories.map((path) => ({
-                        type: "filesystem",
-                        matcher: { type: "directory", path },
-                    })),
-                });
-                break;
-            }
-            case "setMode":
-                changes.push({
-                    type: "permission_mode",
-                    operation: "set",
-                    provider: "claudeCode",
-                    mode: update.mode,
-                    description: `Set Claude Code permission mode to ${update.mode}`,
-                    lifetime: permissionLifetime(update.destination),
-                });
-                break;
-            default:
-                break;
-        }
-    }
-    return { version: 1, changes };
-}
 /**
  * Bridges {@link AcpClient} to the connection-scoped {@link AgentContext}
  * exposed by `AgentApp.connect(...)` as `connection.client`. The peer handle is
@@ -545,7 +482,7 @@ class ClientConnection {
         this.ctx = ctx;
     }
     sessionUpdate(params) {
-        return this.ctx.notify(methods.client.session.update, params);
+        return this.ctx.notify(methods.client.session.update, asSdkSessionNotification(params));
     }
     requestPermission(params, signal) {
         return this.ctx.request(methods.client.session.requestPermission, params, {
@@ -570,16 +507,152 @@ class ClientConnection {
         return this.ctx.notify(method, params);
     }
 }
+function raceWithAbort(operation, signal) {
+    return new Promise((resolve, reject) => {
+        const cleanup = () => signal.removeEventListener("abort", onAbort);
+        const onAbort = () => {
+            cleanup();
+            reject(new Error("Tool use aborted"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        if (signal.aborted) {
+            onAbort();
+        }
+        void operation.then((value) => {
+            cleanup();
+            resolve(value);
+        }, (error) => {
+            cleanup();
+            reject(error);
+        });
+    });
+}
+/** Background OAuth work is implementation state, not part of the public
+ *  `Session` shape exposed through `ClaudeAcpAgent.sessions`. */
+const mcpAuthentications = new WeakMap();
+/** Start OAuth for ACP-provided MCP servers that Claude reported as needing
+ *  authentication. This runs after session creation has returned so an
+ *  interactive browser flow never delays `session/new`. */
+function startMcpAuthentication(host, sessionId, mcpServers) {
+    if (!host.clientCapabilities?.elicitation?.url || mcpServers.length === 0)
+        return;
+    const session = host.sessions[sessionId];
+    if (!session || mcpAuthentications.has(session))
+        return;
+    const requestedServers = new Set(mcpServers.map((server) => server.name));
+    const authentication = authenticateMcpServers(host, sessionId, session.query, requestedServers)
+        .catch((error) => {
+        if (!session.abortController.signal.aborted) {
+            host.logger.error(`Failed to inspect MCP servers for OAuth: ${error}`);
+        }
+    })
+        .finally(() => {
+        if (mcpAuthentications.get(session) === authentication) {
+            mcpAuthentications.delete(session);
+        }
+    });
+    mcpAuthentications.set(session, authentication);
+}
+async function authenticateMcpServers(host, sessionId, query, requestedServers) {
+    if (!supportsMcpOAuth(query)) {
+        host.logger.error("The Claude Agent SDK does not expose MCP OAuth authentication.");
+        return;
+    }
+    const statuses = await query.mcpServerStatus();
+    for (const status of statuses) {
+        if (status.status !== "needs-auth" || !requestedServers.has(status.name))
+            continue;
+        try {
+            await authenticateMcpServer(host, sessionId, query, status.name);
+        }
+        catch (error) {
+            const session = host.sessions[sessionId];
+            if (session && !session.abortController.signal.aborted) {
+                host.logger.error(`Failed to authenticate MCP server ${status.name}: ${error}`);
+            }
+        }
+    }
+}
+/** Bridge Claude Code's startup MCP OAuth control to ACP URL elicitation.
+ *  Claude opens and owns the localhost callback listener; the ACP client only
+ *  needs to present the returned authorization URL. */
+async function authenticateMcpServer(host, sessionId, query, serverName) {
+    const session = host.sessions[sessionId];
+    if (!session)
+        return;
+    const login = await query.mcpAuthenticate(serverName);
+    if (!login.requiresUserAction)
+        return;
+    if (!login.authUrl) {
+        throw new Error("Claude Code requested user action without returning an authorization URL");
+    }
+    const elicitationId = `mcp-oauth-${randomUUID()}`;
+    const flowAbort = new AbortController();
+    const abortFlow = () => flowAbort.abort(session.abortController.signal.reason);
+    session.abortController.signal.addEventListener("abort", abortFlow, { once: true });
+    if (session.abortController.signal.aborted)
+        abortFlow();
+    try {
+        const completed = waitForMcpAuthentication(host.sessions, sessionId, query, serverName, flowAbort.signal);
+        const elicitation = host.client.unstable_createElicitation({
+            mode: "url",
+            sessionId,
+            message: `Authenticate with MCP server ${serverName}`,
+            url: login.authUrl,
+            elicitationId,
+        }, flowAbort.signal);
+        const first = await Promise.race([
+            completed.then((authenticated) => ({ type: "completed", authenticated })),
+            elicitation.then((response) => ({ type: "elicitation", response })),
+        ]);
+        if (first.type === "elicitation" && !CreateElicitationResponse.isAccept(first.response)) {
+            return;
+        }
+        if (first.type === "elicitation") {
+            await completed;
+        }
+        try {
+            await host.client.unstable_completeElicitation({ elicitationId });
+        }
+        catch (error) {
+            if (!flowAbort.signal.aborted) {
+                host.logger.error(`Failed to complete MCP OAuth elicitation: ${error}`);
+            }
+        }
+    }
+    finally {
+        flowAbort.abort();
+        session.abortController.signal.removeEventListener("abort", abortFlow);
+    }
+}
+async function waitForMcpAuthentication(sessions, sessionId, query, serverName, signal) {
+    const deadline = Date.now() + MCP_OAUTH_TIMEOUT_MS;
+    while (!signal.aborted && Date.now() < deadline) {
+        const session = sessions[sessionId];
+        if (!session || session.query !== query)
+            return false;
+        const status = (await query.mcpServerStatus()).find((server) => server.name === serverName);
+        if (!status || status.status === "failed" || status.status === "disabled")
+            return false;
+        if (status.status === "connected")
+            return true;
+        if (!(await waitUnlessAborted(MCP_OAUTH_STATUS_POLL_MS, signal)))
+            return false;
+    }
+    return false;
+}
 export class ClaudeAcpAgent {
     sessions;
     client;
     clientCapabilities;
     logger;
+    sessionModes;
     gatewayAuthRequest;
     /** Set while ACP overrides the agent's native provider configuration. */
     providerConfig;
     /** Serializes provider changes while every open query is recreated between turns. */
     providerUpdate = null;
+    exitPlan;
     /** Grace period before a `session/cancel` forces a wedged prompt loop to
      *  return "cancelled". See {@link DEFAULT_FORCE_CANCEL_GRACE_MS}. Mutable so
      *  tests can shrink it. */
@@ -588,6 +661,52 @@ export class ClaudeAcpAgent {
         this.sessions = {};
         this.client = client;
         this.logger = logger ?? console;
+        this.exitPlan = new ExitPlanCoordinator({
+            currentSession: (id) => this.sessions[id],
+            closeQueryStream: (session) => this.closeQueryStream(session),
+            restartSession: async (params, options) => {
+                await this.createSession(params, options);
+                const session = this.sessions[options.publicSessionId];
+                if (!session)
+                    throw new Error("Fresh Claude context was not created");
+                return session;
+            },
+            applyFastMode: (session, enabled) => this.applyFastMode(session, enabled),
+            sessionUpdate: (notification) => this.client.sessionUpdate(notification),
+            ensureConsumer: (session, id) => this.ensureConsumer(session, id),
+            logError: (message, error) => this.logger.error(message, error),
+            destroyReplacement: (id, session) => {
+                disarmForceCancel(session);
+                session.cancelController?.abort();
+                this.closeQueryStream(session);
+                session.abortController.abort();
+                session.eagerToolCallSessions?.clear();
+                clearHookCallbacks(id);
+                session.nativeSubagentRuntime?.clear();
+                session.asyncTaskRuntime?.clear();
+                if (this.sessions[id] === session)
+                    delete this.sessions[id];
+            },
+            settleCancelledTurn: (original, session, turn) => {
+                disarmForceCancel(session);
+                this.finishFileChangeAudit(session, turn, "cancelled");
+                turn.settled = true;
+                turn.resolve({ stopReason: "cancelled", usage: sessionUsage(original) });
+            },
+            settleFailedTurn: (session, turn, error) => {
+                disarmForceCancel(session);
+                this.finishFileChangeAudit(session, turn, "providerError");
+                turn.settled = true;
+                turn.reject(error);
+            },
+        });
+        this.sessionModes = new SessionModeManager({
+            getSession: (sessionId) => this.sessions[sessionId],
+            sessionEndedMessage: SESSION_ENDED_MESSAGE,
+            updateConfigOption: (sessionId, configId, value) => this.updateConfigOption(sessionId, configId, value),
+            sessionUpdate: (params) => this.client.sessionUpdate(params),
+            logError: (...args) => this.logger.error(...args),
+        });
     }
     async initialize(request) {
         this.clientCapabilities = request.clientCapabilities;
@@ -686,6 +805,15 @@ export class ClaudeAcpAgent {
                 terminalAuthMethods.push(consoleLoginMethod);
             }
         }
+        const sessionCapabilities = {
+            additionalDirectories: {},
+            close: {},
+            delete: {},
+            fork: {},
+            list: {},
+            resume: {},
+            subagents: {},
+        };
         return {
             protocolVersion: 1,
             agentCapabilities: {
@@ -710,14 +838,7 @@ export class ClaudeAcpAgent {
                 // capability prerequisite for the provider methods.
                 providers: {},
                 loadSession: true,
-                sessionCapabilities: {
-                    additionalDirectories: {},
-                    close: {},
-                    delete: {},
-                    fork: {},
-                    list: {},
-                    resume: {},
-                },
+                sessionCapabilities,
             },
             agentInfo: {
                 name: packageJson.name,
@@ -732,7 +853,7 @@ export class ClaudeAcpAgent {
             // steering extension contract: advertises the `_session/steering` request
             // so clients know they may inject a follow-up into a running turn.
             _meta: {
-                ...airSessionFailureCapabilityMeta(AGENT_FILE_CHANGE_REPORT_CAPABILITY),
+                ...airSessionFailureCapabilityMeta(AGENT_FILE_CHANGE_REPORT_CAPABILITY, AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY, AIR_ASYNC_TASKS_CAPABILITY),
                 steering: {
                     supported: true,
                 },
@@ -754,26 +875,17 @@ export class ClaudeAcpAgent {
         // Needs to happen after we return the session
         setTimeout(() => {
             this.sendAvailableCommandsUpdate(response.sessionId);
+            startMcpAuthentication(this, response.sessionId, params.mcpServers);
         }, 0);
         return response;
     }
     async unstable_forkSession(params) {
         if (this.providerUpdate)
             await this.providerUpdate;
-        const response = await this.createSession({
-            cwd: params.cwd,
-            mcpServers: params.mcpServers ?? [],
-            additionalDirectories: params.additionalDirectories,
-            _meta: params._meta,
-        }, {
-            resume: params.sessionId,
-            forkSession: true,
+        return forkSession(params, {
+            liveMessageIdToUuid: this.sessions[params.sessionId]?.messageIdToUuid,
+            messageIdForGrouping,
         });
-        // Needs to happen after we return the session
-        setTimeout(() => {
-            this.sendAvailableCommandsUpdate(response.sessionId);
-        }, 0);
-        return response;
     }
     async resumeSession(params) {
         if (this.providerUpdate)
@@ -782,6 +894,7 @@ export class ClaudeAcpAgent {
         // Needs to happen after we return the session
         setTimeout(() => {
             this.sendAvailableCommandsUpdate(params.sessionId);
+            startMcpAuthentication(this, params.sessionId, params.mcpServers ?? []);
         }, 0);
         return result;
     }
@@ -793,6 +906,7 @@ export class ClaudeAcpAgent {
         // Send available commands after replay so it doesn't interleave with history
         setTimeout(() => {
             this.sendAvailableCommandsUpdate(params.sessionId);
+            startMcpAuthentication(this, params.sessionId, params.mcpServers ?? []);
         }, 0);
         return result;
     }
@@ -813,40 +927,6 @@ export class ClaudeAcpAgent {
             sessions,
         };
     }
-    /** Read the SDK-maintained title for a session and, if it changed since the
-     *  last time we looked, notify the client with a `session_info_update`. The
-     *  SDK has no push event for the title it auto-generates in the background, so
-     *  we pull it at turn-end. A missing session file or read error is non-fatal:
-     *  the title is best-effort and another turn will retry. */
-    async maybeUpdateSessionTitle(sessionId, session) {
-        let info;
-        try {
-            info = await getSessionInfo(sessionId, { dir: session.cwd });
-        }
-        catch (error) {
-            this.logger.error(`Session ${sessionId}: failed to read session info: ${error}`);
-            return;
-        }
-        // `customTitle` is a user-set `/rename`; `summary` is the auto-generated
-        // title (or first prompt). Prefer the explicit title when present.
-        const rawTitle = info?.customTitle ?? info?.summary;
-        if (!rawTitle) {
-            return;
-        }
-        const title = sanitizeTitle(rawTitle);
-        if (title === session.lastTitle) {
-            return;
-        }
-        session.lastTitle = title;
-        await this.client.sessionUpdate({
-            sessionId,
-            update: {
-                sessionUpdate: "session_info_update",
-                title,
-                updatedAt: new Date(info.lastModified).toISOString(),
-            },
-        });
-    }
     async authenticate(_params) {
         if (_params.methodId === "gateway" || _params.methodId === "gateway-bedrock") {
             this.gatewayAuthRequest = _params;
@@ -983,6 +1063,9 @@ export class ClaudeAcpAgent {
         if (session.queryClosed) {
             throw RequestError.internalError(undefined, SESSION_ENDED_MESSAGE);
         }
+        if (session.autoModeFallbackWarningPending) {
+            await this.sessionModes.publishFallbackWarning(params.sessionId, session);
+        }
         if (Array.from(session.taskState.values()).some((task) => task.status !== "completed")) {
             await this.publishTaskPlan(params.sessionId, session.taskState);
         }
@@ -1002,6 +1085,7 @@ export class ClaudeAcpAgent {
             session.fileChangeReportRequestIds.add(fileChangeReportRequestId);
             fileChangeAudit = createFileChangeAuditTurnState(fileChangeReportRequestId);
         }
+        session.titles.onPrompt(params.prompt);
         // Each prompt is a Turn whose deferred the persistent consumer settles once
         // the turn's outcome is known. `prompt()` owns no loop: it enqueues the
         // turn, pushes the user message onto the streaming input, makes sure the
@@ -1109,11 +1193,13 @@ export class ClaudeAcpAgent {
      *  an `SDKUserMessage` onto the same streaming input, which the SDK routes
      *  into the in-flight turn. The injected message's echo carries a uuid that
      *  matches no queued turn, so the consumer drops it as an unrelated replay
-     *  without promoting/settling anything. It is delivered at {@link
-     *  STEER_PRIORITY} (`now`) so it pre-empts the current generation (interrupting
-     *  a single-shot response, or slotting in between a multi-step turn's tool
-     *  calls). The steered message's own output streams via `session/update`, not
-     *  this response.
+     *  without promoting/settling anything. It is normally delivered at priority
+     *  `now` so it pre-empts the current generation (interrupting a single-shot
+     *  response, or slotting in between a multi-step turn's tool calls). While a
+     *  permission or elicitation is awaiting user input it uses `later`, because
+     *  interrupting that SDK callback cancels the ACP request and can strand the
+     *  prompt (IJAI-1191). The steered message's own output streams via
+     *  `session/update`, not this response.
      *
      *  Pre-empting means ABORTING: the interrupted cycle emits a `result` of its
      *  own and the steered message runs as a second one, so the turn is marked
@@ -1165,7 +1251,8 @@ export class ClaudeAcpAgent {
         userMessage.uuid = steeredUuid;
         // Deliver into the running turn rather than queuing behind it as a fresh
         // prompt would.
-        userMessage.priority = STEER_PRIORITY;
+        userMessage.priority =
+            (session.pendingUserInputCount ?? 0) > 0 ? STEER_PRIORITY_LATER : STEER_PRIORITY_NOW;
         // Mark before the push and in the same synchronous section as the in-flight
         // check: the interrupt can have the CLI finalizing the aborted cycle by the
         // time the consumer next runs, and an unmarked result would settle the turn
@@ -1183,6 +1270,21 @@ export class ClaudeAcpAgent {
         await this.publishGoalFromPrompt(sessionId, firstText, steeredUuid);
         return { outcome: "injected" };
     }
+    async stopAsyncTask(params) {
+        const session = this.sessions[params.sessionId];
+        const asyncTasks = session?.asyncTaskRuntime;
+        if (!session || !asyncTasks?.claimStop(params.asyncTaskId))
+            return { stopped: false };
+        try {
+            await session.query.stopTask(params.asyncTaskId);
+            await asyncTasks.taskStopped(params.asyncTaskId);
+            return { stopped: true };
+        }
+        catch (error) {
+            asyncTasks.releaseStop(params.asyncTaskId);
+            throw error;
+        }
+    }
     /** Publish the audit terminal for every turn path that did not reach the
      *  report tool. The support flips the turn state synchronously before its
      *  transport await, so callers can stay fail-open and settle the ACP prompt
@@ -1271,8 +1373,27 @@ export class ClaudeAcpAgent {
          *  recognizable by the `parentToolUseId` meta that toAcpNotifications
          *  stamps from `parent_tool_use_id`, and never reach the top-level feed
          *  as the turn's answer. */
+        const subagents = (session.nativeSubagentRuntime ??= new NativeSubagentRuntime(clientSupportsSubagents(this.clientCapabilities), params.sessionId, session, async (notification) => this.client.sessionUpdate(asSdkSessionNotification(notification)), this.logger));
+        const asyncTasks = (session.asyncTaskRuntime ??= new AsyncTaskRuntime(clientSupportsAsyncTasks(this.clientCapabilities), params.sessionId, async (notification) => this.client.sessionUpdate(asSdkSessionNotification(notification))));
         const sendUpdate = async (notification) => {
             const { update } = notification;
+            const claudeMeta = update._meta?.claudeCode;
+            const toolCallId = update.sessionUpdate === "tool_call" || update.sessionUpdate === "tool_call_update"
+                ? update.toolCallId
+                : undefined;
+            const eagerOwnerSessionId = toolCallId
+                ? session.eagerToolCallSessions?.get(toolCallId)
+                : undefined;
+            const routedNotification = await subagents.route(notification, sendUpdate, eagerOwnerSessionId);
+            if (!routedNotification) {
+                // Native Agent/Task control calls are intentionally not transcript
+                // tools. Do not let the mapper's pre-send de-duplication mark make a
+                // later permission request believe that a suppressed call exists.
+                if (toolCallId && isNativeSubagentControlUpdate(update)) {
+                    session.emittedToolCalls.delete(toolCallId);
+                }
+                return;
+            }
             if (isFileChangeAuditReportPhase(session.activeTurn?.fileChangeAudit) &&
                 (update.sessionUpdate === "agent_message_chunk" ||
                     update.sessionUpdate === "agent_thought_chunk" ||
@@ -1282,12 +1403,32 @@ export class ClaudeAcpAgent {
                 return;
             }
             if (update.sessionUpdate === "agent_message_chunk") {
-                const claudeMeta = update._meta?.claudeCode;
                 if (!claudeMeta?.parentToolUseId) {
                     session.emittedAssistantText = true;
+                    session.titles.onAssistantText(update.content);
                 }
             }
-            await this.client.sessionUpdate(notification);
+            await this.client.sessionUpdate(routedNotification);
+            if (toolCallId &&
+                update.sessionUpdate === "tool_call_update" &&
+                (update.status === "completed" || update.status === "failed")) {
+                session.eagerToolCallSessions?.delete(toolCallId);
+            }
+        };
+        // toAcpNotifications registers deferred tool hooks that publish through
+        // the client passed to it. Keep those later updates on the same child-aware
+        // routing path as the immediate notifications.
+        const routedNotificationClient = { sessionUpdate: sendUpdate };
+        session.nativeSubagentDeliver = sendUpdate;
+        const finishLifecycle = async (nativeState, asyncState, context) => {
+            await Promise.all([
+                subagents
+                    .finishAll(nativeState, sendUpdate)
+                    .catch((error) => this.logger.error(`Session ${params.sessionId}: failed to publish terminal subagent state ${context}`, error)),
+                asyncTasks
+                    .finishAll(asyncState)
+                    .catch((error) => this.logger.error(`Session ${params.sessionId}: failed to publish terminal async task state ${context}`, error)),
+            ]);
         };
         let pendingWorkerShutdown = false;
         const isCurrentConsumer = () => this.sessions[params.sessionId] === session;
@@ -1344,12 +1485,17 @@ export class ClaudeAcpAgent {
             // cleared when each consolidated message consumes it. #785 stopped
             // resetting the streamed-content tracking here but left this line.
             stopReason = "end_turn";
-            session.accumulatedUsage = {
+            session.accumulatedUsage = session.activeTurn?.carriedUsage ?? {
                 inputTokens: 0,
                 outputTokens: 0,
                 cachedReadTokens: 0,
                 cachedWriteTokens: 0,
             };
+            session.accumulatedModelUsage = session.activeTurn?.carriedModelUsage ?? {};
+            if (session.activeTurn) {
+                session.activeTurn.carriedUsage = undefined;
+                session.activeTurn.carriedModelUsage = undefined;
+            }
         };
         /** Promote a queued turn to active: it becomes the one output is attributed
          *  to, and its scratch starts fresh. Clears the cancelled flag so a turn
@@ -1648,11 +1794,7 @@ export class ClaudeAcpAgent {
                 return;
             }
             sessionFailures.recordActive(failure);
-            settleActive({
-                stopReason: "end_turn",
-                usage: sessionUsage(session),
-                _meta: sessionFailureMeta(failure),
-            }, "providerError");
+            settleActive(turnOutcome(session, "end_turn", sessionFailureMeta(failure)), "providerError");
         };
         /** Reject every in-flight turn — used when the stream dies. */
         const failAllTurns = (error) => {
@@ -1724,7 +1866,9 @@ export class ClaudeAcpAgent {
                         // spent would never drain (it would swallow an unrelated later
                         // echo-less result instead).
                         const active = session.activeTurn;
-                        if (active.commandFinished === "completed" || active.commandFinished === "discarded") {
+                        if (active.commandFinished === "completed" ||
+                            active.commandFinished === "discarded" ||
+                            active.commandFinished === "refused") {
                             // Finished SDK-side; any result already passed. Nothing to
                             // track.
                         }
@@ -1749,7 +1893,7 @@ export class ClaudeAcpAgent {
                             this.trackOrphanCommand(session, active.promptUuid, "started");
                         }
                     }
-                    settleActive({ stopReason: "cancelled", usage: sessionUsage(session) });
+                    settleActive(turnOutcome(session, "cancelled"));
                     // The cancelled turn's result may never come (that's why the
                     // backstop fired) — close its delivery stretch here so partial
                     // streamed text can't suppress the next turn's issue-#453 fallback.
@@ -1803,9 +1947,10 @@ export class ClaudeAcpAgent {
                     // a deferred turn's stored outcome (followup results never mutate
                     // it), but the stored one is the authoritative source.
                     const inFlight = session.activeTurn;
+                    await finishLifecycle(session.cancelled ? "cancelled" : "failed", session.cancelled ? "stopped" : "failed", "at end of stream");
                     settleActive(session.cancelled
-                        ? { stopReason: "cancelled", usage: sessionUsage(session) }
-                        : (inFlight?.deferredSettle ?? { stopReason, usage: sessionUsage(session) }));
+                        ? turnOutcome(session, "cancelled")
+                        : (inFlight?.deferredSettle ?? turnOutcome(session, stopReason)));
                     // Queued turns the SDK never started never ran, so reject them rather
                     // than reporting a success (end_turn) — or a misleading "cancelled" —
                     // for a prompt that produced no output. (A cancel already settled the
@@ -1835,7 +1980,7 @@ export class ClaudeAcpAgent {
                 }
                 // CLIs 2.1.206+ (capability msg_lifecycle_v1) report the fate of every
                 // uuid-stamped queued command (queued/started/completed/cancelled/
-                // discarded) as `command_lifecycle` frames — 2-3 per prompt, since
+                // discarded/refused) as `command_lifecycle` frames — 2-3 per prompt, since
                 // prompt() stamps a uuid on every message. The frame is @internal and
                 // absent from the SDKMessage union, so handle it BEFORE the exhaustive
                 // switch: it must not reach `unreachable`'s error log, and a `case`
@@ -1870,6 +2015,7 @@ export class ClaudeAcpAgent {
                         }
                         case "completed":
                         case "discarded":
+                        case "refused":
                         case "cancelled": {
                             // Terminal frames. Latch the fate on a still-queued turn so a
                             // later cancel() doesn't seed an orphan entry for a command
@@ -1892,6 +2038,7 @@ export class ClaudeAcpAgent {
                                 const state = session.orphanCommands?.get(frame.command_uuid);
                                 if (state === "pending") {
                                     session.orphanCommands?.delete(frame.command_uuid);
+                                    session.pendingEmptyInterruptionDiagnosticCommands?.delete(frame.command_uuid);
                                 }
                                 else if (state === "started") {
                                     session.orphanCommands?.set(frame.command_uuid, "zombie");
@@ -1903,7 +2050,11 @@ export class ClaudeAcpAgent {
                             // command folded into another turn whose result is attributed
                             // elsewhere — either way no echo-less result remains to skip.
                             // "discarded" = session ended with it still queued; no result.
+                            // "refused" (2.1.238+) = a cross-session peer message declined
+                            // by receive-side policy before dispatch; never a prompt-lane
+                            // command of ours, and no result will ever come.
                             session.orphanCommands?.delete(frame.command_uuid);
+                            session.pendingEmptyInterruptionDiagnosticCommands?.delete(frame.command_uuid);
                             break;
                         }
                         default:
@@ -2026,6 +2177,7 @@ export class ClaudeAcpAgent {
                                 const usedTokens = await fetchContextUsedTokens(session.query, this.logger);
                                 lastAssistantUsage = null;
                                 lastAssistantTotalUsage = usedTokens ?? 0;
+                                session.contextUsedTokens = usedTokens ?? 0;
                                 await sendUpdate({
                                     sessionId: message.session_id,
                                     update: {
@@ -2079,7 +2231,7 @@ export class ClaudeAcpAgent {
                                     // the interrupted turn's tokens entirely (issue #844). Zero
                                     // when the cancel pre-empted the result (wedge/force-cancel).
                                     if (session.cancelled && session.activeTurn && !session.activeTurn.settled) {
-                                        settleActive({ stopReason: "cancelled", usage: sessionUsage(session) });
+                                        settleActive(turnOutcome(session, "cancelled"));
                                         // An interrupt can pre-empt the turn's result entirely
                                         // (nothing ran the result-case `finally`), so close the
                                         // delivery stretch here: idle is the SDK's authoritative
@@ -2153,11 +2305,9 @@ export class ClaudeAcpAgent {
                                             `for the active turn; failing the in-flight prompt (issue #825)`);
                                         await failActiveWithSessionFailure("internal_error", RequestError.internalError(errorKindData("no_result"), TURN_NO_RESULT_MESSAGE), TURN_NO_RESULT_MESSAGE);
                                     }
-                                    // The SDK generates the session title in a background task and
-                                    // persists it to the session file; `idle` is the turn-over
-                                    // signal, so it's the point at which a new title may have
-                                    // landed. Push it to the client if it changed.
-                                    await this.maybeUpdateSessionTitle(params.sessionId, session);
+                                    // Turn-over is when a title may have landed or become
+                                    // generatable; see SessionTitles.onTurnEnd.
+                                    await session.titles.onTurnEnd(session);
                                 }
                                 break;
                             }
@@ -2223,6 +2373,7 @@ export class ClaudeAcpAgent {
                                 break;
                             }
                             case "permission_denied": {
+                                unregisterHookCallback(message.tool_use_id);
                                 // A tool call was auto-denied (by a rule, the classifier,
                                 // dontAsk mode, etc.) before running. The tool_use block was
                                 // already emitted as a `tool_call`, so mark it failed with the
@@ -2250,6 +2401,16 @@ export class ClaudeAcpAgent {
                                 const parentToolUseId = message.agent_id
                                     ? session.liveBackgroundTasks.get(message.agent_id)?.parentToolUseId
                                     : undefined;
+                                const eagerOwnerSessionId = session.eagerToolCallSessions?.get(message.tool_use_id);
+                                if (message.agent_id &&
+                                    !parentToolUseId &&
+                                    !eagerOwnerSessionId &&
+                                    clientSupportsSubagents(this.clientCapabilities)) {
+                                    // An agent-scoped denial with missing lineage cannot safely
+                                    // be presented in the root transcript. The matching hidden
+                                    // child tool call was not announced there.
+                                    break;
+                                }
                                 const reason = message.decision_reason ?? message.message;
                                 await sendUpdate({
                                     sessionId: message.session_id,
@@ -2304,7 +2465,15 @@ export class ClaudeAcpAgent {
                             case "hook_progress":
                             case "hook_response":
                             case "files_persisted":
+                                break;
                             case "task_progress":
+                                await asyncTasks.taskProgress({
+                                    task_id: message.task_id,
+                                    description: message.description,
+                                    summary: message.summary,
+                                    last_tool_name: message.last_tool_name,
+                                    usage: message.usage,
+                                });
                                 break;
                             case "task_started":
                                 // For subagent tasks `task_id` is the subagent's agent id (the
@@ -2329,6 +2498,23 @@ export class ClaudeAcpAgent {
                                     parentToolUseId: message.tool_use_id,
                                     isSubagent: !!message.subagent_type,
                                 });
+                                await subagents.taskStarted({
+                                    taskId: message.task_id,
+                                    toolUseId: message.tool_use_id,
+                                    subagentType: message.subagent_type,
+                                    description: message.description,
+                                    prompt: message.prompt,
+                                }, sendUpdate);
+                                await asyncTasks.taskStarted({
+                                    task_id: message.task_id,
+                                    task_type: message.task_type,
+                                    description: message.description,
+                                    subagent_type: message.subagent_type,
+                                    is_backgrounded: message.is_backgrounded,
+                                    workflow_name: message.workflow_name,
+                                    skip_transcript: message.skip_transcript,
+                                    tool_use_id: message.tool_use_id,
+                                });
                                 if (message.subagent_type && session.activeTurn && !session.activeTurn.settled) {
                                     (session.activeTurn.spawnedTaskIds ??= new Set()).add(message.task_id);
                                 }
@@ -2336,9 +2522,19 @@ export class ClaudeAcpAgent {
                             case "task_notification":
                                 // The task settled — no further tool calls can originate
                                 // from it, so its registry entry can be dropped.
+                                await subagents.finishTask(message.task_id, message.status, sendUpdate, message.tool_use_id);
+                                await asyncTasks.taskNotification({
+                                    task_id: message.task_id,
+                                    status: message.status,
+                                    summary: message.summary,
+                                    output_file: message.output_file,
+                                });
+                                if (message.tool_use_id)
+                                    subagents.discardPending(message.tool_use_id);
                                 session.liveBackgroundTasks.delete(message.task_id);
                                 break;
                             case "task_updated":
+                                await asyncTasks.taskUpdated(message.task_id, message.patch);
                                 // terminal-status task_updated patch and a (deduplicated)
                                 // task_notification when a task settles, but only the patch is
                                 // guaranteed per transition — prune on it too so the registry
@@ -2347,6 +2543,7 @@ export class ClaudeAcpAgent {
                                 if (message.patch.status === "completed" ||
                                     message.patch.status === "failed" ||
                                     message.patch.status === "killed") {
+                                    await subagents.finishTask(message.task_id, message.patch.status, sendUpdate);
                                     session.liveBackgroundTasks.delete(message.task_id);
                                 }
                                 break;
@@ -2482,6 +2679,7 @@ export class ClaudeAcpAgent {
                             case "control_request_progress":
                                 break;
                             case "background_tasks_changed":
+                                await asyncTasks.backgroundTasksChanged(message.tasks);
                                 // A level signal: the full live background-task set on every
                                 // membership change, with REPLACE semantics. Used only to
                                 // reconcile `liveBackgroundTasks` — dropping (or, for
@@ -2537,6 +2735,8 @@ export class ClaudeAcpAgent {
                         // user-turn lifecycle (stop reason, settles, failActive,
                         // slash-command output forwarding), though their cost is real.
                         const isAutonomousResult = message.origin != null && AUTONOMOUS_RESULT_ORIGINS.has(message.origin.kind);
+                        const pendingExitPlanModeInterruption = session.pendingExitPlanModeInterruption;
+                        const pendingExitPlanContextReset = session.pendingExitPlanContextReset;
                         try {
                             // Reconcile the Fast mode toggle with the SDK's reported state.
                             // Gated to user-driven turns like every other side effect below;
@@ -2637,6 +2837,18 @@ export class ClaudeAcpAgent {
                                 session.accumulatedUsage.cachedWriteTokens +=
                                     message.usage.cache_creation_input_tokens;
                             }
+                            // The same tally split by model, for `_meta.quota.model_usage`.
+                            // `modelUsage` is a running total for the whole query() call, so
+                            // this result's own spend is what it added to the previous
+                            // reading. Advance the reading even for an autonomous result — it
+                            // is part of the running total the NEXT increment is measured
+                            // from — but leave the turn tally alone, exactly as above.
+                            const modelUsageReading = normalizeModelUsage(message.modelUsage);
+                            const resultModelUsage = modelUsageIncrement(modelUsageReading, session.lastModelUsageReading ?? {});
+                            session.lastModelUsageReading = modelUsageReading;
+                            if (!isAutonomousResult) {
+                                session.accumulatedModelUsage = addModelUsage(session.accumulatedModelUsage ?? {}, resultModelUsage);
+                            }
                             const matchingModelUsage = lastAssistantModel
                                 ? getMatchingModelUsage(message.modelUsage, lastAssistantModel)
                                 : null;
@@ -2689,6 +2901,8 @@ export class ClaudeAcpAgent {
                                 });
                             }
                             if (session.cancelled) {
+                                session.pendingExitPlanModeInterruption = undefined;
+                                session.pendingExitPlanContextReset = undefined;
                                 if (!isAutonomousResult) {
                                     await clearFailuresFromEarlierTurns();
                                     stopReason = "cancelled";
@@ -2726,7 +2940,61 @@ export class ClaudeAcpAgent {
                                 }
                                 break;
                             }
+                            // A cancel can race startup before the original prompt's echo.
+                            // The CLI then replays the cancelled prompt, its interruption
+                            // marker, and the replacement prompt before yielding this
+                            // error-shaped diagnostic for the OLD cycle. The replacement's
+                            // echo has already made it active, so treating the diagnostic as
+                            // its result rejects a healthy prompt and leaves its real output
+                            // arriving after session/prompt completed. Ignore only the
+                            // diagnostic's exact empty-user-interruption signature; ordinary
+                            // provider errors still follow the failure lanes below.
+                            if (message.is_error &&
+                                isEmptyUserInterruptionDiagnostic(message) &&
+                                (session.pendingEmptyInterruptionDiagnosticCommands?.size ?? 0) > 0) {
+                                const commandUuid = session
+                                    .pendingEmptyInterruptionDiagnosticCommands.values()
+                                    .next().value;
+                                if (commandUuid) {
+                                    session.pendingEmptyInterruptionDiagnosticCommands.delete(commandUuid);
+                                }
+                                break;
+                            }
+                            // Some CLI versions omit the cancelled cycle's diagnostic. Do
+                            // not let an unused hand-off token swallow a later turn's real
+                            // interruption failure.
+                            session.pendingEmptyInterruptionDiagnosticCommands?.clear();
                             await clearFailuresFromEarlierTurns();
+                            // `interrupt: true` is required to make "No, keep planning"
+                            // terminate the ACP turn. Claude represents that intentional
+                            // interrupt as an error-shaped diagnostic, so translate only a
+                            // diagnostic causally paired with the recorded ExitPlanMode
+                            // permission response.
+                            const diagnostic = executionDiagnostic(message);
+                            if (pendingExitPlanModeInterruption &&
+                                pendingExitPlanModeInterruption.toolResultSeen &&
+                                message.is_error &&
+                                diagnostic &&
+                                /(?:^|\s)result_type=user(?:\s|$)/.test(diagnostic) &&
+                                /(?:^|\s)stop_reason=tool_use(?:\s|$)/.test(diagnostic)) {
+                                session.pendingExitPlanModeInterruption = undefined;
+                                if (pendingExitPlanContextReset &&
+                                    pendingExitPlanContextReset.toolUseId ===
+                                        pendingExitPlanModeInterruption.toolUseId) {
+                                    await this.exitPlan.restart(params.sessionId, session, pendingExitPlanContextReset);
+                                    return;
+                                }
+                                stopReason = "cancelled";
+                                settleOrDefer(turnOutcome(session, "cancelled"));
+                                break;
+                            }
+                            if (pendingExitPlanModeInterruption) {
+                                // This result ended the interrupted cycle without the exact
+                                // correlated cancellation shape. Never carry its marker into
+                                // a later turn, whether or not the tool result was observed.
+                                session.pendingExitPlanModeInterruption = undefined;
+                                session.pendingExitPlanContextReset = undefined;
+                            }
                             // A refusal can arrive on any result subtype (and may even set
                             // is_error), so handle it before the subtype switch — otherwise the
                             // is_error throw below would surface it as an internal error. The
@@ -2749,7 +3017,7 @@ export class ClaudeAcpAgent {
                                 // settling it out from under them would strand their output
                                 // and permission requests out-of-turn (issue #866's deadlock,
                                 // through the refusal lane).
-                                settleOrDefer({ stopReason: "refusal", usage: sessionUsage(session) });
+                                settleOrDefer(turnOutcome(session, "refusal"));
                                 break;
                             }
                             // A priority:'now' steer can make the SDK terminate the
@@ -2760,7 +3028,7 @@ export class ClaudeAcpAgent {
                             if (message.is_error &&
                                 isSteering(session.activeTurn) &&
                                 session.activeTurn.steeredEchoes.size > 0) {
-                                settleOrDefer({ stopReason: "end_turn", usage: sessionUsage(session) });
+                                settleOrDefer(turnOutcome(session, "end_turn"));
                                 break;
                             }
                             if (!message.is_error && lastAssistantModel !== null) {
@@ -2803,7 +3071,7 @@ export class ClaudeAcpAgent {
                                     // prose can be injected into the feed.)
                                     if (session.activeTurn?.isLocalOnlyCommand ||
                                         (!deliveredAssistantText && (message.usage.output_tokens ?? 0) === 0)) {
-                                        for (const notification of toAcpNotifications(message.result, "assistant", params.sessionId, session.toolUseCache, this.client, this.logger)) {
+                                        for (const notification of toAcpNotifications(message.result, "assistant", params.sessionId, session.toolUseCache, routedNotificationClient, this.logger)) {
                                             await sendUpdate(notification);
                                         }
                                     }
@@ -2872,7 +3140,7 @@ export class ClaudeAcpAgent {
                             // idle/abort path. settleActive is idempotent, so a duplicate
                             // idle is a no-op.
                             if (!session.cancelled) {
-                                settleOrDefer({ stopReason, usage: sessionUsage(session) });
+                                settleOrDefer(turnOutcome(session, stopReason));
                             }
                         }
                         finally {
@@ -2975,6 +3243,7 @@ export class ClaudeAcpAgent {
                             const nextUsage = totalTokens(lastAssistantUsage);
                             if (nextUsage !== lastAssistantTotalUsage) {
                                 lastAssistantTotalUsage = nextUsage;
+                                session.contextUsedTokens = nextUsage;
                                 await sendUpdate({
                                     sessionId: params.sessionId,
                                     update: {
@@ -3046,7 +3315,7 @@ export class ClaudeAcpAgent {
                                             session.owedTrailingIdles++;
                                             // Before activateTurn resets the accumulator, so the
                                             // usage still belongs to the cancelled turn.
-                                            settleActive({ stopReason: "cancelled", usage: sessionUsage(session) });
+                                            settleActive(turnOutcome(session, "cancelled"));
                                         }
                                         else if (isHeldOpen(session.activeTurn)) {
                                             // A turn held open for its background subagents (see
@@ -3075,7 +3344,7 @@ export class ClaudeAcpAgent {
                                             settleActive(session.activeTurn.steeredSettle);
                                         }
                                         else {
-                                            settleActive({ stopReason: "end_turn", usage: sessionUsage(session) });
+                                            settleActive(turnOutcome(session, "end_turn"));
                                         }
                                     }
                                     // Unlike the no-result teardown lanes, this hand-off must
@@ -3111,6 +3380,7 @@ export class ClaudeAcpAgent {
                         if (message.type === "assistant" && message.parent_tool_use_id === null) {
                             lastAssistantUsage = snapshotFromUsage(message.message.usage);
                             lastAssistantTotalUsage = totalTokens(lastAssistantUsage);
+                            session.contextUsedTokens = lastAssistantTotalUsage;
                             lastAssistantWasUsageLimit = isSyntheticUsageLimitMessage(message.message);
                             if (message.error || lastAssistantWasUsageLimit) {
                                 lastAssistantFailureTitle = assistantMessageText(message.message);
@@ -3141,7 +3411,7 @@ export class ClaudeAcpAgent {
                             message.message.content.includes("<local-command-stdout>")) {
                             const stripped = stripLocalCommandMetadata(message.message.content);
                             if (typeof stripped === "string") {
-                                for (const notification of toAcpNotifications(stripped, message.message.role, params.sessionId, session.toolUseCache, this.client, this.logger, {
+                                for (const notification of toAcpNotifications(stripped, message.message.role, params.sessionId, session.toolUseCache, routedNotificationClient, this.logger, {
                                     clientCapabilities: this.clientCapabilities,
                                     parentToolUseId: message.parent_tool_use_id,
                                     cwd: session.cwd,
@@ -3251,17 +3521,22 @@ export class ClaudeAcpAgent {
                         }
                         else if (message.type === "assistant" &&
                             !(session.forwardSubagentText || supportsSubagentTranscript(this.clientCapabilities))) {
-                            // Legacy clients don't understand nested transcripts. Keep the
-                            // historical behavior for them: subagent text/thinking remains
-                            // internal to the tool call instead of leaking into the top-level
-                            // feed. Capable clients opt into the branch above unchanged, with
-                            // `parentToolUseId` stamped by toAcpNotifications.
+                            // Legacy clients keep the flattened tool-call representation,
+                            // but nested text/thinking stays internal unless explicitly
+                            // requested through the historical transcript extension.
                             content = message.message.content.filter((item) => item.type !== "text" && item.type !== "thinking");
                         }
                         else {
                             content = message.message.content;
                         }
-                        for (const notification of toAcpNotifications(content, message.message.role, params.sessionId, session.toolUseCache, this.client, this.logger, {
+                        const acceptedPlanToolUseId = observeExitPlanToolResults(message, content, session);
+                        let backgroundBashTask;
+                        if (message.type === "user") {
+                            backgroundBashTask = backgroundBashTaskFromToolResult(content, message.tool_use_result, session.toolUseCache);
+                            if (backgroundBashTask)
+                                await asyncTasks.taskBackgrounded(backgroundBashTask);
+                        }
+                        for (const notification of toAcpNotifications(content, message.message.role, params.sessionId, session.toolUseCache, routedNotificationClient, this.logger, {
                             clientCapabilities: this.clientCapabilities,
                             parentToolUseId: message.parent_tool_use_id,
                             cwd: session.cwd,
@@ -3279,7 +3554,7 @@ export class ClaudeAcpAgent {
                             // filtered out of `content` above; blocks that do pass through
                             // (e.g. a subagent image) carry the stamped parentToolUseId
                             // meta and are excluded there.
-                            await sendUpdate(notification);
+                            await sendUpdate(backgroundedBashToolCall(acceptedPlanToolResult(notification, acceptedPlanToolUseId), backgroundBashTask, asyncTasks.enabled));
                         }
                         break;
                     }
@@ -3303,6 +3578,11 @@ export class ClaudeAcpAgent {
                         if (toolCallId === null || !session.emittedToolCalls.has(toolCallId)) {
                             break;
                         }
+                        const subagentParentToolUseId = message.parent_tool_use_id
+                            ? [...session.liveBackgroundTasks.values()].some((task) => task.isSubagent && task.parentToolUseId === message.parent_tool_use_id)
+                                ? message.parent_tool_use_id
+                                : undefined
+                            : undefined;
                         await sendUpdate({
                             sessionId: message.session_id,
                             update: {
@@ -3312,6 +3592,9 @@ export class ClaudeAcpAgent {
                                 _meta: {
                                     claudeCode: {
                                         toolName: message.tool_name,
+                                        ...(subagentParentToolUseId
+                                            ? { parentToolUseId: subagentParentToolUseId }
+                                            : {}),
                                         toolResponse: {
                                             elapsedTimeSeconds: message.elapsed_time_seconds,
                                             // For Agent/Task calls: the subagent's type, and — when
@@ -3351,8 +3634,17 @@ export class ClaudeAcpAgent {
                         // and task store are independent of the previous transcript.
                         // Clear both the in-memory snapshot and the client's visible plan
                         // before any follow-up prompt can republish stale tasks.
+                        await finishLifecycle("failed", "failed", "during conversation reset");
+                        subagents.clear();
+                        asyncTasks.clear();
+                        session.eagerToolCallSessions?.clear();
+                        clearHookCallbacks(params.sessionId);
                         session.taskState.clear();
                         await this.publishTaskPlan(params.sessionId, session.taskState);
+                        // A reset mounts a fresh transcript (`new_conversation_id`), so our
+                        // cached title no longer describes the session: drop it and
+                        // re-evaluate at the next turn-end.
+                        session.titles.reset();
                         break;
                     }
                     case "tool_use_summary":
@@ -3383,6 +3675,7 @@ export class ClaudeAcpAgent {
                     message.includes("process exited with") ||
                     message.includes("process terminated by signal") ||
                     message.includes("Failed to write to process stdin"));
+            await finishLifecycle(session.cancelled ? "cancelled" : "failed", session.cancelled ? "stopped" : "failed", "after stream error");
             if (supportsAirSessionFailures(this.clientCapabilities) && session.activeTurn) {
                 if (!isHeldOpen(session.activeTurn)) {
                     await failActiveWithSessionFailure("transport_lost", internalErrorForClient({ errorKind: "transport_lost" }));
@@ -3405,6 +3698,10 @@ export class ClaudeAcpAgent {
                 this.logger.error(`Session ${params.sessionId}: Claude Agent process died: ${message}`);
                 failAllTurns(RequestError.internalError(undefined, "The Claude Agent process exited unexpectedly. Please start a new session."));
                 this.closeQueryStream(session);
+                session.eagerToolCallSessions?.clear();
+                clearHookCallbacks(params.sessionId);
+                session.nativeSubagentRuntime?.clear();
+                session.asyncTaskRuntime?.clear();
                 delete this.sessions[params.sessionId];
             }
             else {
@@ -3441,18 +3738,34 @@ export class ClaudeAcpAgent {
         }
     }
     async cancel(params) {
+        this.exitPlan.cancel(params.sessionId);
         const session = this.sessions[params.sessionId];
         if (!session) {
             return;
         }
+        session.cancelled = true;
+        session.pendingExitPlanModeInterruption = undefined;
+        session.pendingExitPlanContextReset = undefined;
         // The stream already ended (see closeQueryStream): every in-flight turn was
         // settled when it closed, and there is no live query to interrupt. Calling
         // query.interrupt() on a finished iterator could reject and surface from
         // this fire-and-forget notification, so there is nothing to do here.
         if (session.queryClosed) {
+            session.eagerToolCallSessions?.clear();
+            clearHookCallbacks(params.sessionId);
             return;
         }
-        session.cancelled = true;
+        try {
+            await session.nativeSubagentRuntime?.finishAll("cancelled", session.nativeSubagentDeliver ??
+                (async (notification) => this.client.sessionUpdate(asSdkSessionNotification(notification))));
+        }
+        catch (error) {
+            this.logger.error(`Session ${params.sessionId}: failed to publish cancelled subagent state`, error);
+        }
+        finally {
+            session.eagerToolCallSessions?.clear();
+            clearHookCallbacks(params.sessionId);
+        }
         // A priority steer may still be queued in the SDK when cancellation
         // settles its owning turn. Its later echo matches no live turn, and its
         // result must be skipped rather than promoted onto the next prompt.
@@ -3496,7 +3809,9 @@ export class ClaudeAcpAgent {
             // never see lifecycle frames, so commandStarted/commandFinished stay
             // unset and every turn takes the plain-seed path below).
             for (const turn of orphanedTurns) {
-                if (turn.commandFinished === "completed" || turn.commandFinished === "discarded") {
+                if (turn.commandFinished === "completed" ||
+                    turn.commandFinished === "discarded" ||
+                    turn.commandFinished === "refused") {
                     // The command already finished SDK-side and its terminal frame was
                     // consumed while the turn sat queued — nothing is left to skip, and
                     // a seeded entry would never drain.
@@ -3525,6 +3840,24 @@ export class ClaudeAcpAgent {
             }
             session.turnQueue = session.turnQueue.filter((turn) => turn === session.activeTurn && !turn.settled);
         }
+        const diagnosticTurns = orphanedTurns.filter((turn) => {
+            if (turn.commandFinished === "completed" ||
+                turn.commandFinished === "discarded" ||
+                turn.commandFinished === "refused") {
+                return false;
+            }
+            if (turn.commandStarted && turn.commandResultSeen)
+                return false;
+            if (turn.commandFinished === "cancelled" && !turn.commandStarted)
+                return false;
+            return true;
+        });
+        if (diagnosticTurns.length > 0) {
+            session.pendingEmptyInterruptionDiagnosticCommands ??= new Set();
+            for (const turn of diagnosticTurns) {
+                session.pendingEmptyInterruptionDiagnosticCommands.add(turn.promptUuid);
+            }
+        }
         // A deferred active turn (see Turn.deferredSettle) already has its
         // result — it is only held open for its background subagents, which the
         // interrupt below tears down. Settle it "cancelled" NOW: during the hold
@@ -3571,7 +3904,14 @@ export class ClaudeAcpAgent {
                 if (session.lastSessionState !== "idle") {
                     session.owedTrailingIdles++;
                 }
-                active.resolve({ stopReason: "cancelled", usage: active.deferredSettle.usage });
+                // Carries the held outcome's `_meta` too: a deferred outcome's only
+                // metadata is its quota breakdown, the counterpart of the usage taken
+                // from it here.
+                active.resolve({
+                    stopReason: "cancelled",
+                    usage: active.deferredSettle.usage,
+                    ...(active.deferredSettle._meta ? { _meta: active.deferredSettle._meta } : {}),
+                });
             }
         }
         // A steered active turn (see Turn.steeredEchoes) settles "cancelled" in the
@@ -3622,6 +3962,11 @@ export class ClaudeAcpAgent {
         // activation-time self-heal.
         if (Array.isArray(receipt?.still_queued) && orphanedTurns.length > 0) {
             const stillQueued = new Set(receipt.still_queued);
+            const droppedTurns = orphanedTurns.filter((turn) => !stillQueued.has(turn.promptUuid));
+            const droppedCount = droppedTurns.length;
+            for (const turn of droppedTurns) {
+                session.pendingEmptyInterruptionDiagnosticCommands?.delete(turn.promptUuid);
+            }
             if (lifecycleLane) {
                 // Lifecycle lane: forget dropped orphans by uuid. Only entries still
                 // "pending" — an orphan absent from `still_queued` because it was
@@ -3640,9 +3985,8 @@ export class ClaudeAcpAgent {
                 }
             }
             else {
-                const dropped = orphanedTurns.filter((turn) => !stillQueued.has(turn.promptUuid)).length;
-                if (dropped > 0) {
-                    session.pendingOrphanResults = Math.max(0, (session.pendingOrphanResults ?? 0) - dropped);
+                if (droppedCount > 0) {
+                    session.pendingOrphanResults = Math.max(0, (session.pendingOrphanResults ?? 0) - droppedCount);
                 }
             }
         }
@@ -3683,7 +4027,12 @@ export class ClaudeAcpAgent {
         if (!session) {
             return;
         }
-        await this.cancel({ sessionId });
+        try {
+            await this.cancel({ sessionId });
+        }
+        catch (error) {
+            this.logger.error(`Session ${sessionId}: cancellation failed during teardown`, error);
+        }
         // cancel() arms the force-cancel floor and interrupts gracefully, but a
         // wedged consumer only wakes when `cancelController` aborts — closeQueryStream
         // below doesn't touch it. Since we're tearing the session down anyway, wake
@@ -3699,6 +4048,10 @@ export class ClaudeAcpAgent {
         // here the client has asked us to close the session, so signalling abort is
         // appropriate; query.close() above has already torn the subprocess down.
         session.abortController.abort();
+        session.eagerToolCallSessions?.clear();
+        clearHookCallbacks(sessionId);
+        session.nativeSubagentRuntime?.clear();
+        session.asyncTaskRuntime?.clear();
         delete this.sessions[sessionId];
     }
     /** Tear down all active sessions. Called when the ACP connection closes. */
@@ -3722,19 +4075,7 @@ export class ClaudeAcpAgent {
         return {};
     }
     async setSessionMode(params) {
-        const session = this.sessions[params.sessionId];
-        if (!session) {
-            throw new Error("Session not found");
-        }
-        // The SDK query stream already ended (see closeQueryStream); the session is
-        // a husk and `query.setPermissionMode` below would act on a closed query.
-        // Fail with the same clear message prompt()/cancel() give for a dead stream.
-        if (session.queryClosed) {
-            throw RequestError.internalError(undefined, SESSION_ENDED_MESSAGE);
-        }
-        await this.applySessionMode(params.sessionId, params.modeId);
-        await this.updateConfigOption(params.sessionId, MODE_CONFIG_ID, params.modeId);
-        return {};
+        return this.sessionModes.setSessionMode(params);
     }
     async setSessionConfigOption(params) {
         const session = this.sessions[params.sessionId];
@@ -3804,15 +4145,10 @@ export class ClaudeAcpAgent {
         // Use the canonical option value so downstream code always receives the
         // model ID rather than the caller-supplied alias.
         const resolvedValue = validValue.value;
+        let effectiveValue = resolvedValue;
         if (params.configId === MODE_CONFIG_ID) {
-            await this.applySessionMode(params.sessionId, resolvedValue);
-            await this.client.sessionUpdate({
-                sessionId: params.sessionId,
-                update: {
-                    sessionUpdate: "current_mode_update",
-                    currentModeId: resolvedValue,
-                },
-            });
+            effectiveValue = await this.sessionModes.selectMode(params.sessionId, resolvedValue);
+            await this.sessionModes.publishCurrent(params.sessionId, effectiveValue);
         }
         else if (params.configId === MODEL_CONFIG_ID) {
             await this.sessions[params.sessionId].query.setModel(resolvedValue);
@@ -3820,44 +4156,9 @@ export class ClaudeAcpAgent {
         // Effort SDK sync is handled inside applyConfigOptionValue so that direct
         // effort changes and effort changes induced by a model switch go through
         // the same path.
-        await this.applyConfigOptionValue(params.sessionId, session, params.configId, resolvedValue);
+        await this.applyConfigOptionValue(params.sessionId, session, params.configId, effectiveValue);
         return { configOptions: session.configOptions };
     }
-    async applySessionMode(sessionId, modeId) {
-        switch (modeId) {
-            case "auto":
-            case "default":
-            case "acceptEdits":
-            case "bypassPermissions":
-            case "dontAsk":
-            case "plan":
-                break;
-            default:
-                throw new Error("Invalid Mode");
-        }
-        const session = this.sessions[sessionId];
-        if (!session) {
-            throw new Error("Session not found");
-        }
-        if (!session.modes.availableModes.some((mode) => mode.id === modeId)) {
-            throw new Error(`Mode ${modeId} is not available in this session`);
-        }
-        try {
-            await session.query.setPermissionMode(modeId);
-        }
-        catch (error) {
-            if (error instanceof Error) {
-                if (!error.message) {
-                    error.message = "Invalid Mode";
-                }
-                throw error;
-            }
-            else {
-                // eslint-disable-next-line preserve-caught-error
-                throw new Error("Invalid Mode");
-            }
-        }
-    }
     async replaySessionHistory(sessionId) {
         const toolUseCache = {};
         const messages = await getSessionMessages(sessionId);
@@ -3883,6 +4184,101 @@ export class ClaudeAcpAgent {
         // ends an incomplete audit lane.
         let replayingFileChangeAudit = false;
         const replayFileChangeAuditToolUseIds = new Set();
+        const nativeReplayEnabled = clientSupportsSubagents(this.clientCapabilities);
+        const replayTerminalStates = new Map();
+        const replayChildren = new Map();
+        if (nativeReplayEnabled) {
+            for (const message of messages) {
+                const content = message.message
+                    ?.content;
+                if (!Array.isArray(content))
+                    continue;
+                const ownerToolUseId = parentToolUseIdOf(message);
+                for (const block of content) {
+                    if (typeof block === "object" &&
+                        block !== null &&
+                        "type" in block &&
+                        (block.type === "tool_result" || block.type === "mcp_tool_result") &&
+                        "tool_use_id" in block &&
+                        typeof block.tool_use_id === "string") {
+                        replayTerminalStates.set(block.tool_use_id, replaySubagentTerminalState(block));
+                    }
+                    if (typeof block !== "object" ||
+                        block === null ||
+                        !("type" in block) ||
+                        !["tool_use", "server_tool_use", "mcp_tool_use"].includes(String(block.type)) ||
+                        !("id" in block) ||
+                        typeof block.id !== "string" ||
+                        !("name" in block) ||
+                        !isNativeSubagentControlTool(block.name)) {
+                        continue;
+                    }
+                    const input = "input" in block && typeof block.input === "object" && block.input !== null
+                        ? block.input
+                        : {};
+                    const task = [input.prompt, input.description]
+                        .find((value) => typeof value === "string" && value.trim().length > 0)
+                        ?.trim() ?? "Delegated task restored from session history";
+                    const name = [input.name, input.description, input.subagent_type]
+                        .find((value) => typeof value === "string" && value.trim().length > 0)
+                        ?.trim() ?? "Restored agent";
+                    replayChildren.set(block.id, {
+                        sessionId: `${sessionId}:replay-subagent:${block.id}`,
+                        ...(ownerToolUseId ? { parentToolUseId: ownerToolUseId } : {}),
+                        name,
+                        task,
+                        reconstructable: true,
+                        announced: false,
+                        terminalState: replayTerminalStates.get(block.id),
+                    });
+                }
+            }
+            for (const [toolUseId, terminalState] of replayTerminalStates) {
+                const child = replayChildren.get(toolUseId);
+                if (child)
+                    child.terminalState = terminalState;
+            }
+        }
+        const announceReplayChild = async (parentToolUseId, ancestors = new Set()) => {
+            let child = replayChildren.get(parentToolUseId);
+            if (!child) {
+                child = {
+                    sessionId: `${sessionId}:replay-subagent:${parentToolUseId}`,
+                    name: "Disconnected agent",
+                    task: "Subagent restored without persisted launch metadata",
+                    reconstructable: false,
+                    announced: false,
+                };
+                replayChildren.set(parentToolUseId, child);
+            }
+            if (ancestors.has(parentToolUseId)) {
+                child.reconstructable = false;
+                child.terminalState = undefined;
+                child.parentToolUseId = undefined;
+            }
+            if (child.parentToolUseId) {
+                const nextAncestors = new Set(ancestors);
+                nextAncestors.add(parentToolUseId);
+                await announceReplayChild(child.parentToolUseId, nextAncestors);
+            }
+            if (!child.announced) {
+                const parentSessionId = child.parentToolUseId
+                    ? (replayChildren.get(child.parentToolUseId)?.sessionId ?? sessionId)
+                    : sessionId;
+                await this.client.sessionUpdate(asSdkSessionNotification({
+                    sessionId: parentSessionId,
+                    update: {
+                        sessionUpdate: "subagent_spawned",
+                        subagentSessionId: child.sessionId,
+                        name: child.name,
+                        task: child.task,
+                        capabilities: {},
+                    },
+                }));
+                child.announced = true;
+            }
+            return child.sessionId;
+        };
         for (const message of messages) {
             if (message.type === "user" &&
                 message.parent_tool_use_id === null &&
@@ -3923,7 +4319,13 @@ export class ClaudeAcpAgent {
             // @ts-expect-error - untyped in SDK but we handle all of these
             let content = message.message.content;
             const parentToolUseId = parentToolUseIdOf(message);
-            if (message.type === "assistant" && parentToolUseId && !forwardSubagentText) {
+            const replayTargetSessionId = nativeReplayEnabled && parentToolUseId
+                ? await announceReplayChild(parentToolUseId)
+                : sessionId;
+            if (message.type === "assistant" &&
+                parentToolUseId &&
+                !nativeReplayEnabled &&
+                !forwardSubagentText) {
                 content = stripSubagentTextAndThinking(content);
             }
             // @ts-expect-error - untyped in SDK but we handle all of these
@@ -3995,7 +4397,37 @@ export class ClaudeAcpAgent {
                 messageId: replayMessageId,
                 parentToolUseId,
             })) {
-                await this.client.sessionUpdate(notification);
+                const toolName = notification.update._meta?.claudeCode?.toolName;
+                if (nativeReplayEnabled &&
+                    (notification.update.sessionUpdate === "tool_call" ||
+                        notification.update.sessionUpdate === "tool_call_update") &&
+                    isNativeSubagentControlTool(toolName)) {
+                    continue;
+                }
+                await this.client.sessionUpdate({ ...notification, sessionId: replayTargetSessionId });
+            }
+        }
+        if (nativeReplayEnabled) {
+            // Claude history persists sidechain messages and Agent/Task tool uses,
+            // but not task_started/task_updated lifecycle frames. Recover terminal
+            // state from the launch tool_result. Missing results and malformed or
+            // orphan lineage use the draft protocol's deterministic disconnected state.
+            for (const child of [...replayChildren.values()].reverse()) {
+                if (!child.announced)
+                    continue;
+                const parentSessionId = child.parentToolUseId
+                    ? (replayChildren.get(child.parentToolUseId)?.sessionId ?? sessionId)
+                    : sessionId;
+                await this.client.sessionUpdate(asSdkSessionNotification({
+                    sessionId: parentSessionId,
+                    update: {
+                        sessionUpdate: "subagent_state_update",
+                        subagentSessionId: child.sessionId,
+                        state: child.reconstructable
+                            ? (child.terminalState ?? "disconnected")
+                            : "disconnected",
+                    },
+                }));
             }
         }
     }
@@ -4007,23 +4439,45 @@ export class ClaudeAcpAgent {
         const response = await this.client.writeTextFile(params);
         return response;
     }
+    /** Mark a client request as blocking on user input for exactly the lifetime
+     *  of its promise. Steering consults this session-local count synchronously,
+     *  so a message arriving while any permission/elicitation card is open uses
+     *  non-interrupting SDK delivery. */
+    async withPendingUserInput(sessionId, request) {
+        const session = this.sessions[sessionId];
+        if (!session)
+            return request();
+        session.pendingUserInputCount = (session.pendingUserInputCount ?? 0) + 1;
+        try {
+            return await request();
+        }
+        finally {
+            session.pendingUserInputCount = Math.max(0, (session.pendingUserInputCount ?? 1) - 1);
+        }
+    }
     /** Forward a permission request to the client, wiring the tool call's
      *  `signal` through as a `cancellationSignal`. When the turn is cancelled
      *  while the client's prompt is still open the signal aborts, the SDK sends
-     *  `$/cancel_request`, and the client settles the request (a `cancelled`
-     *  outcome or a `requestCancelled` rejection). Either way we surface the same
-     *  "Tool use aborted" the callers already expect, so a cancelled dialog no
-     *  longer leaves the `await` hanging. */
-    async requestPermissionFromClient(params, toolName, signal, parentToolUseId) {
+     *  `$/cancel_request`, and our local abort race settles even if the client
+     *  ignores it. A `cancelled` outcome, request rejection, and local abort all
+     *  surface the same "Tool use aborted" the callers already expect. */
+    async requestPermissionFromClient(params, toolName, signal, parentToolUseId, ownerSessionId = params.sessionId) {
+        if (signal.aborted)
+            throw new Error("Tool use aborted");
         // The SDK may invoke `canUseTool` (and therefore this permission request)
         // before the assistant message's tool_use block streams to us. Some ACP clients
         // expect the `tool_call` a permission request references to already exist,
         // so emit it now if it hasn't been sent yet. The streamed tool_use chunk
         // later refines it with a `tool_call_update` rather than emitting a
         // duplicate (see `emittedToolCalls` in `toAcpNotifications`).
-        await this.ensureToolCallEmitted(params.sessionId, toolName, params.toolCall.toolCallId, params.toolCall.rawInput, parentToolUseId);
+        await this.ensureToolCallEmitted(ownerSessionId, toolName, params.toolCall.toolCallId, params.toolCall.rawInput, parentToolUseId, signal, params.sessionId);
+        if (signal.aborted)
+            throw new Error("Tool use aborted");
+        // Do not rely on every ACP client settling requestPermission after the
+        // cancellation signal. The local race guarantees that Claude's tool call
+        // is released even when an older or broken client ignores $/cancel_request.
         try {
-            return await this.client.requestPermission(params, signal);
+            return await this.withPendingUserInput(params.sessionId, () => raceWithAbort(this.client.requestPermission(params, signal), signal));
         }
         catch (error) {
             if (signal.aborted) {
@@ -4044,7 +4498,7 @@ export class ClaudeAcpAgent {
      *  are resolved at tool_result time instead (see `toAcpNotifications`).
      *  `parentToolUseId` attributes a subagent's tool call to the Agent/Task call
      *  that spawned it, matching the streamed path's `_meta`. */
-    async ensureToolCallEmitted(sessionId, toolName, toolCallId, toolInput, parentToolUseId) {
+    async ensureToolCallEmitted(sessionId, toolName, toolCallId, toolInput, parentToolUseId, signal, notificationSessionId = sessionId) {
         const session = this.sessions[sessionId];
         if (!session) {
             return;
@@ -4053,6 +4507,7 @@ export class ClaudeAcpAgent {
             return;
         }
         session.emittedToolCalls.add(toolCallId);
+        (session.eagerToolCallSessions ??= new Map()).set(toolCallId, notificationSessionId);
         const supportsTerminalOutput = this.clientCapabilities?._meta?.["terminal_output"] === true;
         const update = toolCallNotification({ id: toolCallId, name: toolName, input: toolInput }, toolInput, supportsTerminalOutput, session.cwd);
         if (parentToolUseId) {
@@ -4064,10 +4519,21 @@ export class ClaudeAcpAgent {
                 },
             };
         }
-        await this.client.sessionUpdate({ sessionId, update });
+        try {
+            const emission = this.client.sessionUpdate({ sessionId: notificationSessionId, update });
+            await (signal ? raceWithAbort(emission, signal) : emission);
+        }
+        catch (error) {
+            // The set is also the de-duplication guard for the later streamed
+            // tool_use. Keep it truthful: if emission failed, that path must still
+            // be allowed to publish the tool call instead of refining a phantom one.
+            session.emittedToolCalls.delete(toolCallId);
+            session.eagerToolCallSessions?.delete(toolCallId);
+            throw error;
+        }
     }
     canUseTool(sessionId) {
-        return async (toolName, toolInput, { signal, suggestions, toolUseID, agentID, matchedAskRule }) => {
+        return async (toolName, toolInput, { signal, suggestions, toolUseID, agentID, matchedAskRule, blockedPath, decisionReason, title, displayName, description, }) => {
             const supportsTerminalOutput = this.clientCapabilities?._meta?.["terminal_output"] === true;
             const session = this.sessions[sessionId];
             if (!session) {
@@ -4103,6 +4569,17 @@ export class ClaudeAcpAgent {
             const parentToolUseId = agentID
                 ? session.liveBackgroundTasks.get(agentID)?.parentToolUseId
                 : undefined;
+            const permissionSessionId = clientSupportsSubagents(this.clientCapabilities) && agentID
+                ? (() => {
+                    const child = session.nativeSubagentsByTaskId?.get(agentID);
+                    // A request must never target a child session before its
+                    // subagent_spawned notification. In the rare SDK ordering where
+                    // canUseTool beats the spawning Agent/Task frame, keep the
+                    // permission on the root session; the later frame will announce
+                    // the child with correct nested lineage.
+                    return child?.announced ? child.sessionId : sessionId;
+                })()
+                : sessionId;
             if (agentID && !parentToolUseId) {
                 // The attribution rests on an undocumented SDK invariant
                 // (task_started.task_id === canUseTool's agentID for subagent tasks;
@@ -4120,152 +4597,81 @@ export class ClaudeAcpAgent {
             if (toolName === "AskUserQuestion" && this.clientCapabilities?.elicitation?.form) {
                 // Like permission requests, the elicitation references this toolUseID, so
                 // make sure the tool_call has surfaced to the client before we send it.
-                await this.ensureToolCallEmitted(sessionId, toolName, toolUseID, toolInput, parentToolUseId);
-                return this.handleAskUserQuestion(sessionId, toolInput, toolUseID, signal);
+                await this.ensureToolCallEmitted(sessionId, toolName, toolUseID, toolInput, parentToolUseId, signal, permissionSessionId);
+                return this.handleAskUserQuestion(permissionSessionId, toolInput, toolUseID, signal);
             }
-            if (toolName === "ExitPlanMode") {
-                const optionsAll = [
-                    { kind: "allow_always", name: 'Yes, and use "auto" mode', optionId: "auto" },
-                    {
-                        kind: "allow_always",
-                        name: "Yes, and auto-accept edits",
-                        optionId: "acceptEdits",
-                    },
-                    { kind: "allow_once", name: "Yes, and manually approve edits", optionId: "default" },
-                    { kind: "reject_once", name: "No, keep planning", optionId: "plan" },
-                ];
-                if (ALLOW_BYPASS) {
-                    optionsAll.unshift({
-                        kind: "allow_always",
-                        name: "Yes, and bypass permissions",
-                        optionId: "bypassPermissions",
-                    });
-                }
-                // Filter against the session's currently-advertised modes so we never
-                // present options the active model can't honor (e.g. `auto` on Haiku).
-                // `bypassPermissions` is already covered by `availableModes` via
-                // `buildAvailableModes`/`ALLOW_BYPASS`. The `plan` option is a
-                // "keep planning" reject path; it's always present in `availableModes`.
-                const options = optionsAll.filter((o) => session.modes.availableModes.some((m) => m.id === o.optionId));
-                const response = await this.requestPermissionFromClient({
-                    options,
-                    sessionId,
-                    toolCall: {
-                        toolCallId: toolUseID,
-                        rawInput: toolInput,
-                        ...toolInfoFromToolUse({ name: toolName, input: toolInput, id: toolUseID }, supportsTerminalOutput, session?.cwd),
-                        // `claudeCode` metas always carry `toolName` (see ToolUpdateMeta),
-                        // so clients can rely on one shape everywhere.
-                        ...(parentToolUseId
-                            ? { _meta: { claudeCode: { toolName, parentToolUseId } } }
-                            : {}),
-                    },
-                }, toolName, signal, parentToolUseId);
-                if (signal.aborted || response.outcome?.outcome === "cancelled") {
-                    throw new Error("Tool use aborted");
-                }
-                const selectedMode = response.outcome?.outcome === "selected" ? response.outcome.optionId : undefined;
-                const selectedModeWasOffered = options.some((option) => option.optionId === selectedMode);
-                if (selectedModeWasOffered &&
-                    (selectedMode === "default" ||
-                        selectedMode === "acceptEdits" ||
-                        selectedMode === "auto" ||
-                        selectedMode === "bypassPermissions")) {
-                    await this.client.sessionUpdate({
-                        sessionId,
-                        update: {
-                            sessionUpdate: "current_mode_update",
-                            currentModeId: selectedMode,
-                        },
-                    });
-                    await this.updateConfigOption(sessionId, MODE_CONFIG_ID, selectedMode);
-                    return {
-                        behavior: "allow",
-                        updatedInput: toolInput,
-                        updatedPermissions: suggestions ?? [
-                            { type: "setMode", mode: selectedMode, destination: "session" },
-                        ],
-                    };
-                }
-                else {
-                    return {
-                        behavior: "deny",
-                        message: "User rejected request to exit plan mode.",
-                    };
-                }
-            }
-            // In bypass mode the CLI skips permission checks itself; the asks that
-            // still reach canUseTool are the ones it insists on prompting for even
-            // under --dangerously-skip-permissions. Keep auto-allowing those —
-            // bypass means bypass — EXCEPT rule-forced asks (`matchedAskRule`): the
-            // user explicitly configured a permissions.ask rule for this tool, and
-            // the SDK's guidance is that hosts running auto-approval must treat such
-            // asks as a human prompt. Fall through to the normal request below.
-            if (session.modes.currentModeId === "bypassPermissions" && !matchedAskRule) {
-                return {
-                    behavior: "allow",
-                    updatedInput: toolInput,
-                    updatedPermissions: suggestions ?? [
-                        { type: "addRules", rules: [{ toolName }], behavior: "allow", destination: "session" },
-                    ],
+            // Do not auto-allow here based on the session's advertised mode. Claude
+            // Code applies bypassPermissions before invoking canUseTool; a request
+            // that still reaches this callback is deliberately bypass-immune (for
+            // example a safety check, a tool requiring user interaction, or an
+            // explicit ask rule). Re-applying bypass in the host would erase that
+            // provider safety decision.
+            const durableChangeSet = normalizeDurablePermissionChangeSet(suggestions, matchedAskRule !== undefined);
+            const presentation = buildClaudePermissionPresentation({
+                toolName,
+                input: toolInput,
+                toolUseID,
+                cwd: session.cwd,
+                supportsTerminalOutput,
+                blockedPath,
+                title,
+                displayName,
+                description,
+                decisionReason,
+            });
+            if (parentToolUseId) {
+                presentation.toolCall._meta = {
+                    claudeCode: { toolName, parentToolUseId },
                 };
             }
+            const permissionOptions = buildClaudePermissionOptions({
+                toolName,
+                displayName,
+                input: toolInput,
+                cwd: session.cwd,
+                durableChangeSet,
+                allowPersistentOptions: matchedAskRule === undefined,
+                availableModes: this.sessionModes.availableModeIds(session.modes),
+                contextUsedPercent: session.contextUsedTokens === undefined || session.contextWindowSize <= 0
+                    ? undefined
+                    : Math.max(0, Math.min(100, Math.round((session.contextUsedTokens / session.contextWindowSize) * 100))),
+            });
             const response = await this.requestPermissionFromClient({
-                options: [
-                    { kind: "reject_once", name: "Deny", optionId: "reject" },
-                    { kind: "allow_once", name: "Allow Once", optionId: "allow" },
-                    {
-                        kind: "allow_always",
-                        name: "Always Allow",
-                        optionId: "allow_always",
-                        _meta: {
-                            permission: permissionMetadataForAlwaysAllow(suggestions, toolName),
-                        },
-                    },
-                ],
-                sessionId,
-                toolCall: {
-                    toolCallId: toolUseID,
-                    rawInput: toolInput,
-                    ...toolInfoFromToolUse({ name: toolName, input: toolInput, id: toolUseID }, supportsTerminalOutput, session?.cwd),
-                    // `claudeCode` metas always carry `toolName` (see ToolUpdateMeta),
-                    // so clients can rely on one shape everywhere.
-                    ...(parentToolUseId
-                        ? { _meta: { claudeCode: { toolName, parentToolUseId } } }
-                        : {}),
-                },
-            }, toolName, signal, parentToolUseId);
-            if (signal.aborted || response.outcome?.outcome === "cancelled") {
+                ...presentation,
+                options: permissionOptions,
+                sessionId: permissionSessionId,
+            }, toolName, signal, parentToolUseId, sessionId);
+            if (signal.aborted)
                 throw new Error("Tool use aborted");
+            const decodedPermission = decodeClaudePermissionResponse(response, toolName, toolInput, toolUseID, permissionOptions, durableChangeSet);
+            let permissionResult = decodedPermission.permissionResult;
+            const autoFallback = this.sessionModes.applyPermissionFallback(session, permissionResult);
+            permissionResult = autoFallback.permissionResult;
+            if (autoFallback.fallbackApplied) {
+                await this.sessionModes.publishFallbackWarning(sessionId, session);
             }
-            if (response.outcome?.outcome === "selected" &&
-                (response.outcome.optionId === "allow" || response.outcome.optionId === "allow_always")) {
-                // If Claude Code has suggestions, it will update their settings already
-                if (response.outcome.optionId === "allow_always") {
-                    return {
-                        behavior: "allow",
-                        updatedInput: toolInput,
-                        updatedPermissions: suggestions ?? [
-                            {
-                                type: "addRules",
-                                rules: [{ toolName }],
-                                behavior: "allow",
-                                destination: "session",
-                            },
-                        ],
-                    };
-                }
-                return {
-                    behavior: "allow",
-                    updatedInput: toolInput,
+            const clearContextMode = decodedPermission.contextResetMode
+                ? this.sessionModes.effectiveMode(session, decodedPermission.contextResetMode)
+                : undefined;
+            if (toolName === "ExitPlanMode" && clearContextMode) {
+                const plan = typeof toolInput.plan === "string" ? toolInput.plan.trim() : "";
+                if (!plan)
+                    throw new Error("ExitPlanMode clear-context selection requires a plan");
+                session.pendingExitPlanContextReset = {
+                    toolUseId: toolUseID,
+                    plan,
+                    mode: clearContextMode,
                 };
             }
-            else {
-                return {
-                    behavior: "deny",
-                    message: "User refused permission to run tool",
+            if (toolName === "ExitPlanMode" &&
+                permissionResult.behavior === "deny" &&
+                permissionResult.interrupt === true) {
+                session.pendingExitPlanModeInterruption = {
+                    toolUseId: toolUseID,
+                    toolResultSeen: false,
                 };
             }
+            return permissionResult;
         };
     }
     /**
@@ -4284,7 +4690,7 @@ export class ClaudeAcpAgent {
                 return { action: "decline" };
             }
             try {
-                const response = await this.client.unstable_createElicitation(createRequest, signal);
+                const response = await this.withPendingUserInput(sessionId, () => this.client.unstable_createElicitation(createRequest, signal));
                 if (signal.aborted) {
                     return { action: "cancel" };
                 }
@@ -4314,7 +4720,7 @@ export class ClaudeAcpAgent {
         const createRequest = askUserQuestionsToCreateRequest(questions, sessionId, toolUseID);
         let response;
         try {
-            response = await this.client.unstable_createElicitation(createRequest, signal);
+            response = await this.withPendingUserInput(sessionId, () => this.client.unstable_createElicitation(createRequest, signal));
         }
         catch (error) {
             // A cancellation we requested (signal aborted) settles as an aborted tool
@@ -4354,7 +4760,7 @@ export class ClaudeAcpAgent {
             }
             let response;
             try {
-                response = await this.client.unstable_createElicitation(refusalFallbackToCreateRequest(prompt, sessionId), signal);
+                response = await this.withPendingUserInput(sessionId, () => this.client.unstable_createElicitation(refusalFallbackToCreateRequest(prompt, sessionId), signal));
             }
             catch (error) {
                 // A cancellation we requested (signal aborted) is expected teardown;
@@ -4400,12 +4806,11 @@ export class ClaudeAcpAgent {
     }
     async applyConfigOptionValue(sessionId, session, configId, value) {
         if (configId === MODE_CONFIG_ID) {
-            session.modes = { ...session.modes, currentModeId: value };
-            session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
+            this.sessionModes.syncConfig(session, value);
         }
         else if (configId === MODEL_CONFIG_ID) {
-            // `ModelInfo.supportsAutoMode` is the canonical SDK signal for clamping
-            // modes below; its `displayName`/`description` also let us infer the
+            // `ModelInfo.supportsAutoMode` is the canonical SDK signal for applying
+            // the Auto fallback below; its `displayName`/`description` also let us infer the
             // context window for semantic aliases (e.g. `default`) whose ID alone
             // carries no "1m" token.
             const newModelInfo = session.modelInfos.find((m) => m.value === value);
@@ -4427,41 +4832,7 @@ export class ClaudeAcpAgent {
                 session.contextWindowAuthoritative = seeded.authoritative;
             }
             session.models = { ...session.models, currentModelId: value };
-            // Recompute availableModes for the new model and clamp the current
-            // mode if the SDK no longer offers it (today: "auto" on Haiku). An
-            // unknown model (an SDK-initiated refusal fallback to a model outside
-            // the user's `availableModels` allowlist — user-driven switches are
-            // validated against the options first) tells us nothing about its
-            // capabilities, so keep the current modes rather than spuriously
-            // downgrading (e.g. kicking the user out of "auto" for a model that
-            // does support it).
-            const newAvailableModes = newModelInfo
-                ? buildAvailableModes(newModelInfo)
-                : session.modes.availableModes;
-            // Capture BEFORE mutating session.modes so the log message reflects
-            // the invalidated mode rather than "default".
-            const previousModeId = session.modes.currentModeId;
-            let modeDowngraded = false;
-            if (!newAvailableModes.some((m) => m.id === previousModeId)) {
-                session.modes = {
-                    availableModes: newAvailableModes,
-                    currentModeId: "default",
-                };
-                try {
-                    await session.query.setPermissionMode("default");
-                }
-                catch (err) {
-                    // Failing the entire model switch over a bookkeeping sync error is
-                    // worse UX than logging and continuing; the user explicitly asked
-                    // to change models. The next setPermissionMode from the user will
-                    // either succeed or surface a fresh error.
-                    this.logger.error(`Failed to sync permissionMode to "default" after model switch invalidated "${previousModeId}":`, err);
-                }
-                modeDowngraded = true;
-            }
-            else {
-                session.modes = { ...session.modes, availableModes: newAvailableModes };
-            }
+            const modeDowngraded = await this.sessionModes.reconcileForModel(session, newModelInfo);
             // `model_not_allowed` described the model we just left, so it must not
             // follow us onto the new one; the remaining reasons are account- or
             // environment-scoped and stay true across a switch. Either way the next
@@ -4496,13 +4867,7 @@ export class ClaudeAcpAgent {
             // still precedes the caller's config_option_update so order-sensitive
             // clients update currentModeId before re-rendering the option list.
             if (modeDowngraded) {
-                await this.client.sessionUpdate({
-                    sessionId,
-                    update: {
-                        sessionUpdate: "current_mode_update",
-                        currentModeId: "default",
-                    },
-                });
+                await this.sessionModes.publishFallbackState(sessionId, session);
             }
         }
         else if (configId === AGENT_CONFIG_ID) {
@@ -4703,7 +5068,10 @@ export class ClaudeAcpAgent {
         // We want to create a new session id unless it is resume,
         // but not resume + forkSession.
         let sessionId;
-        if (creationOpts.forkSession) {
+        if (creationOpts.publicSessionId) {
+            sessionId = creationOpts.publicSessionId;
+        }
+        else if (creationOpts.forkSession) {
             sessionId = randomUUID();
         }
         else if (creationOpts.resume) {
@@ -4762,10 +5130,12 @@ export class ClaudeAcpAgent {
             }
         }
         const permissionMode = resolvePermissionMode(settingsManager.getSettings().permissions?.defaultMode, this.logger);
+        const initialPermissionMode = creationOpts.permissionMode ?? permissionMode;
         // Extract options from _meta if provided
         const sessionMeta = params._meta;
         const userProvidedOptions = sessionMeta?.claudeCode?.options;
-        const forwardSubagentText = supportsSubagentTranscript(this.clientCapabilities) ||
+        const forwardSubagentText = clientSupportsSubagents(this.clientCapabilities) ||
+            supportsSubagentTranscript(this.clientCapabilities) ||
             userProvidedOptions?.forwardSubagentText === true;
         // Configure thinking behavior from environment variable
         const thinking = resolveThinkingConfig(process.env.MAX_THINKING_TOKENS, this.logger);
@@ -4884,7 +5254,7 @@ export class ClaudeAcpAgent {
             // If we want bypassPermissions to be an option, we have to allow it here.
             // But it doesn't work in root mode, so we only activate it if it will work.
             allowDangerouslySkipPermissions: ALLOW_BYPASS,
-            permissionMode,
+            permissionMode: initialPermissionMode,
             canUseTool: this.canUseTool(sessionId),
             // Forward MCP elicitation requests onto ACP elicitation. Only attached
             // when the client advertised support, so non-supporting clients keep the
@@ -4928,13 +5298,7 @@ export class ClaudeAcpAgent {
                         hooks: [
                             createPostToolUseHook({
                                 onEnterPlanMode: async () => {
-                                    await this.client.sessionUpdate({
-                                        sessionId,
-                                        update: {
-                                            sessionUpdate: "current_mode_update",
-                                            currentModeId: "plan",
-                                        },
-                                    });
+                                    await this.sessionModes.publishCurrent(sessionId, "plan");
                                     await this.updateConfigOption(sessionId, MODE_CONFIG_ID, "plan");
                                 },
                             }),
@@ -4972,7 +5336,8 @@ export class ClaudeAcpAgent {
                     },
                 ],
             },
-            ...creationOpts,
+            ...(creationOpts.resume !== undefined && { resume: creationOpts.resume }),
+            ...(creationOpts.forkSession !== undefined && { forkSession: creationOpts.forkSession }),
             abortController,
         };
         // Prefer the official ACP `additionalDirectories` field. Fall back to the
@@ -4982,7 +5347,7 @@ export class ClaudeAcpAgent {
         options.additionalDirectories = additionalDirectories;
         if (creationOpts?.resume === undefined || creationOpts?.forkSession) {
             // Set our own session id if not resuming an existing session.
-            options.sessionId = sessionId;
+            options.sessionId = creationOpts.publicSessionId ? randomUUID() : sessionId;
         }
         // Handle abort controller from meta options
         if (abortController?.signal.aborted) {
@@ -5021,8 +5386,8 @@ export class ClaudeAcpAgent {
             ? applyAvailableModelsAllowlist(initializationResult.models, settingsAvailableModels, settingsModelOverrides)
             : initializationResult.models;
         const { modelState: models, resumedContextWindow } = await getAvailableModels(q, allowedModels, initializationResult.models, settingsManager, this.logger, creationOpts.resume !== undefined);
-        // Gate `auto` (and future model-specific modes) on the resolved model's
-        // `ModelInfo`. See `buildAvailableModes` for the canonical SDK signal.
+        // Resolve the current model's capabilities separately from the stable
+        // permission-mode catalog advertised to ACP clients.
         // A resumed session can be running a model outside the `availableModels`
         // allowlist (currentModelId is then the verbatim live id, see
         // `matchResumedModel`); its capabilities are still known to the SDK's
@@ -5056,38 +5421,12 @@ export class ClaudeAcpAgent {
                 },
             ]
             : allowedModels;
-        const availableModes = buildAvailableModes(currentModelInfo);
-        // Clamp `permissionMode` if the resolved session does not offer it. The
-        // common case is `permissions.defaultMode: "auto"` resolving to a model
-        // that does not support auto mode (e.g. Haiku); without this clamp the
-        // SDK would later throw `"auto mode unavailable for this model"` from
-        // `setPermissionMode`. Keep `permissionMode` as the resolved user intent
-        // (matches what was passed into `options.permissionMode` above) and use
-        // `effectiveMode` for the post-clamp value the session actually runs in.
-        let effectiveMode = permissionMode;
-        if (!availableModes.some((m) => m.id === effectiveMode)) {
-            if (effectiveMode === "auto") {
-                this.logger.error(`permissions.defaultMode "auto" is not available for model ` +
-                    `"${models.currentModelId}"; falling back to "default".`);
-            }
-            else {
-                this.logger.error(`permissions.defaultMode "${effectiveMode}" is not available in ` +
-                    `this session; falling back to "default".`);
-            }
-            effectiveMode = "default";
-            // Sync the SDK so it doesn't keep "auto" cached internally. Wrapped in
-            // try/catch since failing here would abort session creation entirely.
-            try {
-                await q.setPermissionMode("default");
-            }
-            catch (err) {
-                this.logger.error("Failed to sync clamped permissionMode to SDK:", err);
-            }
-        }
-        const modes = {
-            currentModeId: effectiveMode,
-            availableModes,
-        };
+        const { modes, autoModeFallbackWarningPending } = await this.sessionModes.initialize({
+            query: q,
+            requestedMode: initialPermissionMode,
+            currentModelInfo,
+            currentModelId: models.currentModelId,
+        });
         const agents = await discoverCustomAgents(q);
         // Only adopt the requested agent as the selected value if it's one we
         // actually surface in the picker. A built-in (filtered out above) or
@@ -5165,15 +5504,20 @@ export class ClaudeAcpAgent {
             sessionFingerprint: computeSessionFingerprint(params),
             creationParams: params,
             settingsManager,
+            titles: new SessionTitles(this, sessionId),
             accumulatedUsage: {
                 inputTokens: 0,
                 outputTokens: 0,
                 cachedReadTokens: 0,
                 cachedWriteTokens: 0,
             },
+            accumulatedModelUsage: {},
+            lastModelUsageReading: {},
             modes,
             models,
             modelInfos,
+            autoModeFallbackWarningShown: false,
+            autoModeFallbackWarningPending,
             configOptions,
             agents,
             currentAgent,
@@ -5188,7 +5532,11 @@ export class ClaudeAcpAgent {
             taskState,
             toolUseCache: {},
             emittedToolCalls: new Set(),
+            eagerToolCallSessions: new Map(),
             liveBackgroundTasks: new Map(),
+            nativeSubagentsByTaskId: new Map(),
+            nativeSubagentTaskIdByToolUseId: new Map(),
+            nativeSubagentParentByToolUseId: new Map(),
             emittedAssistantText: false,
             owedTrailingIdles: 0,
             messageIdToUuid: new Map(),
@@ -5253,12 +5601,125 @@ function sessionUsage(session) {
         outputTokens: session.accumulatedUsage.outputTokens,
         cachedReadTokens: session.accumulatedUsage.cachedReadTokens,
         cachedWriteTokens: session.accumulatedUsage.cachedWriteTokens,
-        totalTokens: session.accumulatedUsage.inputTokens +
-            session.accumulatedUsage.outputTokens +
-            session.accumulatedUsage.cachedReadTokens +
-            session.accumulatedUsage.cachedWriteTokens,
+        totalTokens: tallyTotal(session.accumulatedUsage),
+    };
+}
+/** The prompt response for a turn ending in `stopReason`: its usage and the
+ *  `_meta.quota` breakdown, both read off the session accumulators in the same
+ *  breath so a stored outcome (see Turn.deferredSettle / Turn.steeredSettle)
+ *  can't carry a usage and a quota from different moments. `extraMeta` merges
+ *  in alongside quota — a terminal session failure, today. */
+function turnOutcome(session, stopReason, extraMeta) {
+    return {
+        stopReason,
+        usage: sessionUsage(session),
+        _meta: { ...turnQuotaMeta(session), ...extraMeta },
     };
 }
+/** `_meta.quota` for a prompt response: what the turn spent, shaped like
+ *  codex-acp's (snake_case container keys, camelCase counters) so a client
+ *  reads one shape from either agent.
+ *
+ *  The two halves have different scopes, and by design don't have to add up.
+ *  `token_count` mirrors the response's own `usage`, which the SDK reports for
+ *  the MAIN AGENT LOOP only. The `model_usage` rows come from
+ *  `result.modelUsage`, which also counts Task subagents, sidechains and
+ *  internal calls such as compaction — the accounting-grade figure per the SDK,
+ *  so the rows can total more than `token_count`. They are the fuller picture,
+ *  not a decomposition of it. */
+function turnQuotaMeta(session) {
+    return {
+        quota: {
+            token_count: quotaTokenCount(session.accumulatedUsage),
+            model_usage: Object.entries(session.accumulatedModelUsage ?? {}).map(([model, usage]) => ({
+                model,
+                token_count: quotaTokenCount(usage),
+            })),
+        },
+    };
+}
+/** One `token_count` object. `cachedInputTokens` is cache reads, matching
+ *  codex's field; Claude also reports cache writes, which codex has no slot
+ *  for, so those ride along in an extra sibling (the same name the ACP `usage`
+ *  field already uses) and are counted in `totalTokens`. `reasoningOutputTokens`
+ *  is always 0: Claude bills thinking inside its output tokens and never breaks
+ *  it out — the key is kept so the shape stays uniform across agents. */
+function quotaTokenCount(usage) {
+    return {
+        totalTokens: tallyTotal(usage),
+        inputTokens: usage.inputTokens,
+        cachedInputTokens: usage.cachedReadTokens,
+        cachedWriteTokens: usage.cachedWriteTokens,
+        outputTokens: usage.outputTokens,
+        reasoningOutputTokens: 0,
+    };
+}
+/** Sum a tally's four counters. Per the Anthropic API `inputTokens` excludes
+ *  the cache counters, so this is not double-counting (see `totalTokens`). */
+function tallyTotal(usage) {
+    return usage.inputTokens + usage.outputTokens + usage.cachedReadTokens + usage.cachedWriteTokens;
+}
+/** Project `result.modelUsage` into our tally shape. Counters are coerced the
+ *  way `snapshotFromUsage` coerces the stream's: third-party backends have been
+ *  observed omitting fields, and a missing or NaN counter must not reach the
+ *  wire as NaN (which `JSON.stringify` writes as `null`). */
+function normalizeModelUsage(modelUsage) {
+    const tally = {};
+    for (const [model, usage] of Object.entries(modelUsage ?? {})) {
+        tally[model] = {
+            inputTokens: finiteCount(usage?.inputTokens),
+            outputTokens: finiteCount(usage?.outputTokens),
+            cachedReadTokens: finiteCount(usage?.cacheReadInputTokens),
+            cachedWriteTokens: finiteCount(usage?.cacheCreationInputTokens),
+        };
+    }
+    return tally;
+}
+function finiteCount(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+/** `current - previous` per model, dropping models with nothing to report so a
+ *  turn only lists the models it actually ran on. A reading that fell BELOW the
+ *  previous one means the running total restarted under us (a mid-session
+ *  /clear, a resumed session starting fresh, a zeroed crash result): there is no
+ *  usable reference left to subtract, so the reading itself is the increment. */
+function modelUsageIncrement(current, previous) {
+    const increment = {};
+    for (const [model, usage] of Object.entries(current)) {
+        const base = previous[model];
+        const subtracted = base
+            ? {
+                inputTokens: usage.inputTokens - base.inputTokens,
+                outputTokens: usage.outputTokens - base.outputTokens,
+                cachedReadTokens: usage.cachedReadTokens - base.cachedReadTokens,
+                cachedWriteTokens: usage.cachedWriteTokens - base.cachedWriteTokens,
+            }
+            : usage;
+        const rewound = Object.values(subtracted).some((count) => count < 0);
+        const resolved = rewound ? usage : subtracted;
+        if (tallyTotal(resolved) > 0) {
+            increment[model] = resolved;
+        }
+    }
+    return increment;
+}
+/** Fold `increment` into `base` per model — the per-model counterpart of the
+ *  `+=` the turn's flat accumulator uses. */
+function addModelUsage(base, increment) {
+    const merged = { ...base };
+    for (const [model, usage] of Object.entries(increment)) {
+        const existing = merged[model];
+        merged[model] = existing
+            ? {
+                inputTokens: existing.inputTokens + usage.inputTokens,
+                outputTokens: existing.outputTokens + usage.outputTokens,
+                cachedReadTokens: existing.cachedReadTokens + usage.cachedReadTokens,
+                cachedWriteTokens: existing.cachedWriteTokens + usage.cachedWriteTokens,
+            }
+            : usage;
+    }
+    return merged;
+}
 /** Sum all four fields as a proxy for post-turn context occupancy: the current
  *  turn's output becomes next turn's input. Per the Anthropic API, input_tokens
  *  excludes cache tokens — cache_read and cache_creation are reported
@@ -5384,50 +5845,6 @@ function isValidBaseUrl(baseUrl) {
     }
     return parsed.protocol === "http:" || parsed.protocol === "https:";
 }
-/**
- * Build the list of permission modes the agent will advertise for the given
- * model. `auto` is gated by `ModelInfo.supportsAutoMode === true`, which is
- * the SDK's model-level availability signal. `undefined`/`false` both exclude
- * `auto`. `bypassPermissions` is still gated by `ALLOW_BYPASS`.
- */
-function buildAvailableModes(modelInfo) {
-    const modes = [];
-    // Only advertise "auto" when the SDK reports the model supports it.
-    if (modelInfo?.supportsAutoMode === true) {
-        modes.push({
-            id: "auto",
-            name: "Auto",
-            description: "Use a model classifier to approve/deny permission prompts",
-        });
-    }
-    modes.push({
-        // Claude Code 2.1.200 renamed this mode to "Manual" across its surfaces;
-        // the wire id stays "default" ("manual" is only an accepted input alias).
-        id: "default",
-        name: "Manual",
-        description: "Standard behavior, prompts for dangerous operations",
-    }, {
-        id: "acceptEdits",
-        name: "Accept Edits",
-        description: "Auto-accept file edit operations",
-    }, {
-        id: "plan",
-        name: "Plan Mode",
-        description: "Planning mode, no actual tool execution",
-    }, {
-        id: "dontAsk",
-        name: "Don't Ask",
-        description: "Don't prompt for permissions, deny if not pre-approved",
-    });
-    if (ALLOW_BYPASS) {
-        modes.push({
-            id: "bypassPermissions",
-            name: "Bypass Permissions",
-            description: "Bypass all permission checks",
-        });
-    }
-    return modes;
-}
 // Translate a UI effort value into the flag-layer payload. The SDK
 // shallow-merges `applyFlagSettings`, drops `undefined` during JSON transport,
 // and only clears a key when an explicit `null` is sent — see
@@ -5458,7 +5875,6 @@ export const BUILTIN_AGENT_NAMES = new Set([
 // reserved sentinel: a custom agent named exactly this would collide with it
 // (two options sharing the value, selection silently routing to `null`), so we
 // exclude that name from discovery.
-export const DEFAULT_AGENT_ID = "default";
 /** Discover user/plugin/project-configured main-thread agents, excluding the
  *  built-in subagents and the reserved "default" sentinel. Returns an empty
  *  list if discovery fails so a flaky control request never blocks session
@@ -5476,9 +5892,8 @@ export async function discoverCustomAgents(q) {
  *  Centralized so the option declarations in `buildConfigOptions` and the
  *  handlers in `setSessionConfigOption`/`applyConfigOptionValue` reference the
  *  same identifiers and can't drift apart. */
-export const MODE_CONFIG_ID = "mode";
+export { MODE_CONFIG_ID };
 export const MODEL_CONFIG_ID = "model";
-export const EFFORT_CONFIG_ID = "effort";
 export const AGENT_CONFIG_ID = "agent";
 export const FAST_MODE_CONFIG_ID = "fast";
 /** Select-fallback values used when the client has not opted into boolean
@@ -5577,19 +5992,7 @@ export function resolveFastModeEnabled(params) {
 }
 export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel, agents = [], currentAgent = DEFAULT_AGENT_ID, fastMode) {
     const options = [
-        {
-            id: MODE_CONFIG_ID,
-            name: "Mode",
-            description: "Session permission mode",
-            category: "mode",
-            type: "select",
-            currentValue: modes.currentModeId,
-            options: modes.availableModes.map((m) => ({
-                value: m.id,
-                name: m.name,
-                description: m.description,
-            })),
-        },
+        SessionModeManager.configOption(modes),
         {
             id: MODEL_CONFIG_ID,
             name: "Model",
@@ -6258,6 +6661,46 @@ function claudeCodeMetaFromToolUse(toolUse, cwd) {
         ...(skillPath ? { skillPath } : {}),
     };
 }
+/**
+ * Marks the Bash `tool_call_update` whose command detached into the background.
+ *
+ * A backgrounded Bash call returns as soon as the command is handed off, so the
+ * card reaches `completed` while the command itself runs on for minutes. ACP has
+ * no tool-call status for "still running elsewhere", so this marker is what lets
+ * a client render the card as backgrounded work instead of finished work. It
+ * rides the update the tool result already emits, so it costs no extra
+ * notification and cannot arrive out of order.
+ *
+ * The command's own lifecycle -- progress, completion, the stop control -- is
+ * published separately as an async task; this says only that the card has one.
+ * Hence the AIR namespace rather than `claudeCode`: to a client without the
+ * `asyncTasks` capability, which is never sent that lifecycle, the marker would
+ * promise a card state it has no way to ever resolve.
+ */
+function backgroundedBashToolCall(notification, task, asyncTasksSupported) {
+    const update = notification.update;
+    const toolCallId = task ? nonBlankTaskField(task.toolCallId ?? task.tool_use_id) : undefined;
+    if (!asyncTasksSupported ||
+        !toolCallId ||
+        update.sessionUpdate !== "tool_call_update" ||
+        update.toolCallId !== toolCallId) {
+        return notification;
+    }
+    return {
+        ...notification,
+        update: {
+            ...update,
+            _meta: withAirMeta(update._meta, AIR_ASYNC_TASKS_CAPABILITY, { backgrounded: true }),
+        },
+    };
+}
+/** The task fields arrive as `unknown` off the wire; only non-blank strings carry a link. */
+function nonBlankTaskField(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : undefined;
+}
 /** Roots a skill's directory may sit under, relative to the directory the scope resolves to. */
 const SKILL_CONTAINER_DIRS = [".claude/skills", ".agents/skills"];
 /**
@@ -6349,33 +6792,6 @@ function streamedInputRefinement(toolUse, input, supportsTerminalOutput, cwd) {
         ...(locations ? { locations } : {}),
     };
 }
-/** Validates the SDK user message's `tool_result_meta` sidecar (emitted on the
- *  wire by CLI ≥ 2.1.216 but absent from sdk.d.ts, hence unknown-typed) into a
- *  by-tool_use_id lookup. Each entry explains why an is_error tool_result
- *  carries harness prose instead of the tool's own output — "user-rejected",
- *  "permission-rule", "interrupted", "cancelled", … (open set: new kinds ship
- *  on the wire ahead of schema updates, so no enum check). Malformed entries
- *  are skipped rather than failing the message. */
-function parseToolResultMeta(raw) {
-    if (!Array.isArray(raw)) {
-        return undefined;
-    }
-    let byToolUseId;
-    for (const entry of raw) {
-        if (typeof entry !== "object" || entry === null) {
-            continue;
-        }
-        const { id, non_execution_kind, user_feedback } = entry;
-        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;
-}
 /**
  * Convert an SDKAssistantMessage (Claude) to a SessionNotification (ACP).
  * Only handles text, image, and thinking chunks for now.
@@ -6523,6 +6939,9 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                                         claudeCode: {
                                             toolResponse,
                                             toolName,
+                                            ...(options?.parentToolUseId
+                                                ? { parentToolUseId: options.parentToolUseId }
+                                                : {}),
                                         },
                                     },
                                     toolCallId: toolUseId,
@@ -6534,7 +6953,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                                     update,
                                 });
                             },
-                        });
+                        }, sessionId);
                     }
                     let rawInput;
                     try {
@@ -6576,6 +6995,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
             case "mcp_tool_result": {
                 const wasEmitted = options?.emittedToolCalls?.has(chunk.tool_use_id) === true;
                 options?.emittedToolCalls?.delete(chunk.tool_use_id);
+                completeHookCallback(chunk.tool_use_id);
                 // Why this is_error result carries harness prose instead of tool
                 // output (user-rejected / interrupted / …), when the SDK said so.
                 // Spread into the claudeCode meta of every update emitted below; the
@@ -6713,7 +7133,12 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                         toolCallId: chunk.tool_use_id,
                         sessionUpdate: "tool_call_update",
                         status: "is_error" in chunk && chunk.is_error ? "failed" : "completed",
-                        rawOutput: chunk.content,
+                        // terminal_output already carried the exact bytes in the preceding
+                        // update. Repeating them as rawOutput wastes bandwidth and lets a
+                        // client accidentally render the same output twice.
+                        ...(toolMeta?.terminal_output
+                            ? {}
+                            : { rawOutput: exitPlanModeRawOutput(toolUse.name, chunk.content) }),
                         ...toolUpdate,
                     };
                 }
@@ -6734,7 +7159,6 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
             case "compaction":
             case "compaction_delta":
             case "advisor_tool_result":
-            case "mid_conv_system":
             case "fallback":
                 break;
             default:
@@ -6922,6 +7346,7 @@ export function runAcp(logger) {
         .onRequest(methods.agent.session.prompt, (ctx) => runPromptWithCancellation(agent, ctx.params, ctx.signal))
         .onNotification(methods.agent.session.cancel, (ctx) => agent.cancel(ctx.params))
         .onRequest(STEER_METHOD, { parse: parseSteerRequest }, (ctx) => agent.steer(ctx.params))
+        .onRequest(ASYNC_TASK_STOP_METHOD, { parse: parseAsyncTaskStopRequest }, (ctx) => agent.stopAsyncTask(ctx.params))
         .onRequest(GOAL_CONTROL_METHOD, { parse: parseGoalRequest }, (ctx) => agent.goal(ctx.params))
         .connect(stream);
     agent = new ClaudeAcpAgent(new ClientConnection(connection.client), logger);