@agentclientprotocol/claude-agent-acp 0.85.2-preview.4 → 0.85.2-preview.6

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) {
@@ -1402,6 +1392,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 +1466,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 +1858,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 +1965,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 +1977,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 +1988,8 @@ export class ClaudeAcpAgent {
                 events.ended(outcome);
                 completeTurn();
             },
-            reject: (error) => {
-                events.failed(error);
+            reject: (error, title) => {
+                events.failed(error, title);
                 completeTurn();
             },
         };
@@ -2015,7 +2100,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 +2113,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 +2578,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 +2625,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
@@ -2732,27 +2824,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 +2998,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 +3024,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 +3041,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 +3065,7 @@ export class ClaudeAcpAgent {
                 return;
             }
             if (!supportsAirSessionFailures(this.clientCapabilities)) {
-                failActive(error);
+                failActive(error, title);
                 return;
             }
             if (!session.activeTurn || session.activeTurn.settled) {
@@ -2980,7 +3075,7 @@ export class ClaudeAcpAgent {
             }
             const failure = await createSessionFailure(kind, { title });
             if (!failure) {
-                failActive(error);
+                failActive(error, title);
                 return;
             }
             sessionFailures.recordActive(failure);
@@ -3365,17 +3460,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;
@@ -3534,11 +3630,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 +4407,7 @@ export class ClaudeAcpAgent {
                                         update: {
                                             sessionUpdate: "agent_message_chunk",
                                             content: { type: "text", text: lastRefusalExplanation },
+                                            messageId: messageIdForGrouping(message),
                                         },
                                     });
                                 }
@@ -4384,10 +4482,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);
                                         }
                                     }
@@ -4780,16 +4881,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);
                                     }
                                 }
@@ -5089,7 +5190,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
@@ -5531,13 +5632,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 +5652,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 +5812,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 +5826,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 +5920,8 @@ export class ClaudeAcpAgent {
                 registerHooks: false,
                 replay: true,
                 clientCapabilities: this.clientCapabilities,
-                cwd: this.sessions[sessionId]?.cwd,
-                taskState: this.sessions[sessionId]?.taskState,
+                cwd: replayState()?.cwd,
+                taskState: replayState()?.taskState,
                 messageId: replayMessageId,
                 parentToolUseId,
             })) {
@@ -5858,7 +5966,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
@@ -6292,7 +6400,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())),
             },
         });
     }
@@ -6613,6 +6721,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 +6738,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 +6745,8 @@ export class ClaudeAcpAgent {
             _meta: params._meta,
         }, {
             resume: params.sessionId,
-            resumedModelHint,
+            permissionMode: livePermissionMode,
+            ...(resumedSession ? { resumedModelHint: resumedSession.model } : {}),
         });
         return {
             sessionId: response.sessionId,
@@ -6667,6 +6775,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 +6818,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,7 +6888,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;
@@ -6778,9 +6901,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)
@@ -6806,7 +6927,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 +7220,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.
@@ -7248,8 +7369,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 +7411,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
@@ -7771,7 +7895,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",
@@ -7782,8 +7919,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 +7932,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 {