@agentclientprotocol/claude-agent-acp 0.81.2 → 0.81.3-preview.2

package/dist/acp-agent.js

@@ -1,23 +1,22 @@
 import { agent as acpAgent, CreateElicitationResponse, methods, ndJsonStream, RequestError, } from "@agentclientprotocol/sdk";
-import { deleteSession, getSessionMessages, listSessions, query, } from "@anthropic-ai/claude-agent-sdk";
+import { deleteSession, getSessionMessages, getSubagentMessages, listSessions, query, } from "@anthropic-ai/claude-agent-sdk";
 import { GOAL_ACTIONS, GOAL_CONTROL_METHOD, GOAL_EXTENSION_VERSION, goalUpdateFromPrompt, parseGoalRequest, toGoalSnapshot, } from "./goal-extension.js";
 import { sanitizeTitle, SessionTitles } from "./session-titles.js";
 import { AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY, asSdkSessionNotification, clientSupportsSubagents, } from "./acp-subagents.js";
-import { isNativeSubagentControlTool, isNativeSubagentControlUpdate, NativeSubagentRuntime, } from "./native-subagents.js";
-import { AIR_ASYNC_TASKS_CAPABILITY, AIR_RECOMMENDED_CONFIG_VALUE_CAPABILITY, clientSupportsAirCapability, withAirMeta, } from "./air-extension.js";
+import { isNativeSubagentControlTool, isNativeSubagentControlUpdate, NativeSubagentRuntime, resumedNativeSubagentId, sendMessageResumePrompt, } from "./native-subagents.js";
+import { AIR_ASYNC_TASKS_CAPABILITY, AIR_DIFF_PATCH_CAPABILITY, AIR_PLAN_FILE_CAPABILITY, AIR_GOAL_KEY, AIR_RECOMMENDED_CONFIG_VALUE_CAPABILITY, clientSupportsAirCapability, withAirMeta, } from "./air-extension.js";
 import { AsyncTaskRuntime, backgroundBashTaskFromToolResult, clientSupportsAsyncTasks, } from "./async-tasks.js";
 import { AUTH_STATUS_PROBE_TIMEOUT_MS, AUTH_STATUS_UPDATE_METHOD, authStatusCapability, fromAccountInfo, fromCliStatus, gatewayAuthStatus, mergeAuthStatus, notLoggedInAuthStatus, sameAuthStatus, } from "./auth-status.js";
 import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { existsSync } from "node:fs";
 import * as fs from "node:fs/promises";
-import * as os from "node:os";
 import * as path from "node:path";
 import { promisify } from "node:util";
 import packageJson from "../package.json" with { type: "json" };
 import { applyAskElicitationResponse, askUserQuestionsToCreateRequest, createElicitationResponseToElicitResult, extractAskUserQuestions, extractRefusalFallbackPrompt, mcpElicitationToCreateRequest, REFUSAL_FALLBACK_DIALOG_KIND, refusalFallbackResultFromResponse, refusalFallbackToCreateRequest, } from "./elicitation.js";
 import { forkSession } from "./fork-session.js";
-import { readResumedSession } from "./resumed-session.js";
+import { subagentHistory } from "./subagent-history.js";
+import { readResumedModel, readResumedSession, } from "./resumed-session.js";
 import { SessionTiming } from "./session-timing.js";
 import { ALLOW_BYPASS, resolvePermissionMode } from "./permissions/modes.js";
 import { normalizeDurablePermissionChangeSet } from "./permissions/normalization.js";
@@ -26,14 +25,19 @@ 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";
-import { billsClaudeSubscription, CLAUDE_SUBSCRIPTION_NOT_SUPPORTED_MESSAGE, CLAUDE_SUBSCRIPTION_NOT_SUPPORTED_REASON, claudeLoginRequiredError, claudeSubscriptionNotSupportedError, holdsNonSubscriptionCredential, refuseClaudeSubscriptionTurn, shouldHideClaudeAuth, warnClaudeSubscriptionGuardDegraded, } from "./hide-claude-auth.js";
+import { billsClaudeSubscription, claudeLoginRequiredError, claudeSubscriptionNotSupportedError, holdsNonSubscriptionCredential, refuseClaudeSubscriptionTurn, shouldHideClaudeAuth, warnClaudeSubscriptionGuardDegraded, } from "./hide-claude-auth.js";
 import { AGENT_FILE_CHANGE_REPORT_CAPABILITY, agentFileChangeReportMeta, createNativeFileChangeReporter, supportsAgentFileChangeReport, } from "./file-change-audit.js";
 import { ContextCompactionLifecycle, clientSupportsCompactionUpdates, contextCompactionMetadataFromBoundary, isCompactSummaryMessage, } from "./context-compaction.js";
 import { clientSupportsNotices, MAX_NOTICE_TITLE_LENGTH, normalizeNoticeText, noticeOrTranscriptUpdate, sentenceCase, splitNoticeText, } from "./session-notices.js";
-import { applyTaskCreate, applyTaskList, applyTaskUpdate, clearHookCallbacks, completeHookCallback, createPostToolUseHook, createTaskHook, parseTaskCreateOutput, parseTaskListOutput, parseTaskUpdateOutput, planEntries, registerHookCallback, taskStateToPlanEntries, toolInfoFromToolUse, toolUpdateFromToolResult, unregisterHookCallback, } from "./tools.js";
-import { toolUpdateFromDiffToolResponse } from "./diff.js";
+import { applyTaskCreate, applyTaskList, applyTaskUpdate, clearHookCallbacks, completeHookCallback, createPostToolUseHook, hasHookCallback, createTaskHook, parseTaskCreateOutput, parseTaskListOutput, parseTaskUpdateOutput, planEntries, registerHookCallback, changedTaskPlanEntries, forgetPublishedTaskPlan, unregisterHookCallback, } from "./tools.js";
+import { previewPatchContent } from "./diff.js";
+import { backgroundedBashToolCall } from "./tool-calls/background.js";
+import { ChangedMetaFilter } from "./tool-calls/changed-meta-filter.js";
+import { ToolCallFieldTracker } from "./tool-calls/field-tracker.js";
+import { ClientCapabilities as ToolCallClientCapabilities } from "./tool-calls/client-capabilities.js";
+import { AcpToolCallRenderer } from "./tool-calls/renderer.js";
 import { nodeToWebReadable, nodeToWebWritable, Pushable, unreachable } from "./utils.js";
-import { acceptedPlanToolResult, ExitPlanCoordinator, exitPlanModeRawOutput, isExitPlanInterruptionResult, observeExitPlanToolResults, } from "./exit-plan.js";
+import { acceptedPlanToolResult, ExitPlanCoordinator, isExitPlanInterruptionResult, observeExitPlanToolResults, } from "./exit-plan.js";
 import { parseToolResultMeta } from "./tool-result-meta.js";
 import { formatUsageResponse, isUsageCommandText, parseUsageResponse } from "./usage-markdown.js";
 import { MODE_CONFIG_ID, SessionModeManager } from "./session-mode.js";
@@ -41,7 +45,6 @@ import { applyAvailableModelsAllowlist, buildModelConfigOption, getAvailableMode
 import { buildEffortConfigOption, EFFORT_CONFIG_ID, mergeEffortSettings, settingsEffortForModel, toSdkEffortLevel, } from "./session-effort.js";
 export { EFFORT_CONFIG_ID, settingsEffortForModel } from "./session-effort.js";
 export { applyAvailableModelsAllowlist, matchResumedModel, MODEL_CONFIG_ID, resolveModelPreference, } from "./session-model.js";
-export const CLAUDE_CONFIG_DIR = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
 const execFileAsync = promisify(execFile);
 /** Claude CLI emits this synthetic result when an interrupted cycle ends on
  *  queued user input before producing any assistant content. It is a hand-off
@@ -74,6 +77,27 @@ 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;
+/** The number of settled subagents whose parent tool call a session keeps for
+ *  a later resume (see `resumableSubagents`). */
+const MAX_RESUMABLE_SUBAGENTS = 256;
+/** Removes a settled task from `liveBackgroundTasks`. A subagent keeps its
+ *  parent tool call in `resumableSubagents` for a later resume. */
+function settleLiveBackgroundTask(session, taskId) {
+    const record = session.liveBackgroundTasks.get(taskId);
+    if (!record)
+        return;
+    session.liveBackgroundTasks.delete(taskId);
+    if (!record.isSubagent)
+        return;
+    const resumable = (session.resumableSubagents ??= new Map());
+    resumable.delete(taskId);
+    resumable.set(taskId, { parentToolUseId: record.parentToolUseId });
+    if (resumable.size > MAX_RESUMABLE_SUBAGENTS) {
+        const oldest = resumable.keys().next().value;
+        if (oldest !== undefined)
+            resumable.delete(oldest);
+    }
+}
 /** Best-effort structured presentation for a local `/usage` turn. The command
  * itself always runs through Claude Code; null tells the consumer to forward
  * its original output unchanged. The timeout prevents an unstable control
@@ -412,15 +436,95 @@ const SUPPORTED_PROTOCOLS = ["anthropic", "bedrock", "vertex"];
 const PROVIDER_ID = "main";
 const DEFAULT_ANTHROPIC_BASE_URL = "https://api.anthropic.com";
 const DEFAULT_VERTEX_BASE_URL = "https://aiplatform.googleapis.com";
+/**
+ * The blocks of a consolidated assistant message without the text that
+ * already streamed as deltas.
+ *
+ * Each assembled text/thinking block is diffed against the streamed blocks in
+ * document order: nothing is left if it streamed in full (the common case),
+ * the whole block if it never streamed (a non-streaming gateway), and just the
+ * tail if the stream was cut short mid-block. Matching on content rather than
+ * the message id keeps the dedupe robust for gateways without a stable id.
+ * Tool-use and other blocks pass through untouched.
+ */
+function unstreamedRemainder(blocks, streamedBlocks) {
+    const kept = [];
+    let streamPos = 0;
+    for (const item of blocks) {
+        if (item.type !== "text" && item.type !== "thinking") {
+            kept.push(item);
+            continue;
+        }
+        const block = item;
+        const full = (item.type === "text" ? block.text : block.thinking) ?? "";
+        // Empty assembled blocks carry nothing: drop them.
+        if (full.length === 0)
+            continue;
+        // A streamed block of the same type whose text is a prefix of this one
+        // was already delivered, at least partly. A non-empty streamed text is
+        // required so an empty or aborted streamed block does not swallow it.
+        const streamed = streamedBlocks[streamPos];
+        if (streamed &&
+            streamed.type === item.type &&
+            streamed.text.length > 0 &&
+            full.startsWith(streamed.text)) {
+            streamPos++;
+            const remainder = full.slice(streamed.text.length);
+            if (remainder.length === 0)
+                continue;
+            kept.push({ ...item, [item.type === "text" ? "text" : "thinking"]: remainder });
+            continue;
+        }
+        kept.push(item);
+    }
+    return kept;
+}
+/** Attributes a report to the Agent/Task tool call of the subagent that made it. */
+function stampParentToolUseId(update, parentToolUseId) {
+    update._meta = {
+        ...update._meta,
+        claudeCode: {
+            ...(update._meta?.claudeCode ?? {}),
+            parentToolUseId,
+        },
+    };
+}
 const SUBAGENT_TRANSCRIPT_CAPABILITY = "subagent-transcript";
 function supportsSubagentTranscript(capabilities) {
     return capabilities?._meta?.[SUBAGENT_TRANSCRIPT_CAPABILITY] === true;
 }
+/**
+ * The number of sessions in one page of session/list. The SDK scans the whole
+ * project directory for each page, so a page holds all sessions of a usual
+ * project.
+ */
+const SESSION_LIST_PAGE_SIZE = 1000;
+/** The offset that a session/list cursor names. */
+function sessionListOffset(cursor) {
+    if (cursor === null || cursor === undefined)
+        return 0;
+    const match = /^offset:(\d+)$/.exec(cursor);
+    if (!match)
+        throw RequestError.invalidParams(undefined, `Unknown session/list cursor: ${cursor}`);
+    return Number(match[1]);
+}
 function parentToolUseIdOf(message) {
     if (!("parent_tool_use_id" in message))
         return null;
     return typeof message.parent_tool_use_id === "string" ? message.parent_tool_use_id : null;
 }
+/** The ids of the Agent and Task tool uses in the content of a message. */
+function subagentLaunchIds(content) {
+    if (!Array.isArray(content))
+        return [];
+    return content.flatMap((block) => typeof block === "object" &&
+        block !== null &&
+        block.type === "tool_use" &&
+        typeof block.id === "string" &&
+        isNativeSubagentControlTool(block.name)
+        ? [block.id]
+        : []);
+}
 function replaySubagentTerminalState(block) {
     if (block.is_error !== true)
         return "completed";
@@ -457,11 +561,19 @@ function stripSubagentTextAndThinking(content) {
  * that sit at the top level of the input object — everything before such a
  * comma is a set of complete fields. Returns true once the input object's
  * closing brace arrives.
+ *
+ * The lexer reads the fragment itself, never `partialJson` by index. V8 keeps a
+ * string built with `+=` as a chain of parts, and the first index access
+ * copies the whole chain into one flat string. An index scan of `partialJson`
+ * would copy the whole input on each delta, so a large Write would cost
+ * quadratic time. A test in `acp-agent.test.ts` checks this.
  */
-function scanStreamedToolInput(state) {
+function scanStreamedToolInput(state, fragment) {
+    const offset = state.partialJson.length;
+    state.partialJson += fragment;
     let complete = false;
-    for (let index = state.scannedTo; index < state.partialJson.length; index++) {
-        const character = state.partialJson[index];
+    for (let index = 0; index < fragment.length; index++) {
+        const character = fragment[index];
         if (state.inString) {
             if (state.escaped) {
                 state.escaped = false;
@@ -493,10 +605,9 @@ function scanStreamedToolInput(state) {
             state.arrayDepth--;
         }
         else if (character === "," && state.objectDepth === 1 && state.arrayDepth === 0) {
-            state.lastTopLevelComma = index;
+            state.lastTopLevelComma = offset + index;
         }
     }
-    state.scannedTo = state.partialJson.length;
     return complete;
 }
 /** Parse the complete top-level fields before a top-level comma by closing the
@@ -758,6 +869,47 @@ class ClientConnection {
         return this.ctx.notify(method, params);
     }
 }
+/**
+ * The client that the agent talks to. For an AIR client, every session update
+ * passes the {@link ChangedMetaFilter} last, after the native subagent routing,
+ * so a `tool_call_update` carries only the `_meta` keys that changed. ACP
+ * merges only the top-level tool call fields, not the `_meta` keys. So another
+ * client gets the full `_meta` on each update.
+ */
+class ChangedMetaClient {
+    inner;
+    airClient;
+    filter = new ChangedMetaFilter();
+    constructor(inner, airClient) {
+        this.inner = inner;
+        this.airClient = airClient;
+    }
+    async sessionUpdate(params) {
+        if (!this.airClient())
+            return this.inner.sessionUpdate(params);
+        const update = this.filter.apply(params.update);
+        if (update)
+            await this.inner.sessionUpdate({ ...params, update });
+    }
+    requestPermission(params, signal) {
+        return this.inner.requestPermission(params, signal);
+    }
+    readTextFile(params) {
+        return this.inner.readTextFile(params);
+    }
+    writeTextFile(params) {
+        return this.inner.writeTextFile(params);
+    }
+    createElicitation(params, signal) {
+        return this.inner.createElicitation(params, signal);
+    }
+    completeElicitation(params) {
+        return this.inner.completeElicitation(params);
+    }
+    extNotification(method, params) {
+        return this.inner.extNotification(method, params);
+    }
+}
 function raceWithAbort(operation, signal) {
     return new Promise((resolve, reject) => {
         const cleanup = () => signal.removeEventListener("abort", onAbort);
@@ -896,6 +1048,8 @@ export class ClaudeAcpAgent {
     sessions;
     client;
     clientCapabilities;
+    /** The tool call report choices, read once from {@link clientCapabilities} in `initialize`. */
+    toolCallCapabilities = new ToolCallClientCapabilities();
     logger;
     sessionModes;
     gatewayAuthRequest;
@@ -929,7 +1083,7 @@ export class ClaudeAcpAgent {
     forceCancelGraceMs = DEFAULT_FORCE_CANCEL_GRACE_MS;
     constructor(client, logger) {
         this.sessions = {};
-        this.client = client;
+        this.client = new ChangedMetaClient(client, () => this.toolCallCapabilities.air.client);
         this.logger = logger ?? console;
         this.exitPlan = new ExitPlanCoordinator({
             currentSession: (id) => this.sessions[id],
@@ -951,6 +1105,7 @@ export class ClaudeAcpAgent {
                 this.closeQueryStream(session);
                 session.abortController.abort();
                 session.eagerToolCallSessions?.clear();
+                session.toolCallFields?.clear();
                 clearHookCallbacks(id);
                 session.nativeSubagentRuntime?.clear();
                 session.asyncTaskRuntime?.clear();
@@ -972,6 +1127,7 @@ export class ClaudeAcpAgent {
         });
         this.sessionModes = new SessionModeManager({
             getSession: (sessionId) => this.sessions[sessionId],
+            airClient: () => this.toolCallCapabilities.air.client,
             sessionEndedMessage: SESSION_ENDED_MESSAGE,
             updateConfigOption: (sessionId, configId, value) => this.updateConfigOption(sessionId, configId, value),
             sessionUpdate: (params) => this.client.sessionUpdate(params),
@@ -982,6 +1138,7 @@ export class ClaudeAcpAgent {
     }
     async initialize(request) {
         this.clientCapabilities = request.clientCapabilities;
+        this.toolCallCapabilities = ToolCallClientCapabilities.from(request.clientCapabilities);
         // 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
@@ -1135,16 +1292,19 @@ export class ClaudeAcpAgent {
             // Top-level `_meta` (sibling of `agentCapabilities`), per the existing ACP
             // steering extension contract: advertises the `_session/steering` request
             // so clients know they may inject a follow-up into a running turn.
+            // Only AIR gets the AIR capabilities and the goal capability, under
+            // `jetbrains.air`.
             _meta: {
-                ...airSessionFailureCapabilityMeta(AGENT_FILE_CHANGE_REPORT_CAPABILITY, AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY, AIR_ASYNC_TASKS_CAPABILITY, AIR_RECOMMENDED_CONFIG_VALUE_CAPABILITY),
+                ...(this.toolCallCapabilities.air.client
+                    ? withAirMeta(airSessionFailureCapabilityMeta(AGENT_FILE_CHANGE_REPORT_CAPABILITY, AIR_NATIVE_SUBAGENT_SESSIONS_CAPABILITY, AIR_ASYNC_TASKS_CAPABILITY, AIR_RECOMMENDED_CONFIG_VALUE_CAPABILITY, AIR_DIFF_PATCH_CAPABILITY, AIR_PLAN_FILE_CAPABILITY), AIR_GOAL_KEY, {
+                        version: GOAL_EXTENSION_VERSION,
+                        controlMethod: GOAL_CONTROL_METHOD,
+                        actions: [...GOAL_ACTIONS],
+                    })
+                    : {}),
                 steering: {
                     supported: true,
                 },
-                goal: {
-                    version: GOAL_EXTENSION_VERSION,
-                    controlMethod: GOAL_CONTROL_METHOD,
-                    actions: [...GOAL_ACTIONS],
-                },
             },
         };
     }
@@ -1198,10 +1358,21 @@ export class ClaudeAcpAgent {
         }, 0);
         return result;
     }
+    /**
+     * One page of the sessions, newest first. The cursor is the offset of the
+     * page. The SDK then orders the transcripts by their modification time and
+     * reads the start and the end only of the transcripts of the page.
+     */
     async listSessions(params) {
-        const sdk_sessions = await listSessions({ dir: params.cwd ?? undefined });
+        const offset = sessionListOffset(params.cursor);
+        // One more session than the page tells whether a next page exists.
+        const sdkSessions = await listSessions({
+            dir: params.cwd ?? undefined,
+            limit: SESSION_LIST_PAGE_SIZE + 1,
+            offset,
+        });
         const sessions = [];
-        for (const session of sdk_sessions) {
+        for (const session of sdkSessions.slice(0, SESSION_LIST_PAGE_SIZE)) {
             if (!session.cwd)
                 continue;
             sessions.push({
@@ -1211,9 +1382,9 @@ export class ClaudeAcpAgent {
                 updatedAt: new Date(session.lastModified).toISOString(),
             });
         }
-        return {
-            sessions,
-        };
+        return sdkSessions.length > SESSION_LIST_PAGE_SIZE
+            ? { sessions, nextCursor: `offset:${offset + SESSION_LIST_PAGE_SIZE}` }
+            : { sessions };
     }
     /**
      * `authenticate` — the legacy gateway methods store a provider override that
@@ -1791,14 +1962,6 @@ export class ClaudeAcpAgent {
             // The guard reads the account anyway; reuse that read to keep the
             // reported identity current, refusal or not.
             onAccount: (account) => this.publishSessionAccountIdentity(account),
-            sessionFailures: () => new SessionFailureController({
-                sessionId,
-                state: session.sessionFailureState,
-                capabilities: this.clientCapabilities,
-                isCurrent: () => this.sessions[sessionId] === session,
-                sendUpdate: (notification) => this.client.sessionUpdate(notification),
-                logger: this.logger,
-            }),
         });
     }
     async goal(params) {
@@ -1819,21 +1982,24 @@ export class ClaudeAcpAgent {
         if (session) {
             session.lastPublishedGoal = goal;
         }
+        // The goal is an AIR extension: only AIR gets it.
+        if (!this.toolCallCapabilities.air.client)
+            return;
         await this.client.sessionUpdate({
             sessionId,
             update: {
                 sessionUpdate: "session_info_update",
-                _meta: { goal },
+                _meta: withAirMeta(undefined, AIR_GOAL_KEY, goal),
             },
         });
     }
     async publishTaskPlan(sessionId, taskState) {
+        const entries = changedTaskPlanEntries(taskState, this.toolCallCapabilities.air.client);
+        if (!entries)
+            return;
         await this.client.sessionUpdate({
             sessionId,
-            update: {
-                sessionUpdate: "plan",
-                entries: taskStateToPlanEntries(taskState),
-            },
+            update: { sessionUpdate: "plan", entries },
         });
     }
     async publishGoalFromPrompt(sessionId, prompt, commandUuid) {
@@ -2033,7 +2199,28 @@ export class ClaudeAcpAgent {
         // on content rather than the Anthropic message id makes dedupe robust to
         // gateways that don't carry a stable/matching id across the stream and the
         // consolidated message. Reset after each consolidated message consumes it.
-        const streamedBlocks = [];
+        //
+        // Keyed by the parent tool use of the stream ("" for the top level), so a
+        // subagent message gets the same remainder diff as a top-level message.
+        // The entry of a subagent goes when the subagent finishes.
+        const streamedBlocksByParent = new Map();
+        const streamedBlocksOf = (parentToolUseId) => {
+            const key = parentToolUseId ?? "";
+            let blocks = streamedBlocksByParent.get(key);
+            if (!blocks)
+                streamedBlocksByParent.set(key, (blocks = []));
+            return blocks;
+        };
+        // A client gets the consolidated subagent text when it negotiated the
+        // transcript extension or the `forwardSubagentText` session option. AIR
+        // also gets it with native subagent sessions, and AIR gets no streamed
+        // subagent text without it: nested text then stays internal to the Agent
+        // tool call. Every other client gets the streamed subagent text, like
+        // upstream.
+        const airClient = this.toolCallCapabilities.air.client;
+        const forwardsSubagentText = () => session.forwardSubagentText ||
+            supportsSubagentTranscript(this.clientCapabilities) ||
+            (airClient && clientSupportsSubagents(this.clientCapabilities));
         // Tool-use blocks start streaming before their JSON input. Keep the
         // partial input per parent message and block index so completed top-level
         // fields can refine the pending tool call while it streams. Entries are
@@ -2062,9 +2249,15 @@ export class ClaudeAcpAgent {
          *  `tool_use_id` so hosts can collapse them; a notice has no lifecycle to
          *  update, so only the first becomes one. */
         const noticedToolUses = new Set();
-        const asyncTasks = (session.asyncTaskRuntime ??= new AsyncTaskRuntime(clientSupportsAsyncTasks(this.clientCapabilities), params.sessionId, async (notification) => this.client.sessionUpdate(asSdkSessionNotification(notification)), { notices: supportsNotices }));
+        const asyncTasks = (session.asyncTaskRuntime ??= new AsyncTaskRuntime(clientSupportsAsyncTasks(this.clientCapabilities), params.sessionId, async (notification) => this.client.sessionUpdate(asSdkSessionNotification(notification)), {
+            notices: supportsNotices,
+            // 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)),
+        }));
         const compaction = new ContextCompactionLifecycle((notification) => sendUpdate(notification), {
             sessionId: params.sessionId,
+            airClient: this.toolCallCapabilities.air.client,
             presentation: clientSupportsCompactionUpdates(this.clientCapabilities)
                 ? "compaction_update"
                 : "tool_call",
@@ -2188,12 +2381,12 @@ export class ClaudeAcpAgent {
             lastAssistantWasUsageLimit = false;
             lastAssistantFailureTitle = undefined;
             lastRefusalExplanation = null;
-            // Do NOT reset currentStreamMessageId or streamedBlocks here. Turn
+            // Do NOT reset currentStreamMessageId or the streamed blocks here. Turn
             // activation can fire mid-message (the replayed user echo with
             // --replay-user-messages lands between a message's blocks); clearing the
             // streamed-content record on activation would drop the blocks that
             // streamed before the echo, so the consolidated assistant message would
-            // re-emit them as duplicates. streamedBlocks is bounded instead by being
+            // re-emit them as duplicates. The streamed blocks are bounded instead by being
             // cleared when each consolidated message consumes it. #785 stopped
             // resetting the streamed-content tracking here but left this line.
             stopReason = "end_turn";
@@ -2241,7 +2434,7 @@ export class ClaudeAcpAgent {
                         continue;
                     }
                     if (record.endedPerLevel === "sweep-armed") {
-                        session.liveBackgroundTasks.delete(taskId);
+                        settleLiveBackgroundTask(session, taskId);
                     }
                     else {
                         record.endedPerLevel = "sweep-armed";
@@ -2431,6 +2624,28 @@ export class ClaudeAcpAgent {
             turn.usageOriginalOutput = originalOutput;
             return markdown;
         };
+        /** Registers a live background task (see `liveBackgroundTasks`). A
+         *  subagent is also recorded on the active turn, so that turn holds until
+         *  the subagent settles (see `Turn.spawnedTaskIds`). */
+        const registerLiveTask = (taskId, parentToolUseId, isSubagent) => {
+            session.liveBackgroundTasks.set(taskId, { parentToolUseId, isSubagent });
+            session.resumableSubagents?.delete(taskId);
+            if (isSubagent && session.activeTurn && !session.activeTurn.settled) {
+                (session.activeTurn.spawnedTaskIds ??= new Set()).add(taskId);
+            }
+        };
+        const settleLiveTask = (taskId) => settleLiveBackgroundTask(session, taskId);
+        /** Registers a settled subagent again when the SDK resumes it without a
+         *  new `task_started`. The active turn is the one that resumed it, so it
+         *  holds until the subagent settles again. A repeated resume signal finds
+         *  the subagent live and changes nothing. */
+        const resumeLiveTask = (taskId) => {
+            if (session.liveBackgroundTasks.has(taskId))
+                return;
+            const settled = session.resumableSubagents?.get(taskId);
+            if (settled)
+                registerLiveTask(taskId, settled.parentToolUseId, true);
+        };
         /** Whether any background subagent this turn spawned is still live —
          *  while true, the turn's settlement stays deferred so the subagent's
          *  output and permission requests land inside it (see
@@ -2561,34 +2776,16 @@ export class ClaudeAcpAgent {
          *  signal that starts the client's own auth flow (AIR parks the refused
          *  prompt, shows its method chooser, and resumes the prompt after sign-in),
          *  so replacing it with a successful `end_turn` would disable that flow.
-         *  Every client keeps the rejection; capable clients additionally receive
-         *  the signed-out *state* as one session-scoped failure whose `login`
-         *  action remains the way back in after the client's auth prompt is
-         *  dismissed. Its title stays the policy's client-neutral fallback — the
-         *  CLI's own text ("… Please run /login") is TUI advice, meaningless in an
-         *  ACP client, so it travels as expandable details instead. */
+         *  Every client keeps the rejection. The client owns the login UI. */
         const failActiveWithSessionFailure = async (kind, error, title) => {
             if (session.activeTurn && !session.activeTurn.settled) {
                 await compaction.interrupt();
             }
             if (kind === "auth_required") {
-                // One sign-out arrives twice — the synthetic login assistant message
-                // and the turn's error-shaped result repeat the same text — and the
-                // signed-out state does not change in between: publish once, and skip
-                // republishing while the previous sign-out is still active. A retry
-                // warning of the same kind is not a sign-out and must not suppress it.
-                if (!sessionFailures.hasActiveSessionError(kind)) {
-                    await publishSessionFailure(kind, { turnScoped: false, details: title });
-                }
-                // Preserve legacy codes: only explicit `/login` signals trigger ACP's auth flow.
-                // The first delivery rejects the turn, so the second one finds it settled.
-                // That is the normal course here, not the lost-failure case `failActive`
-                // logs an error for.
+                // The auth error starts the client's login flow. Do not send an access
+                // failure as a second notification or render login text in the chat.
                 if (session.activeTurn && !session.activeTurn.settled)
-                    failActive(error);
-                // The row is published and the turn is rejected. Under
-                // `--hide-claude-auth` the account cached at `initialize` is now
-                // wrong, so end the query and let the next turn recreate it.
+                    failActive(RequestError.authRequired());
                 this.markSessionForSignOutRespawn(params.sessionId, session);
                 return;
             }
@@ -2907,7 +3104,7 @@ export class ClaudeAcpAgent {
                                 // A fresh `system`/init (e.g. after reinitialize) can carry an
                                 // updated Fast mode state; reconcile it with what we seeded at
                                 // session creation.
-                                await this.syncFastModeState(message.session_id, session, message.fast_mode_state, message.fast_mode_disabled_reason);
+                                await this.syncFastModeState(params.sessionId, session, message.fast_mode_state, message.fast_mode_disabled_reason);
                                 // Terminal-bound slash commands (absent when none, and on
                                 // older CLIs). The session/new advertisement runs before any
                                 // init frame can be observed, so the first latch (or a
@@ -2917,7 +3114,7 @@ export class ClaudeAcpAgent {
                                         JSON.stringify(session.terminalSlashCommands)) {
                                     session.terminalSlashCommands = message.terminal_slash_commands;
                                     try {
-                                        await this.sendAvailableCommandsUpdate(message.session_id);
+                                        await this.sendAvailableCommandsUpdate(params.sessionId);
                                     }
                                     catch (error) {
                                         // Advisory reconcile only — the client keeps its current
@@ -2963,7 +3160,7 @@ export class ClaudeAcpAgent {
                                 lastAssistantTotalUsage = usedTokens;
                                 session.contextUsedTokens = usedTokens;
                                 await sendUpdate({
-                                    sessionId: message.session_id,
+                                    sessionId: params.sessionId,
                                     update: attachUsageModel({
                                         sessionUpdate: "usage_update",
                                         used: lastAssistantTotalUsage,
@@ -2983,7 +3180,7 @@ export class ClaudeAcpAgent {
                                 if (usageMarkdown === null)
                                     break;
                                 await sendUpdate({
-                                    sessionId: message.session_id,
+                                    sessionId: params.sessionId,
                                     update: {
                                         sessionUpdate: "agent_message_chunk",
                                         content: { type: "text", text: usageMarkdown ?? message.content },
@@ -3132,39 +3329,9 @@ export class ClaudeAcpAgent {
                                 break;
                             }
                             case "memory_recall": {
-                                const isSynthesis = message.mode === "synthesize";
-                                const locations = isSynthesis
-                                    ? []
-                                    : message.memories.map((m) => ({ path: m.path }));
-                                const content = isSynthesis
-                                    ? message.memories
-                                        .filter((m) => typeof m.content === "string")
-                                        .map((m) => ({
-                                        type: "content",
-                                        content: { type: "text", text: m.content },
-                                    }))
-                                    : [];
-                                const count = message.memories.length;
-                                const title = isSynthesis
-                                    ? "Recalled synthesized memory"
-                                    : `Recalled ${count} ${count === 1 ? "memory" : "memories"}`;
                                 await sendUpdate({
-                                    sessionId: message.session_id,
-                                    update: {
-                                        sessionUpdate: "tool_call",
-                                        toolCallId: message.uuid,
-                                        title,
-                                        kind: "read",
-                                        status: "completed",
-                                        ...(locations.length > 0 && { locations }),
-                                        ...(content.length > 0 && { content }),
-                                        _meta: {
-                                            claudeCode: {
-                                                toolName: "memory_recall",
-                                                toolResponse: { mode: message.mode },
-                                            },
-                                        },
-                                    },
+                                    sessionId: params.sessionId,
+                                    update: new AcpToolCallRenderer(this.toolCallCapabilities).memoryRecall(message),
                                 });
                                 break;
                             }
@@ -3176,7 +3343,7 @@ export class ClaudeAcpAgent {
                                 // it's authoritative, and re-querying supportedCommands()
                                 // would just return the same list with an extra round-trip.
                                 await sendUpdate({
-                                    sessionId: message.session_id,
+                                    sessionId: params.sessionId,
                                     update: {
                                         sessionUpdate: "available_commands_update",
                                         availableCommands: getAvailableSlashCommands(message.commands, session.terminalSlashCommands),
@@ -3231,32 +3398,18 @@ export class ClaudeAcpAgent {
                                     // child tool call was not announced there.
                                     break;
                                 }
-                                const reason = message.decision_reason ?? message.message;
-                                await sendUpdate({
-                                    sessionId: message.session_id,
-                                    update: {
-                                        sessionUpdate: "tool_call_update",
-                                        toolCallId: message.tool_use_id,
-                                        status: "failed",
-                                        content: [
-                                            {
-                                                type: "content",
-                                                content: { type: "text", text: `Permission denied: ${reason}` },
-                                            },
-                                        ],
-                                        _meta: {
-                                            claudeCode: {
-                                                toolName: message.tool_name,
-                                                ...(parentToolUseId ? { parentToolUseId } : {}),
-                                                toolResponse: {
-                                                    decisionReasonType: message.decision_reason_type,
-                                                    decisionReason: message.decision_reason,
-                                                    message: message.message,
-                                                },
-                                            },
-                                        },
-                                    },
+                                const denied = new AcpToolCallRenderer(this.toolCallCapabilities).permissionDenied({
+                                    toolCallId: message.tool_use_id,
+                                    toolName: message.tool_name,
+                                    parentToolUseId,
+                                    decisionReasonType: message.decision_reason_type,
+                                    decisionReason: message.decision_reason,
+                                    message: message.message,
                                 });
+                                // A denial is final, so it replaces a pinned approval patch.
+                                if (toolCallFieldsOf(session).apply(denied, { replacePinnedContent: true })) {
+                                    await sendUpdate({ sessionId: params.sessionId, update: denied });
+                                }
                                 break;
                             }
                             case "informational": {
@@ -3291,7 +3444,7 @@ export class ClaudeAcpAgent {
                                     ? message.content
                                     : `**${sentenceCase(message.level)}:** ${message.content}`;
                                 await sendUpdate({
-                                    sessionId: message.session_id,
+                                    sessionId: params.sessionId,
                                     update: noticeOrTranscriptUpdate({
                                         severity,
                                         ...splitNoticeText(message.content, severity === "warning"
@@ -3317,6 +3470,7 @@ export class ClaudeAcpAgent {
                                     summary: message.summary,
                                     last_tool_name: message.last_tool_name,
                                     usage: message.usage,
+                                    tool_use_id: message.tool_use_id,
                                 });
                                 break;
                             case "task_started":
@@ -3338,10 +3492,7 @@ export class ClaudeAcpAgent {
                                 // turn: a turn only ever waits on its own subagents, and a
                                 // spawn during a held-open drain window (an agent chain)
                                 // extends that turn's hold.
-                                session.liveBackgroundTasks.set(message.task_id, {
-                                    parentToolUseId: message.tool_use_id,
-                                    isSubagent: !!message.subagent_type,
-                                });
+                                registerLiveTask(message.task_id, message.tool_use_id, !!message.subagent_type);
                                 await subagents.taskStarted({
                                     taskId: message.task_id,
                                     toolUseId: message.tool_use_id,
@@ -3359,9 +3510,6 @@ export class ClaudeAcpAgent {
                                     skip_transcript: message.skip_transcript,
                                     tool_use_id: message.tool_use_id,
                                 });
-                                if (message.subagent_type && session.activeTurn && !session.activeTurn.settled) {
-                                    (session.activeTurn.spawnedTaskIds ??= new Set()).add(message.task_id);
-                                }
                                 break;
                             case "task_notification":
                                 // The task settled — no further tool calls can originate
@@ -3372,10 +3520,14 @@ export class ClaudeAcpAgent {
                                     status: message.status,
                                     summary: message.summary,
                                     output_file: message.output_file,
+                                    tool_use_id: message.tool_use_id,
                                 });
-                                if (message.tool_use_id)
+                                if (message.tool_use_id) {
                                     subagents.discardPending(message.tool_use_id);
-                                session.liveBackgroundTasks.delete(message.task_id);
+                                    // The subagent streams no more text under this parent.
+                                    streamedBlocksByParent.delete(message.tool_use_id);
+                                }
+                                settleLiveTask(message.task_id);
                                 break;
                             case "task_updated":
                                 await asyncTasks.taskUpdated(message.task_id, message.patch);
@@ -3388,7 +3540,17 @@ export class ClaudeAcpAgent {
                                     message.patch.status === "failed" ||
                                     message.patch.status === "killed") {
                                     await subagents.finishTask(message.task_id, message.patch.status, sendUpdate);
-                                    session.liveBackgroundTasks.delete(message.task_id);
+                                    const parentToolUseId = session.liveBackgroundTasks.get(message.task_id)?.parentToolUseId;
+                                    if (parentToolUseId)
+                                        streamedBlocksByParent.delete(parentToolUseId);
+                                    settleLiveTask(message.task_id);
+                                }
+                                else if (message.patch.status === "running" ||
+                                    message.patch.status === "pending") {
+                                    // The SDK can resume a finished subagent under the same
+                                    // agent id without a new task_started.
+                                    resumeLiveTask(message.task_id);
+                                    await subagents.taskResumed(message.task_id, sendUpdate, sendMessageResumePrompt(session.toolUseCache, message.task_id));
                                 }
                                 break;
                             case "worker_shutting_down":
@@ -3506,7 +3668,7 @@ export class ClaudeAcpAgent {
                                             ...(explanation ? { description: explanation } : {}),
                                         };
                                     await sendUpdate({
-                                        sessionId: message.session_id,
+                                        sessionId: params.sessionId,
                                         update: noticeOrTranscriptUpdate({ severity: "warning", ...notice }, supportsNotices, `**Model fallback:** ${fallbackNotice}`),
                                     });
                                 }
@@ -3588,6 +3750,9 @@ export class ClaudeAcpAgent {
                         }
                         break;
                     case "result": {
+                        // The result ends the model turn. A background task that still
+                        // waits for its tool call id gets its spawn now, without the id.
+                        await asyncTasks.releaseHeld();
                         // A result from an autonomous cycle — a task-notification
                         // followup, or a peer/coordinator/observer message the model
                         // handled on its own (see AUTONOMOUS_RESULT_ORIGINS) — is not
@@ -3984,9 +4149,7 @@ export class ClaudeAcpAgent {
                                     // it reports a login the query process itself runs, and a
                                     // client can sign the user in out of band (AIR runs
                                     // `claude /login` in a terminal, in a separate process).
-                                    // Without this a stale signed-out record would outlive the
-                                    // sign-out and suppress the next one, which the
-                                    // `auth_required` dedupe below reads.
+                                    // Clear any older signed-out record after a real answer.
                                     failure.recoveryPolicy === "auth_status" ||
                                     (failure.severity === "warning" && failure.turnId === activeTurnId));
                             }
@@ -4158,19 +4321,16 @@ export class ClaudeAcpAgent {
                             // the top-level record. Fires once, before any of this message's
                             // blocks, so it doesn't disturb the mid-message turn-activation
                             // path the way resetting on turn activation would.
-                            if (message.parent_tool_use_id === null) {
-                                streamedBlocks.length = 0;
-                            }
+                            streamedBlocksOf(message.parent_tool_use_id).length = 0;
                         }
                         // Accumulate the text/thinking actually streamed live, so the
                         // `assistant` case below can diff its assembled blocks against what
                         // already reached the client as chunks and forward only the
-                        // remainder. Gated on `parent_tool_use_id === null` so a subagent
-                        // stream can't attribute its content to the top-level message.
+                        // remainder. Each stream (top level or one subagent) keeps its own
+                        // record, so a subagent cannot attribute content to another stream.
                         // Contiguous deltas of the same block (same index and type) extend
                         // the current entry; anything else opens a new one.
-                        if (message.parent_tool_use_id === null &&
-                            message.event.type === "content_block_delta") {
+                        if (message.event.type === "content_block_delta") {
                             const delta = message.event.delta;
                             const chunk = delta.type === "text_delta"
                                 ? { type: "text", text: delta.text }
@@ -4184,6 +4344,7 @@ export class ClaudeAcpAgent {
                             // re-emitting the next block as a duplicate.
                             if (chunk?.text) {
                                 const index = message.event.index;
+                                const streamedBlocks = streamedBlocksOf(message.parent_tool_use_id);
                                 const last = streamedBlocks[streamedBlocks.length - 1];
                                 if (last && last.index === index && last.type === chunk.type) {
                                     last.text += chunk.text;
@@ -4250,9 +4411,19 @@ export class ClaudeAcpAgent {
                             cwd: session.cwd,
                             taskState: session.taskState,
                             emittedToolCalls: session.emittedToolCalls,
+                            toolCallFields: toolCallFieldsOf(session),
                             messageId: currentStreamMessageId,
                             streamedToolInputs,
                         })) {
+                            // Nested text stays internal for an AIR client that does not
+                            // get it, like the consolidated subagent message below.
+                            if (message.parent_tool_use_id !== null &&
+                                airClient &&
+                                !forwardsSubagentText() &&
+                                (notification.update.sessionUpdate === "agent_message_chunk" ||
+                                    notification.update.sessionUpdate === "agent_thought_chunk")) {
+                                continue;
+                            }
                             // sendUpdate records delivery; a subagent stream's chunks carry
                             // the stamped parentToolUseId meta and are excluded there.
                             await sendUpdate(notification);
@@ -4264,7 +4435,7 @@ export class ClaudeAcpAgent {
                         // 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
-                        // for the id we hand clients. Not read yet (see messageIdToUuid).
+                        // for the id we hand clients. Fork reads it (see messageIdToUuid).
                         const mappedMessageId = messageIdForGrouping(message);
                         if (mappedMessageId && typeof message.uuid === "string" && message.uuid.length > 0) {
                             session.messageIdToUuid.set(mappedMessageId, message.uuid);
@@ -4485,73 +4656,22 @@ export class ClaudeAcpAgent {
                             break;
                         }
                         let content;
-                        if (message.type === "assistant" && message.parent_tool_use_id === null) {
-                            // Top-level assistant message: each text/thinking block may have
-                            // already been streamed live as deltas. Diff each against what
-                            // streamed (`streamedBlocks`, in document order) and forward only
-                            // the un-streamed remainder — nothing if it streamed in full (the
-                            // common case), the whole block if it never streamed (a
-                            // non-streaming gateway), or just the tail if the stream was cut
-                            // short mid-block. `streamPos` walks the streamed blocks in step
-                            // with the assembled text/thinking blocks; tool_use and other
-                            // blocks pass through untouched (their own `toolUseCache` collapses
-                            // the streamed/assembled pair) without advancing it.
-                            const blocks = message.message.content;
-                            const kept = [];
-                            let streamPos = 0;
-                            for (const item of blocks) {
-                                if (item.type !== "text" && item.type !== "thinking") {
-                                    kept.push(item);
-                                    continue;
-                                }
-                                const full = item.type === "text" ? item.text : item.thinking;
-                                // Empty assembled blocks carry nothing (some gateways emit an
-                                // empty `thinking` block before the real text) — drop them.
-                                if (full.length === 0) {
-                                    continue;
-                                }
-                                // A streamed block of the same type whose accumulated text is a
-                                // prefix of this one was already (at least partly) delivered as
-                                // chunks; consume it and forward only what's left. A non-empty
-                                // streamed text is required so an empty/aborted streamed block
-                                // doesn't swallow the assembled copy.
-                                const streamed = streamedBlocks[streamPos];
-                                if (streamed &&
-                                    streamed.type === item.type &&
-                                    streamed.text.length > 0 &&
-                                    full.startsWith(streamed.text)) {
-                                    streamPos++;
-                                    const remainder = full.slice(streamed.text.length);
-                                    if (remainder.length === 0) {
-                                        continue;
-                                    }
-                                    // Overwrite in place with just the un-streamed tail (the
-                                    // assembled message isn't read again after this) so the block
-                                    // keeps its exact SDK type.
-                                    if (item.type === "text") {
-                                        item.text = remainder;
-                                    }
-                                    else {
-                                        item.thinking = remainder;
-                                    }
-                                    kept.push(item);
-                                    continue;
-                                }
-                                // Not matched: never streamed (or the stream diverged from the
-                                // assembled text) — forward the block in full.
-                                kept.push(item);
-                            }
-                            content = kept;
-                            // Consumed: reset so the next message's blocks accumulate fresh and
-                            // the record stays bounded to the in-flight message.
-                            streamedBlocks.length = 0;
+                        if (message.type === "assistant" &&
+                            (message.parent_tool_use_id === null || forwardsSubagentText())) {
+                            // Each text/thinking block may have streamed live as deltas
+                            // already, for the top level and for a subagent. Forward only
+                            // the un-streamed remainder (see `unstreamedRemainder`), and
+                            // reset the record of the stream so the next message starts
+                            // fresh.
+                            const streamed = streamedBlocksOf(message.parent_tool_use_id);
+                            content = unstreamedRemainder(message.message.content, streamed);
+                            streamed.length = 0;
                         }
-                        else if (message.type === "assistant" &&
-                            !(session.forwardSubagentText || supportsSubagentTranscript(this.clientCapabilities))) {
-                            // Legacy clients keep the flattened tool-call representation,
-                            // but nested text/thinking stays internal unless explicitly
-                            // requested through the historical transcript extension.
+                        else if (message.type === "assistant") {
+                            // Nested text/thinking stays internal for a client that does
+                            // not get subagent text.
                             content = message.message.content.filter((item) => item.type !== "text" && item.type !== "thinking");
+                            streamedBlocksOf(message.parent_tool_use_id).length = 0;
                         }
                         else {
                             content = message.message.content;
@@ -4562,6 +4682,13 @@ export class ClaudeAcpAgent {
                             backgroundBashTask = backgroundBashTaskFromToolResult(content, message.tool_use_result, session.toolUseCache);
                             if (backgroundBashTask)
                                 await asyncTasks.taskBackgrounded(backgroundBashTask);
+                            const resumedAgentId = resumedNativeSubagentId(message.tool_use_result);
+                            if (resumedAgentId) {
+                                resumeLiveTask(resumedAgentId);
+                                await subagents.taskResumed(resumedAgentId, sendUpdate, sendMessageResumePrompt(session.toolUseCache, resumedAgentId, Array.isArray(content)
+                                    ? content.flatMap((block) => block.type === "tool_result" ? [block.tool_use_id] : [])
+                                    : []));
+                            }
                         }
                         for (const notification of toAcpNotifications(content, message.message.role, params.sessionId, session.toolUseCache, routedNotificationClient, this.logger, {
                             clientCapabilities: this.clientCapabilities,
@@ -4569,6 +4696,7 @@ export class ClaudeAcpAgent {
                             cwd: session.cwd,
                             taskState: session.taskState,
                             emittedToolCalls: session.emittedToolCalls,
+                            toolCallFields: toolCallFieldsOf(session),
                             messageId: messageIdForGrouping(message),
                             toolUseResult: message.type === "user" ? message.tool_use_result : undefined,
                             // On the wire since CLI 2.1.216 but not in SDKUserMessage's
@@ -4610,42 +4738,29 @@ export class ClaudeAcpAgent {
                                 ? message.parent_tool_use_id
                                 : undefined
                             : undefined;
-                        await sendUpdate({
-                            sessionId: message.session_id,
-                            update: {
-                                sessionUpdate: "tool_call_update",
-                                toolCallId,
-                                status: "in_progress",
-                                _meta: {
-                                    claudeCode: {
-                                        toolName: message.tool_name,
-                                        ...(subagentParentToolUseId
-                                            ? { parentToolUseId: subagentParentToolUseId }
-                                            : {}),
-                                        toolResponse: {
-                                            elapsedTimeSeconds: message.elapsed_time_seconds,
-                                            // For Agent/Task calls: the subagent's type, and — when
-                                            // the subagent is waiting out an API rate-limit retry —
-                                            // the SDK's retry counters (attempt, max_retries,
-                                            // retry_delay_ms, …), forwarded verbatim so clients can
-                                            // show why a spawn looks stalled.
-                                            ...(message.subagent_type !== undefined && {
-                                                subagentType: message.subagent_type,
-                                            }),
-                                            ...(message.subagent_retry !== undefined && {
-                                                subagentRetry: message.subagent_retry,
-                                            }),
-                                        },
-                                    },
-                                },
-                            },
+                        // `tool_name` names the tool that reports the beat. When the beat
+                        // falls back to the parent call, AIR gets the name of that call,
+                        // or no name. Every other client gets `tool_name`, like upstream.
+                        const toolName = toolCallId !== message.tool_use_id && this.toolCallCapabilities.air.client
+                            ? session.toolUseCache[toolCallId]?.name
+                            : message.tool_name;
+                        const beat = new AcpToolCallRenderer(this.toolCallCapabilities).progress({
+                            toolCallId,
+                            toolName,
+                            parentToolUseId: subagentParentToolUseId,
+                            elapsedTimeSeconds: message.elapsed_time_seconds,
+                            subagentType: message.subagent_type,
+                            subagentRetry: message.subagent_retry,
                         });
+                        if (toolCallFieldsOf(session).apply(beat)) {
+                            await sendUpdate({ sessionId: params.sessionId, update: beat });
+                        }
                         break;
                     }
                     case "rate_limit_event": {
                         if (lastAssistantTotalUsage !== null) {
                             await sendUpdate({
-                                sessionId: message.session_id,
+                                sessionId: params.sessionId,
                                 update: attachUsageModel({
                                     sessionUpdate: "usage_update",
                                     used: lastAssistantTotalUsage,
@@ -4665,6 +4780,7 @@ export class ClaudeAcpAgent {
                         subagents.clear();
                         asyncTasks.clear();
                         session.eagerToolCallSessions?.clear();
+                        session.toolCallFields?.clear();
                         clearHookCallbacks(params.sessionId);
                         session.taskState.clear();
                         await this.publishTaskPlan(params.sessionId, session.taskState);
@@ -4726,6 +4842,7 @@ export class ClaudeAcpAgent {
                 failAllTurns(RequestError.internalError(undefined, "The Claude Agent process exited unexpectedly. Please start a new session."));
                 this.closeQueryStream(session);
                 session.eagerToolCallSessions?.clear();
+                session.toolCallFields?.clear();
                 clearHookCallbacks(params.sessionId);
                 session.nativeSubagentRuntime?.clear();
                 session.asyncTaskRuntime?.clear();
@@ -4781,6 +4898,7 @@ export class ClaudeAcpAgent {
         // this fire-and-forget notification, so there is nothing to do here.
         if (session.queryClosed) {
             session.eagerToolCallSessions?.clear();
+            session.toolCallFields?.clear();
             clearHookCallbacks(params.sessionId);
             return;
         }
@@ -4797,6 +4915,7 @@ export class ClaudeAcpAgent {
         }
         finally {
             session.eagerToolCallSessions?.clear();
+            session.toolCallFields?.clear();
             clearHookCallbacks(params.sessionId);
         }
         // A priority steer may still be queued in the SDK when cancellation
@@ -5094,6 +5213,7 @@ export class ClaudeAcpAgent {
         // appropriate; query.close() above has already torn the subprocess down.
         session.abortController.abort();
         session.eagerToolCallSessions?.clear();
+        session.toolCallFields?.clear();
         clearHookCallbacks(sessionId);
         session.nativeSubagentRuntime?.clear();
         session.asyncTaskRuntime?.clear();
@@ -5211,6 +5331,9 @@ export class ClaudeAcpAgent {
         const historyLoadedAt = performance.now();
         this.logger.log(`[session/replay] sessionId=${sessionId} phase=read durationMs=${Math.round(historyLoadedAt - replayStartedAt)} messages=${messages.length}`);
         const session = this.sessions[sessionId];
+        // A replay rebuilds the client view, so its plan goes out again.
+        if (session?.taskState)
+            forgetPublishedTaskPlan(session.taskState);
         const forwardSubagentText = session?.forwardSubagentText ?? supportsSubagentTranscript(this.clientCapabilities);
         const supportsTypedFailures = supportsAirSessionFailures(this.clientCapabilities);
         const activeUsageLimit = supportsTypedFailures ? activeUsageLimitMessage(messages) : undefined;
@@ -5229,8 +5352,10 @@ export class ClaudeAcpAgent {
         const replayCompactionUpdates = clientSupportsCompactionUpdates(this.clientCapabilities);
         const replayTerminalStates = new Map();
         const replayChildren = new Map();
-        if (nativeReplayEnabled) {
-            for (const message of messages) {
+        // Registers the Agent and Task launches of `list`, and the terminal state
+        // of each launch from its tool_result.
+        const registerLaunches = (list) => {
+            for (const message of list) {
                 const content = message.message
                     ?.content;
                 if (!Array.isArray(content))
@@ -5280,7 +5405,9 @@ export class ClaudeAcpAgent {
                 if (child)
                     child.terminalState = terminalState;
             }
-        }
+        };
+        if (nativeReplayEnabled)
+            registerLaunches(messages);
         const announceReplayChild = async (parentToolUseId, ancestors = new Set()) => {
             let child = replayChildren.get(parentToolUseId);
             if (!child) {
@@ -5321,7 +5448,12 @@ export class ClaudeAcpAgent {
             }
             return child.sessionId;
         };
-        for (const message of messages) {
+        // Only a history with an Agent or Task launch has subagent transcripts to read.
+        const subagents = nativeReplayEnabled && replayChildren.size > 0
+            ? await subagentHistory(sessionId)
+            : { ids: new Map() };
+        const replayedSubagents = new Set();
+        const replayMessage = async (message) => {
             if (message.type === "user" &&
                 message.parent_tool_use_id === null &&
                 typeof message.uuid === "string" &&
@@ -5341,7 +5473,7 @@ export class ClaudeAcpAgent {
             // assistant message into an authRequired error instead of showing its
             // TUI-specific text; skip it on replay too (issue #863).
             if (message.type === "assistant" && isSyntheticLoginMessage(message.message)) {
-                continue;
+                return;
             }
             // Capable clients saw every synthetic usage-limit message as a typed
             // failure live, so replay it at the same transcript position. The
@@ -5356,7 +5488,7 @@ export class ClaudeAcpAgent {
                 if (title) {
                     await sessionFailures.restore(replayTurnId ? `${replayTurnId}:error` : `${sessionId}:history-error:${message.uuid}`, "quota_exhausted", title, message.uuid === activeUsageLimit?.uuid);
                 }
-                continue;
+                return;
             }
             // @ts-expect-error - untyped in SDK but we handle all of these
             let content = message.message.content;
@@ -5374,7 +5506,7 @@ export class ClaudeAcpAgent {
             if (message.message.role === "user") {
                 content = stripLocalCommandMetadata(content);
                 if (content === null)
-                    continue;
+                    return;
             }
             // Claude persists the retained summary as a user message framed with
             // continuation instructions for the model. Clients on the compaction
@@ -5393,10 +5525,14 @@ export class ClaudeAcpAgent {
                 parentToolUseId === null &&
                 typeof message.uuid === "string" &&
                 message.uuid.length > 0) {
-                const replayCompaction = new ContextCompactionLifecycle((notification) => this.client.sessionUpdate(notification), { sessionId, presentation: "compaction_update" });
+                const replayCompaction = new ContextCompactionLifecycle((notification) => this.client.sessionUpdate(notification), {
+                    sessionId,
+                    presentation: "compaction_update",
+                    airClient: this.toolCallCapabilities.air.client,
+                });
                 if (replayCompaction.recordSummary(assistantMessageText(message.message))) {
                     await replayCompaction.finish(message.uuid, "completed");
-                    continue;
+                    return;
                 }
             }
             for (const notification of toAcpNotifications(
@@ -5405,6 +5541,7 @@ export class ClaudeAcpAgent {
             // @ts-expect-error - untyped in SDK but we handle all of these
             message.message.role, sessionId, toolUseCache, this.client, this.logger, {
                 registerHooks: false,
+                replay: true,
                 clientCapabilities: this.clientCapabilities,
                 cwd: this.sessions[sessionId]?.cwd,
                 taskState: this.sessions[sessionId]?.taskState,
@@ -5420,7 +5557,38 @@ export class ClaudeAcpAgent {
                 }
                 await this.client.sessionUpdate({ ...notification, sessionId: replayTargetSessionId });
             }
-        }
+            // The history of each subagent is in its own transcript. The replay
+            // sends it to the child session right after the launch, one message at
+            // a time, and keeps no subagent history after that.
+            if (nativeReplayEnabled && message.type === "assistant") {
+                for (const toolUseId of subagentLaunchIds(content)) {
+                    await announceReplayChild(toolUseId);
+                    const agentId = subagents.ids.get(toolUseId);
+                    if (!agentId || replayedSubagents.has(agentId))
+                        continue;
+                    replayedSubagents.add(agentId);
+                    let childMessages = [];
+                    try {
+                        // With the project directory, the SDK skips its search of every project.
+                        // A session opened from another directory falls back to that search.
+                        if (subagents.dir) {
+                            childMessages = await getSubagentMessages(sessionId, agentId, { dir: subagents.dir });
+                        }
+                        if (childMessages.length === 0) {
+                            childMessages = await getSubagentMessages(sessionId, agentId);
+                        }
+                    }
+                    catch (error) {
+                        this.logger.error(`Failed to read the history of subagent ${agentId}:`, error);
+                    }
+                    registerLaunches(childMessages);
+                    for (const childMessage of childMessages)
+                        await replayMessage(childMessage);
+                }
+            }
+        };
+        for (const message of messages)
+            await replayMessage(message);
         if (nativeReplayEnabled) {
             // Claude history persists sidechain messages and Agent/Task tool uses,
             // but not task_started/task_updated lifecycle frames. Recover terminal
@@ -5477,7 +5645,7 @@ export class ClaudeAcpAgent {
      *  `$/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 = params.sessionId) {
+    async requestPermissionFromClient(params, toolName, signal, parentToolUseId, ownerSessionId, toolInput, previewContent) {
         if (signal.aborted)
             throw new Error("Tool use aborted");
         // The SDK may invoke `canUseTool` (and therefore this permission request)
@@ -5486,7 +5654,7 @@ export class ClaudeAcpAgent {
         // so emit it now if it hasn't been sent yet. The streamed tool_use chunk
         // later refines it with a `tool_call_update` rather than emitting a
         // duplicate (see `emittedToolCalls` in `toAcpNotifications`).
-        await this.ensureToolCallEmitted(ownerSessionId, toolName, params.toolCall.toolCallId, params.toolCall.rawInput, parentToolUseId, signal, params.sessionId);
+        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
@@ -5514,28 +5682,29 @@ export class ClaudeAcpAgent {
      *  are resolved at tool_result time instead (see `toAcpNotifications`).
      *  `parentToolUseId` attributes a subagent's tool call to the Agent/Task call
      *  that spawned it, matching the streamed path's `_meta`. */
-    async ensureToolCallEmitted(sessionId, toolName, toolCallId, toolInput, parentToolUseId, signal, notificationSessionId = sessionId) {
+    async ensureToolCallEmitted(sessionId, toolName, toolCallId, toolInput, parentToolUseId, signal, notificationSessionId = sessionId, previewContent) {
         const session = this.sessions[sessionId];
         if (!session) {
             return;
         }
+        // The permission request shows an exact approval patch. The streamed
+        // tool input must not replace it with the standard diff of the snippet.
+        const pinPreview = () => {
+            if (previewContent) {
+                toolCallFieldsOf(session).pinContent(toolCallId, previewContent);
+            }
+        };
         if (session.emittedToolCalls.has(toolCallId)) {
+            pinPreview();
             return;
         }
         session.emittedToolCalls.add(toolCallId);
         (session.eagerToolCallSessions ??= new Map()).set(toolCallId, notificationSessionId);
-        const supportsTerminalOutput = this.clientCapabilities?._meta?.["terminal_output"] === true ||
-            this.clientCapabilities?._meta?.["terminal_output_delta"] === true;
-        const update = toolCallNotification({ id: toolCallId, name: toolName, input: toolInput }, toolInput, supportsTerminalOutput, session.cwd);
-        if (parentToolUseId) {
-            update._meta = {
-                ...update._meta,
-                claudeCode: {
-                    ...(update._meta?.claudeCode || {}),
-                    parentToolUseId,
-                },
-            };
-        }
+        const update = new AcpToolCallRenderer(this.toolCallCapabilities).toolCall({ id: toolCallId, name: toolName, input: toolInput }, { cwd: session.cwd, previewContent });
+        if (parentToolUseId)
+            stampParentToolUseId(update, parentToolUseId);
+        toolCallFieldsOf(session).apply(update);
+        pinPreview();
         try {
             const emission = this.client.sessionUpdate({ sessionId: notificationSessionId, update });
             await (signal ? raceWithAbort(emission, signal) : emission);
@@ -5546,13 +5715,12 @@ export class ClaudeAcpAgent {
             // be allowed to publish the tool call instead of refining a phantom one.
             session.emittedToolCalls.delete(toolCallId);
             session.eagerToolCallSessions?.delete(toolCallId);
+            session.toolCallFields?.delete(toolCallId);
             throw error;
         }
     }
     canUseTool(sessionId) {
         return async (toolName, toolInput, { signal, suggestions, toolUseID, agentID, matchedAskRule, blockedPath, decisionReason, title, displayName, description, defaultToNo, suppressAlwaysAllowRule, mcpServer, }) => {
-            const supportsTerminalOutput = this.clientCapabilities?._meta?.["terminal_output"] === true ||
-                this.clientCapabilities?._meta?.["terminal_output_delta"] === true;
             const session = this.sessions[sessionId];
             if (!session) {
                 return {
@@ -5611,12 +5779,17 @@ export class ClaudeAcpAgent {
             // Artifact publishes).
             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)
+                : undefined;
             const presentation = buildClaudePermissionPresentation({
                 toolName,
                 input: toolInput,
                 toolUseID,
                 cwd: session.cwd,
-                supportsTerminalOutput,
+                capabilities,
+                previewContent,
                 blockedPath,
                 title,
                 displayName,
@@ -5630,11 +5803,14 @@ export class ClaudeAcpAgent {
             // server; anything else is configuration) instead of parsing the
             // tool-name prefix. The name is the config key as authored — untrusted
             // text, so it rides `_meta` rather than the title.
-            if (parentToolUseId || mcpServer) {
+            // AIR already holds the tool name and the parent tool call. Every
+            // other client gets them again, like upstream.
+            const airClient = capabilities.air.client;
+            if (mcpServer || (parentToolUseId && !airClient)) {
                 presentation.toolCall._meta = {
                     claudeCode: {
-                        toolName,
-                        ...(parentToolUseId ? { parentToolUseId } : {}),
+                        ...(airClient ? {} : { toolName }),
+                        ...(parentToolUseId && !airClient ? { parentToolUseId } : {}),
                         ...(mcpServer ? { mcpServer: { name: mcpServer.name, source: mcpServer.source } } : {}),
                     },
                 };
@@ -5657,7 +5833,7 @@ export class ClaudeAcpAgent {
                 ...presentation,
                 options: permissionOptions,
                 sessionId: permissionSessionId,
-            }, toolName, signal, parentToolUseId, sessionId);
+            }, toolName, signal, parentToolUseId, sessionId, toolInput, previewContent);
             if (signal.aborted)
                 throw new Error("Tool use aborted");
             const decodedPermission = decodeClaudePermissionResponse(response, toolName, toolInput, toolUseID, permissionOptions, durableChangeSet);
@@ -5748,7 +5924,7 @@ export class ClaudeAcpAgent {
         if (!questions) {
             return { behavior: "deny", message: "AskUserQuestion called with no valid questions." };
         }
-        const createRequest = askUserQuestionsToCreateRequest(questions, sessionId, toolUseID);
+        const createRequest = askUserQuestionsToCreateRequest(questions, sessionId, toolUseID, this.toolCallCapabilities.air.client);
         let response;
         try {
             response = await this.withPendingUserInput(sessionId, () => this.client.createElicitation(createRequest, signal));
@@ -6125,7 +6301,7 @@ export class ClaudeAcpAgent {
         }
         const resumedModelHint = resumedSession
             ? resumedSession.model
-            : (await readResumedSession(params.sessionId, this.logger)).model;
+            : await readResumedModel(params.sessionId, this.logger);
         const response = await this.createSession({
             cwd: params.cwd,
             mcpServers: params.mcpServers ?? [],
@@ -6202,7 +6378,7 @@ export class ClaudeAcpAgent {
         let resumedModelHint = creationOpts.resumedModelHint;
         if (creationOpts.resume !== undefined &&
             !Object.prototype.hasOwnProperty.call(creationOpts, "resumedModelHint")) {
-            resumedModelHint = (await readResumedSession(creationOpts.resume, this.logger)).model;
+            resumedModelHint = await readResumedModel(creationOpts.resume, this.logger);
             timing.phase("resume-transcript");
         }
         const input = new Pushable();
@@ -6815,12 +6991,12 @@ export class ClaudeAcpAgent {
             }
         }
     }
-    /** Tell a capable client that a session died during a provider switch. The
-     *  session is already removed, so the failure is published on the state it
-     *  left behind, with the refusal reason when the error carries one. */
+    /** 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}`);
         const isAuthRequired = error instanceof RequestError && error.code === AUTH_REQUIRED_CODE;
+        if (isAuthRequired)
+            return;
         const reason = error instanceof RequestError &&
             typeof error.data === "object" &&
             error.data !== null &&
@@ -6828,11 +7004,7 @@ export class ClaudeAcpAgent {
             typeof error.data.reason === "string"
             ? error.data.reason
             : undefined;
-        const details = reason === CLAUDE_SUBSCRIPTION_NOT_SUPPORTED_REASON
-            ? CLAUDE_SUBSCRIPTION_NOT_SUPPORTED_MESSAGE
-            : error instanceof Error
-                ? error.message
-                : String(error);
+        const details = error instanceof Error ? error.message : String(error);
         const controller = new SessionFailureController({
             sessionId,
             state: session.sessionFailureState,
@@ -6844,7 +7016,7 @@ export class ClaudeAcpAgent {
             logger: this.logger,
         });
         void controller
-            .publish(isAuthRequired ? "auth_required" : "internal_error", {
+            .publish("internal_error", {
             sessionScoped: true,
             details,
             ...(reason ? { reason } : {}),
@@ -7458,164 +7630,9 @@ function isTaskTool(toolName) {
 function shouldEmitToolCall(toolName) {
     return toolName !== "TodoWrite" && !isTaskTool(toolName);
 }
-/** Build the Claude Code-specific metadata for a tool call. Shell (Bash and
- *  PowerShell) descriptions are kept out of ACP's standard `title`, which
- *  clients may use as the shell command preview, while still giving clients
- *  access to Claude's concise human-readable title. */
-function claudeCodeMetaFromToolUse(toolUse, cwd) {
-    const description = (toolUse.name === "Bash" || toolUse.name === "PowerShell") &&
-        toolUse.input !== null &&
-        typeof toolUse.input === "object" &&
-        "description" in toolUse.input &&
-        typeof toolUse.input.description === "string"
-        ? toolUse.input.description
-        : undefined;
-    const skillName = toolUse.name === "Skill"
-        ? toolUse.input?.skill
-        : undefined;
-    const skillPath = skillName ? resolveSkillPath(skillName, cwd) : undefined;
-    return {
-        toolName: toolUse.name,
-        ...(description ? { title: description } : {}),
-        ...((toolUse.name === "Agent" || toolUse.name === "Task") && { subagent: true }),
-        ...(skillName ? { skill: skillName } : {}),
-        ...(skillPath ? { skillPath } : {}),
-    };
-}
-/**
- * Marks the Bash `tool_call_update` whose command detached into the background.
- *
- * A backgrounded Bash call returns as soon as the command is handed off, so the
- * card reaches `completed` while the command itself runs on for minutes. ACP has
- * no tool-call status for "still running elsewhere", so this marker is what lets
- * a client render the card as backgrounded work instead of finished work. It
- * rides the update the tool result already emits, so it costs no extra
- * notification and cannot arrive out of order.
- *
- * The command's own lifecycle -- progress, completion, the stop control -- is
- * published separately as an async task; this says only that the card has one.
- * Hence the AIR namespace rather than `claudeCode`: to a client without the
- * `asyncTasks` capability, which is never sent that lifecycle, the marker would
- * promise a card state it has no way to ever resolve.
- */
-function backgroundedBashToolCall(notification, task, asyncTasksSupported) {
-    const update = notification.update;
-    const toolCallId = task ? nonBlankTaskField(task.toolCallId ?? task.tool_use_id) : undefined;
-    if (!asyncTasksSupported ||
-        !toolCallId ||
-        update.sessionUpdate !== "tool_call_update" ||
-        update.toolCallId !== toolCallId) {
-        return notification;
-    }
-    return {
-        ...notification,
-        update: {
-            ...update,
-            _meta: withAirMeta(update._meta, AIR_ASYNC_TASKS_CAPABILITY, { backgrounded: true }),
-        },
-    };
-}
-/** The task fields arrive as `unknown` off the wire; only non-blank strings carry a link. */
-function nonBlankTaskField(value) {
-    if (typeof value !== "string")
-        return undefined;
-    const trimmed = value.trim();
-    return trimmed ? trimmed : undefined;
-}
-/** Roots a skill's directory may sit under, relative to the directory the scope resolves to. */
-const SKILL_CONTAINER_DIRS = [".claude/skills", ".agents/skills"];
-/**
- * Absolute path of a skill's `SKILL.md`, or `undefined` when none of the known layouts holds one.
- *
- * The `Skill` tool reports only the skill's name, so the file has to be located by probing the layouts skills
- * actually use: project- and user-level `.claude/skills` (plus this repo's `.agents/skills` source of truth), and
- * for a `<prefix>:<name>` spelling either a plugin (`.claude/plugins/<prefix>/skills/<name>`) or a
- * directory-scoped skill (`<prefix>/.claude/skills/<name>`), which share that spelling. Only a path that exists
- * on disk is returned, so a wrong guess costs nothing and clients never render a link to a missing file.
- */
-function resolveSkillPath(skillName, cwd) {
-    if (!cwd) {
-        return undefined;
-    }
-    const colon = skillName.indexOf(":");
-    const scope = colon < 0 ? undefined : skillName.slice(0, colon);
-    const name = colon < 0 ? skillName : skillName.slice(colon + 1);
-    if (!name) {
-        return undefined;
-    }
-    const candidates = [];
-    const addCandidates = (base) => {
-        for (const container of SKILL_CONTAINER_DIRS) {
-            candidates.push(path.join(base, container, name, "SKILL.md"));
-        }
-    };
-    if (scope) {
-        // A `<prefix>:<name>` skill is either directory-scoped or a plugin's; both spellings look identical.
-        addCandidates(path.join(cwd, scope));
-        candidates.push(path.join(cwd, ".claude/plugins", scope, "skills", name, "SKILL.md"));
-    }
-    addCandidates(cwd);
-    addCandidates(os.homedir());
-    return candidates.find((candidate) => existsSync(candidate));
-}
-/** Build the `tool_call` (or, with `refine`, the `tool_call_update`)
- *  notification for a tool_use. Shared by every site that surfaces a tool call:
- *  the streamed tool_use path (first encounter → tool_call, later encounter →
- *  refine) and the permission flow (`ensureToolCallEmitted`), so they can't
- *  drift. The initial `tool_call` carries `status: "pending"` and, for shell tools,
- *  the `terminal_info` _meta that the later `terminal_output`/`terminal_exit`
- *  updates key off of, and the programmatic tool `name` (ACP's tool-call-name
- *  RFD); a refining `tool_call_update` carries none of these. `name` is set
- *  once at first report — on a v1 update, omitting it means "unchanged", and
- *  the tool behind a `toolCallId` never changes. */
-function toolCallNotification(toolUse, rawInput, supportsTerminalOutput, cwd, refine = false) {
-    if (refine) {
-        return {
-            _meta: { claudeCode: claudeCodeMetaFromToolUse(toolUse, cwd) },
-            toolCallId: toolUse.id,
-            sessionUpdate: "tool_call_update",
-            rawInput,
-            ...toolInfoFromToolUse(toolUse, supportsTerminalOutput, cwd),
-        };
-    }
-    return {
-        _meta: {
-            claudeCode: claudeCodeMetaFromToolUse(toolUse, cwd),
-            ...((toolUse.name === "Bash" || toolUse.name === "PowerShell") && supportsTerminalOutput
-                ? { terminal_info: { terminal_id: toolUse.id } }
-                : {}),
-        },
-        toolCallId: toolUse.id,
-        sessionUpdate: "tool_call",
-        name: toolUse.name,
-        rawInput,
-        status: "pending",
-        ...toolInfoFromToolUse(toolUse, supportsTerminalOutput, cwd),
-    };
-}
-/** Refine a pending tool call from the complete top-level fields recovered
- *  from its still-streaming input. Shares `toolInfoFromToolUse` with the
- *  consolidated path but never carries `content`: content built from partial
- *  input is misleading (an Edit missing its `new_string` renders as a pure
- *  deletion) or invalid (a Write diff without `content` lacks the required
- *  `newText`), and the consolidated message supplies it moments later. */
-function streamedInputRefinement(toolUse, input, supportsTerminalOutput, cwd) {
-    // TodoWrite/Task* never surfaced a tool_call to refine (plan lane).
-    if (!shouldEmitToolCall(toolUse.name)) {
-        return undefined;
-    }
-    const { title, kind, locations } = toolInfoFromToolUse({ ...toolUse, input }, supportsTerminalOutput, cwd);
-    return {
-        _meta: {
-            claudeCode: claudeCodeMetaFromToolUse({ ...toolUse, input }, cwd),
-        },
-        toolCallId: toolUse.id,
-        sessionUpdate: "tool_call_update",
-        rawInput: input,
-        title,
-        kind,
-        ...(locations ? { locations } : {}),
-    };
+/** The tool-call field tracker of a session, created on first use. */
+function toolCallFieldsOf(session) {
+    return (session.toolCallFields ??= new ToolCallFieldTracker());
 }
 /**
  * Convert an SDKAssistantMessage (Claude) to a SessionNotification (ACP).
@@ -7624,8 +7641,7 @@ function streamedInputRefinement(toolUse, input, supportsTerminalOutput, cwd) {
 export function toAcpNotifications(content, role, sessionId, toolUseCache, client, logger, options) {
     const taskState = options?.taskState ?? new Map();
     const registerHooks = options?.registerHooks !== false;
-    const supportsTerminalOutputDelta = options?.clientCapabilities?._meta?.["terminal_output_delta"] === true;
-    const supportsTerminalOutput = supportsTerminalOutputDelta || options?.clientCapabilities?._meta?.["terminal_output"] === true;
+    const renderer = AcpToolCallRenderer.for(options?.clientCapabilities, options?.replay);
     if (typeof content === "string") {
         if (content.length === 0) {
             return [];
@@ -7638,15 +7654,8 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
             },
         };
         applyMessageId(update, options?.messageId);
-        if (options?.parentToolUseId) {
-            update._meta = {
-                ...update._meta,
-                claudeCode: {
-                    ...(update._meta?.claudeCode || {}),
-                    parentToolUseId: options.parentToolUseId,
-                },
-            };
-        }
+        if (options?.parentToolUseId)
+            stampParentToolUseId(update, options.parentToolUseId);
         return [{ sessionId, update }];
     }
     // `tool_use_result` is message-level and carries no tool_use_id of its own:
@@ -7665,6 +7674,8 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
     // Only handle the first chunk for streaming; extend as needed for batching
     for (const chunk of content) {
         let update = null;
+        // The tool call that this chunk finishes, if it is a tool result.
+        let finishedToolCallId;
         switch (chunk.type) {
             case "text":
             case "text_delta": {
@@ -7733,38 +7744,27 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                         // closing over the name keeps the diff working without depending on
                         // (or pinning) the cache entry's lifetime.
                         const toolName = chunk.name;
+                        const hookToolCallId = chunk.id;
                         registerHookCallback(chunk.id, {
-                            onPostToolUseHook: async (toolUseId, toolInput, toolResponse) => {
-                                // Both `Edit` and `Write` produce a structuredPatch in their
-                                // PostToolUse tool_response. For Edit the diff replaces the
-                                // optimistic content built at tool_use time. For Write the
-                                // optimistic content (built from `input.content` alone with
-                                // `oldText: null`) shows "creation" semantics regardless of
-                                // whether the file existed; the structuredPatch from the
-                                // hook lets us emit the real diff for `type: "update"`. The
-                                // helper returns `{}` if the response shape isn't usable.
-                                const editDiff = toolName === "Edit" || toolName === "Write"
-                                    ? toolUpdateFromDiffToolResponse(toolResponse)
-                                    : {};
-                                const update = {
-                                    _meta: {
-                                        claudeCode: {
-                                            toolResponse,
-                                            toolName,
-                                            ...(options?.parentToolUseId
-                                                ? { parentToolUseId: options.parentToolUseId }
-                                                : {}),
-                                        },
-                                    },
-                                    toolCallId: toolUseId,
-                                    sessionUpdate: "tool_call_update",
-                                    ...editDiff,
-                                };
-                                await client.sessionUpdate({
-                                    sessionId,
-                                    update,
-                                });
+                            onPostToolUseHook: async (toolUseId, _toolInput, toolResponse) => {
+                                // The final diff of an Edit or a Write replaces the
+                                // optimistic content built from the input. Only the marker
+                                // fields of the tool_response travel: the rest repeats
+                                // output that the content already carries.
+                                const update = await renderer.hookResult({ id: toolUseId, name: toolName }, toolResponse, options?.cwd);
+                                if (!update)
+                                    return;
+                                if (options?.parentToolUseId) {
+                                    stampParentToolUseId(update, options.parentToolUseId);
+                                }
+                                // The final result may replace a pinned approval patch.
+                                if (options?.toolCallFields &&
+                                    !options.toolCallFields.apply(update, { replacePinnedContent: true })) {
+                                    return;
+                                }
+                                await client.sessionUpdate({ sessionId, update });
                             },
+                            onRelease: () => options?.toolCallFields?.finishHook(hookToolCallId),
                         }, sessionId);
                     }
                     let rawInput;
@@ -7774,6 +7774,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                     catch {
                         // ignore if we can't turn it to JSON
                     }
+                    const toolUse = { id: chunk.id, name: chunk.name, input: rawInput };
                     // Emit a `tool_call` only the first time this id surfaces to the
                     // client; afterwards refine it with a `tool_call_update`. The first
                     // surface may be this stream chunk OR an earlier permission request
@@ -7783,17 +7784,20 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                     const emittedToolCalls = options?.emittedToolCalls;
                     const alreadyEmitted = emittedToolCalls ? emittedToolCalls.has(chunk.id) : alreadyCached;
                     emittedToolCalls?.add(chunk.id);
-                    if (alreadyEmitted) {
-                        // Already surfaced (full assistant message after streaming, or a
-                        // permission request emitted it first) — refine with a
-                        // tool_call_update rather than emitting a duplicate tool_call.
-                        update = toolCallNotification(chunk, rawInput, supportsTerminalOutput, options?.cwd, true);
-                    }
-                    else {
-                        // First surface (streaming content_block_start or replay) — send as
-                        // tool_call (with terminal_info for Bash).
-                        update = toolCallNotification(chunk, rawInput, supportsTerminalOutput, options?.cwd);
-                    }
+                    // A permission request surfaced the tool call with its complete
+                    // input. The empty input at the stream start has nothing to add.
+                    if (alreadyEmitted && options?.inputComplete === false)
+                        break;
+                    update = alreadyEmitted
+                        ? // Already surfaced (full assistant message after streaming, or a
+                            // permission request emitted it first): refine it with the
+                            // complete input.
+                            renderer.refinement(toolUse, options?.cwd)
+                        : // First surface (streaming content_block_start or replay).
+                            renderer.toolCall(toolUse, {
+                                cwd: options?.cwd,
+                                inputComplete: options?.inputComplete,
+                            });
                 }
                 break;
             }
@@ -7808,6 +7812,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                 const wasEmitted = options?.emittedToolCalls?.has(chunk.tool_use_id) === true;
                 options?.emittedToolCalls?.delete(chunk.tool_use_id);
                 completeHookCallback(chunk.tool_use_id);
+                finishedToolCallId = chunk.tool_use_id;
                 // Why this is_error result carries harness prose instead of tool
                 // output (user-rejected / interrupted / …), when the SDK said so.
                 // Spread into the claudeCode meta of every update emitted below; the
@@ -7901,58 +7906,27 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                             }
                         }
                     }
-                    if (shouldEmitTaskPlan) {
-                        update = {
-                            sessionUpdate: "plan",
-                            entries: taskStateToPlanEntries(taskState),
-                        };
-                    }
+                    const entries = shouldEmitTaskPlan
+                        ? changedTaskPlanEntries(taskState, renderer.capabilities.air.client)
+                        : undefined;
+                    if (entries)
+                        update = { sessionUpdate: "plan", entries };
                 }
                 else if (toolUse.name !== "TodoWrite") {
-                    const { _meta: toolMeta, ...toolUpdate } = toolUpdateFromToolResult(chunk, toolUseCache[chunk.tool_use_id], supportsTerminalOutput, toolUseResult, supportsTerminalOutputDelta);
-                    const terminalOutput = toolMeta?.terminal_output_delta ?? toolMeta?.terminal_output;
-                    const terminalOutputKey = toolMeta?.terminal_output_delta
-                        ? "terminal_output_delta"
-                        : "terminal_output";
-                    // When terminal output is supported, send its payload as a
-                    // separate notification to match codex-acp's streaming lifecycle:
-                    //   1. tool_call       → _meta.terminal_info  (already sent above)
-                    //   2. tool_call_update → terminal output      (sent here)
-                    //   3. tool_call_update → _meta.terminal_exit  (sent below with status)
-                    if (terminalOutput) {
-                        output.push({
-                            sessionId,
-                            update: {
-                                _meta: {
-                                    [terminalOutputKey]: terminalOutput,
-                                    ...(options?.parentToolUseId
-                                        ? { claudeCode: { parentToolUseId: options.parentToolUseId } }
-                                        : {}),
-                                },
-                                toolCallId: chunk.tool_use_id,
-                                sessionUpdate: "tool_call_update",
-                            },
-                        });
+                    // A command sends its output first, then the exit and the status.
+                    const [finalUpdate, ...rest] = renderer
+                        .result(toolUse, chunk, {
+                        structured: toolUseResult,
+                        nonExecution: nonExecution,
+                    })
+                        .reverse();
+                    for (const outputUpdate of rest.reverse()) {
+                        if (options?.parentToolUseId) {
+                            stampParentToolUseId(outputUpdate, options.parentToolUseId);
+                        }
+                        output.push({ sessionId, update: outputUpdate });
                     }
-                    update = {
-                        _meta: {
-                            claudeCode: {
-                                toolName: toolUse.name,
-                                ...(nonExecution ?? {}),
-                            },
-                            ...(toolMeta?.terminal_exit ? { terminal_exit: toolMeta.terminal_exit } : {}),
-                        },
-                        toolCallId: chunk.tool_use_id,
-                        sessionUpdate: "tool_call_update",
-                        status: "is_error" in chunk && chunk.is_error ? "failed" : "completed",
-                        // The terminal output already carried the exact bytes in the preceding
-                        // update. Repeating them as rawOutput wastes bandwidth and lets a
-                        // client accidentally render the same output twice.
-                        ...(terminalOutput
-                            ? {}
-                            : { rawOutput: exitPlanModeRawOutput(toolUse.name, chunk.content) }),
-                        ...toolUpdate,
-                    };
+                    update = finalUpdate;
                 }
                 // The tool_use is fully resolved now — drop it so a long session doesn't
                 // retain every tool call. The PostToolUse hook (Edit/Write diffs) closes
@@ -7978,17 +7952,22 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                 break;
         }
         if (update) {
-            if (options?.parentToolUseId) {
-                update._meta = {
-                    ...update._meta,
-                    claudeCode: {
-                        ...(update._meta?.claudeCode || {}),
-                        parentToolUseId: options.parentToolUseId,
-                    },
-                };
-            }
+            if (options?.parentToolUseId)
+                stampParentToolUseId(update, options.parentToolUseId);
             applyMessageId(update, options?.messageId);
-            output.push({ sessionId, update });
+            // A tool result is final, so it may replace a pinned approval patch,
+            // for example with the error text of a rejected Edit.
+            if (!options?.toolCallFields ||
+                options.toolCallFields.apply(update, {
+                    replacePinnedContent: finishedToolCallId !== undefined,
+                })) {
+                output.push({ sessionId, update });
+            }
+        }
+        if (finishedToolCallId !== undefined) {
+            // The PostToolUse hook can still send the final diff, so the fields
+            // stay tracked until its callback leaves the registry.
+            options?.toolCallFields?.finishResult(finishedToolCallId, hasHookCallback(finishedToolCallId));
         }
     }
     return output;
@@ -8003,6 +7982,7 @@ export function streamEventToAcpNotifications(message, sessionId, toolUseCache,
         cwd: options?.cwd,
         taskState: options?.taskState,
         emittedToolCalls: options?.emittedToolCalls,
+        toolCallFields: options?.toolCallFields,
         messageId: options?.messageId,
     };
     switch (event.type) {
@@ -8021,7 +8001,6 @@ export function streamEventToAcpNotifications(message, sessionId, toolUseCache,
                     id: block.id,
                     name: block.name,
                     partialJson: "",
-                    scannedTo: 0,
                     inString: false,
                     escaped: false,
                     objectDepth: 0,
@@ -8030,15 +8009,19 @@ export function streamEventToAcpNotifications(message, sessionId, toolUseCache,
                     emittedThroughComma: -1,
                 });
             }
-            return toAcpNotifications([block], "assistant", sessionId, toolUseCache, client, logger, forwardedOptions);
+            // The input of a streamed tool_use starts empty and streams after this
+            // event, so the tool_call waits for the complete input.
+            return toAcpNotifications([block], "assistant", sessionId, toolUseCache, client, logger, {
+                ...forwardedOptions,
+                inputComplete: false,
+            });
         }
         case "content_block_delta": {
             if (event.delta.type === "input_json_delta") {
                 const streamedInput = streamedToolInputs?.get(streamKey)?.get(event.index);
                 if (!streamedInput)
                     return [];
-                streamedInput.partialJson += event.delta.partial_json;
-                if (scanStreamedToolInput(streamedInput)) {
+                if (scanStreamedToolInput(streamedInput, event.delta.partial_json)) {
                     // Input complete: the consolidated assistant message replays the
                     // block with its full input and refines the call there; emitting
                     // here too would send a duplicate identical update.
@@ -8055,20 +8038,17 @@ export function streamEventToAcpNotifications(message, sessionId, toolUseCache,
                 const input = recoveredToolInput(streamedInput.partialJson.slice(0, streamedInput.lastTopLevelComma));
                 if (!input)
                     return [];
-                const supportsTerminalOutput = options?.clientCapabilities?._meta?.["terminal_output"] === true;
-                const update = streamedInputRefinement(streamedInput, input, supportsTerminalOutput, options?.cwd);
-                if (!update)
+                // TodoWrite and the Task* tools never surfaced a tool_call to refine.
+                if (!shouldEmitToolCall(streamedInput.name))
                     return [];
-                if (message.parent_tool_use_id) {
-                    update._meta = {
-                        ...update._meta,
-                        claudeCode: {
-                            ...(update._meta?.claudeCode || {}),
-                            parentToolUseId: message.parent_tool_use_id,
-                        },
-                    };
-                }
+                const update = AcpToolCallRenderer.for(options?.clientCapabilities).partialRefinement(streamedInput, input, options?.cwd);
+                if (message.parent_tool_use_id)
+                    stampParentToolUseId(update, message.parent_tool_use_id);
                 applyMessageId(update, options?.messageId);
+                // A refinement resends only what changed: rawInput grows with every
+                // field, and title, kind, and locations usually stay the same.
+                if (options?.toolCallFields && !options.toolCallFields.apply(update))
+                    return [];
                 return [{ sessionId, update }];
             }
             return toAcpNotifications([event.delta], "assistant", sessionId, toolUseCache, client, logger, forwardedOptions);