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

package/dist/acp-agent.js

@@ -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
@@ -3130,11 +3145,18 @@ export class ClaudeAcpAgent {
                     .then((result) => ({ kind: "message", result }));
                 const nextMessage = pendingNext;
                 // Fresh abort listener per iteration, removed when next() wins, so a
-                // long-lived session doesn't accumulate listeners on one signal.
+                // long-lived session doesn't accumulate listeners on one signal. An
+                // abort that fired while the consumer was busy elsewhere, such as
+                // sending an update, still wakes it: a listener added to an aborted
+                // signal never fires. The consumer re-arms after each abort it
+                // handles, so an aborted signal here is always an unhandled abort.
                 let onAbort;
                 const abortRace = new Promise((resolve) => {
                     onAbort = () => resolve("abort");
-                    cancelController.signal.addEventListener("abort", onAbort, { once: true });
+                    if (cancelController.signal.aborted)
+                        onAbort();
+                    else
+                        cancelController.signal.addEventListener("abort", onAbort, { once: true });
                 });
                 const raced = await Promise.race([nextMessage, abortRace]);
                 cancelController.signal.removeEventListener("abort", onAbort);
@@ -4723,6 +4745,7 @@ export class ClaudeAcpAgent {
                         }
                         for (const notification of streamEventToAcpNotifications(message, params.sessionId, session.toolUseCache, this.client, this.logger, {
                             clientCapabilities: this.clientCapabilities,
+                            toolCallCapabilities: this.toolCallCapabilities,
                             cwd: session.cwd,
                             taskState: session.taskState,
                             emittedToolCalls: session.emittedToolCalls,
@@ -4926,6 +4949,7 @@ export class ClaudeAcpAgent {
                             if (typeof stripped === "string") {
                                 for (const notification of toAcpNotifications(stripped, message.message.role, params.sessionId, session.toolUseCache, routedNotificationClient, this.logger, {
                                     clientCapabilities: this.clientCapabilities,
+                                    toolCallCapabilities: this.toolCallCapabilities,
                                     parentToolUseId: message.parent_tool_use_id,
                                     cwd: session.cwd,
                                     taskState: session.taskState,
@@ -5007,6 +5031,7 @@ export class ClaudeAcpAgent {
                         }
                         for (const notification of toAcpNotifications(content, message.message.role, params.sessionId, session.toolUseCache, routedNotificationClient, this.logger, {
                             clientCapabilities: this.clientCapabilities,
+                            toolCallCapabilities: this.toolCallCapabilities,
                             parentToolUseId: message.parent_tool_use_id,
                             cwd: session.cwd,
                             taskState: session.taskState,
@@ -5554,12 +5579,18 @@ export class ClaudeAcpAgent {
         session.query.close();
     }
     /** Cleanly tear down a session: cancel in-flight work, release stream
-     *  resources, and remove it from the session map. */
+     *  resources, and remove it from the session map. Returns once the turns it
+     *  cancels have ended, so their end (a v1 `session/prompt` response, a v2
+     *  `idle` state) goes out before the caller answers: ACP v2's
+     *  `session/close` cancels "as if `session/cancel` had been called", then
+     *  frees the session. A wedged consumer holds it at most
+     *  {@link TEARDOWN_TURN_END_TIMEOUT_MS}. */
     async teardownSession(sessionId) {
         const session = this.sessions[sessionId];
         if (!session) {
             return;
         }
+        const turnsEnded = Promise.all((session.turnQueue ?? []).flatMap((turn) => (turn.completion ? [turn.completion] : [])));
         try {
             await this.cancelTurns({ sessionId }, { awaitInterrupt: false });
         }
@@ -5587,6 +5618,10 @@ export class ClaudeAcpAgent {
         session.nativeSubagentRuntime?.clear();
         session.asyncTaskRuntime?.clear();
         delete this.sessions[sessionId];
+        const ended = await raceTimeoutAndAbort(turnsEnded, TEARDOWN_TURN_END_TIMEOUT_MS, new AbortController().signal);
+        if (ended.type === "timeout") {
+            this.logger.error(`Session ${sessionId}: its cancelled turns did not end within ${TEARDOWN_TURN_END_TIMEOUT_MS}ms of the teardown`);
+        }
     }
     /** Tear down all active sessions. Called when the ACP connection closes. */
     async dispose() {
@@ -5981,6 +6016,7 @@ export class ClaudeAcpAgent {
                 registerHooks: false,
                 replay: true,
                 clientCapabilities: this.clientCapabilities,
+                toolCallCapabilities: this.toolCallCapabilities,
                 cwd: replayState()?.cwd,
                 taskState: replayState()?.taskState,
                 messageId: replayMessageId,
@@ -6120,8 +6156,10 @@ export class ClaudeAcpAgent {
         // Do not rely on every ACP client settling requestPermission after the
         // cancellation signal. The local race guarantees that Claude's tool call
         // is released even when an older or broken client ignores $/cancel_request.
+        // The request goes to a subagent's child session for a tool call of that
+        // subagent, but it blocks the turn of the owner session.
         try {
-            return await this.withPendingUserInput(params.sessionId, () => raceWithAbort(this.client.requestPermission(params, signal), signal));
+            return await this.withPendingUserInput(ownerSessionId, () => raceWithAbort(this.client.requestPermission(params, signal), signal));
         }
         catch (error) {
             if (signal.aborted) {
@@ -6231,7 +6269,7 @@ export class ClaudeAcpAgent {
                 // Like permission requests, the elicitation references this toolUseID, so
                 // make sure the tool_call has surfaced to the client before we send it.
                 await this.ensureToolCallEmitted(sessionId, toolName, toolUseID, toolInput, parentToolUseId, signal, permissionSessionId);
-                return this.handleAskUserQuestion(permissionSessionId, toolInput, toolUseID, signal);
+                return this.handleAskUserQuestion(sessionId, permissionSessionId, toolInput, toolUseID, signal);
             }
             // Do not auto-allow here based on the session's advertised mode. Claude
             // Code applies bypassPermissions before invoking canUseTool; a request
@@ -6247,8 +6285,8 @@ export class ClaudeAcpAgent {
             const noPersistentRule = matchedAskRule !== undefined || suppressAlwaysAllowRule === true;
             const durableChangeSet = normalizeDurablePermissionChangeSet(suggestions, noPersistentRule);
             const capabilities = this.toolCallCapabilities;
-            const previewContent = capabilities.diffPatch
-                ? await previewPatchContent(toolName, toolInput, session.cwd)
+            const previewContent = capabilities.diffPatch || capabilities.v2
+                ? await previewPatchContent(toolName, toolInput, session.cwd, capabilities.v2 ? "v2" : "air")
                 : undefined;
             const presentation = buildClaudePermissionPresentation({
                 toolName,
@@ -6385,13 +6423,15 @@ export class ClaudeAcpAgent {
      * Present the built-in AskUserQuestion tool's questions as an ACP form
      * elicitation and return the answers as the tool's `updatedInput`. Called from
      * `canUseTool` since that is where the SDK routes the tool's permission check.
+     * The elicitation goes to `requestSessionId`, a subagent's child session for
+     * a question it asks, and blocks the turn of `sessionId`.
      */
-    async handleAskUserQuestion(sessionId, toolInput, toolUseID, signal) {
+    async handleAskUserQuestion(sessionId, requestSessionId, toolInput, toolUseID, signal) {
         const questions = extractAskUserQuestions(toolInput);
         if (!questions) {
             return { behavior: "deny", message: "AskUserQuestion called with no valid questions." };
         }
-        const createRequest = askUserQuestionsToCreateRequest(questions, sessionId, toolUseID, this.toolCallCapabilities.air.client);
+        const createRequest = askUserQuestionsToCreateRequest(questions, requestSessionId, toolUseID, this.toolCallCapabilities.air.client);
         let response;
         try {
             response = await this.withPendingUserInput(sessionId, () => this.client.createElicitation(createRequest, signal));
@@ -6479,15 +6519,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 +6545,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 +6615,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 +6694,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 +7012,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 +7377,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 +7413,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 +7474,8 @@ export class ClaudeAcpAgent {
                         initialEffort?.currentValue === userProvidedOptions.effort
                         ? userProvidedOptions.effort
                         : undefined,
+                agents,
+                currentAgent,
                 fastModeEnabled,
                 fastModeDisabledReason,
                 abortController,
@@ -7844,11 +7908,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 +8046,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 +8060,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, 
@@ -8201,10 +8318,19 @@ function toolCallFieldsOf(session) {
  * Convert an SDKAssistantMessage (Claude) to a SessionNotification (ACP).
  * Only handles text, image, and thinking chunks for now.
  */
+/**
+ * The renderer of the notification functions: the agent's tool call
+ * capabilities when they are passed, else those of the ACP capabilities.
+ */
+function toolCallRenderer(options) {
+    return options?.toolCallCapabilities
+        ? new AcpToolCallRenderer(options.toolCallCapabilities, options.replay)
+        : AcpToolCallRenderer.for(options?.clientCapabilities, options?.replay);
+}
 export function toAcpNotifications(content, role, sessionId, toolUseCache, client, logger, options) {
     const taskState = options?.taskState ?? new Map();
     const registerHooks = options?.registerHooks !== false;
-    const renderer = AcpToolCallRenderer.for(options?.clientCapabilities, options?.replay);
+    const renderer = toolCallRenderer(options);
     if (typeof content === "string") {
         if (content.length === 0) {
             return [];
@@ -8542,6 +8668,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 +8732,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);

package/dist/clear-context-coordinator.d.ts

@@ -29,6 +29,7 @@ export type ClearContextSession<Turn extends ClearContextTurn = ClearContextTurn
         currentModelId: string;
     };
     configOptions: SessionConfigOption[];
+    currentAgent: string;
     fastModeEnabled: boolean;
     effortPinnedLevel?: string;
     activeTurn?: Turn | null;

package/dist/clear-context-coordinator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clear-context-coordinator.d.ts","sourceRoot":"","sources":["../src/clear-context-coordinator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"clear-context-coordinator.d.ts","sourceRoot":"","sources":["../src/clear-context-coordinator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,KAAK,EAGV,cAAc,EACd,cAAc,EACf,MAAM,gCAAgC,CAAC;AAGxC,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;CACtB,CAAC;AAEF,KAAK,KAAK,GAAG;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,KAAK,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;CAC3C,CAAC;AAEF;;+EAE+E;AAC/E,MAAM,MAAM,mBAAmB,CAAC,IAAI,SAAS,gBAAgB,GAAG,gBAAgB,IAAI;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,CAAC,EAAE,iBAAiB,CAAC;IACnC,gBAAgB,EAAE,KAAK,CAAC;IACxB,qBAAqB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC9C,MAAM,EAAE;QAAE,cAAc,EAAE,MAAM,CAAA;KAAE,CAAC;IACnC,aAAa,EAAE,mBAAmB,EAAE,CAAC;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACzB,SAAS,CAAC,EAAE,IAAI,EAAE,CAAC;IACnB,2BAA2B,CAAC,EAAE,iBAAiB,CAAC;IAChD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE;QAAE,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAA;KAAE,CAAC;CACnD,CAAC;AAEF,MAAM,MAAM,2BAA2B,CACrC,OAAO,SAAS,mBAAmB,CAAC,IAAI,CAAC,EACzC,IAAI,SAAS,gBAAgB,IAC3B;IACF,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IACvD,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACzC,cAAc,CACZ,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE;QAAE,eAAe,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,cAAc,CAAA;KAAE,GACnE,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,mBAAmB,CACjB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,cAAc,EACpB,aAAa,EAAE,mBAAmB,EAAE,GACnC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,CAAC;IACzF,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACjD,CAAC;AAiCF;;kEAEkE;AAClE,wBAAsB,0BAA0B,CAC9C,IAAI,SAAS,gBAAgB,EAC7B,OAAO,SAAS,mBAAmB,CAAC,IAAI,CAAC,EAEzC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,OAAO,EACnB,KAAK,EAAE,iBAAiB,EACxB,IAAI,EAAE,2BAA2B,CAAC,OAAO,EAAE,IAAI,CAAC,EAChD,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,IAAI,CAAC,CAkDf"}

package/dist/clear-context-coordinator.js

@@ -1,4 +1,4 @@
-import { DEFAULT_MODEL_ID } from "./session-config-ids.js";
+import { DEFAULT_AGENT_ID, DEFAULT_MODEL_ID } from "./session-config-ids.js";
 function restartParams(session) {
     const originalParams = session.creationParams ?? { cwd: session.cwd, mcpServers: [] };
     const originalMeta = originalParams._meta;
@@ -18,6 +18,7 @@ function restartParams(session) {
                     ...(session.models.currentModelId !== DEFAULT_MODEL_ID
                         ? { model: session.models.currentModelId }
                         : {}),
+                    ...(session.currentAgent !== DEFAULT_AGENT_ID ? { agent: session.currentAgent } : {}),
                     ...(session.effortPinnedLevel !== undefined
                         ? { effort: session.effortPinnedLevel }
                         : {}),

package/dist/diff.d.ts

@@ -23,6 +23,17 @@ interface PatchHunk {
 }
 /** The kind of file change that a git patch describes. */
 type FileChange = "create" | "update";
+/**
+ * The diff that carries an exact patch: AIR's `diffPatch` extension of a v1
+ * diff, or an ACP v2 diff.
+ */
+export type PatchForm = "air" | "v2";
+/**
+ * How a git patch names its file. `git` is git's own form: the leading slash
+ * dropped and the `a/` and `b/` prefixes added. `absolute` is the form of an
+ * ACP v2 `git_patch`, whose paths must be absolute: the path itself.
+ */
+type GitPatchPaths = "git" | "absolute";
 /**
  * Builds the exact patch shown before Claude runs an Edit or Write tool.
  *
@@ -35,14 +46,14 @@ type FileChange = "create" | "update";
  * normalizes quotes or fails.
  *
  * A Write always gets content that shows the change: the patch, the standard
- * diff of a text that cannot have an exact patch, or a notice that the Write
- * overwrites a file that the adapter cannot show.
+ * diff (in v2, the change alone) of a text that cannot have an exact patch, or
+ * a notice that the Write overwrites a file that the adapter cannot show.
  *
  * The preview uses the tool input as it is. Claude can still remove the
  * trailing whitespace of a line before it writes. The PostToolUse hook then
  * sends the patch of the written file.
  */
-export declare function previewPatchContent(toolName: string, input: Record<string, unknown>, cwd?: string): Promise<ToolCallContent[] | undefined>;
+export declare function previewPatchContent(toolName: string, input: Record<string, unknown>, cwd?: string, form?: PatchForm): Promise<ToolCallContent[] | undefined>;
 /**
  * Builds the git patch for a finished Edit or Write from the file on disk.
  *
@@ -54,7 +65,7 @@ export declare function previewPatchContent(toolName: string, input: Record<stri
  * A written file that contains a CR or a byte order mark is declined, because
  * Claude removed those bytes from `originalFile`.
  */
-export declare function patchUpdateFromDiffToolResponse(toolResponse: unknown): Promise<{
+export declare function patchUpdateFromDiffToolResponse(toolResponse: unknown, form?: PatchForm): Promise<{
     content: ToolCallContent[];
     locations: ToolCallLocation[];
 } | undefined>;
@@ -69,13 +80,39 @@ export declare function toolUpdateFromDiffToolResponse(toolResponse: unknown): {
     content?: ToolCallContent[];
     locations?: ToolCallLocation[];
 };
+/**
+ * The ACP v2 diff of a finished Edit or Write: the exact patch of
+ * {@link patchUpdateFromDiffToolResponse} when it can be built, else the
+ * change with a patch from what the toolResponse holds.
+ *
+ * The fallback patch of an update comes from the `structuredPatch`, which is
+ * display data (see {@link patchUpdateFromDiffToolResponse}). That is enough
+ * for a v2 patch, which is renderable text, not a patch to apply. An update
+ * without hunks, such as one whose previous content was too large to diff,
+ * gets the change alone. An Edit with an empty `old_string` reports the same
+ * response for a created file and a filled empty one, so it gets no diff.
+ */
+export declare function v2UpdateFromDiffToolResponse(toolResponse: unknown): Promise<{
+    content?: ToolCallContent[];
+    locations?: ToolCallLocation[];
+}>;
 /**
  * The text of one git patch for `filePath`.
  *
- * The headers follow `git diff`: the path loses its leading slash, gets the
- * `a/` and `b/` prefixes, and is quoted when git would quote it. A created
- * file gets its mode line and a `/dev/null` side.
+ * The headers follow `git diff`: the path is quoted when git would quote it,
+ * and a created file gets its mode line and a `/dev/null` side. With `git`
+ * paths, the path loses its leading slash and gets the `a/` and `b/` prefixes.
+ */
+export declare function gitPatchText(filePath: string, change: FileChange, hunks: PatchHunk[], paths?: GitPatchPaths): string;
+/**
+ * The ACP v2 diff of a change to the text file `filePath`: the change and,
+ * given hunks, its git patch.
+ *
+ * The agent builds tool call content in v1 types, and v1 cannot express a v2
+ * diff, so the diff travels as v1 content. Nothing in the agent reads inside a
+ * diff, and only a v2 client gets one: the v2 surface sends it as it is
+ * (`src/v2/tool-call.ts`).
  */
-export declare function gitPatchText(filePath: string, change: FileChange, hunks: PatchHunk[]): string;
+export declare function v2DiffContent(filePath: string, change: FileChange, hunks?: PatchHunk[]): ToolCallContent;
 export {};
 //# sourceMappingURL=diff.d.ts.map

package/dist/diff.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAQ7E;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,QAAc,CAAC;AAkBhD;;;;;GAKG;AACH,UAAU,SAAS;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AA0BD,0DAA0D;AAC1D,KAAK,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEtC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,eAAe,EAAE,GAAG,SAAS,CAAC,CAkExC;AA0CD;;;;;;;;;;GAUG;AACH,wBAAsB,+BAA+B,CACnD,YAAY,EAAE,OAAO,GACpB,OAAO,CAAC;IAAE,OAAO,EAAE,eAAe,EAAE,CAAC;IAAC,SAAS,EAAE,gBAAgB,EAAE,CAAA;CAAE,GAAG,SAAS,CAAC,CA0CpF;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,YAAY,EAAE,OAAO,GAAG;IACrE,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;IAC5B,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAChC,CAoEA;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,CAM7F"}
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../src/diff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAS7E;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,QAAc,CAAC;AAkBhD;;;;;GAKG;AACH,UAAU,SAAS;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AA0BD,0DAA0D;AAC1D,KAAK,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAQtC;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,IAAI,CAAC;AAErC;;;;GAIG;AACH,KAAK,aAAa,GAAG,KAAK,GAAG,UAAU,CAAC;AAKxC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,GAAG,CAAC,EAAE,MAAM,EACZ,IAAI,GAAE,SAAiB,GACtB,OAAO,CAAC,eAAe,EAAE,GAAG,SAAS,CAAC,CAoExC;AA0CD;;;;;;;;;;GAUG;AACH,wBAAsB,+BAA+B,CACnD,YAAY,EAAE,OAAO,EACrB,IAAI,GAAE,SAAiB,GACtB,OAAO,CAAC;IAAE,OAAO,EAAE,eAAe,EAAE,CAAC;IAAC,SAAS,EAAE,gBAAgB,EAAE,CAAA;CAAE,GAAG,SAAS,CAAC,CA0CpF;AAED;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAAC,YAAY,EAAE,OAAO,GAAG;IACrE,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;IAC5B,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAChC,CAoEA;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,4BAA4B,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,CAAC;IACjF,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;IAC5B,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;CAChC,CAAC,CAgCD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,SAAS,EAAE,EAClB,KAAK,GAAE,aAAqB,GAC3B,MAAM,CAMR;AA2OD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,UAAU,EAClB,KAAK,CAAC,EAAE,SAAS,EAAE,GAClB,eAAe,CAajB"}