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

package/dist/acp-agent.js

@@ -5,7 +5,7 @@ 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_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 { AsyncTaskRuntime, backgroundBashTaskFromToolResult, backgroundedBashToolCallIds, 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";
 import { randomUUID } from "node:crypto";
@@ -21,7 +21,7 @@ import { SessionTiming } from "./session-timing.js";
 import { ALLOW_BYPASS } from "./permissions/modes.js";
 import { normalizeDurablePermissionChangeSet } from "./permissions/normalization.js";
 import { buildClaudePermissionOptions } from "./permissions/options.js";
-import { buildClaudePermissionPresentation } from "./permissions/presentation.js";
+import { buildClaudePermissionPresentation, } from "./permissions/presentation.js";
 import { decodeClaudePermissionResponse } from "./permissions/response.js";
 import { SettingsManager } from "./settings.js";
 import { activeUsageLimitMessage, airSessionFailureCapabilityMeta, assistantMessageText, createSessionFailureState, isSyntheticUsageLimitMessage, providerFailureCategory, SessionFailureController, sessionFailureMeta, supportsAirSessionFailures, } from "./session-failure-extension.js";
@@ -39,8 +39,10 @@ import { AcpToolCallRenderer } from "./tool-calls/renderer.js";
 import { resolveSkillPath } from "./tool-calls/reporters/interaction.js";
 import { nodeToWebReadable, nodeToWebWritable, Pushable, raceTimeoutAndAbort, unreachable, } from "./utils.js";
 import { acceptedPlanToolResult, ExitPlanCoordinator, isExitPlanInterruptionResult, observeExitPlanToolResults, } from "./exit-plan.js";
+import { DEFAULT_AGENT_ID } from "./session-config-ids.js";
 import { parseToolResultMeta } from "./tool-result-meta.js";
 import { formatUsageResponse, isUsageCommandText, parseUsageResponse } from "./usage-markdown.js";
+export { DEFAULT_AGENT_ID } from "./session-config-ids.js";
 import { MCP_AVAILABLE_COMMAND, parseMcpCommand, runMcpCommand } from "./mcp-command.js";
 import { MODE_CONFIG_ID, resolveInitialPermissionMode, SessionModeManager, } from "./session-mode.js";
 import { applyAvailableModelsAllowlist, buildModelConfigOption, getAvailableModels, MODEL_CONFIG_ID, resolveModelPreference, } from "./session-model.js";
@@ -79,6 +81,10 @@ const DEFAULT_CONTEXT_WINDOW = 200000;
  *  pre-empt a slow-but-healthy interrupt. */
 const DEFAULT_FORCE_CANCEL_GRACE_MS = 30_000;
 const STRUCTURED_USAGE_TIMEOUT_MS = 5_000;
+/** How long a session teardown waits for the turns that it cancels to end.
+ *  The teardown wakes the consumer itself, so they end within a few ticks
+ *  unless the consumer is wedged. */
+const TEARDOWN_TURN_END_TIMEOUT_MS = 5_000;
 /** The number of settled subagents whose parent tool call a session keeps for
  *  a later resume (see `resumableSubagents`). */
 const MAX_RESUMABLE_SUBAGENTS = 256;
@@ -1151,7 +1157,14 @@ export class ClaudeAcpAgent {
      *  return "cancelled". See {@link DEFAULT_FORCE_CANCEL_GRACE_MS}. Mutable so
      *  tests can shrink it. */
     forceCancelGraceMs = DEFAULT_FORCE_CANCEL_GRACE_MS;
-    constructor(client, logger) {
+    /**
+     * The connection serves ACP v2 (`src/v2/`). The agent still speaks v1
+     * types, except for the tool call content that v2 needs and v1 cannot
+     * express: see {@link ToolCallClientCapabilities.v2}.
+     */
+    v2;
+    constructor(client, logger, options = {}) {
+        this.v2 = options.v2 ?? false;
         this.sessions = {};
         this.client = new ChangedMetaClient(client, () => this.toolCallCapabilities.air.client);
         this.logger = logger ?? console;
@@ -1208,7 +1221,9 @@ export class ClaudeAcpAgent {
     }
     async initialize(request) {
         this.clientCapabilities = request.clientCapabilities;
-        this.toolCallCapabilities = ToolCallClientCapabilities.from(request.clientCapabilities);
+        this.toolCallCapabilities = ToolCallClientCapabilities.from(request.clientCapabilities, {
+            v2: this.v2,
+        });
         // Learn the auth identity in the background: `initialize` never waits on
         // the CLI probe, and no snapshot rides in its response. When the probe
         // lands it calls `setAuthStatus`, which pushes `_auth/status_update` — the
@@ -2450,6 +2465,7 @@ export class ClaudeAcpAgent {
             // A task that a subagent tool call started belongs to the child
             // session of that tool call, like the tool call itself.
             routeOf: (toolCallId) => session.nativeSubagentRuntime?.routeOfToolCall(toolCallId, session.eagerToolCallSessions?.get(toolCallId)),
+            toolNameOf: (toolCallId) => session.toolUseCache[toolCallId]?.name ?? session.resolvedToolNames?.get(toolCallId),
         }));
         const compaction = new ContextCompactionLifecycle((notification) => sendUpdate(notification), {
             sessionId: params.sessionId,
@@ -2510,6 +2526,7 @@ export class ClaudeAcpAgent {
                 update.sessionUpdate === "tool_call_update" &&
                 (update.status === "completed" || update.status === "failed")) {
                 session.eagerToolCallSessions?.delete(toolCallId);
+                session.dispatchedToolCalls?.delete(toolCallId);
             }
         };
         // toAcpNotifications registers deferred tool hooks that publish through
@@ -2951,38 +2968,48 @@ export class ClaudeAcpAgent {
                 // Check only this turn's tools. A tool_result removes its id from
                 // emittedToolCalls even when its PostToolUse hook has not arrived yet.
                 const unfinished = [...(turn.foregroundToolCallIds ?? [])].filter((id) => session.emittedToolCalls.has(id) && !backgroundTools.has(id));
-                if (unfinished.length > 0) {
-                    const message = `Claude ended the turn without returning results for tool calls: ${unfinished.join(", ")}`;
+                /** Closes a tool call as failed. Returns false when the turn ended meanwhile. */
+                const failToolCall = async (toolCallId, text) => {
+                    // A late hook must not overwrite the failure we are about to send.
+                    unregisterHookCallback(toolCallId);
+                    session.emittedToolCalls.delete(toolCallId);
+                    delete session.toolUseCache[toolCallId];
+                    session.toolCallFields?.delete(toolCallId);
+                    session.dispatchedToolCalls?.delete(toolCallId);
+                    await sendUpdate({
+                        sessionId: params.sessionId,
+                        update: {
+                            sessionUpdate: "tool_call_update",
+                            toolCallId,
+                            status: "failed",
+                            content: [{ type: "content", content: { type: "text", text } }],
+                        },
+                    });
+                    // Cancellation can arrive while we await the client update.
+                    if (turn.settled || session.activeTurn !== turn)
+                        return false;
+                    if (session.cancelled) {
+                        await settleActive({ ...result, stopReason: "cancelled" });
+                        return false;
+                    }
+                    return true;
+                };
+                // A streamed tool_use that never reached a complete assistant message
+                // never ran: Claude abandoned it, for example for a steering message.
+                // It is not a failure of the turn.
+                const abandoned = unfinished.filter((id) => !session.dispatchedToolCalls?.has(id));
+                const stuck = unfinished.filter((id) => session.dispatchedToolCalls?.has(id));
+                for (const toolCallId of abandoned) {
+                    if (!(await failToolCall(toolCallId, "Claude stopped this tool call before it ran."))) {
+                        return;
+                    }
+                }
+                if (stuck.length > 0) {
+                    const message = `Claude ended the turn without returning results for tool calls: ${stuck.join(", ")}`;
                     this.logger.error(`Session ${params.sessionId}, turn ${turn.promptUuid}, stopReason=${result.stopReason}: ${message}`);
                     // Fail every unfinished tool before reporting one error for the prompt.
-                    for (const toolCallId of unfinished) {
-                        // A late hook must not overwrite the failure we are about to send.
-                        unregisterHookCallback(toolCallId);
-                        session.emittedToolCalls.delete(toolCallId);
-                        delete session.toolUseCache[toolCallId];
-                        session.toolCallFields?.delete(toolCallId);
-                        await sendUpdate({
-                            sessionId: params.sessionId,
-                            update: {
-                                sessionUpdate: "tool_call_update",
-                                toolCallId,
-                                status: "failed",
-                                content: [
-                                    {
-                                        type: "content",
-                                        content: {
-                                            type: "text",
-                                            text: "Claude ended the turn without returning a result for this tool.",
-                                        },
-                                    },
-                                ],
-                            },
-                        });
-                        // Cancellation can arrive while we await the client update.
-                        if (turn.settled || session.activeTurn !== turn)
-                            return;
-                        if (session.cancelled) {
-                            await settleActive({ ...result, stopReason: "cancelled" });
+                    for (const toolCallId of stuck) {
+                        if (!(await failToolCall(toolCallId, "Claude ended the turn without returning a result for this tool."))) {
                             return;
                         }
                     }
@@ -3130,11 +3157,18 @@ export class ClaudeAcpAgent {
                     .then((result) => ({ kind: "message", result }));
                 const nextMessage = pendingNext;
                 // Fresh abort listener per iteration, removed when next() wins, so a
-                // long-lived session doesn't accumulate listeners on one signal.
+                // long-lived session doesn't accumulate listeners on one signal. An
+                // abort that fired while the consumer was busy elsewhere, such as
+                // sending an update, still wakes it: a listener added to an aborted
+                // signal never fires. The consumer re-arms after each abort it
+                // handles, so an aborted signal here is always an unhandled abort.
                 let onAbort;
                 const abortRace = new Promise((resolve) => {
                     onAbort = () => resolve("abort");
-                    cancelController.signal.addEventListener("abort", onAbort, { once: true });
+                    if (cancelController.signal.aborted)
+                        onAbort();
+                    else
+                        cancelController.signal.addEventListener("abort", onAbort, { once: true });
                 });
                 const raced = await Promise.race([nextMessage, abortRace]);
                 cancelController.signal.removeEventListener("abort", onAbort);
@@ -4723,6 +4757,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,
@@ -4747,6 +4782,8 @@ export class ClaudeAcpAgent {
                     }
                     case "user":
                     case "assistant": {
+                        if (message.type === "assistant")
+                            recordDispatchedToolUses(session, message.message.content);
                         // Record the ACP messageId -> SDK uuid mapping for this message
                         // (including replays). The consolidated message carries both ids, so
                         // this is where we learn the uuid the SDK's rewind/resume APIs key on
@@ -4926,6 +4963,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,
@@ -4992,11 +5030,14 @@ export class ClaudeAcpAgent {
                             content = message.message.content;
                         }
                         const acceptedPlanToolUseId = observeExitPlanToolResults(message, content, session);
-                        let backgroundBashTask;
+                        let backgroundedToolCalls = new Set();
                         if (message.type === "user") {
-                            backgroundBashTask = backgroundBashTaskFromToolResult(content, message.tool_use_result, session.toolUseCache);
+                            rememberResolvedToolNames(session, content);
+                            const backgroundBashTask = backgroundBashTaskFromToolResult(content, message.tool_use_result, session.toolUseCache);
                             if (backgroundBashTask)
                                 await asyncTasks.taskBackgrounded(backgroundBashTask);
+                            await asyncTasks.toolResults(content);
+                            backgroundedToolCalls = backgroundedBashToolCallIds(content, session.toolUseCache, asyncTasks, backgroundBashTask);
                             const resumedAgentId = resumedNativeSubagentId(message.tool_use_result);
                             if (resumedAgentId) {
                                 resumeLiveTask(resumedAgentId);
@@ -5007,6 +5048,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,
@@ -5024,7 +5066,7 @@ export class ClaudeAcpAgent {
                             // filtered out of `content` above; blocks that do pass through
                             // (e.g. a subagent image) carry the stamped parentToolUseId
                             // meta and are excluded there.
-                            await sendUpdate(backgroundedBashToolCall(acceptedPlanToolResult(notification, acceptedPlanToolUseId), backgroundBashTask, asyncTasks.enabled));
+                            await sendUpdate(backgroundedBashToolCall(acceptedPlanToolResult(notification, acceptedPlanToolUseId), backgroundedToolCalls, asyncTasks.enabled));
                         }
                         break;
                     }
@@ -5094,6 +5136,7 @@ export class ClaudeAcpAgent {
                         await finishLifecycle("failed", "failed", "during conversation reset");
                         subagents.clear();
                         asyncTasks.clear();
+                        session.resolvedToolNames?.clear();
                         session.eagerToolCallSessions?.clear();
                         session.toolCallFields?.clear();
                         clearHookCallbacks(params.sessionId);
@@ -5554,12 +5597,18 @@ export class ClaudeAcpAgent {
         session.query.close();
     }
     /** Cleanly tear down a session: cancel in-flight work, release stream
-     *  resources, and remove it from the session map. */
+     *  resources, and remove it from the session map. Returns once the turns it
+     *  cancels have ended, so their end (a v1 `session/prompt` response, a v2
+     *  `idle` state) goes out before the caller answers: ACP v2's
+     *  `session/close` cancels "as if `session/cancel` had been called", then
+     *  frees the session. A wedged consumer holds it at most
+     *  {@link TEARDOWN_TURN_END_TIMEOUT_MS}. */
     async teardownSession(sessionId) {
         const session = this.sessions[sessionId];
         if (!session) {
             return;
         }
+        const turnsEnded = Promise.all((session.turnQueue ?? []).flatMap((turn) => (turn.completion ? [turn.completion] : [])));
         try {
             await this.cancelTurns({ sessionId }, { awaitInterrupt: false });
         }
@@ -5587,6 +5636,10 @@ export class ClaudeAcpAgent {
         session.nativeSubagentRuntime?.clear();
         session.asyncTaskRuntime?.clear();
         delete this.sessions[sessionId];
+        const ended = await raceTimeoutAndAbort(turnsEnded, TEARDOWN_TURN_END_TIMEOUT_MS, new AbortController().signal);
+        if (ended.type === "timeout") {
+            this.logger.error(`Session ${sessionId}: its cancelled turns did not end within ${TEARDOWN_TURN_END_TIMEOUT_MS}ms of the teardown`);
+        }
     }
     /** Tear down all active sessions. Called when the ACP connection closes. */
     async dispose() {
@@ -5843,6 +5896,7 @@ export class ClaudeAcpAgent {
                     ? (notification) => ({ ...notification, sessionId: target })
                     : undefined;
             },
+            toolNameOf: (toolCallId) => replayToolUses.get(toolCallId)?.name,
         });
         // The replay counterpart of the live `task_notification` frame.
         const restoreTaskNotification = async (notification) => {
@@ -5926,6 +5980,8 @@ export class ClaudeAcpAgent {
             }
             // @ts-expect-error - untyped in SDK but we handle all of these
             if (message.message.role === "user") {
+                // Like live, a tool result gives the output path of a known task.
+                await replayAsyncTasks.toolResults(content);
                 for (const notification of taskNotificationsOf(content)) {
                     await restoreTaskNotification(notification);
                 }
@@ -5981,6 +6037,7 @@ export class ClaudeAcpAgent {
                 registerHooks: false,
                 replay: true,
                 clientCapabilities: this.clientCapabilities,
+                toolCallCapabilities: this.toolCallCapabilities,
                 cwd: replayState()?.cwd,
                 taskState: replayState()?.taskState,
                 messageId: replayMessageId,
@@ -6120,8 +6177,10 @@ export class ClaudeAcpAgent {
         // Do not rely on every ACP client settling requestPermission after the
         // cancellation signal. The local race guarantees that Claude's tool call
         // is released even when an older or broken client ignores $/cancel_request.
+        // The request goes to a subagent's child session for a tool call of that
+        // subagent, but it blocks the turn of the owner session.
         try {
-            return await this.withPendingUserInput(params.sessionId, () => raceWithAbort(this.client.requestPermission(params, signal), signal));
+            return await this.withPendingUserInput(ownerSessionId, () => raceWithAbort(this.client.requestPermission(params, signal), signal));
         }
         catch (error) {
             if (signal.aborted) {
@@ -6154,6 +6213,8 @@ export class ClaudeAcpAgent {
                 toolCallFieldsOf(session).pinContent(toolCallId, previewContent);
             }
         };
+        // A permission request comes only for a tool call that is about to run.
+        recordDispatchedToolCall(session, toolCallId);
         if (session.emittedToolCalls.has(toolCallId)) {
             pinPreview();
             return;
@@ -6231,7 +6292,7 @@ export class ClaudeAcpAgent {
                 // Like permission requests, the elicitation references this toolUseID, so
                 // make sure the tool_call has surfaced to the client before we send it.
                 await this.ensureToolCallEmitted(sessionId, toolName, toolUseID, toolInput, parentToolUseId, signal, permissionSessionId);
-                return this.handleAskUserQuestion(permissionSessionId, toolInput, toolUseID, signal);
+                return this.handleAskUserQuestion(sessionId, permissionSessionId, toolInput, toolUseID, signal);
             }
             // Do not auto-allow here based on the session's advertised mode. Claude
             // Code applies bypassPermissions before invoking canUseTool; a request
@@ -6247,8 +6308,8 @@ export class ClaudeAcpAgent {
             const noPersistentRule = matchedAskRule !== undefined || suppressAlwaysAllowRule === true;
             const durableChangeSet = normalizeDurablePermissionChangeSet(suggestions, noPersistentRule);
             const capabilities = this.toolCallCapabilities;
-            const previewContent = capabilities.diffPatch
-                ? await previewPatchContent(toolName, toolInput, session.cwd)
+            const previewContent = capabilities.diffPatch || capabilities.v2
+                ? await previewPatchContent(toolName, toolInput, session.cwd, capabilities.v2 ? "v2" : "air")
                 : undefined;
             const presentation = buildClaudePermissionPresentation({
                 toolName,
@@ -6385,13 +6446,15 @@ export class ClaudeAcpAgent {
      * Present the built-in AskUserQuestion tool's questions as an ACP form
      * elicitation and return the answers as the tool's `updatedInput`. Called from
      * `canUseTool` since that is where the SDK routes the tool's permission check.
+     * The elicitation goes to `requestSessionId`, a subagent's child session for
+     * a question it asks, and blocks the turn of `sessionId`.
      */
-    async handleAskUserQuestion(sessionId, toolInput, toolUseID, signal) {
+    async handleAskUserQuestion(sessionId, requestSessionId, toolInput, toolUseID, signal) {
         const questions = extractAskUserQuestions(toolInput);
         if (!questions) {
             return { behavior: "deny", message: "AskUserQuestion called with no valid questions." };
         }
-        const createRequest = askUserQuestionsToCreateRequest(questions, sessionId, toolUseID, this.toolCallCapabilities.air.client);
+        const createRequest = askUserQuestionsToCreateRequest(questions, requestSessionId, toolUseID, this.toolCallCapabilities.air.client);
         let response;
         try {
             response = await this.withPendingUserInput(sessionId, () => this.client.createElicitation(createRequest, signal));
@@ -6479,15 +6542,21 @@ export class ClaudeAcpAgent {
         });
     }
     /**
-     * Replace a heuristic context window with `getContextUsage().rawMaxTokens`
+     * Refine a heuristic context window with `getContextUsage().rawMaxTokens`,
      * without blocking the caller. The text heuristic misses natively-1M models
-     * whose picker rows carry no "1m" token (`sonnet`, and since CLI 2.1.283
-     * `opus`/`default`), which would otherwise report 200k until the first
-     * result's modelUsage. Never awaited: SDK control requests are serialized,
-     * so an awaited call would delay session/new or a model switch (before the
-     * first turn it took ~15s on older CLIs, issues #886/#880; ~0.5s on 2.1.283).
-     * Not written to `contextWindowCache` — that stays keyed to the
-     * `result.modelUsage` spellings — and a result still overwrites it.
+     * whose picker rows carry no "1m" token (e.g. `sonnet`, and since CLI
+     * 2.1.283 `opus`/`default`), so those would otherwise show 200k until the
+     * first result's modelUsage arrives.
+     *
+     * Never awaited: SDK control requests are serialized, so awaiting here
+     * would delay session/new or a model switch (~15s on older CLIs, issues
+     * #886/#880; ~0.5s on 2.1.283). Requests the `summary` detail instead of
+     * the default `full` breakdown, which issues one `messages/count_tokens`
+     * call per category (~18 for a bare session) and hit rate limits on every
+     * model switch; `summary` answers locally with the same `rawMaxTokens`.
+     *
+     * Does not write `contextWindowCache` (that stays keyed to the
+     * `result.modelUsage` spellings) — a later result still overwrites this.
      */
     refreshContextWindowInBackground(sessionId, session) {
         if (session.contextWindowAuthoritative)
@@ -6499,7 +6568,7 @@ export class ClaudeAcpAgent {
             session.models.currentModelId === modelId;
         // A synchronous throw must not fail the caller either.
         Promise.resolve()
-            .then(() => query.getContextUsage())
+            .then(() => query.getContextUsage({ detail: "summary" }))
             .then((usage) => {
             if (!stillCurrent() || session.contextWindowAuthoritative)
                 return;
@@ -6569,7 +6638,7 @@ export class ClaudeAcpAgent {
             const seedEffort = effortPinnedForNewModel
                 ? pinnedEffort
                 : settingsEffortForModel(mergeEffortSettings(session.settingsManager.getSettings(), session.effortSettingsOverride), newModelInfo, value);
-            session.configOptions = buildConfigOptions(session.modes, session.models, session.modelInfos, seedEffort, {
+            session.configOptions = buildConfigOptions(session.modes, session.models, session.modelInfos, seedEffort, session.agents, session.currentAgent, {
                 // The toggle follows the newly selected model: it disappears when the
                 // model lacks fast support and reappears (with the retained user
                 // intent) when a supporting model is selected again.
@@ -6648,6 +6717,18 @@ export class ClaudeAcpAgent {
             if (modelChanged)
                 this.refreshContextWindowInBackground(sessionId, session);
         }
+        else if (configId === AGENT_CONFIG_ID) {
+            // Live agent switch — no subprocess restart needed. Apply the SDK flag
+            // first so a rejected control request leaves both `currentAgent` and the
+            // config option untouched (no UI/SDK desync). Passing `null` clears the
+            // flag layer back to the standard Claude Code agent; the change takes
+            // effect on the next turn (SDK >= 0.3.161).
+            await session.query.applyFlagSettings({
+                agent: value === DEFAULT_AGENT_ID ? null : value,
+            });
+            session.currentAgent = value;
+            session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
+        }
         else if (configId === EFFORT_CONFIG_ID) {
             // Apply first so a rejected control request cannot leave the displayed
             // value ahead of the SDK flag layer.
@@ -6954,14 +7035,7 @@ export class ClaudeAcpAgent {
             resumed: resumedPermissionMode,
             defaultMode: settingsManager.getSettings().permissions?.defaultMode,
         }, this.logger, allowBypass);
-        const userProvidedOptions = sessionMeta?.claudeCode?.options
-            ? { ...sessionMeta.claudeCode.options }
-            : undefined;
-        // Main-thread agent selection is intentionally not part of this adapter's
-        // ACP contract. Ignore the provider-specific option instead of forwarding
-        // hidden state that the Client cannot inspect or change.
-        if (userProvidedOptions)
-            delete userProvidedOptions.agent;
+        const userProvidedOptions = sessionMeta?.claudeCode?.options;
         const forwardSubagentText = this.forwardsSubagentText(params._meta);
         // Configure thinking behavior from environment variable
         const thinking = resolveThinkingConfig(process.env.MAX_THINKING_TOKENS, this.logger);
@@ -7326,6 +7400,17 @@ export class ClaudeAcpAgent {
                 allowBypass,
             });
             timing.phase("modes");
+            const agents = await discoverCustomAgents(q);
+            timing.phase("agents");
+            // Only adopt the requested agent as the selected value if it's one we
+            // actually surface in the picker. A built-in (filtered out above) or
+            // otherwise-unknown name would leave the config option's `currentValue`
+            // pointing at an entry not in its own `options` list, which clients render
+            // as a blank/invalid selection.
+            const requestedAgent = userProvidedOptions?.agent;
+            const currentAgent = requestedAgent && agents.some((a) => a.name === requestedAgent)
+                ? requestedAgent
+                : DEFAULT_AGENT_ID;
             // Seed Fast mode from the SDK's reported state so the UI reflects reality
             // (the CLI may start a session with fast mode already on, or force it off
             // when `fastModePerSessionOptIn` is set). The toggle is only surfaced while
@@ -7351,7 +7436,7 @@ export class ClaudeAcpAgent {
             // Legacy clients still leave effort resolution entirely to the CLI.
             const useRecommendedValue = clientSupportsRecommendedConfigValue(this.clientCapabilities);
             const effortSettings = mergeEffortSettings(settingsManager.getSettings(), configuredSettingsObject);
-            const configOptions = buildConfigOptions(modes, models, modelInfos, userProvidedOptions?.effort ?? settingsEffortForModel(effortSettings, currentModelInfo), fastMode, {
+            const configOptions = buildConfigOptions(modes, models, modelInfos, userProvidedOptions?.effort ?? settingsEffortForModel(effortSettings, currentModelInfo), agents, currentAgent, fastMode, {
                 useRecommendedValue,
             });
             const initialEffort = configOptions.find((option) => option.id === EFFORT_CONFIG_ID);
@@ -7412,6 +7497,8 @@ export class ClaudeAcpAgent {
                         initialEffort?.currentValue === userProvidedOptions.effort
                         ? userProvidedOptions.effort
                         : undefined,
+                agents,
+                currentAgent,
                 fastModeEnabled,
                 fastModeDisabledReason,
                 abortController,
@@ -7844,11 +7931,43 @@ function isValidBaseUrl(baseUrl) {
     }
     return parsed.protocol === "http:" || parsed.protocol === "https:";
 }
+// `supportedAgents()` always returns Claude Code's built-in subagents — the
+// ones used for Task-tool delegation (Explore, Plan, etc.) — even when the user
+// has configured none of their own. Those aren't meaningful *main-thread*
+// personas, so we filter them out and only surface the Agent picker when the
+// user (or a plugin/project) has configured custom agents. Update this set if
+// the SDK's built-in roster changes.
+export const BUILTIN_AGENT_NAMES = new Set([
+    "claude",
+    "general-purpose",
+    "Explore",
+    "Plan",
+    "statusline-setup",
+]);
+// Value of the synthetic "Default" entry in the agent picker, which maps to the
+// standard Claude Code agent (`applyFlagSettings({ agent: null })`). It is a
+// reserved sentinel: a custom agent named exactly this would collide with it
+// (two options sharing the value, selection silently routing to `null`), so we
+// exclude that name from discovery.
+/** Discover user/plugin/project-configured main-thread agents, excluding the
+ *  built-in subagents and the reserved "default" sentinel. Returns an empty
+ *  list if discovery fails so a flaky control request never blocks session
+ *  creation. */
+export async function discoverCustomAgents(q) {
+    try {
+        const agents = await q.supportedAgents();
+        return agents.filter((a) => !BUILTIN_AGENT_NAMES.has(a.name) && a.name !== DEFAULT_AGENT_ID);
+    }
+    catch {
+        return [];
+    }
+}
 /** Stable ids for the session config options surfaced via `configOptions`.
  *  Centralized so the option declarations in `buildConfigOptions` and the
  *  handlers in `setSessionConfigOption`/`applyConfigOptionValue` reference the
  *  same identifiers and can't drift apart. */
 export { MODE_CONFIG_ID };
+export const AGENT_CONFIG_ID = "agent";
 export const FAST_MODE_CONFIG_ID = "fast";
 /** Select-fallback values used when the client has not opted into boolean
  *  config options (see {@link createFastModeConfigOption}). */
@@ -7950,7 +8069,7 @@ export function resolveFastModeEnabled(params) {
     }
     throw new Error(`Invalid value for config option ${FAST_MODE_CONFIG_ID}: ${value}`);
 }
-export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel, fastMode, presentation) {
+export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel, agents = [], currentAgent = DEFAULT_AGENT_ID, fastMode, presentation) {
     const options = [
         SessionModeManager.configOption(modes),
         buildModelConfigOption(models, modelInfos, presentation?.useRecommendedValue === true),
@@ -7964,6 +8083,27 @@ export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel
     if (fastMode?.supported) {
         options.push(createFastModeConfigOption(fastMode.enabled, fastMode.useBooleanOption, fastMode.disabledReason));
     }
+    // Only surface the Agent picker when there's a real choice — i.e. the user
+    // has configured at least one custom agent (built-ins are filtered out in
+    // discoverCustomAgents). With none configured, "Default" would be the only
+    // entry, so we omit the option entirely.
+    if (agents.length > 0) {
+        options.push({
+            id: AGENT_CONFIG_ID,
+            name: "Agent",
+            description: "Main-thread agent persona",
+            type: "select",
+            currentValue: currentAgent,
+            options: [
+                { value: DEFAULT_AGENT_ID, name: "Default", description: "Standard Claude Code agent" },
+                ...agents.map((a) => ({
+                    value: a.name,
+                    name: a.name,
+                    description: a.description || undefined,
+                })),
+            ],
+        });
+    }
     return options;
 }
 function getAvailableSlashCommands(commands, 
@@ -8182,6 +8322,31 @@ function isTaskTool(toolName) {
 function shouldEmitToolCall(toolName) {
     return toolName !== "TodoWrite" && !isTaskTool(toolName);
 }
+const MAX_DISPATCHED_TOOL_CALLS = 1000;
+/** Records a tool call that Claude Code sent to the tool runner. */
+function recordDispatchedToolCall(session, toolCallId) {
+    const calls = (session.dispatchedToolCalls ??= new Set());
+    calls.delete(toolCallId);
+    calls.add(toolCallId);
+    if (calls.size > MAX_DISPATCHED_TOOL_CALLS) {
+        const oldest = calls.values().next().value;
+        if (oldest !== undefined)
+            calls.delete(oldest);
+    }
+}
+/** Records the tool_use blocks of a complete assistant message. */
+function recordDispatchedToolUses(session, content) {
+    if (!Array.isArray(content))
+        return;
+    for (const block of content) {
+        if ((block?.type === "tool_use" ||
+            block?.type === "server_tool_use" ||
+            block?.type === "mcp_tool_use") &&
+            typeof block.id === "string") {
+            recordDispatchedToolCall(session, block.id);
+        }
+    }
+}
 /** Streamed and permission-surfaced tools can precede the SDK's user echo. */
 function recordForegroundToolCall(session, toolCallId) {
     const turn = session.activeTurn ?? session.turnQueue?.find((queued) => !queued.settled);
@@ -8201,10 +8366,40 @@ 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);
+}
+const MAX_RESOLVED_TOOL_NAMES = 1000;
+/** Keeps the tool names of the tool results in `content` before the tool use cache drops them. */
+function rememberResolvedToolNames(session, content) {
+    if (!Array.isArray(content))
+        return;
+    for (const block of content) {
+        if (block?.type !== "tool_result" || typeof block.tool_use_id !== "string")
+            continue;
+        const name = session.toolUseCache[block.tool_use_id]?.name;
+        if (!name)
+            continue;
+        const names = (session.resolvedToolNames ??= new Map());
+        names.delete(block.tool_use_id);
+        names.set(block.tool_use_id, name);
+        if (names.size > MAX_RESOLVED_TOOL_NAMES) {
+            const oldest = names.keys().next().value;
+            if (oldest !== undefined)
+                names.delete(oldest);
+        }
+    }
+}
 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 [];
@@ -8542,6 +8737,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,
@@ -8605,7 +8801,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);