@agentclientprotocol/claude-agent-acp 0.85.2-preview.2 → 0.85.2-preview.21

package/dist/acp-agent.js

@@ -4,7 +4,7 @@ import { GOAL_ACTIONS, GOAL_CONTROL_METHOD, GOAL_EXTENSION_VERSION, goalUpdateFr
 import { sanitizeTitle, SessionTitles } from "./session-titles.js";
 import { AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY, asSdkSessionNotification, clientSupportsSubagents, } from "./acp-subagents.js";
 import { isNativeSubagentControlTool, isNativeSubagentControlUpdate, NativeSubagentRuntime, nativeSubagentState, resumedNativeSubagentId, sendMessageResumePrompt, } from "./native-subagents.js";
-import { AIR_ASYNC_TASKS_CAPABILITY, AIR_DIFF_PATCH_CAPABILITY, AIR_PLAN_FILE_CAPABILITY, AIR_GOAL_KEY, AIR_RECOMMENDED_CONFIG_VALUE_CAPABILITY, clientSupportsAirCapability, withAirMeta, } from "./air-extension.js";
+import { AIR_ASYNC_TASKS_CAPABILITY, AIR_DIFF_PATCH_CAPABILITY, AIR_PLAN_FILE_CAPABILITY, AIR_GOAL_KEY, AIR_KIND_KEY, AIR_RECOMMENDED_CONFIG_VALUE_CAPABILITY, AIR_SKILL_PATH_KEY, clientSupportsAirCapability, withAirMeta, } from "./air-extension.js";
 import { AsyncTaskRuntime, backgroundBashTaskFromToolResult, clientSupportsAsyncTasks, } from "./async-tasks.js";
 import { AUTH_STATUS_PROBE_TIMEOUT_MS, AUTH_STATUS_UPDATE_METHOD, authStatusCapability, fromAccountInfo, fromCliStatus, gatewayAuthStatus, mergeAuthStatus, notLoggedInAuthStatus, sameAuthStatus, } from "./auth-status.js";
 import { execFile } from "node:child_process";
@@ -16,12 +16,12 @@ 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 { subagentHistory } from "./subagent-history.js";
-import { readResumedModel, readResumedSession, } from "./resumed-session.js";
+import { readResumedSession, readResumedTail, } from "./resumed-session.js";
 import { SessionTiming } from "./session-timing.js";
-import { ALLOW_BYPASS, resolvePermissionMode } from "./permissions/modes.js";
+import { ALLOW_BYPASS } from "./permissions/modes.js";
 import { normalizeDurablePermissionChangeSet } from "./permissions/normalization.js";
 import { buildClaudePermissionOptions } from "./permissions/options.js";
-import { buildClaudePermissionPresentation } from "./permissions/presentation.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";
@@ -36,11 +36,15 @@ import { ChangedMetaFilter } from "./tool-calls/changed-meta-filter.js";
 import { ToolCallFieldTracker } from "./tool-calls/field-tracker.js";
 import { ClientCapabilities as ToolCallClientCapabilities } from "./tool-calls/client-capabilities.js";
 import { AcpToolCallRenderer } from "./tool-calls/renderer.js";
-import { nodeToWebReadable, nodeToWebWritable, Pushable, unreachable } from "./utils.js";
+import { resolveSkillPath } from "./tool-calls/reporters/interaction.js";
+import { nodeToWebReadable, nodeToWebWritable, Pushable, raceTimeoutAndAbort, unreachable, } from "./utils.js";
 import { acceptedPlanToolResult, ExitPlanCoordinator, isExitPlanInterruptionResult, observeExitPlanToolResults, } from "./exit-plan.js";
+import { DEFAULT_AGENT_ID } from "./session-config-ids.js";
 import { parseToolResultMeta } from "./tool-result-meta.js";
 import { formatUsageResponse, isUsageCommandText, parseUsageResponse } from "./usage-markdown.js";
-import { MODE_CONFIG_ID, SessionModeManager } from "./session-mode.js";
+export { DEFAULT_AGENT_ID } from "./session-config-ids.js";
+import { MCP_AVAILABLE_COMMAND, parseMcpCommand, runMcpCommand } from "./mcp-command.js";
+import { MODE_CONFIG_ID, resolveInitialPermissionMode, SessionModeManager, } from "./session-mode.js";
 import { applyAvailableModelsAllowlist, buildModelConfigOption, getAvailableModels, MODEL_CONFIG_ID, resolveModelPreference, } from "./session-model.js";
 import { buildEffortConfigOption, EFFORT_CONFIG_ID, effortFlagSettings, mergeEffortSettings, settingsEffortForModel, } from "./session-effort.js";
 export { EFFORT_CONFIG_ID, settingsEffortForModel } from "./session-effort.js";
@@ -77,6 +81,10 @@ const DEFAULT_CONTEXT_WINDOW = 200000;
  *  pre-empt a slow-but-healthy interrupt. */
 const DEFAULT_FORCE_CANCEL_GRACE_MS = 30_000;
 const STRUCTURED_USAGE_TIMEOUT_MS = 5_000;
+/** How long a session teardown waits for the turns that it cancels to end.
+ *  The teardown wakes the consumer itself, so they end within a few ticks
+ *  unless the consumer is wedged. */
+const TEARDOWN_TURN_END_TIMEOUT_MS = 5_000;
 /** The number of settled subagents whose parent tool call a session keeps for
  *  a later resume (see `resumableSubagents`). */
 const MAX_RESUMABLE_SUBAGENTS = 256;
@@ -105,32 +113,18 @@ function settleLiveBackgroundTask(session, taskId) {
 async function structuredUsageMarkdown(query, signal, logger) {
     if (signal.aborted)
         return null;
-    let timeout;
-    let onAbort;
     try {
-        const response = await Promise.race([
-            // Keeping the deliberately unstable method name visible makes an SDK
-            // upgrade fail at compile time if Anthropic removes or renames it.
-            query.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET(),
-            new Promise((resolve) => {
-                timeout = setTimeout(() => resolve(null), STRUCTURED_USAGE_TIMEOUT_MS);
-                timeout.unref?.();
-            }),
-            new Promise((resolve) => {
-                onAbort = () => resolve(null);
-                if (signal.aborted)
-                    onAbort();
-                else
-                    signal.addEventListener("abort", onAbort, { once: true });
-            }),
-        ]);
-        if (response === null) {
-            if (!signal.aborted) {
+        const outcome = await raceTimeoutAndAbort(
+        // Keeping the deliberately unstable method name visible makes an SDK
+        // upgrade fail at compile time if Anthropic removes or renames it.
+        query.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET(), STRUCTURED_USAGE_TIMEOUT_MS, signal);
+        if (outcome.type !== "done") {
+            if (outcome.type === "timeout") {
                 logger.error("Structured /usage timed out; preserving Claude Code output");
             }
             return null;
         }
-        const usage = parseUsageResponse(response);
+        const usage = parseUsageResponse(outcome.value);
         if (!usage) {
             logger.error("Structured /usage returned an incompatible response; preserving Claude Code output");
             return null;
@@ -141,12 +135,6 @@ async function structuredUsageMarkdown(query, signal, logger) {
         logger.error(`Structured /usage failed; preserving Claude Code output: ${error}`);
         return null;
     }
-    finally {
-        if (timeout)
-            clearTimeout(timeout);
-        if (onAbort)
-            signal.removeEventListener("abort", onAbort);
-    }
 }
 /** Claude Code keeps the OAuth callback listener open in the background after
  *  `mcpAuthenticate` returns the authorization URL. The SDK does not expose
@@ -680,6 +668,7 @@ const REPLAY_HIDDEN_COMMANDS = new Set([
     ...LOCAL_ONLY_COMMANDS,
     "/compact",
     "/model",
+    "/mcp",
     "/status",
     "/usage",
 ]);
@@ -1017,12 +1006,19 @@ const mcpAuthentications = new WeakMap();
  *  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)
+    if (mcpServers.length === 0)
+        return;
+    startMcpServerAuthentication(host, sessionId, new Set(mcpServers.map((server) => server.name)));
+}
+/** Start OAuth in the background for the servers in `requestedServers` that
+ *  Claude reports as needing authentication. Startup and `/mcp` use it. It
+ *  does nothing while another OAuth run of the session is in progress. */
+function startMcpServerAuthentication(host, sessionId, requestedServers) {
+    if (!host.clientCapabilities?.elicitation?.url)
         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) {
@@ -1161,7 +1157,14 @@ export class ClaudeAcpAgent {
      *  return "cancelled". See {@link DEFAULT_FORCE_CANCEL_GRACE_MS}. Mutable so
      *  tests can shrink it. */
     forceCancelGraceMs = DEFAULT_FORCE_CANCEL_GRACE_MS;
-    constructor(client, logger) {
+    /**
+     * The connection serves ACP v2 (`src/v2/`). The agent still speaks v1
+     * types, except for the tool call content that v2 needs and v1 cannot
+     * express: see {@link ToolCallClientCapabilities.v2}.
+     */
+    v2;
+    constructor(client, logger, options = {}) {
+        this.v2 = options.v2 ?? false;
         this.sessions = {};
         this.client = new ChangedMetaClient(client, () => this.toolCallCapabilities.air.client);
         this.logger = logger ?? console;
@@ -1218,7 +1221,9 @@ export class ClaudeAcpAgent {
     }
     async initialize(request) {
         this.clientCapabilities = request.clientCapabilities;
-        this.toolCallCapabilities = ToolCallClientCapabilities.from(request.clientCapabilities);
+        this.toolCallCapabilities = ToolCallClientCapabilities.from(request.clientCapabilities, {
+            v2: this.v2,
+        });
         // Learn the auth identity in the background: `initialize` never waits on
         // the CLI probe, and no snapshot rides in its response. When the probe
         // lands it calls `setAuthStatus`, which pushes `_auth/status_update` — the
@@ -1402,6 +1407,56 @@ export class ClaudeAcpAgent {
         }, 0);
         return response;
     }
+    /**
+     * Start the CLI of a loaded session, and replay the history while the CLI
+     * starts. The CLI start takes most of the load time, and the replay needs
+     * only the transcript and the {@link ReplayState}. An invalid `cwd` fails
+     * before the first update. A failed CLI start stops the replay.
+     */
+    async createSessionWhileReplaying(params, timing) {
+        await this.validateCwd(params.cwd);
+        const pending = {
+            state: {
+                cwd: params.cwd,
+                taskState: new Map(),
+                forwardSubagentText: this.forwardsSubagentText(params._meta),
+                messageIdToUuid: new Map(),
+                sessionFailureState: createSessionFailureState(),
+            },
+            stopped: false,
+        };
+        const transcript = readResumedSession(params.sessionId, this.logger);
+        const replay = transcript
+            .then(({ messages }) => this.replaySessionHistory(params.sessionId, messages, pending))
+            .then(() => ({ ok: true }), (error) => ({ ok: false, error }));
+        let response;
+        try {
+            response = await this.createSession({
+                cwd: params.cwd,
+                mcpServers: params.mcpServers ?? [],
+                additionalDirectories: params.additionalDirectories,
+                _meta: params._meta,
+            }, {
+                resume: params.sessionId,
+                resumedModelHint: transcript.then(({ model }) => model),
+                replayState: pending.state,
+            });
+        }
+        catch (error) {
+            pending.stopped = true;
+            await replay;
+            throw error;
+        }
+        timing.phase("session-ready");
+        const replayed = await replay;
+        if (!replayed.ok)
+            throw replayed.error;
+        return {
+            sessionId: response.sessionId,
+            modes: response.modes,
+            configOptions: response.configOptions,
+        };
+    }
     async unstable_forkSession(params) {
         if (this.providerUpdate)
             await this.providerUpdate;
@@ -1426,10 +1481,16 @@ export class ClaudeAcpAgent {
         const timing = new SessionTiming(this.logger, "load", params.sessionId);
         if (this.providerUpdate)
             await this.providerUpdate;
-        const resumedSession = await readResumedSession(params.sessionId, this.logger);
-        const result = await this.getOrCreateSession(params, resumedSession);
-        timing.phase("session-ready");
-        await this.replaySessionHistory(params.sessionId, resumedSession.messages);
+        let result;
+        if (this.sessions[params.sessionId]) {
+            const resumedSession = await readResumedSession(params.sessionId, this.logger);
+            result = await this.getOrCreateSession(params, resumedSession);
+            timing.phase("session-ready");
+            await this.replaySessionHistory(params.sessionId, resumedSession.messages);
+        }
+        else {
+            result = await this.createSessionWhileReplaying(params, timing);
+        }
         timing.phase("replay");
         // Send available commands after replay so it doesn't interleave with history
         setTimeout(() => {
@@ -1812,6 +1873,47 @@ export class ClaudeAcpAgent {
             this.setAuthStatus(notLoggedInAuthStatus());
         }
     }
+    /** The structured replacement for a prompt that is exactly `/usage` or a
+     *  `/mcp` command. Claude Code runs the command, and the replacement takes
+     *  the place of its text. Claude Code refuses a `/mcp` reconnect, enable,
+     *  or disable in SDK mode. The `/mcp` producer runs them through the SDK
+     *  control API when the text arrives, so the action stays in the turn. */
+    localCommandMarkdown(params) {
+        const text = params.prompt.length === 1 && params.prompt[0]?.type === "text"
+            ? params.prompt[0].text
+            : undefined;
+        if (text === undefined)
+            return undefined;
+        if (isUsageCommandText(text)) {
+            return {
+                startsAtActivation: true,
+                produce: (query, signal) => structuredUsageMarkdown(query, signal, this.logger),
+            };
+        }
+        const command = parseMcpCommand(text);
+        if (!command)
+            return undefined;
+        let reconnected = [];
+        return {
+            startsAtActivation: false,
+            produce: async (query, signal, originalOutput) => {
+                const outcome = await runMcpCommand(query, command, originalOutput, signal, (message) => this.logger.error(message));
+                reconnected = outcome.reconnected;
+                return outcome.markdown;
+            },
+            // A reconnect starts OAuth for the ACP servers that it tried, as the
+            // session start does. A plain `/mcp` and a cancelled turn start none.
+            afterDelivery: () => {
+                const session = this.sessions[params.sessionId];
+                if (!session || session.cancelled)
+                    return;
+                const acpServers = new Set((session.creationParams?.mcpServers ?? []).map((server) => server.name));
+                const servers = new Set(reconnected.filter((server) => acpServers.has(server)));
+                if (servers.size > 0)
+                    startMcpServerAuthentication(this, params.sessionId, servers);
+            },
+        };
+    }
     /**
      * Serves an ACP v1 `session/prompt`, which answers when the turn ends. The
      * outcome of a turn is field for field a v1 prompt response.
@@ -1878,10 +1980,8 @@ export class ClaudeAcpAgent {
         const firstText = params.prompt[0]?.type === "text" ? params.prompt[0].text : "";
         const isLocalOnlyCommand = firstText.startsWith("/") && LOCAL_ONLY_COMMANDS.has(firstText.split(" ", 1)[0]);
         const fileChangeReport = session.fileChangeReporter?.request(params._meta);
-        const isUsageCommand = params.prompt.length === 1 &&
-            params.prompt[0]?.type === "text" &&
-            isUsageCommandText(params.prompt[0].text);
-        const usageMarkdownAbort = isUsageCommand ? new AbortController() : undefined;
+        const localCommand = this.localCommandMarkdown(params);
+        const localCommandAbort = localCommand ? new AbortController() : undefined;
         session.titles.onPrompt(params.prompt);
         // Each prompt is a Turn that the persistent consumer settles once the
         // turn's outcome is known. `startTurn()` owns no loop: it enqueues the
@@ -1892,8 +1992,8 @@ export class ClaudeAcpAgent {
             promptUuid,
             events,
             isLocalOnlyCommand,
-            ...(isUsageCommand ? { isUsageCommand: true } : {}),
-            ...(usageMarkdownAbort ? { usageMarkdownAbort } : {}),
+            ...(localCommand ? { localCommand } : {}),
+            ...(localCommandAbort ? { localCommandAbort } : {}),
             ...(fileChangeReport ? { fileChangeReport } : {}),
             settled: false,
             completion: new Promise((resolve) => {
@@ -1903,8 +2003,8 @@ export class ClaudeAcpAgent {
                 events.ended(outcome);
                 completeTurn();
             },
-            reject: (error) => {
-                events.failed(error);
+            reject: (error, title) => {
+                events.failed(error, title);
                 completeTurn();
             },
         };
@@ -2015,7 +2115,10 @@ export class ClaudeAcpAgent {
         try {
             // `resume` names the Claude session, which shares the ACP session id, so
             // the new query continues the same conversation under the same id.
-            await this.createSession(creationParams, { resume: sessionId });
+            await this.createSession(creationParams, {
+                resume: sessionId,
+                permissionMode: session.modes.currentModeId,
+            });
         }
         catch (error) {
             if (error instanceof RequestError && error.code === RequestError.resourceNotFound().code) {
@@ -2025,7 +2128,10 @@ export class ClaudeAcpAgent {
                 // better answer than a session the client can never use again.
                 this.logger.log(`session ${sessionId} was never persisted; starting a fresh query under the same id`);
                 try {
-                    await this.createSession(creationParams, { reuseSessionId: sessionId });
+                    await this.createSession(creationParams, {
+                        reuseSessionId: sessionId,
+                        permissionMode: session.modes.currentModeId,
+                    });
                     return;
                 }
                 catch (fallbackError) {
@@ -2487,11 +2593,11 @@ export class ClaudeAcpAgent {
             };
         };
         const internalErrorForClient = (data, rawDetail) => RequestError.internalError(data, supportsAirSessionFailures(this.clientCapabilities) ? undefined : rawDetail);
-        const ensureUsageMarkdown = (turn) => {
-            if (!turn.isUsageCommand || !turn.usageMarkdownAbort)
+        const ensureLocalCommandMarkdown = (turn, originalOutput = "") => {
+            if (!turn.localCommand || !turn.localCommandAbort)
                 return undefined;
-            turn.usageMarkdown ??= structuredUsageMarkdown(session.query, turn.usageMarkdownAbort.signal, this.logger);
-            return turn.usageMarkdown;
+            turn.localCommandMarkdown ??= turn.localCommand.produce(session.query, turn.localCommandAbort.signal, originalOutput);
+            return turn.localCommandMarkdown;
         };
         const resetTurnScratch = () => {
             lastAssistantTotalUsage = null;
@@ -2534,7 +2640,8 @@ export class ClaudeAcpAgent {
             session.activeTurn = turn;
             session.cancelled = false;
             compaction.resume();
-            ensureUsageMarkdown(turn);
+            if (turn.localCommand?.startsAtActivation)
+                ensureLocalCommandMarkdown(turn);
             session.pendingOrphanResults = 0;
             session.orphanCommands?.clear();
             // Two-phase sweep of registry entries the level signal ended (see
@@ -2562,18 +2669,23 @@ export class ClaudeAcpAgent {
                 }
             }
             resetTurnScratch();
-            // Activation is when Claude Code takes the prompt in: its echo, or for an
-            // echo-less command, its result. That inserts it into the conversation.
-            // A turn can be settled by now: an echo hand-off awaits settling the
-            // previous turn, and a cancel in that window settles the queued one.
-            if (!turn.insertedReported && !turn.settled) {
-                turn.insertedReported = true;
-                turn.events.inserted(turn.promptUuid);
-            }
+            // Without a command_lifecycle "started" frame before it (see that
+            // handler), activation is the first sign that Claude Code took the
+            // prompt in: its echo, or for an echo-less command, its result.
+            reportInserted(turn);
             // A request can already be open: Claude Code asks for a queued prompt
             // before the consumer reaches its echo.
             this.syncAwaitingUser(session);
         };
+        /** Report that Claude Code took the turn's prompt in, once. A turn can be
+         *  settled by now: an echo hand-off awaits settling the previous turn, and
+         *  a cancel in that window settles the queued one. */
+        const reportInserted = (turn) => {
+            if (turn.insertedReported || turn.settled)
+                return;
+            turn.insertedReported = true;
+            turn.events.inserted(turn.promptUuid);
+        };
         /** Ensure there is an active turn before a user-turn result that carries no
          *  echo to activate it, by promoting the queue head. Most turns are
          *  activated by their replayed user message before their result, but some
@@ -2732,27 +2844,28 @@ export class ClaudeAcpAgent {
          *  the autonomous stretch-close guard. */
         const firstUnsettledQueuedTurn = () => (session.turnQueue ?? []).find((t) => !t.settled);
         /** Claim the structured replacement for the turn currently producing a
-         * local-command output. Undefined means this is not a structured usage
-         * turn (or its request failed), null means another SDK message shape
-         * already delivered it, and string is the one replacement to publish. */
-        const takeUsageMarkdown = async (originalOutput) => {
+         * local-command output. Undefined means this is not a structured
+         * local-command turn (or its request failed), null means another SDK
+         * message shape already delivered it, and string is the one replacement
+         * to publish. */
+        const takeLocalCommandMarkdown = async (originalOutput) => {
             const turn = session.activeTurn ?? firstUnsettledQueuedTurn();
             if (!turn)
                 return undefined;
-            const usageMarkdown = ensureUsageMarkdown(turn);
-            if (!usageMarkdown)
+            const pending = ensureLocalCommandMarkdown(turn, originalOutput);
+            if (!pending)
                 return undefined;
-            const markdown = await usageMarkdown;
+            const markdown = await pending;
             if (markdown === null)
                 return undefined;
-            if (turn.usageMarkdownDelivered) {
+            if (turn.localCommandDelivered) {
                 // Different SDK message shapes can mirror the same local-command
                 // output. Suppress an exact mirror, but let a later, distinct frame
                 // (for example an interruption diagnostic) follow the normal path.
-                return turn.usageOriginalOutput === originalOutput ? null : undefined;
+                return turn.localCommandOriginalOutput === originalOutput ? null : undefined;
             }
-            turn.usageMarkdownDelivered = true;
-            turn.usageOriginalOutput = originalOutput;
+            turn.localCommandDelivered = true;
+            turn.localCommandOriginalOutput = originalOutput;
             return markdown;
         };
         /** Registers a live background task (see `liveBackgroundTasks`). A
@@ -2905,7 +3018,9 @@ export class ClaudeAcpAgent {
             // Captured before the settled flip below (isHeldOpen tests !settled).
             const wasHeld = isHeldOpen(turn);
             turn.settled = true;
-            turn.usageMarkdownAbort?.abort();
+            turn.localCommandAbort?.abort();
+            if (turn.localCommandDelivered)
+                turn.localCommand?.afterDelivery?.();
             disarmForceCancel(session);
             session.turnQueue = (session.turnQueue ?? []).filter((t) => t !== turn);
             session.activeTurn = null;
@@ -2929,7 +3044,7 @@ export class ClaudeAcpAgent {
         };
         /** Reject the active turn (auth required, error result, …) without tearing
          *  down the consumer: the stream continues to idle and later turns proceed. */
-        const failActive = (error) => {
+        const failActive = (error, title) => {
             disarmForceCancel(session);
             const turn = session.activeTurn;
             if (!turn || turn.settled) {
@@ -2946,7 +3061,7 @@ export class ClaudeAcpAgent {
             // start the next stretch clean, or its stale delivery record would
             // suppress the next turn's issue-#453 result-text fallback.
             session.emittedAssistantText = false;
-            turn.reject(error);
+            turn.reject(error, title);
         };
         /** Complete a negotiated terminal failure on the prompt response itself,
          *  which is the canonical AIR carrier. Legacy clients keep the historical
@@ -2970,7 +3085,7 @@ export class ClaudeAcpAgent {
                 return;
             }
             if (!supportsAirSessionFailures(this.clientCapabilities)) {
-                failActive(error);
+                failActive(error, title);
                 return;
             }
             if (!session.activeTurn || session.activeTurn.settled) {
@@ -2980,7 +3095,7 @@ export class ClaudeAcpAgent {
             }
             const failure = await createSessionFailure(kind, { title });
             if (!failure) {
-                failActive(error);
+                failActive(error, title);
                 return;
             }
             sessionFailures.recordActive(failure);
@@ -3030,11 +3145,18 @@ export class ClaudeAcpAgent {
                     .then((result) => ({ kind: "message", result }));
                 const nextMessage = pendingNext;
                 // Fresh abort listener per iteration, removed when next() wins, so a
-                // long-lived session doesn't accumulate listeners on one signal.
+                // long-lived session doesn't accumulate listeners on one signal. An
+                // abort that fired while the consumer was busy elsewhere, such as
+                // sending an update, still wakes it: a listener added to an aborted
+                // signal never fires. The consumer re-arms after each abort it
+                // handles, so an aborted signal here is always an unhandled abort.
                 let onAbort;
                 const abortRace = new Promise((resolve) => {
                     onAbort = () => resolve("abort");
-                    cancelController.signal.addEventListener("abort", onAbort, { once: true });
+                    if (cancelController.signal.aborted)
+                        onAbort();
+                    else
+                        cancelController.signal.addEventListener("abort", onAbort, { once: true });
                 });
                 const raced = await Promise.race([nextMessage, abortRace]);
                 cancelController.signal.removeEventListener("abort", onAbort);
@@ -3084,7 +3206,7 @@ export class ClaudeAcpAgent {
                         }
                     }
                     await compaction.interrupt();
-                    await settleActive(turnOutcome(session, "cancelled"));
+                    await settleActive(cancelledOutcome(session, session.activeTurn));
                     // 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.
@@ -3140,7 +3262,7 @@ export class ClaudeAcpAgent {
                     const inFlight = session.activeTurn;
                     await finishLifecycle(session.cancelled ? "cancelled" : "failed", session.cancelled ? "stopped" : "failed", "at end of stream");
                     await settleActive(session.cancelled
-                        ? turnOutcome(session, "cancelled")
+                        ? cancelledOutcome(session, inFlight)
                         : (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" —
@@ -3175,10 +3297,10 @@ export class ClaudeAcpAgent {
                 // 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`
-                // for it wouldn't typecheck. It feeds only the orphan accounting (see
-                // Session.orphanCommands); turn settlement stays driven by
-                // echoes/results/idle. (Raw-mode emission above still forwards these
-                // frames.)
+                // for it wouldn't typecheck. It feeds the orphan accounting (see
+                // Session.orphanCommands) and reports a turn inserted at "started";
+                // turn activation and settlement stay driven by echoes/results/idle.
+                // (Raw-mode emission above still forwards these frames.)
                 if (message.type === "command_lifecycle") {
                     const frame = message;
                     switch (frame.state) {
@@ -3189,6 +3311,17 @@ export class ClaudeAcpAgent {
                             if (queued) {
                                 queued.commandStarted = true;
                                 compaction.resume();
+                                // Claude Code took the prompt in: it drained into a turn. A
+                                // fresh turn reports that before anything it produces, its echo
+                                // and first stream events included, so this is the earliest
+                                // insertion point. (A prompt folded into a running turn reports
+                                // it after its echo, which already activated it.) While another
+                                // turn is still active (held for background work, steered, or
+                                // cancelled and awaiting its trailing idle), insertion waits
+                                // for this turn's echo, whose hand-off ends that turn first.
+                                const active = session.activeTurn;
+                                if (!active || active.settled || active === queued)
+                                    reportInserted(queued);
                             }
                             // ...and promote an already-orphaned command: once dispatched,
                             // a bare `cancelled` no longer means "dropped without running".
@@ -3365,17 +3498,18 @@ export class ClaudeAcpAgent {
                                 if (compaction.consumeDuplicateErrorOutput(message.content)) {
                                     break;
                                 }
-                                const usageTurn = session.activeTurn ?? firstUnsettledQueuedTurn();
-                                const usageMarkdown = await takeUsageMarkdown(message.content);
-                                if (usageTurn?.isUsageCommand && session.cancelled)
+                                const commandTurn = session.activeTurn ?? firstUnsettledQueuedTurn();
+                                const commandMarkdown = await takeLocalCommandMarkdown(message.content);
+                                if (commandTurn?.localCommand && session.cancelled)
                                     break;
-                                if (usageMarkdown === null)
+                                if (commandMarkdown === null)
                                     break;
                                 await sendUpdate({
                                     sessionId: params.sessionId,
                                     update: {
                                         sessionUpdate: "agent_message_chunk",
-                                        content: { type: "text", text: usageMarkdown ?? message.content },
+                                        content: { type: "text", text: commandMarkdown ?? message.content },
+                                        messageId: messageIdForGrouping(message),
                                     },
                                 });
                                 break;
@@ -3432,7 +3566,13 @@ 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) {
-                                        await settleActive(turnOutcome(session, "cancelled"));
+                                        // A held turn's result passed long ago; this idle is the
+                                        // trailer of the followup cycle the cancel interrupted,
+                                        // whose result (an autonomous one) recorded it as owed.
+                                        if (isHeldOpen(session.activeTurn) && session.owedTrailingIdles > 0) {
+                                            session.owedTrailingIdles--;
+                                        }
+                                        await settleActive(cancelledOutcome(session, session.activeTurn));
                                         // 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
@@ -3534,11 +3674,12 @@ export class ClaudeAcpAgent {
                                 // list with this payload. Forward message.commands directly —
                                 // it's authoritative, and re-querying supportedCommands()
                                 // would just return the same list with an extra round-trip.
+                                session.skillPaths = new Map();
                                 await sendUpdate({
                                     sessionId: params.sessionId,
                                     update: {
                                         sessionUpdate: "available_commands_update",
-                                        availableCommands: getAvailableSlashCommands(message.commands, session.terminalSlashCommands),
+                                        availableCommands: getAvailableSlashCommands(message.commands, session.terminalSlashCommands, this.toolCallCapabilities.air.client ? session.cwd : undefined, session.skillPaths),
                                     },
                                 });
                                 break;
@@ -4310,6 +4451,7 @@ export class ClaudeAcpAgent {
                                         update: {
                                             sessionUpdate: "agent_message_chunk",
                                             content: { type: "text", text: lastRefusalExplanation },
+                                            messageId: messageIdForGrouping(message),
                                         },
                                     });
                                 }
@@ -4384,10 +4526,13 @@ export class ClaudeAcpAgent {
                                             (message.usage.output_tokens ?? 0) === 0 &&
                                             !session.activeTurn?.noticeTexts?.includes(normalizeNoticeText(message.result)));
                                     if (shouldForwardResult) {
-                                        const usageMarkdown = await takeUsageMarkdown(message.result);
-                                        if (usageMarkdown === null)
+                                        const commandTurn = session.activeTurn ?? firstUnsettledQueuedTurn();
+                                        const commandMarkdown = await takeLocalCommandMarkdown(message.result);
+                                        if (commandTurn?.localCommand && session.cancelled)
                                             break;
-                                        for (const notification of toAcpNotifications(usageMarkdown ?? message.result, "assistant", params.sessionId, session.toolUseCache, routedNotificationClient, this.logger)) {
+                                        if (commandMarkdown === null)
+                                            break;
+                                        for (const notification of toAcpNotifications(commandMarkdown ?? message.result, "assistant", params.sessionId, session.toolUseCache, routedNotificationClient, this.logger, { messageId: messageIdForGrouping(message) })) {
                                             await sendUpdate(notification);
                                         }
                                     }
@@ -4600,6 +4745,7 @@ export class ClaudeAcpAgent {
                         }
                         for (const notification of streamEventToAcpNotifications(message, params.sessionId, session.toolUseCache, this.client, this.logger, {
                             clientCapabilities: this.clientCapabilities,
+                            toolCallCapabilities: this.toolCallCapabilities,
                             cwd: session.cwd,
                             taskState: session.taskState,
                             emittedToolCalls: session.emittedToolCalls,
@@ -4669,7 +4815,7 @@ export class ClaudeAcpAgent {
                                             session.owedTrailingIdles++;
                                             // Before activateTurn resets the accumulator, so the
                                             // usage still belongs to the cancelled turn.
-                                            await settleActive(turnOutcome(session, "cancelled"));
+                                            await settleActive(cancelledOutcome(session, session.activeTurn));
                                         }
                                         else if (isHeldOpen(session.activeTurn)) {
                                             // A turn held open for its background subagents (see
@@ -4780,16 +4926,16 @@ export class ClaudeAcpAgent {
                         // Depending on the Claude Code build, a local command can arrive
                         // as the dedicated system message above or as a synthetic
                         // assistant message. Replace only the output owned by the exact
-                        // /usage turn; no content signatures or text parsing are involved.
+                        // /usage or /mcp turn; no content signatures or text parsing are involved.
                         if (message.type === "assistant" &&
                             message.parent_tool_use_id === null &&
                             message.message.model === "<synthetic>") {
-                            const usageMarkdown = await takeUsageMarkdown(assistantMessageText(message.message) ?? "");
+                            const commandMarkdown = await takeLocalCommandMarkdown(assistantMessageText(message.message) ?? "");
                             if (session.cancelled)
                                 break;
-                            if (usageMarkdown !== undefined) {
-                                if (usageMarkdown !== null) {
-                                    for (const notification of toAcpNotifications(usageMarkdown, "assistant", params.sessionId, session.toolUseCache, routedNotificationClient, this.logger, { messageId: messageIdForGrouping(message) })) {
+                            if (commandMarkdown !== undefined) {
+                                if (commandMarkdown !== null) {
+                                    for (const notification of toAcpNotifications(commandMarkdown, "assistant", params.sessionId, session.toolUseCache, routedNotificationClient, this.logger, { messageId: messageIdForGrouping(message) })) {
                                         await sendUpdate(notification);
                                     }
                                 }
@@ -4803,6 +4949,7 @@ export class ClaudeAcpAgent {
                             if (typeof stripped === "string") {
                                 for (const notification of toAcpNotifications(stripped, message.message.role, params.sessionId, session.toolUseCache, routedNotificationClient, this.logger, {
                                     clientCapabilities: this.clientCapabilities,
+                                    toolCallCapabilities: this.toolCallCapabilities,
                                     parentToolUseId: message.parent_tool_use_id,
                                     cwd: session.cwd,
                                     taskState: session.taskState,
@@ -4884,6 +5031,7 @@ export class ClaudeAcpAgent {
                         }
                         for (const notification of toAcpNotifications(content, message.message.role, params.sessionId, session.toolUseCache, routedNotificationClient, this.logger, {
                             clientCapabilities: this.clientCapabilities,
+                            toolCallCapabilities: this.toolCallCapabilities,
                             parentToolUseId: message.parent_tool_use_id,
                             cwd: session.cwd,
                             taskState: session.taskState,
@@ -5073,6 +5221,36 @@ export class ClaudeAcpAgent {
             session.pendingOrphanResults = (session.pendingOrphanResults ?? 0) + 1;
         }
     }
+    /** Ask Claude Code to drop user messages it still has queued, so that a
+     *  prompt a cancel settled is not run after all. Claude Code keeps queued
+     *  messages through an interrupt and runs them next (the receipt's
+     *  `still_queued`), unless they are cancelled first with
+     *  `cancel_async_message`: a no-op for a message it already dequeued, which
+     *  then still runs, as an orphan (see `orphanCommands`).
+     *
+     *  Not awaited: the SDK writes control requests in call order, so the drops
+     *  reach Claude Code before a request sent after them, and a wedged CLI must
+     *  not hold up the cancel. The orphan accounting needs no update here: a
+     *  dropped message gets a `cancelled` lifecycle frame and is missing from the
+     *  interrupt receipt's `still_queued`, which both already account for. The
+     *  SDK implements the request as `Query.cancelAsyncMessage` without typing
+     *  it, so it is looked up, and a CLI that lacks it rejects the request. */
+    dropQueuedMessages(sessionId, query, uuids) {
+        const cancelAsyncMessage = query
+            .cancelAsyncMessage;
+        if (typeof cancelAsyncMessage !== "function")
+            return;
+        const logFailure = (uuid, error) => this.logger.error(`Session ${sessionId}: could not drop the queued message ${uuid} from Claude Code:`, error);
+        for (const uuid of uuids) {
+            // Called synchronously: deferring it would let the interrupt go first.
+            try {
+                Promise.resolve(cancelAsyncMessage.call(query, uuid)).catch((error) => logFailure(uuid, error));
+            }
+            catch (error) {
+                logFailure(uuid, error);
+            }
+        }
+    }
     async cancel(params) {
         await this.cancelTurns(params, { awaitInterrupt: true });
     }
@@ -5089,7 +5267,7 @@ export class ClaudeAcpAgent {
         }
         session.cancelled = true;
         for (const turn of session.turnQueue ?? [])
-            turn.usageMarkdownAbort?.abort();
+            turn.localCommandAbort?.abort();
         session.pendingExitPlanModeInterruption = undefined;
         session.pendingExitPlanContextReset = undefined;
         // The stream already ended (see closeQueryStream): every in-flight turn was
@@ -5118,12 +5296,16 @@ export class ClaudeAcpAgent {
             session.toolCallFields?.clear();
             clearHookCallbacks(params.sessionId);
         }
+        // The user messages this cancel abandons while Claude Code may still have
+        // them queued: they are dropped from its queue before the interrupt.
+        const abandoned = [];
         // 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.
         if (isSteering(session.activeTurn)) {
             for (const uuid of session.activeTurn.steeredEchoes) {
                 this.trackOrphanCommand(session, uuid, "pending");
+                abandoned.push(uuid);
             }
         }
         // Capture the orphan-accounting lane before anything can await: the
@@ -5147,11 +5329,13 @@ export class ClaudeAcpAgent {
                     // accumulator (the active turn's tally) is not its spend.
                     turn.resolve({ stopReason: "cancelled" });
                     orphanedTurns.push(turn);
+                    abandoned.push(turn.promptUuid);
                 }
             }
-            // Each removed queued turn's user message was already pushed to the SDK,
-            // which processes input FIFO and will still emit a result for it with no
-            // user echo to match (0.3.246+ CLIs do stamp results with the
+            // Each removed queued turn's user message was already pushed to the SDK.
+            // It is dropped from Claude Code's queue below (see dropQueuedMessages),
+            // but one Claude Code already dequeued still runs, FIFO, and emits a
+            // result with no user echo to match (0.3.246+ CLIs do stamp results with the
             // triggering send's user_message_uuid, which ensureActiveTurn uses as
             // an exact join when present). Track those so the consumer skips them
             // (see ensureActiveTurn) rather than misattributing them to the head.
@@ -5214,15 +5398,23 @@ export class ClaudeAcpAgent {
         }
         // A deferred active turn (see Turn.deferredSettle) already has its result
         // and is only held open for subagents. A settling turn likewise has its
-        // result but is awaiting the bounded checkpoint preview. Settle either one
-        // "cancelled" NOW: the consumer cannot process the interrupt's trailing
-        // idle while blocked in that preview, and a held turn may already be idle.
-        // The captured outcome preserves usage and metadata (issue #844), while
-        // reporter state makes a late checkpoint response harmless.
+        // result but is awaiting the bounded checkpoint preview. Settle it
+        // "cancelled" NOW where the consumer cannot: it cannot process the
+        // interrupt's trailing idle while blocked in that preview, and a held turn
+        // whose session sits idle gets no trailing idle (the interrupt emits
+        // nothing; with no state events consumed yet, the same is assumed).
+        // A held turn whose followup cycle is live (running, or blocked on a
+        // permission request) is left to that idle, like any live turn: the
+        // interrupt still flushes the cycle's output, which must reach the client
+        // before the turn ends cancelled. The captured outcome preserves usage and
+        // metadata (issue #844), while reporter state makes a late checkpoint
+        // response harmless.
         {
             const active = session.activeTurn;
-            const pendingOutcome = active?.deferredSettle ?? active?.settlingOutcome;
-            if (active && pendingOutcome && (isHeldOpen(active) || active.settling)) {
+            const followupLive = session.lastSessionState === "running" || session.lastSessionState === "requires_action";
+            if (active &&
+                (active.settling || (isHeldOpen(active) && !followupLive)) &&
+                (active.deferredSettle ?? active.settlingOutcome)) {
                 session.fileChangeReporter?.finish(active.fileChangeReport, "cancelled");
                 active.settled = true;
                 // Mirror settleActive's invariants (it is consumer-scoped and
@@ -5236,17 +5428,16 @@ export class ClaudeAcpAgent {
                 // text since the last boundary was its followups', and left latched
                 // it would suppress a following replayed turn's issue-#453 fallback.
                 session.emittedAssistantText = false;
-                // When the interrupt below pre-empts a live cycle — running, or
-                // blocked on a permission request (requires_action, the #866 shape
-                // users cancel out of) — it produces a trailer idle with no counted
-                // result; with the hold's own trailer typically already absorbed,
-                // that idle would be un-owed and could lag past the next prompt's
-                // echo — read as the fresh turn ending without a result (issue #825
-                // false-fail). Pre-count it unless the session sits idle: there the
-                // interrupt emits nothing, and a debt that never drains would mask
-                // one future #825 detection. (lastSessionState is last-CONSUMED, so
-                // both stale reads exist and both are accepted one-cycle windows: a
-                // running transition still in the backlog reads as stale idle and
+                // When the interrupt below pre-empts a live cycle (a settling turn's,
+                // or one no state event reported), it produces a trailer idle with no
+                // counted result; that idle would be un-owed and could lag past the
+                // next prompt's echo — read as the fresh turn ending without a result
+                // (issue #825 false-fail).
+                // Pre-count it unless the session sits idle: there the interrupt
+                // emits nothing, and a debt that never drains would mask one future
+                // #825 detection. (lastSessionState is last-CONSUMED, so both stale
+                // reads exist and both are accepted one-cycle windows: a running
+                // transition still in the backlog reads as stale idle and
                 // under-counts — that false-fail additionally needs the trailer to
                 // lag past the next echo — while a cycle already completed into the
                 // backlog reads as stale non-idle and over-counts, masking one
@@ -5256,14 +5447,7 @@ export class ClaudeAcpAgent {
                 if (session.lastSessionState !== "idle") {
                     session.owedTrailingIdles++;
                 }
-                // 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: pendingOutcome.usage,
-                    ...(pendingOutcome._meta ? { _meta: pendingOutcome._meta } : {}),
-                });
+                active.resolve(cancelledOutcome(session, active));
             }
         }
         // A steered active turn (see Turn.steeredEchoes) settles "cancelled" in the
@@ -5296,6 +5480,9 @@ export class ClaudeAcpAgent {
                 cancelController.abort();
             }, this.forceCancelGraceMs);
         }
+        // Before the interrupt: once it stops the running turn, Claude Code starts
+        // the next queued message right away.
+        this.dropQueuedMessages(params.sessionId, session.query, abandoned);
         const interrupt = session.query.interrupt();
         if (!options.awaitInterrupt) {
             // The caller closes the query next, which rejects the pending reply.
@@ -5392,12 +5579,18 @@ export class ClaudeAcpAgent {
         session.query.close();
     }
     /** Cleanly tear down a session: cancel in-flight work, release stream
-     *  resources, and remove it from the session map. */
+     *  resources, and remove it from the session map. Returns once the turns it
+     *  cancels have ended, so their end (a v1 `session/prompt` response, a v2
+     *  `idle` state) goes out before the caller answers: ACP v2's
+     *  `session/close` cancels "as if `session/cancel` had been called", then
+     *  frees the session. A wedged consumer holds it at most
+     *  {@link TEARDOWN_TURN_END_TIMEOUT_MS}. */
     async teardownSession(sessionId) {
         const session = this.sessions[sessionId];
         if (!session) {
             return;
         }
+        const turnsEnded = Promise.all((session.turnQueue ?? []).flatMap((turn) => (turn.completion ? [turn.completion] : [])));
         try {
             await this.cancelTurns({ sessionId }, { awaitInterrupt: false });
         }
@@ -5425,6 +5618,10 @@ export class ClaudeAcpAgent {
         session.nativeSubagentRuntime?.clear();
         session.asyncTaskRuntime?.clear();
         delete this.sessions[sessionId];
+        const ended = await raceTimeoutAndAbort(turnsEnded, TEARDOWN_TURN_END_TIMEOUT_MS, new AbortController().signal);
+        if (ended.type === "timeout") {
+            this.logger.error(`Session ${sessionId}: its cancelled turns did not end within ${TEARDOWN_TURN_END_TIMEOUT_MS}ms of the teardown`);
+        }
     }
     /** Tear down all active sessions. Called when the ACP connection closes. */
     async dispose() {
@@ -5531,13 +5728,15 @@ export class ClaudeAcpAgent {
         await this.applyConfigOptionValue(params.sessionId, session, params.configId, effectiveValue);
         return { configOptions: session.configOptions };
     }
-    async replaySessionHistory(sessionId, resumedMessages) {
+    async replaySessionHistory(sessionId, resumedMessages, pending) {
         const replayStartedAt = performance.now();
         const toolUseCache = {};
         const messages = resumedMessages ?? (await getSessionMessages(sessionId));
         const historyLoadedAt = performance.now();
         this.logger.log(`[session/replay] sessionId=${sessionId} phase=read durationMs=${Math.round(historyLoadedAt - replayStartedAt)} messages=${messages.length}`);
-        const session = this.sessions[sessionId];
+        // A pending replay has no session record yet. It uses the state that the record takes later.
+        const replayState = () => pending?.state ?? this.sessions[sessionId];
+        const session = replayState();
         // A replay rebuilds the client view, so its plan goes out again.
         if (session?.taskState)
             forgetPublishedTaskPlan(session.taskState);
@@ -5549,7 +5748,12 @@ export class ClaudeAcpAgent {
                 sessionId,
                 state: session.sessionFailureState,
                 capabilities: this.clientCapabilities,
-                isCurrent: () => this.sessions[sessionId] === session,
+                isCurrent: () => {
+                    const live = this.sessions[sessionId];
+                    if (!live)
+                        return pending !== undefined && !pending.stopped;
+                    return live.sessionFailureState === session.sessionFailureState;
+                },
                 sendUpdate: (notification) => this.client.sessionUpdate(notification),
                 logger: this.logger,
             })
@@ -5704,7 +5908,7 @@ export class ClaudeAcpAgent {
             await replayAsyncTasks.taskNotification(notification);
         };
         const replayMessage = async (message) => {
-            if (isReplayHiddenMetaMessage(message)) {
+            if (pending?.stopped || isReplayHiddenMetaMessage(message)) {
                 return;
             }
             if (message.type === "user" &&
@@ -5718,7 +5922,7 @@ export class ClaudeAcpAgent {
             // a client-supplied id without an extra getSessionMessages read. Not read
             // yet (see Session.messageIdToUuid).
             const replayMessageId = messageIdForGrouping(message);
-            const replaySession = this.sessions[sessionId];
+            const replaySession = replayState();
             if (replaySession && replayMessageId && message.uuid) {
                 replaySession.messageIdToUuid.set(replayMessageId, message.uuid);
             }
@@ -5812,8 +6016,9 @@ export class ClaudeAcpAgent {
                 registerHooks: false,
                 replay: true,
                 clientCapabilities: this.clientCapabilities,
-                cwd: this.sessions[sessionId]?.cwd,
-                taskState: this.sessions[sessionId]?.taskState,
+                toolCallCapabilities: this.toolCallCapabilities,
+                cwd: replayState()?.cwd,
+                taskState: replayState()?.taskState,
                 messageId: replayMessageId,
                 parentToolUseId,
             })) {
@@ -5858,7 +6063,7 @@ export class ClaudeAcpAgent {
         };
         for (const message of messages)
             await replayMessage(message);
-        if (nativeReplayEnabled) {
+        if (nativeReplayEnabled && !pending?.stopped) {
             // 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
@@ -5951,8 +6156,10 @@ export class ClaudeAcpAgent {
         // 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.
+        // The request goes to a subagent's child session for a tool call of that
+        // subagent, but it blocks the turn of the owner session.
         try {
-            return await this.withPendingUserInput(params.sessionId, () => raceWithAbort(this.client.requestPermission(params, signal), signal));
+            return await this.withPendingUserInput(ownerSessionId, () => raceWithAbort(this.client.requestPermission(params, signal), signal));
         }
         catch (error) {
             if (signal.aborted) {
@@ -6062,7 +6269,7 @@ export class ClaudeAcpAgent {
                 // 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, signal, permissionSessionId);
-                return this.handleAskUserQuestion(permissionSessionId, toolInput, toolUseID, signal);
+                return this.handleAskUserQuestion(sessionId, permissionSessionId, toolInput, toolUseID, signal);
             }
             // Do not auto-allow here based on the session's advertised mode. Claude
             // Code applies bypassPermissions before invoking canUseTool; a request
@@ -6078,8 +6285,8 @@ export class ClaudeAcpAgent {
             const noPersistentRule = matchedAskRule !== undefined || suppressAlwaysAllowRule === true;
             const durableChangeSet = normalizeDurablePermissionChangeSet(suggestions, noPersistentRule);
             const capabilities = this.toolCallCapabilities;
-            const previewContent = capabilities.diffPatch
-                ? await previewPatchContent(toolName, toolInput, session.cwd)
+            const previewContent = capabilities.diffPatch || capabilities.v2
+                ? await previewPatchContent(toolName, toolInput, session.cwd, capabilities.v2 ? "v2" : "air")
                 : undefined;
             const presentation = buildClaudePermissionPresentation({
                 toolName,
@@ -6216,13 +6423,15 @@ export class ClaudeAcpAgent {
      * Present the built-in AskUserQuestion tool's questions as an ACP form
      * elicitation and return the answers as the tool's `updatedInput`. Called from
      * `canUseTool` since that is where the SDK routes the tool's permission check.
+     * The elicitation goes to `requestSessionId`, a subagent's child session for
+     * a question it asks, and blocks the turn of `sessionId`.
      */
-    async handleAskUserQuestion(sessionId, toolInput, toolUseID, signal) {
+    async handleAskUserQuestion(sessionId, requestSessionId, toolInput, toolUseID, signal) {
         const questions = extractAskUserQuestions(toolInput);
         if (!questions) {
             return { behavior: "deny", message: "AskUserQuestion called with no valid questions." };
         }
-        const createRequest = askUserQuestionsToCreateRequest(questions, sessionId, toolUseID, this.toolCallCapabilities.air.client);
+        const createRequest = askUserQuestionsToCreateRequest(questions, requestSessionId, toolUseID, this.toolCallCapabilities.air.client);
         let response;
         try {
             response = await this.withPendingUserInput(sessionId, () => this.client.createElicitation(createRequest, signal));
@@ -6292,7 +6501,7 @@ export class ClaudeAcpAgent {
             sessionId,
             update: {
                 sessionUpdate: "available_commands_update",
-                availableCommands: getAvailableSlashCommands(commands, session.terminalSlashCommands),
+                availableCommands: getAvailableSlashCommands(commands, session.terminalSlashCommands, this.toolCallCapabilities.air.client ? session.cwd : undefined, (session.skillPaths ??= new Map())),
             },
         });
     }
@@ -6400,7 +6609,7 @@ export class ClaudeAcpAgent {
             const seedEffort = effortPinnedForNewModel
                 ? pinnedEffort
                 : settingsEffortForModel(mergeEffortSettings(session.settingsManager.getSettings(), session.effortSettingsOverride), newModelInfo, value);
-            session.configOptions = buildConfigOptions(session.modes, session.models, session.modelInfos, seedEffort, {
+            session.configOptions = buildConfigOptions(session.modes, session.models, session.modelInfos, seedEffort, session.agents, session.currentAgent, {
                 // The toggle follows the newly selected model: it disappears when the
                 // model lacks fast support and reappears (with the retained user
                 // intent) when a supporting model is selected again.
@@ -6479,6 +6688,18 @@ export class ClaudeAcpAgent {
             if (modelChanged)
                 this.refreshContextWindowInBackground(sessionId, session);
         }
+        else if (configId === AGENT_CONFIG_ID) {
+            // Live agent switch — no subprocess restart needed. Apply the SDK flag
+            // first so a rejected control request leaves both `currentAgent` and the
+            // config option untouched (no UI/SDK desync). Passing `null` clears the
+            // flag layer back to the standard Claude Code agent; the change takes
+            // effect on the next turn (SDK >= 0.3.161).
+            await session.query.applyFlagSettings({
+                agent: value === DEFAULT_AGENT_ID ? null : value,
+            });
+            session.currentAgent = value;
+            session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
+        }
         else if (configId === EFFORT_CONFIG_ID) {
             // Apply first so a rejected control request cannot leave the displayed
             // value ahead of the SDK flag layer.
@@ -6613,6 +6834,8 @@ export class ClaudeAcpAgent {
     }
     async getOrCreateSession(params, resumedSession) {
         const existingSession = this.sessions[params.sessionId];
+        // A recreated live session keeps its mode, not the mode of the transcript.
+        const livePermissionMode = existingSession?.modes.currentModeId;
         if (existingSession) {
             const fingerprint = computeSessionFingerprint(params);
             if (fingerprint === existingSession.sessionFingerprint) {
@@ -6628,9 +6851,6 @@ export class ClaudeAcpAgent {
             // up the new values.
             await this.teardownSession(params.sessionId);
         }
-        const resumedModelHint = resumedSession
-            ? resumedSession.model
-            : await readResumedModel(params.sessionId, this.logger);
         const response = await this.createSession({
             cwd: params.cwd,
             mcpServers: params.mcpServers ?? [],
@@ -6638,7 +6858,8 @@ export class ClaudeAcpAgent {
             _meta: params._meta,
         }, {
             resume: params.sessionId,
-            resumedModelHint,
+            permissionMode: livePermissionMode,
+            ...(resumedSession ? { resumedModelHint: resumedSession.model } : {}),
         });
         return {
             sessionId: response.sessionId,
@@ -6667,6 +6888,12 @@ export class ClaudeAcpAgent {
             throw RequestError.invalidParams({ cwd }, `\`cwd\` is not a directory: ${cwd}`);
         }
     }
+    /** Whether the session forwards the text and the thinking of a subagent. */
+    forwardsSubagentText(meta) {
+        return (clientSupportsSubagents(this.clientCapabilities) ||
+            supportsSubagentTranscript(this.clientCapabilities) ||
+            meta?.claudeCode?.options?.forwardSubagentText === true);
+    }
     async createSession(params, creationOpts = {}) {
         const createStartedAt = performance.now();
         // Validate `cwd` up front. The ACP spec requires an absolute path, and the
@@ -6704,10 +6931,15 @@ export class ClaudeAcpAgent {
         // sign-out respawn, provider rerouting), so fill the same fast local hint
         // here when the caller did not provide it. Never fall back to the slow
         // getContextUsage control request.
+        // The same tail read gives the permission mode of the resumed session.
         let resumedModelHint = creationOpts.resumedModelHint;
-        if (creationOpts.resume !== undefined &&
-            !Object.prototype.hasOwnProperty.call(creationOpts, "resumedModelHint")) {
-            resumedModelHint = await readResumedModel(creationOpts.resume, this.logger);
+        let resumedPermissionMode;
+        if (creationOpts.resume !== undefined) {
+            const withModel = !Object.prototype.hasOwnProperty.call(creationOpts, "resumedModelHint");
+            const tail = await readResumedTail(creationOpts.resume, this.logger, withModel);
+            if (withModel)
+                resumedModelHint = tail.model;
+            resumedPermissionMode = tail.permissionMode;
             timing.phase("resume-transcript");
         }
         const input = new Pushable();
@@ -6769,18 +7001,13 @@ export class ClaudeAcpAgent {
         const allowBypass = ALLOW_BYPASS &&
             settingsManager.getSettings().permissions?.disableBypassPermissionsMode !== "disable" &&
             sessionMeta?.claudeCode?.options?.allowDangerouslySkipPermissions !== false;
-        const initialPermissionMode = resolvePermissionMode(creationOpts.permissionMode ?? settingsManager.getSettings().permissions?.defaultMode, this.logger, allowBypass);
-        const userProvidedOptions = sessionMeta?.claudeCode?.options
-            ? { ...sessionMeta.claudeCode.options }
-            : undefined;
-        // Main-thread agent selection is intentionally not part of this adapter's
-        // ACP contract. Ignore the provider-specific option instead of forwarding
-        // hidden state that the Client cannot inspect or change.
-        if (userProvidedOptions)
-            delete userProvidedOptions.agent;
-        const forwardSubagentText = clientSupportsSubagents(this.clientCapabilities) ||
-            supportsSubagentTranscript(this.clientCapabilities) ||
-            userProvidedOptions?.forwardSubagentText === true;
+        const initialPermissionMode = resolveInitialPermissionMode({
+            explicit: creationOpts.permissionMode,
+            resumed: resumedPermissionMode,
+            defaultMode: settingsManager.getSettings().permissions?.defaultMode,
+        }, this.logger, allowBypass);
+        const userProvidedOptions = sessionMeta?.claudeCode?.options;
+        const forwardSubagentText = this.forwardsSubagentText(params._meta);
         // Configure thinking behavior from environment variable
         const thinking = resolveThinkingConfig(process.env.MAX_THINKING_TOKENS, this.logger);
         // Parse model configuration from environment (e.g. Bedrock model overrides)
@@ -6806,7 +7033,7 @@ export class ClaudeAcpAgent {
         // Per-session task state. Created here (rather than in the session record
         // below) so the TaskCreated/TaskCompleted hook callbacks can close over
         // the same Map that the streaming message handler will read from.
-        const taskState = new Map();
+        const taskState = creationOpts.replayState?.taskState ?? new Map();
         // Resolve every workspace root once. The native checkpoint report uses
         // this same set for lexical path validation, and the SDK receives it below.
         const acpAdditionalDirectories = params.additionalDirectories ?? sessionMeta?.additionalRoots ?? [];
@@ -7099,7 +7326,7 @@ export class ClaudeAcpAgent {
             const allowedModels = Array.isArray(settingsAvailableModels)
                 ? applyAvailableModelsAllowlist(initializationResult.models, settingsAvailableModels, settingsModelOverrides, settingsManager.getManagedDeniedModels())
                 : initializationResult.models;
-            const models = await getAvailableModels(q, allowedModels, initializationResult.models, settingsManager, this.logger, creationOpts.resume !== undefined, sessionId, resumedModelHint);
+            const models = await getAvailableModels(q, allowedModels, initializationResult.models, settingsManager, this.logger, creationOpts.resume !== undefined, sessionId, await resumedModelHint);
             timing.phase("models");
             // Resolve the current model's capabilities separately from the stable
             // permission-mode catalog advertised to ACP clients.
@@ -7144,6 +7371,17 @@ export class ClaudeAcpAgent {
                 allowBypass,
             });
             timing.phase("modes");
+            const agents = await discoverCustomAgents(q);
+            timing.phase("agents");
+            // 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
+            // otherwise-unknown name would leave the config option's `currentValue`
+            // pointing at an entry not in its own `options` list, which clients render
+            // as a blank/invalid selection.
+            const requestedAgent = userProvidedOptions?.agent;
+            const currentAgent = requestedAgent && agents.some((a) => a.name === requestedAgent)
+                ? requestedAgent
+                : DEFAULT_AGENT_ID;
             // Seed Fast mode from the SDK's reported state so the UI reflects reality
             // (the CLI may start a session with fast mode already on, or force it off
             // when `fastModePerSessionOptIn` is set). The toggle is only surfaced while
@@ -7169,7 +7407,7 @@ export class ClaudeAcpAgent {
             // Legacy clients still leave effort resolution entirely to the CLI.
             const useRecommendedValue = clientSupportsRecommendedConfigValue(this.clientCapabilities);
             const effortSettings = mergeEffortSettings(settingsManager.getSettings(), configuredSettingsObject);
-            const configOptions = buildConfigOptions(modes, models, modelInfos, userProvidedOptions?.effort ?? settingsEffortForModel(effortSettings, currentModelInfo), fastMode, {
+            const configOptions = buildConfigOptions(modes, models, modelInfos, userProvidedOptions?.effort ?? settingsEffortForModel(effortSettings, currentModelInfo), agents, currentAgent, fastMode, {
                 useRecommendedValue,
             });
             const initialEffort = configOptions.find((option) => option.id === EFFORT_CONFIG_ID);
@@ -7230,6 +7468,8 @@ export class ClaudeAcpAgent {
                         initialEffort?.currentValue === userProvidedOptions.effort
                         ? userProvidedOptions.effort
                         : undefined,
+                agents,
+                currentAgent,
                 fastModeEnabled,
                 fastModeDisabledReason,
                 abortController,
@@ -7248,8 +7488,8 @@ export class ClaudeAcpAgent {
                 nativeSubagentParentByToolUseId: new Map(),
                 emittedAssistantText: false,
                 owedTrailingIdles: 0,
-                messageIdToUuid: new Map(),
-                sessionFailureState: createSessionFailureState(),
+                messageIdToUuid: creationOpts.replayState?.messageIdToUuid ?? new Map(),
+                sessionFailureState: creationOpts.replayState?.sessionFailureState ?? createSessionFailureState(),
                 claudeSubscriptionGuard,
                 accountKind: fromAccountInfo(initializationResult.account)?.kind,
                 fileChangeReporter,
@@ -7290,7 +7530,10 @@ export class ClaudeAcpAgent {
                 this.closeQueryStream(session);
                 delete this.sessions[sessionId];
                 try {
-                    await this.createSession(session.creationParams, { resume: sessionId });
+                    await this.createSession(session.creationParams, {
+                        resume: sessionId,
+                        permissionMode: session.modes.currentModeId,
+                    });
                 }
                 catch (error) {
                     // One session that cannot come back must not abort the switch. The
@@ -7384,6 +7627,20 @@ function turnOutcome(session, stopReason, extraMeta) {
         _meta: { ...turnQuotaMeta(session), ...extraMeta },
     };
 }
+/** The outcome of `turn` when a cancel ends it. A turn that already has its
+ *  result, because it is held open for its background subagents (see
+ *  Turn.deferredSettle) or is settling (see Turn.settlingOutcome), keeps the
+ *  usage and metadata that result recorded (issue #844). */
+function cancelledOutcome(session, turn) {
+    const recorded = turn?.deferredSettle ?? turn?.settlingOutcome;
+    if (!recorded)
+        return turnOutcome(session, "cancelled");
+    return {
+        stopReason: "cancelled",
+        usage: recorded.usage,
+        ...(recorded._meta ? { _meta: recorded._meta } : {}),
+    };
+}
 /** `_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.
@@ -7645,11 +7902,43 @@ function isValidBaseUrl(baseUrl) {
     }
     return parsed.protocol === "http:" || parsed.protocol === "https:";
 }
+// `supportedAgents()` always returns Claude Code's built-in subagents — the
+// ones used for Task-tool delegation (Explore, Plan, etc.) — even when the user
+// has configured none of their own. Those aren't meaningful *main-thread*
+// personas, so we filter them out and only surface the Agent picker when the
+// user (or a plugin/project) has configured custom agents. Update this set if
+// the SDK's built-in roster changes.
+export const BUILTIN_AGENT_NAMES = new Set([
+    "claude",
+    "general-purpose",
+    "Explore",
+    "Plan",
+    "statusline-setup",
+]);
+// Value of the synthetic "Default" entry in the agent picker, which maps to the
+// standard Claude Code agent (`applyFlagSettings({ agent: null })`). It is a
+// 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.
+/** 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
+ *  creation. */
+export async function discoverCustomAgents(q) {
+    try {
+        const agents = await q.supportedAgents();
+        return agents.filter((a) => !BUILTIN_AGENT_NAMES.has(a.name) && a.name !== DEFAULT_AGENT_ID);
+    }
+    catch {
+        return [];
+    }
+}
 /** Stable ids for the session config options surfaced via `configOptions`.
  *  Centralized so the option declarations in `buildConfigOptions` and the
  *  handlers in `setSessionConfigOption`/`applyConfigOptionValue` reference the
  *  same identifiers and can't drift apart. */
 export { MODE_CONFIG_ID };
+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
  *  config options (see {@link createFastModeConfigOption}). */
@@ -7751,7 +8040,7 @@ export function resolveFastModeEnabled(params) {
     }
     throw new Error(`Invalid value for config option ${FAST_MODE_CONFIG_ID}: ${value}`);
 }
-export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel, fastMode, presentation) {
+export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel, agents = [], currentAgent = DEFAULT_AGENT_ID, fastMode, presentation) {
     const options = [
         SessionModeManager.configOption(modes),
         buildModelConfigOption(models, modelInfos, presentation?.useRecommendedValue === true),
@@ -7765,13 +8054,47 @@ export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel
     if (fastMode?.supported) {
         options.push(createFastModeConfigOption(fastMode.enabled, fastMode.useBooleanOption, fastMode.disabledReason));
     }
+    // Only surface the Agent picker when there's a real choice — i.e. the user
+    // has configured at least one custom agent (built-ins are filtered out in
+    // discoverCustomAgents). With none configured, "Default" would be the only
+    // entry, so we omit the option entirely.
+    if (agents.length > 0) {
+        options.push({
+            id: AGENT_CONFIG_ID,
+            name: "Agent",
+            description: "Main-thread agent persona",
+            type: "select",
+            currentValue: currentAgent,
+            options: [
+                { value: DEFAULT_AGENT_ID, name: "Default", description: "Standard Claude Code agent" },
+                ...agents.map((a) => ({
+                    value: a.name,
+                    name: a.name,
+                    description: a.description || undefined,
+                })),
+            ],
+        });
+    }
     return options;
 }
 function getAvailableSlashCommands(commands, 
 // Names the CLI tagged terminal-bound on `system`/init (their UX lives in
 // the CLI's own terminal, which ACP clients aren't) — filtered alongside
 // the static list. Raw CLI names, matched before the MCP rename.
-terminalCommands) {
+terminalCommands, 
+// The session cwd of an AIR client, or undefined for every other client.
+// AIR gets the kind and the SKILL.md path of each skill command.
+airSkillCwd, 
+// The resolved SKILL.md paths of the session, keyed by the cwd and the name.
+skillPaths) {
+    const skillPath = (name, cwd) => {
+        const key = `${cwd}\0${name}`;
+        if (skillPaths?.has(key))
+            return skillPaths.get(key);
+        const resolved = resolveSkillPath(name, cwd);
+        skillPaths?.set(key, resolved);
+        return resolved;
+    };
     const UNSUPPORTED_COMMANDS = [
         "clear",
         "cost",
@@ -7782,8 +8105,10 @@ terminalCommands) {
         "release-notes",
         "todos",
     ];
-    return commands
-        .filter((command) => !terminalCommands?.includes(command.name))
+    // The adapter replaces the terminal text of `/mcp` and runs its actions,
+    // even when Claude Code tags the command terminal-bound.
+    const advertised = commands
+        .filter((command) => command.name !== "mcp" && !terminalCommands?.includes(command.name))
         .map((command) => {
         const input = command.argumentHint
             ? {
@@ -7793,16 +8118,26 @@ terminalCommands) {
             }
             : null;
         let name = command.name;
-        if (command.name.endsWith(" (MCP)")) {
+        const mcpPrompt = command.name.endsWith(" (MCP)");
+        if (mcpPrompt) {
             name = `mcp:${name.replace(" (MCP)", "")}`;
         }
+        const skillMdPath = airSkillCwd && !command.builtin && !mcpPrompt
+            ? skillPath(command.name, airSkillCwd)
+            : undefined;
         return {
             name,
             description: command.description || "",
             input,
+            ...(skillMdPath
+                ? {
+                    _meta: withAirMeta(withAirMeta(undefined, AIR_KIND_KEY, "skill"), AIR_SKILL_PATH_KEY, skillMdPath),
+                }
+                : {}),
         };
     })
         .filter((command) => !UNSUPPORTED_COMMANDS.includes(command.name));
+    return [...advertised, MCP_AVAILABLE_COMMAND];
 }
 function formatUriAsLink(uri) {
     try {
@@ -7977,10 +8312,19 @@ function toolCallFieldsOf(session) {
  * Convert an SDKAssistantMessage (Claude) to a SessionNotification (ACP).
  * Only handles text, image, and thinking chunks for now.
  */
+/**
+ * The renderer of the notification functions: the agent's tool call
+ * capabilities when they are passed, else those of the ACP capabilities.
+ */
+function toolCallRenderer(options) {
+    return options?.toolCallCapabilities
+        ? new AcpToolCallRenderer(options.toolCallCapabilities, options.replay)
+        : AcpToolCallRenderer.for(options?.clientCapabilities, options?.replay);
+}
 export function toAcpNotifications(content, role, sessionId, toolUseCache, client, logger, options) {
     const taskState = options?.taskState ?? new Map();
     const registerHooks = options?.registerHooks !== false;
-    const renderer = AcpToolCallRenderer.for(options?.clientCapabilities, options?.replay);
+    const renderer = toolCallRenderer(options);
     if (typeof content === "string") {
         if (content.length === 0) {
             return [];
@@ -8318,6 +8662,7 @@ export function streamEventToAcpNotifications(message, sessionId, toolUseCache,
     const streamedToolInputs = options?.streamedToolInputs;
     const forwardedOptions = {
         clientCapabilities: options?.clientCapabilities,
+        toolCallCapabilities: options?.toolCallCapabilities,
         parentToolUseId: message.parent_tool_use_id,
         cwd: options?.cwd,
         taskState: options?.taskState,
@@ -8381,7 +8726,7 @@ export function streamEventToAcpNotifications(message, sessionId, toolUseCache,
                 // TodoWrite and the Task* tools never surfaced a tool_call to refine.
                 if (!shouldEmitToolCall(streamedInput.name))
                     return [];
-                const update = AcpToolCallRenderer.for(options?.clientCapabilities).partialRefinement(streamedInput, input, options?.cwd);
+                const update = toolCallRenderer(options).partialRefinement(streamedInput, input, options?.cwd);
                 if (message.parent_tool_use_id)
                     stampParentToolUseId(update, message.parent_tool_use_id);
                 applyMessageId(update, options?.messageId);