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

package/dist/acp-agent.js

@@ -1,4 +1,4 @@
-import { agent as acpAgent, CreateElicitationResponse, methods, ndJsonStream, RequestError, } from "@agentclientprotocol/sdk/unstable";
+import { agent as acpAgent, methods, ndJsonStream, RequestError, } from "@agentclientprotocol/sdk/unstable";
 import { filterEscalatingDefaultMode, getSessionMessages, listSessions, query, resolveSettings, } from "@anthropic-ai/claude-agent-sdk";
 import { GOAL_ACTIONS, GOAL_CONTROL_METHOD, GOAL_EXTENSION_VERSION, goalUpdateFromPrompt, parseGoalRequest, toGoalSnapshot, } from "./goal-extension.js";
 import { blobResourceToClaude } from "./blob-resources.js";
@@ -55,6 +55,7 @@ import { applyAvailableModelsAllowlist, buildModelConfigOption, getAvailableMode
 import { GatewayListingError, listBedrockModels, listGatewayModels, PROVIDER_AUTH_TOKEN_PLACEHOLDER, selectBedrockRegion, } from "./gateway-models.js";
 import { buildEffortConfigOption, EFFORT_CONFIG_ID, effortFlagSettings, effortLevelName, mergeEffortSettings, settingsEffortForModel, } from "./session-effort.js";
 import { createUltracodeConfigOption, readUltracodeSettings, resolveUltracodeEnabled, ULTRACODE_CONFIG_ID, ultracodeSupported, ultracodeWorkflowsEnabled, } from "./session-ultracode.js";
+import { STARTUP_FAILURE_RESULTS_ENV, startupFailureError } from "./startup-failure.js";
 export { EFFORT_CONFIG_ID, settingsEffortForModel } from "./session-effort.js";
 export { applyAvailableModelsAllowlist, matchResumedModel, MODEL_CONFIG_ID, resolveModelPreference, } from "./session-model.js";
 const execFileAsync = promisify(execFile);
@@ -512,6 +513,16 @@ export function computeSessionFingerprint(params) {
         options,
     }));
 }
+/** `params` without `_meta.claudeCode.options.effort`. */
+function withoutEffort(params) {
+    const meta = params._meta;
+    if (meta?.claudeCode?.options?.effort === undefined) {
+        return params;
+    }
+    const options = { ...meta.claudeCode.options };
+    delete options.effort;
+    return { ...params, _meta: { ...meta, claudeCode: { ...meta.claudeCode, options } } };
+}
 /** The JSON-RPC code ACP assigns to `authRequired`. Read from the SDK so it
  *  cannot drift from the errors this agent throws. */
 const AUTH_REQUIRED_CODE = RequestError.authRequired().code;
@@ -944,6 +955,7 @@ class ClientConnection {
     requestPermission(params, signal) {
         return this.ctx.request(methods.client.session.requestPermission, params, {
             cancellationSignal: signal,
+            stopWaitingOnCancel: true,
         });
     }
     readTextFile(params) {
@@ -955,6 +967,7 @@ class ClientConnection {
     createElicitation(params, signal) {
         return this.ctx.request(methods.client.elicitation.create, params, {
             cancellationSignal: signal,
+            stopWaitingOnCancel: true,
         });
     }
     completeElicitation(params) {
@@ -1110,7 +1123,10 @@ async function authenticateMcpServer(host, sessionId, query, serverName) {
             completed.then((authenticated) => ({ type: "completed", authenticated })),
             elicitation.then((response) => ({ type: "elicitation", response })),
         ]);
-        if (first.type === "elicitation" && !CreateElicitationResponse.isAccept(first.response)) {
+        // A url-mode accept carries no content to check. The guard
+        // `CreateElicitationResponse.isAccept` would also reject an accept whose
+        // `content` holds a v2-only value, such as an object.
+        if (first.type === "elicitation" && first.response.action !== "accept") {
             return;
         }
         if (first.type === "elicitation") {
@@ -1159,6 +1175,8 @@ export class ClaudeAcpAgent {
     providerConfig;
     /** Serializes provider changes while every open query is recreated between turns. */
     providerUpdate = null;
+    /** Per session: queue that runs mode/config changes and query restarts one at a time. */
+    configurationChanges = new Map();
     exitPlan;
     /** Last auth identity reported to the client, connection-scoped like
      *  `authenticate`/`logout`. Undefined means "not determined yet". */
@@ -1207,6 +1225,12 @@ export class ClaudeAcpAgent {
     replayedChildModels = new Map();
     /** See the `foreground` constructor option. */
     foregroundEvents;
+    /** Counts the prompts `startTurn()` has received, across sessions. */
+    promptsReceived = 0;
+    /** Per session, the `promptsReceived` count when its last cancel started.
+     *  A prompt received before that cancel that `startTurn()` had not queued
+     *  yet ends as cancelled instead of being queued. */
+    cancelledThrough = new Map();
     /**
      * The foreground work of each session while it runs, by the session id that
      * the client knows, on every connection: only the `foreground` option
@@ -1490,7 +1514,7 @@ export class ClaudeAcpAgent {
      * before the first update. A failed CLI start stops the replay.
      */
     async createSessionWhileReplaying(params, timing) {
-        await this.validateCwd(params.cwd);
+        await this.validateCwd(params.cwd, params.additionalDirectories);
         clientSystemPrompt(params.systemPrompt);
         const pending = {
             state: {
@@ -1548,7 +1572,8 @@ export class ClaudeAcpAgent {
     async unstable_forkSession(params) {
         while (this.providerUpdate)
             await this.providerUpdate;
-        // Reject a prompt the agent cannot apply before copying the transcript.
+        // Reject a bad `cwd` or prompt before copying the transcript.
+        await this.validateCwd(params.cwd, params.additionalDirectories);
         clientSystemPrompt(params.systemPrompt);
         const { sessionId } = await forkSession(params, {
             liveMessageIdToUuid: this.sessions[params.sessionId]?.messageIdToUuid,
@@ -1607,13 +1632,19 @@ export class ClaudeAcpAgent {
      * reads the start and the end only of the transcripts of the page.
      */
     async listSessions(params) {
+        if (params.cwd != null && !path.isAbsolute(params.cwd)) {
+            throw RequestError.invalidParams({ cwd: params.cwd }, `\`cwd\` must be an absolute path, but received: ${params.cwd}`);
+        }
         const indexed = this.sessionIndex.list(params);
         if (indexed)
             return indexed;
         const offset = sessionListOffset(params.cursor);
         // One more session than the page tells whether a next page exists.
+        // `includeWorktrees: false`: a `cwd` filter matches sessions of exactly
+        // that directory, not of the other git worktrees of its repository.
         const sdkSessions = await listSessions({
             dir: params.cwd ?? undefined,
+            includeWorktrees: false,
             limit: SESSION_LIST_PAGE_SIZE + 1,
             offset,
         });
@@ -1689,7 +1720,7 @@ export class ClaudeAcpAgent {
             this.setAuthStatus(gatewayAuthStatus(gatewayRequestToProviderConfig(this.gatewayAuthRequest)?.baseUrl));
             return;
         }
-        throw new Error("Method not implemented.");
+        throw RequestError.invalidParams({ methodId: _params.methodId }, `Unsupported authentication method: ${_params.methodId}`);
     }
     /**
      * Stores `next` and pushes it to the client.
@@ -2131,8 +2162,18 @@ export class ClaudeAcpAgent {
     /**
      * 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.
+     *
+     * A content block that the agent does not advertise, such as `audio`, fails
+     * the request with invalid params (-32602) before anything is queued:
+     * `promptToClaude` would drop it. v2 prompts reach `startTurn` through
+     * `v1PromptRequest`, which rejects these blocks itself.
      */
     async prompt(params) {
+        for (const block of params.prompt) {
+            if (!SUPPORTED_PROMPT_CONTENT_TYPES.includes(block.type)) {
+                throw RequestError.invalidParams({ type: block.type }, `Content blocks of type ${block.type} are not supported`);
+            }
+        }
         let events;
         const outcome = new Promise((resolve, reject) => {
             events = { inserted() { }, ended: resolve, failed: reject };
@@ -2147,6 +2188,7 @@ export class ClaudeAcpAgent {
      * before this resolves.
      */
     async startTurn(params, events) {
+        const received = ++this.promptsReceived;
         while (this.providerUpdate)
             await this.providerUpdate;
         let session = this.sessions[params.sessionId];
@@ -2164,8 +2206,16 @@ export class ClaudeAcpAgent {
         this.useAuthStatusSettings(session.settingsManager, session.effortSettingsOverride, session.creationParams?._meta?.claudeCode?.options?.env);
         void this.probeCliAuthStatus();
         const signOutRespawn = this.respawnSignedOutSession(params.sessionId, session);
-        if (signOutRespawn)
-            session = await signOutRespawn;
+        if (signOutRespawn) {
+            await signOutRespawn;
+            // A provider update can queue its replacement behind the sign-out respawn.
+            // Wait for that replacement too before a prompt starts on the old route.
+            while (this.providerUpdate)
+                await this.providerUpdate;
+            session = this.sessions[params.sessionId];
+            if (!session)
+                throw RequestError.sessionNotFound(params.sessionId);
+        }
         // The SDK query stream already terminated (see `queryClosed`); its iterator
         // can't be revived, so enqueueing here would hang on a deferred that never
         // settles. Fail clearly and let the client start a fresh session.
@@ -2252,7 +2302,9 @@ export class ClaudeAcpAgent {
         // its consumer is gone, so the prompt would never be inserted. End it as
         // the close ends a queued turn: `cancelled` on v1, -32800 on v2. A stream
         // that ended meanwhile fails the prompt as the check above does.
-        if (session.tornDown) {
+        // A `session/cancel` that arrived after this prompt, during the awaits
+        // above, ends it the same way.
+        if (session.tornDown || received <= (this.cancelledThrough.get(params.sessionId) ?? 0)) {
             session.fileChangeReporter?.finish(fileChangeReport, "cancelled");
             events.ended({ stopReason: "cancelled" });
             return;
@@ -2266,6 +2318,7 @@ export class ClaudeAcpAgent {
         // the consumer is running.
         let completeTurn;
         const turn = {
+            received,
             promptUuid,
             events,
             isLocalOnlyCommand,
@@ -2457,36 +2510,29 @@ export class ClaudeAcpAgent {
             });
         }
     }
-    async recreateSignedOutQuery(sessionId, session) {
-        const creationParams = session.creationParams;
-        if (!creationParams) {
-            throw RequestError.internalError(undefined, SESSION_ENDED_MESSAGE);
-        }
-        this.logger.log(`Recreating Claude session ${sessionId} after a sign-out`);
-        // Already closed by `markSessionForSignOutRespawn`; idempotent here so a
-        // husk that reached this by another route still releases its resources.
-        this.closeQueryStream(session);
-        try {
-            // The very first turn may be the one that signed out, so the CLI may
-            // never have written the conversation.
-            await this.recreateLiveSession(creationParams, sessionId, {
-                permissionMode: session.modes.currentModeId,
-            });
-            // The new Session has the same MCP servers; keep the ones already
-            // reported so its first `system`/init doesn't repeat their notices.
-            const recreated = this.sessions[sessionId];
-            if (recreated && session.reportedMcpServers) {
-                recreated.reportedMcpServers = new Set(session.reportedMcpServers);
+    /** Queued per session, so a choice sent during the respawn lands on the new query. */
+    recreateSignedOutQuery(sessionId, session) {
+        return this.serializeConfigurationChange(sessionId, async () => {
+            const creationParams = session.creationParams;
+            if (!creationParams) {
+                throw RequestError.internalError(undefined, SESSION_ENDED_MESSAGE);
             }
-        }
-        catch (error) {
-            // Keep the husk addressable: the client answers the refusal with its own
-            // auth flow and then retries this session.
-            if (!this.sessions[sessionId]) {
-                this.sessions[sessionId] = session;
+            // Already replaced by a provider restart, or closed.
+            if (this.sessions[sessionId] !== session)
+                return;
+            this.logger.log(`Recreating Claude session ${sessionId} after a sign-out`);
+            try {
+                // The signed-out turn may be the first, so the conversation may not be saved yet.
+                await this.replaceSessionQuery(sessionId, session, creationParams);
             }
-            throw error;
-        }
+            catch (error) {
+                // Keep the husk so the client can sign in and retry; a closed session stays closed.
+                if (!session.tornDown && !this.sessions[sessionId]) {
+                    this.sessions[sessionId] = session;
+                }
+                throw error;
+            }
+        });
     }
     /**
      * Starts a new query for the session `sessionId`, which ran on this
@@ -2510,6 +2556,7 @@ export class ClaudeAcpAgent {
             return await this.createSession(params, {
                 reuseSessionId: sessionId,
                 permissionMode: options.permissionMode,
+                replacingSession: options.replacingSession,
             });
         }
     }
@@ -6442,6 +6489,12 @@ export class ClaudeAcpAgent {
             return;
         }
         session.cancelled = true;
+        // Only prompts received before this cancel are cancelled. A prompt that
+        // arrives while the awaits below run is queued and runs after the cancel
+        // (ACP v2: a `session/prompt` received after `session/cancel` is not
+        // cancelled by it).
+        const cancelledThrough = this.promptsReceived;
+        this.cancelledThrough.set(params.sessionId, cancelledThrough);
         // The interrupt below makes Claude Code withdraw the requests that are open
         // now (see `withPendingUserInput`).
         for (const input of session.openUserInputs ?? [])
@@ -6450,7 +6503,7 @@ export class ClaudeAcpAgent {
         // the meantime is already judged against these prompts.
         session.cancelledPrompts ??= new Set();
         for (const turn of session.turnQueue ?? []) {
-            if (turn.settled)
+            if (turn.settled || turn.received > cancelledThrough)
                 continue;
             session.cancelledPrompts.add(turn.promptUuid);
             for (const uuid of turn.steeredUuids ?? [])
@@ -6525,7 +6578,7 @@ export class ClaudeAcpAgent {
         const orphanedTurns = [];
         if (session.turnQueue) {
             for (const turn of session.turnQueue) {
-                if (turn !== session.activeTurn && !turn.settled) {
+                if (turn !== session.activeTurn && !turn.settled && turn.received <= cancelledThrough) {
                     session.fileChangeReporter?.finish(turn.fileChangeReport, "cancelled");
                     turn.settled = true;
                     // Deliberately no `usage`: a queued turn never ran, so the session
@@ -6579,7 +6632,7 @@ export class ClaudeAcpAgent {
                 }
                 this.trackOrphanCommand(session, turn.promptUuid, turn.commandStarted ? "started" : "pending");
             }
-            session.turnQueue = session.turnQueue.filter((turn) => turn === session.activeTurn && !turn.settled);
+            session.turnQueue = session.turnQueue.filter((turn) => !turn.settled);
         }
         const diagnosticTurns = orphanedTurns.filter((turn) => {
             if (turn.commandFinished === "completed" ||
@@ -6702,8 +6755,8 @@ export class ClaudeAcpAgent {
         }
         // Before the interrupt: once it stops the running turn, Claude Code starts
         // the next queued message right away.
-        // A prompt or steer that arrived while this cancel awaited is abandoned
-        // too, after the record above was taken.
+        // A steer that arrived while this cancel awaited is abandoned too, after
+        // the record above was taken.
         for (const uuid of abandoned)
             (session.cancelledPrompts ??= new Set()).add(uuid);
         this.dropQueuedMessages(params.sessionId, session.query, abandoned);
@@ -6853,6 +6906,7 @@ export class ClaudeAcpAgent {
         session.nativeSubagentRuntime?.clear();
         session.asyncTaskRuntime?.clear();
         this.replayedChildModels.delete(sessionId);
+        this.cancelledThrough.delete(sessionId);
         delete this.sessions[sessionId];
         this.sessionIndex.onTeardown(sessionId);
         const ended = await raceTimeoutAndAbort(turnsEnded, TEARDOWN_TURN_END_TIMEOUT_MS, new AbortController().signal);
@@ -6895,10 +6949,13 @@ export class ClaudeAcpAgent {
     async deleteSession(params) {
         return this.sessionIndex.deleteSession(params);
     }
-    async setSessionMode(params) {
-        return this.sessionModes.setSessionMode(params);
+    setSessionMode(params) {
+        return this.serializeConfigurationChange(params.sessionId, () => this.sessionModes.setSessionMode(params));
+    }
+    setSessionConfigOption(params) {
+        return this.serializeConfigurationChange(params.sessionId, () => this.selectSessionConfigOption(params));
     }
-    async setSessionConfigOption(params) {
+    async selectSessionConfigOption(params) {
         const session = this.sessions[params.sessionId];
         if (!session) {
             throw RequestError.sessionNotFound(params.sessionId);
@@ -6914,6 +6971,13 @@ export class ClaudeAcpAgent {
         if (!option) {
             throw RequestError.invalidParams(undefined, `Unknown config option: ${params.configId}`);
         }
+        // The value must match the type the option was advertised with: a
+        // `type: "boolean"` option takes `true`/`false`, not "on"/"off", and a
+        // `type: "select"` option takes a string.
+        const expectedType = option.type === "boolean" ? "boolean" : "string";
+        if (typeof params.value !== expectedType) {
+            throw RequestError.invalidParams({ configId: params.configId, value: params.value }, `Config option ${params.configId} takes a ${expectedType} value, but received: ${JSON.stringify(params.value)}`);
+        }
         // Fast mode and ultracode carry a boolean value (for Clients that opted
         // into boolean config options) or the "on"/"off" select fallback, so they
         // bypass the
@@ -7131,7 +7195,7 @@ export class ClaudeAcpAgent {
             ? await subagentHistory(sessionId)
             : { agents: new Map() };
         const rfdReplay = form === "rfd"
-            ? new RfdSubagentReplay(rfdHistory, (notification) => this.client.sessionUpdate(asSdkSessionNotification(notification)), this.subagentModels(sessionId), !pending)
+            ? new RfdSubagentReplay(rfdHistory, (notification) => this.client.sessionUpdate(asSdkSessionNotification(notification)), this.subagentModels(sessionId), !pending, session?.cwd)
             : undefined;
         rfdReplay?.scan(messages, sessionId);
         // History persists no task_started frame, so a background task gets its
@@ -7678,10 +7742,11 @@ export class ClaudeAcpAgent {
     /** Forward a permission request to the client, wiring the tool call's
      *  `signal` through as a `cancellationSignal`. When the turn is cancelled
      *  while the client's prompt is still open the signal aborts, the SDK sends
-     *  `$/cancel_request`, and our local abort race settles even if the client
-     *  ignores it. A `cancelled` outcome, request rejection, and local abort all
-     *  surface the same "Tool use aborted" the callers already expect. */
-    async requestPermissionFromClient(params, toolName, signal, parentToolUseId, ownerSessionId, agentID, toolInput, previewContent) {
+     *  `$/cancel_request` and stops waiting for the client's answer. The
+     *  rejection surfaces as the "Tool use aborted" that the callers expect.
+     *  `canUseTool` decides what a `cancelled` outcome means. */
+    async requestPermissionFromClient(params, toolName, toolSignal, parentToolUseId, ownerSessionId, agentID, toolInput, previewContent) {
+        const signal = this.untilSessionClosed(ownerSessionId, toolSignal);
         if (signal.aborted)
             throw new Error("Tool use aborted");
         // The SDK may invoke `canUseTool` (and therefore this permission request)
@@ -7693,13 +7758,10 @@ export class ClaudeAcpAgent {
         await this.ensureToolCallEmitted(ownerSessionId, toolName, params.toolCall.toolCallId, toolInput, parentToolUseId, signal, params.sessionId, previewContent);
         if (signal.aborted)
             throw new Error("Tool use aborted");
-        // Do not rely on every ACP client settling requestPermission after the
-        // cancellation signal. The local race guarantees that Claude's tool call
-        // is released even when an older or broken client ignores $/cancel_request.
         // The request goes to a subagent's child session for a tool call of that
         // subagent, but it blocks the turn of the owner session.
         try {
-            return await this.withChildAwaitingUser(ownerSessionId, params.sessionId, signal, () => this.withPendingUserInput(ownerSessionId, signal, () => raceWithAbort(this.client.requestPermission(params, signal), signal), agentID));
+            return await this.withChildAwaitingUser(ownerSessionId, params.sessionId, signal, () => this.withPendingUserInput(ownerSessionId, signal, () => this.client.requestPermission(params, signal), agentID));
         }
         catch (error) {
             if (signal.aborted) {
@@ -7709,15 +7771,23 @@ export class ClaudeAcpAgent {
         }
     }
     /** Send the client an elicitation for a callback of Claude Code. When the
-     *  callback's `signal` aborts, the SDK sends `$/cancel_request` and keeps
-     *  waiting for the client's reply, which a client that ignores the cancel
-     *  never sends. So the call also rejects at once on the abort, as
-     *  {@link requestPermissionFromClient} does for a permission request. Left
-     *  open, the request would stay in `openUserInputs` (see
-     *  {@link withPendingUserInput}), which keeps steering non-interrupting, and
-     *  a child's `openRequests` would not drop. */
+     *  callback's `signal` aborts, the SDK sends `$/cancel_request` and the call
+     *  rejects at once, without waiting for a reply that a client ignoring the
+     *  cancel never sends. Left open, the request would stay in
+     *  `openUserInputs` (see {@link withPendingUserInput}), which keeps steering
+     *  non-interrupting, and a child's `openRequests` would not drop. */
     elicitFromClient(request, signal) {
-        return raceWithAbort(this.client.createElicitation(request, signal), signal);
+        return this.client.createElicitation(request, signal);
+    }
+    /** `signal`, also aborted when `teardownSession` aborts the
+     *  `abortController` of session `sessionId`. Claude Code aborts a callback's
+     *  own signal when its query closes, but not necessarily before
+     *  `session/close` responds, and v2 requires every pending permission
+     *  request and elicitation of the session to be cancelled with
+     *  `$/cancel_request` before that response. */
+    untilSessionClosed(sessionId, signal) {
+        const sessionSignal = this.sessions[sessionId]?.abortController?.signal;
+        return sessionSignal ? AbortSignal.any([signal, sessionSignal]) : signal;
     }
     /** Settle the tool call `ensureToolCallEmitted` emitted for a
      *  SandboxNetworkAccess request once the request is answered. The callback
@@ -7852,6 +7922,11 @@ export class ClaudeAcpAgent {
             const session = this.sessions[sessionId];
             if (!session || !input.agent_id)
                 return { continue: true };
+            // A hook's `cwd` is the child's working directory, e.g. its worktree.
+            // Reported before the hook returns, so before the work that follows it.
+            await session.nativeSubagentRuntime
+                ?.reportCwd(input.agent_id, input.cwd)
+                .catch((error) => this.logger.error(`Session ${sessionId}: failed to report subagent cwd: ${error}`));
             const options = [];
             if (input.permission_mode) {
                 const mode = session.modes.availableModes.find((mode) => mode.id === input.permission_mode);
@@ -8077,9 +8152,13 @@ export class ClaudeAcpAgent {
             // cancel does not stop. Answer such a request with a denial so the
             // subagent reads "the user refused" and goes on. Throwing instead makes
             // Claude Code deny it as "Tool permission request failed".
+            // On ACP v2, `cancelled` also answers a prompt that the user dismissed
+            // or that the client declined by policy. Without a `session/cancel`
+            // (`session.cancelled` unset), that is the user refusing the tool, so it
+            // gets the same denial and the turn goes on.
             if (response.outcome?.outcome === "cancelled" &&
                 this.sessions[sessionId] === session &&
-                !blocksForeground(session, agentID)) {
+                (!blocksForeground(session, agentID) || (this.v2 && !session.cancelled))) {
                 return {
                     behavior: "deny",
                     message: "User refused permission to run tool",
@@ -8143,7 +8222,8 @@ export class ClaudeAcpAgent {
      * an error, is a `cancel`.
      */
     handleMcpElicitation(sessionId, support) {
-        return async (request, { signal }) => {
+        return async (request, { signal: callbackSignal }) => {
+            const signal = this.untilSessionClosed(sessionId, callbackSignal);
             const isUrl = request.mode === "url";
             if ((isUrl && !support.url) || (!isUrl && !support.form)) {
                 return { action: "cancel" };
@@ -8180,7 +8260,8 @@ export class ClaudeAcpAgent {
      * The elicitation goes to `requestSessionId`, a subagent's child session for
      * a question it asks, and blocks the turn of `sessionId`.
      */
-    async handleAskUserQuestion(sessionId, requestSessionId, toolInput, toolUseID, signal, agentID) {
+    async handleAskUserQuestion(sessionId, requestSessionId, toolInput, toolUseID, toolSignal, agentID) {
+        const signal = this.untilSessionClosed(sessionId, toolSignal);
         const questions = extractAskUserQuestions(toolInput);
         if (!questions) {
             return { behavior: "deny", message: "AskUserQuestion called with no valid questions." };
@@ -8219,7 +8300,8 @@ export class ClaudeAcpAgent {
      * refusal-fallback consent prompt, rendered as an ACP form elicitation.
      */
     handleUserDialog(sessionId) {
-        return async (request, { signal }) => {
+        return async (request, { signal: callbackSignal }) => {
+            const signal = this.untilSessionClosed(sessionId, callbackSignal);
             if (request.dialogKind !== REFUSAL_FALLBACK_DIALOG_KIND) {
                 return { behavior: "cancelled" };
             }
@@ -8323,19 +8405,27 @@ export class ClaudeAcpAgent {
     /**
      * The work that follows a session setup response: the session's commands,
      * the current states of the subagents a load replayed, and MCP server
-     * authentication. A v2 client gets the commands in the setup response itself,
-     * and the subagent states from the v2 surface once it has sent its own
-     * response (`src/v2/agent.ts`), so it gets neither here.
+     * authentication. On v2 the setup handlers of `src/v2/agent.ts` do this
+     * work once they have sent their response, so it does nothing here.
      */
     afterSetupResponse(sessionId, mcpServers) {
+        if (this.v2)
+            return;
         setTimeout(() => {
-            if (!this.v2) {
-                this.sendAvailableCommandsUpdate(sessionId);
-                void this.publishCurrentSubagentStates(sessionId);
-            }
+            this.sendAvailableCommandsUpdate(sessionId);
+            void this.publishCurrentSubagentStates(sessionId);
             startMcpAuthentication(this, sessionId, mcpServers);
         }, 0);
     }
+    /**
+     * Starts OAuth in the background for the servers of `mcpServers` that
+     * Claude Code reports as needing it, which sends the client a URL
+     * elicitation. The v2 surface calls it after the setup response, since v2
+     * asks for no elicitation before the `session/new` response.
+     */
+    authenticateMcpServers(sessionId, mcpServers) {
+        startMcpAuthentication(this, sessionId, mcpServers);
+    }
     /**
      * Sends the current state of each subagent that the last load of
      * `sessionId` replayed (see {@link RfdSubagentReplay.currentStates}). Run it
@@ -8595,6 +8685,7 @@ export class ClaudeAcpAgent {
                 agent: value === DEFAULT_AGENT_ID ? null : value,
             });
             session.currentAgent = value;
+            session.agentSelected = true;
             session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
         }
         else if (configId === EFFORT_CONFIG_ID) {
@@ -8740,7 +8831,8 @@ export class ClaudeAcpAgent {
         });
     }
     async getOrCreateSession(params, resumedSession) {
-        // Reject a prompt the agent cannot apply before reusing a live session.
+        // Reject a bad `cwd` or prompt before reusing or tearing down a live session.
+        await this.validateCwd(params.cwd, params.additionalDirectories);
         clientSystemPrompt(params.systemPrompt);
         const existingSession = this.sessions[params.sessionId];
         // A recreated live session keeps its mode, not the mode of the transcript.
@@ -8788,8 +8880,16 @@ export class ClaudeAcpAgent {
      * directory before we create a session. Throws an `invalidParams` error with
      * an actionable message so clients (e.g. Zed) can surface it to the user
      * instead of failing later with an opaque SDK error.
+     *
+     * Each `additionalDirectories` entry must be absolute too. Only the lexical
+     * rule is checked there: a missing extra root does not fail a session.
      */
-    async validateCwd(cwd) {
+    async validateCwd(cwd, additionalDirectories) {
+        for (const dir of additionalDirectories ?? []) {
+            if (!path.isAbsolute(dir)) {
+                throw RequestError.invalidParams({ additionalDirectories }, `\`additionalDirectories\` entries must be absolute paths, but received: ${dir}`);
+            }
+        }
         if (!path.isAbsolute(cwd)) {
             throw RequestError.invalidParams({ cwd }, `\`cwd\` must be an absolute path, but received: ${cwd}`);
         }
@@ -8817,7 +8917,7 @@ export class ClaudeAcpAgent {
         // this check a session is created against a missing directory and the
         // failure only surfaces later as a confusing "native binary failed to
         // launch" error from the SDK (see issue #749).
-        await this.validateCwd(params.cwd);
+        await this.validateCwd(params.cwd, params.additionalDirectories);
         const clientPrompt = clientSystemPrompt(params.systemPrompt);
         // We want to create a new session id unless it is resume,
         // but not resume + forkSession.
@@ -9016,6 +9116,7 @@ export class ClaudeAcpAgent {
             ...providerEnv,
             // Opt-in to session state events like when the agent is idle
             CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS: "1",
+            ...STARTUP_FAILURE_RESULTS_ENV,
         };
         // Scopes the context-window cache to this query's backend (see
         // `contextWindowCache`). Derived from the same `env` object handed to the
@@ -9260,7 +9361,7 @@ export class ClaudeAcpAgent {
                         error.message.includes("No conversation found with session ID"))) {
                     throw RequestError.sessionNotFound(sessionId);
                 }
-                throw error;
+                throw startupFailureError(error) ?? error;
             }
             timing.phase("sdk-initialize");
             // Publish the identity BEFORE the guard can refuse this session. A
@@ -9427,6 +9528,9 @@ export class ClaudeAcpAgent {
             // "opus[1m]" row matched for a bare 200k id), so on the fallback path only
             // the id itself is a trustworthy window signal.
             const seededWindow = immediateContextWindow(providerCacheKey, models.currentModelId, allowlistedModelInfo);
+            if (creationOpts.replacingSession?.tornDown) {
+                throw RequestError.internalError(undefined, SESSION_ENDED_MESSAGE);
+            }
             this.sessions[sessionId] = {
                 query: q,
                 input: input,
@@ -9537,27 +9641,8 @@ export class ClaudeAcpAgent {
                 await Promise.all(activeTurns);
             }
             this.providerConfig = config;
-            for (const [sessionId, session] of sessions) {
-                if (this.sessions[sessionId] !== session || !session.creationParams) {
-                    continue;
-                }
-                this.logger.log(`Recreating Claude session ${sessionId} for provider update`);
-                this.closeQueryStream(session);
-                delete this.sessions[sessionId];
-                try {
-                    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
-                    // `--hide-claude-auth` guard makes this a normal outcome of
-                    // `providers/disable`: the override kept a subscription account
-                    // usable, and creation refuses without it. The session is already
-                    // gone, so tell the client why and go on to the next one.
-                    this.reportSessionLostOnProviderUpdate(sessionId, session, error);
-                }
+            for (const [sessionId] of sessions) {
+                await this.serializeConfigurationChange(sessionId, () => this.restartSessionForProvider(sessionId));
             }
         });
         // Sessions and prompts await `providerUpdate` before they run. A rejected
@@ -9577,6 +9662,126 @@ export class ClaudeAcpAgent {
             }
         }
     }
+    /** Starts a new query for the session under the new provider and restores its choices. */
+    async restartSessionForProvider(sessionId) {
+        // A sign-out respawn ahead of this change can have replaced the snapshot.
+        const session = this.sessions[sessionId];
+        if (!session?.creationParams) {
+            return;
+        }
+        this.logger.log(`Recreating Claude session ${sessionId} for provider update`);
+        try {
+            await this.replaceSessionQuery(sessionId, session, session.creationParams);
+        }
+        catch (error) {
+            if (this.sessions[sessionId] === session)
+                delete this.sessions[sessionId];
+            if (session.tornDown)
+                return;
+            // One session that cannot come back must not abort the switch. The
+            // `--hide-claude-auth` guard makes this a normal outcome of
+            // `providers/disable`: the override kept a subscription account
+            // usable, and creation refuses without it. The session is already
+            // gone, so tell the client why and go on to the next one.
+            this.reportSessionLostOnProviderUpdate(sessionId, session, error);
+        }
+    }
+    /** Recreates the session's query and restores its choices and reported MCP servers, unless it was closed meanwhile. */
+    async replaceSessionQuery(sessionId, session, creationParams) {
+        this.closeQueryStream(session);
+        // Keep the old record visible so closeSession and dispose can mark it torn down.
+        // Without the creation-time effort: restoreSessionChoices restores the current pin instead.
+        await this.recreateLiveSession(withoutEffort(creationParams), sessionId, {
+            permissionMode: session.modes.currentModeId,
+            replacingSession: session,
+        });
+        const recreated = this.sessions[sessionId];
+        if (!recreated || recreated.tornDown)
+            return;
+        // Same MCP servers, so don't repeat their notices.
+        if (session.reportedMcpServers) {
+            recreated.reportedMcpServers = new Set(session.reportedMcpServers);
+        }
+        await this.restoreSessionChoices(sessionId, recreated, session);
+        if (recreated.tornDown)
+            return;
+        // The recreated session works without this update, so a failed send is only logged.
+        await this.client
+            .sessionUpdate({
+            sessionId,
+            update: { sessionUpdate: "config_option_update", configOptions: recreated.configOptions },
+        })
+            .catch((error) => {
+            this.logger.error(`Session ${sessionId}: could not publish the configuration restored after the query restart:`, error);
+        });
+    }
+    /** Re-applies the choices of `previous` to the session that replaced it; a choice the new query rejects is logged. */
+    async restoreSessionChoices(sessionId, session, previous) {
+        const restore = async (choice, apply) => {
+            if (session.tornDown)
+                return;
+            try {
+                await apply();
+            }
+            catch (error) {
+                if (!session.tornDown) {
+                    this.logger.error(`Could not restore ${choice} after the query restart:`, error);
+                }
+            }
+        };
+        const select = (configId, value) => restore(`${configId} "${value}"`, () => this.selectSessionConfigOption({ sessionId, configId, value }));
+        // First: the model decides which modes, effort levels, Fast mode and ultracode exist.
+        if (session.models.currentModelId !== previous.models.currentModelId) {
+            await select(MODEL_CONFIG_ID, previous.models.currentModelId);
+        }
+        // After the model: creation falls back from "auto" to acceptEdits on a model without Auto.
+        if (session.modes.currentModeId !== previous.modes.currentModeId) {
+            await select(MODE_CONFIG_ID, previous.modes.currentModeId);
+            if (session.modes.currentModeId === previous.modes.currentModeId) {
+                session.autoModeFallbackWarningPending = false;
+            }
+        }
+        if (session.modes.currentModeId === "plan") {
+            session.prePlanMode = previous.prePlanMode;
+        }
+        // Compare intent, not the option: the option is hidden on a model without support.
+        if (session.ultracodeEnabled !== previous.ultracodeEnabled) {
+            await restore("ultracode", () => this.applyUltracode(session, previous.ultracodeEnabled));
+        }
+        if (session.fastModeEnabled !== previous.fastModeEnabled) {
+            await restore("Fast mode", () => this.applyFastMode(session, previous.fastModeEnabled));
+        }
+        // After ultracode, since the effort flag carries it.
+        if (previous.effortPinnedLevel !== undefined) {
+            await select(EFFORT_CONFIG_ID, previous.effortPinnedLevel);
+        }
+        // Even when unchanged: Default over a hidden creation-time agent like "Explore" must clear it.
+        if (previous.agentSelected) {
+            if (previous.currentAgent === DEFAULT_AGENT_ID) {
+                // Default is always valid, even when discovery returned no custom agents and hid the picker.
+                await restore("Default agent", () => this.applyConfigOptionValue(sessionId, session, AGENT_CONFIG_ID, DEFAULT_AGENT_ID));
+            }
+            else {
+                await select(AGENT_CONFIG_ID, previous.currentAgent);
+            }
+        }
+        // Keep the original params and fingerprint paired for later load/resume calls.
+        session.creationParams = previous.creationParams;
+        session.sessionFingerprint = previous.sessionFingerprint;
+    }
+    serializeConfigurationChange(sessionId, change) {
+        const result = (this.configurationChanges.get(sessionId) ?? Promise.resolve()).then(change);
+        // Drops the entry once no newer change has queued behind this one.
+        const tail = result
+            .catch(() => { })
+            .then(() => {
+            if (this.configurationChanges.get(sessionId) === tail) {
+                this.configurationChanges.delete(sessionId);
+            }
+        });
+        this.configurationChanges.set(sessionId, tail);
+        return result;
+    }
     /** Tell a capable client when a non-auth error ends a session during a provider switch. */
     reportSessionLostOnProviderUpdate(sessionId, session, error) {
         this.logger.error(`Session ${sessionId}: could not be recreated for the provider update: ${error}`);
@@ -10289,11 +10494,20 @@ skillFiles) {
         };
     })
         .filter((command) => !UNSUPPORTED_COMMANDS.includes(command.name));
+    // Command names must not contain whitespace and must be unique. A name
+    // like "my command" is dropped, and of two commands named "review" only the
+    // first is kept.
+    const names = new Set();
     return [
         ...advertised,
         MCP_AVAILABLE_COMMAND,
         ...remoteControlCommands.filter((command) => !claudeCodeOffersCommand(commands, terminalCommands, command.name)),
-    ];
+    ].filter((command) => {
+        if (/\s/.test(command.name) || names.has(command.name))
+            return false;
+        names.add(command.name);
+        return true;
+    });
 }
 function formatUriAsLink(uri) {
     try {
@@ -10313,15 +10527,26 @@ function formatUriAsLink(uri) {
         return uri;
     }
 }
+/** The prompt content block types that `promptToClaude` converts. The agent
+ *  advertises no `audio` prompt capability. */
+const SUPPORTED_PROMPT_CONTENT_TYPES = [
+    "text",
+    "image",
+    "resource_link",
+    "resource",
+];
 export function promptToClaude(prompt) {
     const content = [];
     const context = [];
+    const firstText = prompt.prompt.find((chunk) => chunk.type === "text");
     for (const chunk of prompt.prompt) {
         switch (chunk.type) {
             case "text": {
                 let text = chunk.text;
-                // change /mcp:server:command args -> /server:command (MCP) args
-                const mcpMatch = text.match(/^\/mcp:([^:\s]+):(\S+)(?:\s(.*))?$/);
+                // A slash command is the first text block. Change
+                // `/mcp:server:command args` to `/server:command (MCP) args`; the
+                // arguments can span lines.
+                const mcpMatch = chunk === firstText ? text.match(/^\/mcp:([^:\s]+):(\S+)(?:\s+([\s\S]*))?$/) : null;
                 if (mcpMatch) {
                     const [, server, command, args] = mcpMatch;
                     text = `/${server}:${command} (MCP)${args ? ` ${args}` : ""}`;