@agentclientprotocol/claude-agent-acp 0.85.2-preview.1 → 0.85.2-preview.11

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,9 +16,9 @@ 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";
@@ -36,11 +36,13 @@ 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 { parseToolResultMeta } from "./tool-result-meta.js";
 import { formatUsageResponse, isUsageCommandText, parseUsageResponse } from "./usage-markdown.js";
-import { MODE_CONFIG_ID, SessionModeManager } from "./session-mode.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";
@@ -105,32 +107,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 +129,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 +662,7 @@ const REPLAY_HIDDEN_COMMANDS = new Set([
     ...LOCAL_ONLY_COMMANDS,
     "/compact",
     "/model",
+    "/mcp",
     "/status",
     "/usage",
 ]);
@@ -1017,12 +1000,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 +1151,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 +1215,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 +1401,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 +1475,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,7 +1867,72 @@ 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.
+     */
     async prompt(params) {
+        let events;
+        const outcome = new Promise((resolve, reject) => {
+            events = {
+                inserted() { },
+                awaitingUser() { },
+                resumed() { },
+                ended: resolve,
+                failed: reject,
+            };
+        });
+        await this.startTurn(params, events);
+        return outcome;
+    }
+    /**
+     * Starts a turn for a prompt. Resolves once the prompt is queued for Claude
+     * Code, and rejects only when the prompt is refused before that. From then
+     * on, `events` reports how the turn goes (see {@link TurnEvents}), possibly
+     * before this resolves.
+     */
+    async startTurn(params, events) {
         if (this.providerUpdate)
             await this.providerUpdate;
         let session = this.sessions[params.sessionId];
@@ -1854,45 +1974,41 @@ 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 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
-        // consumer is running, and awaits the deferred.
+        // Each prompt is a Turn that the persistent consumer settles once the
+        // turn's outcome is known. `startTurn()` owns no loop: it enqueues the
+        // turn, pushes the user message onto the streaming input, and makes sure
+        // the consumer is running.
+        let completeTurn;
         const turn = {
             promptUuid,
+            events,
             isLocalOnlyCommand,
-            ...(isUsageCommand ? { isUsageCommand: true } : {}),
-            ...(usageMarkdownAbort ? { usageMarkdownAbort } : {}),
+            ...(localCommand ? { localCommand } : {}),
+            ...(localCommandAbort ? { localCommandAbort } : {}),
             ...(fileChangeReport ? { fileChangeReport } : {}),
             settled: false,
-            resolve: () => { },
-            reject: () => { },
-        };
-        let completeTurn;
-        turn.completion = new Promise((resolve) => {
-            completeTurn = resolve;
-        });
-        const response = new Promise((resolve, reject) => {
-            turn.resolve = (result) => {
-                resolve(result);
+            completion: new Promise((resolve) => {
+                completeTurn = resolve;
+            }),
+            resolve: (outcome) => {
+                events.ended(outcome);
                 completeTurn();
-            };
-            turn.reject = (error) => {
-                reject(error);
+            },
+            reject: (error, title) => {
+                events.failed(error, title);
                 completeTurn();
-            };
-        });
+            },
+        };
         session.turnQueue ??= [];
         session.turnQueue.push(turn);
         session.input.push(userMessage);
         this.ensureConsumer(session, params.sessionId);
-        await this.publishGoalFromPrompt(params.sessionId, firstText, promptUuid);
-        return response;
+        // The prompt is queued, so its turn goes ahead even if the client misses
+        // the goal it sets; the turn's events report the outcome.
+        await this.publishGoalFromPrompt(params.sessionId, firstText, promptUuid).catch((error) => this.logger.error(`Session ${params.sessionId}: failed to publish the prompt's goal:`, error));
     }
     /** `--hide-claude-auth` applies only to the CLI's own login. A provider
      *  override (`providers/set` or gateway `authenticate`) routes traffic away
@@ -1993,7 +2109,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) {
@@ -2003,7 +2122,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) {
@@ -2465,11 +2587,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;
@@ -2512,7 +2634,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
@@ -2540,6 +2663,22 @@ export class ClaudeAcpAgent {
                 }
             }
             resetTurnScratch();
+            // 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
@@ -2699,27 +2838,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
@@ -2872,7 +3012,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;
@@ -2896,7 +3038,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) {
@@ -2913,7 +3055,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
@@ -2937,7 +3079,7 @@ export class ClaudeAcpAgent {
                 return;
             }
             if (!supportsAirSessionFailures(this.clientCapabilities)) {
-                failActive(error);
+                failActive(error, title);
                 return;
             }
             if (!session.activeTurn || session.activeTurn.settled) {
@@ -2947,7 +3089,7 @@ export class ClaudeAcpAgent {
             }
             const failure = await createSessionFailure(kind, { title });
             if (!failure) {
-                failActive(error);
+                failActive(error, title);
                 return;
             }
             sessionFailures.recordActive(failure);
@@ -3051,7 +3193,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.
@@ -3107,7 +3249,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" —
@@ -3142,10 +3284,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) {
@@ -3156,6 +3298,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".
@@ -3332,17 +3485,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;
@@ -3399,7 +3553,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
@@ -3501,11 +3661,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;
@@ -4277,6 +4438,7 @@ export class ClaudeAcpAgent {
                                         update: {
                                             sessionUpdate: "agent_message_chunk",
                                             content: { type: "text", text: lastRefusalExplanation },
+                                            messageId: messageIdForGrouping(message),
                                         },
                                     });
                                 }
@@ -4351,10 +4513,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;
+                                        if (commandMarkdown === null)
                                             break;
-                                        for (const notification of toAcpNotifications(usageMarkdown ?? message.result, "assistant", params.sessionId, session.toolUseCache, routedNotificationClient, this.logger)) {
+                                        for (const notification of toAcpNotifications(commandMarkdown ?? message.result, "assistant", params.sessionId, session.toolUseCache, routedNotificationClient, this.logger, { messageId: messageIdForGrouping(message) })) {
                                             await sendUpdate(notification);
                                         }
                                     }
@@ -4567,6 +4732,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,
@@ -4636,7 +4802,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
@@ -4747,16 +4913,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);
                                     }
                                 }
@@ -4770,6 +4936,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,
@@ -4851,6 +5018,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,
@@ -5040,6 +5208,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 });
     }
@@ -5056,7 +5254,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
@@ -5085,12 +5283,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
@@ -5114,11 +5316,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.
@@ -5181,15 +5385,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
@@ -5203,17 +5415,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
@@ -5223,14 +5434,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
@@ -5263,6 +5467,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.
@@ -5498,13 +5705,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);
@@ -5516,7 +5725,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,
             })
@@ -5671,7 +5885,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" &&
@@ -5685,7 +5899,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);
             }
@@ -5779,8 +5993,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,
             })) {
@@ -5825,7 +6040,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
@@ -5862,18 +6077,40 @@ export class ClaudeAcpAgent {
     /** 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. */
+     *  non-interrupting SDK delivery. The active turn reports that it awaits the
+     *  user while any such request is open (see `syncAwaitingUser`). */
     async withPendingUserInput(sessionId, request) {
         const session = this.sessions[sessionId];
         if (!session)
             return request();
         session.pendingUserInputCount = (session.pendingUserInputCount ?? 0) + 1;
+        this.syncAwaitingUser(session);
         try {
             return await request();
         }
         finally {
             session.pendingUserInputCount = Math.max(0, (session.pendingUserInputCount ?? 1) - 1);
-        }
+            this.syncAwaitingUser(session);
+        }
+    }
+    /** Report whether the session's active turn awaits the user: exactly while
+     *  a permission request or question is open in the session. A request does
+     *  not say which prompt it is for, and Claude Code can ask for a queued
+     *  prompt before the consumer activates it, so a request is not tied to the
+     *  turn that was active when it opened. Called when the count changes and
+     *  when a turn activates. */
+    syncAwaitingUser(session) {
+        const turn = session.activeTurn;
+        if (!turn || turn.settled || !turn.insertedReported)
+            return;
+        const waiting = (session.pendingUserInputCount ?? 0) > 0;
+        if (waiting === (turn.awaitingUser ?? false))
+            return;
+        turn.awaitingUser = waiting;
+        if (waiting)
+            turn.events.awaitingUser();
+        else
+            turn.events.resumed();
     }
     /** Forward a permission request to the client, wiring the tool call's
      *  `signal` through as a `cancellationSignal`. When the turn is cancelled
@@ -6237,7 +6474,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())),
             },
         });
     }
@@ -6558,6 +6795,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) {
@@ -6573,9 +6812,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 ?? [],
@@ -6583,7 +6819,8 @@ export class ClaudeAcpAgent {
             _meta: params._meta,
         }, {
             resume: params.sessionId,
-            resumedModelHint,
+            permissionMode: livePermissionMode,
+            ...(resumedSession ? { resumedModelHint: resumedSession.model } : {}),
         });
         return {
             sessionId: response.sessionId,
@@ -6612,6 +6849,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
@@ -6649,10 +6892,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();
@@ -6714,7 +6962,11 @@ 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 initialPermissionMode = resolveInitialPermissionMode({
+            explicit: creationOpts.permissionMode,
+            resumed: resumedPermissionMode,
+            defaultMode: settingsManager.getSettings().permissions?.defaultMode,
+        }, this.logger, allowBypass);
         const userProvidedOptions = sessionMeta?.claudeCode?.options
             ? { ...sessionMeta.claudeCode.options }
             : undefined;
@@ -6723,9 +6975,7 @@ export class ClaudeAcpAgent {
         // 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 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)
@@ -6751,7 +7001,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 ?? [];
@@ -7044,7 +7294,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.
@@ -7193,8 +7443,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,
@@ -7235,7 +7485,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
@@ -7329,6 +7582,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.
@@ -7716,7 +7983,20 @@ 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",
@@ -7727,8 +8007,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
             ? {
@@ -7738,16 +8020,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 {
@@ -7922,10 +8214,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 [];
@@ -8263,6 +8564,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,
@@ -8326,7 +8628,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);