@agentclientprotocol/claude-agent-acp 0.89.1 → 0.89.2-preview.10

package/dist/acp-agent.js

@@ -32,7 +32,7 @@ import { ContextCompactionLifecycle, clientSupportsCompactionUpdates, contextCom
 import { clientSupportsNotices, MAX_NOTICE_TITLE_LENGTH, normalizeNoticeText, noticeOrTranscriptUpdate, sentenceCase, splitNoticeText, } from "./session-notices.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 { backgroundedBashToolCall, withRunningTerminal } 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";
@@ -280,6 +280,10 @@ const AUTONOMOUS_RESULT_ORIGINS = new Set([
     "observer",
     "observer-activity",
 ]);
+/** The foreground work of a session (see ForegroundEvents): a prompt's turn,
+ *  or a model cycle that Claude Code started on its own. At most one cycle
+ *  runs at a time, so a constant names it. */
+const AUTONOMOUS_CYCLE = "autonomous-cycle";
 /** Whether this turn's terminal result arrived but its settlement is being
  *  held for background subagents it spawned (see Turn.deferredSettle). The
  *  single spelling of the hold predicate, shared by the consumer's settle
@@ -1194,6 +1198,15 @@ export class ClaudeAcpAgent {
      * express: see {@link ToolCallClientCapabilities.v2}.
      */
     v2;
+    /** See the `foreground` constructor option. */
+    foregroundEvents;
+    /**
+     * The foreground work of each session while it runs, by the session id that
+     * the client knows. A clear-context restart replaces the Claude Code session
+     * behind that id and moves the running turn to it, so the work belongs to the
+     * id, not to a {@link Session}.
+     */
+    foregroundWork = new Map();
     /** The session index (docs/air-extensions.md, "Session index"). */
     sessionIndex = new sessionIndex.SessionIndexConnection({
         agent: this,
@@ -1203,6 +1216,7 @@ export class ClaudeAcpAgent {
     });
     constructor(client, logger, options = {}) {
         this.v2 = options.v2 ?? false;
+        this.foregroundEvents = options.foreground;
         this.sessions = {};
         this.client = new ChangedMetaClient(client, () => this.toolCallCapabilities.air.client);
         this.logger = logger ?? console;
@@ -1987,13 +2001,7 @@ export class ClaudeAcpAgent {
     async prompt(params) {
         let events;
         const outcome = new Promise((resolve, reject) => {
-            events = {
-                inserted() { },
-                awaitingUser() { },
-                resumed() { },
-                ended: resolve,
-                failed: reject,
-            };
+            events = { inserted() { }, ended: resolve, failed: reject };
         });
         await this.startTurn(params, events);
         return outcome;
@@ -2066,10 +2074,12 @@ export class ClaudeAcpAgent {
                 completeTurn = resolve;
             }),
             resolve: (outcome) => {
+                this.endForeground(params.sessionId, turn, { outcome });
                 events.ended(outcome);
                 completeTurn();
             },
             reject: (error) => {
+                this.endForeground(params.sessionId, turn, { error });
                 events.failed(error);
                 completeTurn();
             },
@@ -2387,7 +2397,7 @@ export class ClaudeAcpAgent {
         // Deliver into the running turn rather than queuing behind it as a fresh
         // prompt would.
         userMessage.priority =
-            (session.pendingUserInputCount ?? 0) > 0 ? STEER_PRIORITY_LATER : STEER_PRIORITY_NOW;
+            (session.openUserInputs?.size ?? 0) > 0 ? STEER_PRIORITY_LATER : STEER_PRIORITY_NOW;
         // Mark before the push and in the same synchronous section as the in-flight
         // check: the interrupt can have the CLI finalizing the aborted cycle by the
         // time the consumer next runs, and an unmarked result would settle the turn
@@ -2400,6 +2410,8 @@ export class ClaudeAcpAgent {
         if (turnInFlight.deferredSettle !== undefined) {
             turnInFlight.steeredSettle = turnInFlight.deferredSettle;
             turnInFlight.deferredSettle = undefined;
+            // The held turn's work had ended at its result; the steer resumes it.
+            this.startForeground(sessionId, turnInFlight);
         }
         session.input.push(userMessage);
         const firstText = params.prompt[0]?.type === "text" ? params.prompt[0].text : "";
@@ -2706,6 +2718,7 @@ export class ClaudeAcpAgent {
         const activateTurn = (turn) => {
             session.activeTurn = turn;
             session.cancelled = false;
+            session.cancelledPrompts = undefined;
             compaction.resume();
             if (turn.localCommand?.startsAtActivation)
                 ensureLocalCommandMarkdown(turn);
@@ -2742,7 +2755,7 @@ export class ClaudeAcpAgent {
             reportInserted(turn);
             // A request can already be open: Claude Code asks for a queued prompt
             // before the consumer reaches its echo.
-            this.syncAwaitingUser(session);
+            this.syncAwaitingUser(params.sessionId, session);
         };
         /** Report that Claude Code took the turn's prompt in, once. A turn can be
          *  settled by now: an echo hand-off awaits settling the previous turn, and
@@ -2752,6 +2765,7 @@ export class ClaudeAcpAgent {
                 return;
             turn.insertedReported = true;
             turn.events.inserted(turn.promptUuid);
+            this.startForeground(params.sessionId, turn);
         };
         /** Ensure there is an active turn before a user-turn result that carries no
          *  echo to activate it, by promoting the queue head. Most turns are
@@ -2776,7 +2790,7 @@ export class ClaudeAcpAgent {
          *  a stamp naming an orphaned command consumes the result outright, and a
          *  stamp naming anything else positively refutes "this is a dead turn's
          *  result", so the dup-over-loss one-skip must not eat it. */
-        const ensureActiveTurn = async (resultUserMessageUuid) => {
+        const ensureActiveTurn = async (resultUserMessageUuid, resultUserMessageUuids) => {
             if (session.activeTurn) {
                 if (!isHeldOpen(session.activeTurn)) {
                     return;
@@ -2802,8 +2816,8 @@ export class ClaudeAcpAgent {
             }
             // Orphan accounting runs BEFORE the head check: an orphan's echo-less
             // result can arrive with an EMPTY queue (the common post-cancel
-            // timeline — the active turn settled at the interrupt's idle and the
-            // user hasn't typed yet), and it must still be consumed here. Skipping
+            // timeline — the cancelled turn settled at its interrupted result and
+            // the user hasn't typed yet), and it must still be consumed here. Skipping
             // the bookkeeping when there is nothing to promote would leave a
             // phantom entry/count that swallows the next live echo-less result
             // (e.g. /compact) instead.
@@ -2872,6 +2886,14 @@ export class ClaudeAcpAgent {
                     }
                 }
             }
+            // A result that names a prompt a cancel stopped is that prompt's, even
+            // when the orphan accounting above lost track of it: the interrupt
+            // receipt leaves out a prompt that Claude Code had already taken off its
+            // queue. It must not settle the prompt sent after the cancel.
+            const stamps = resultUserMessageUuids ??
+                (resultUserMessageUuid !== undefined ? [resultUserMessageUuid] : []);
+            if (stamps.some((uuid) => session.cancelledPrompts?.has(uuid)))
+                return;
             const head = firstUnsettledQueuedTurn();
             if (!head) {
                 return;
@@ -2971,17 +2993,53 @@ export class ClaudeAcpAgent {
         };
         /** 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 });
+         *  the subagent settles (see `Turn.spawnedTaskIds`). Its requests may
+         *  already be open, and where it runs decides whether they block the
+         *  foreground work, so that is checked again. */
+        const registerLiveTask = (taskId, parentToolUseId, isSubagent, placement = {}) => {
+            session.liveBackgroundTasks.set(taskId, {
+                parentToolUseId,
+                isSubagent,
+                ...(placement.backgrounded !== undefined ? { backgrounded: placement.backgrounded } : {}),
+                ...(placement.parentTaskId !== undefined ? { parentTaskId: placement.parentTaskId } : {}),
+            });
             if (parentToolUseId)
                 forgetForegroundToolCall(session, parentToolUseId);
             session.resumableSubagents?.delete(taskId);
             if (isSubagent && session.activeTurn && !session.activeTurn.settled) {
                 (session.activeTurn.spawnedTaskIds ??= new Set()).add(taskId);
             }
+            this.syncAwaitingUser(params.sessionId, session);
+        };
+        /** Ends the display terminal of a command that went to the background, once
+         *  its task ends (see `Session.backgroundTerminals`). Claude Code reports no
+         *  exit code for it, and `completed` does not mean 0: Claude Code accepts
+         *  some non-zero codes as a success, such as grep's 1. */
+        const endBackgroundTerminal = async (taskId) => {
+            const terminal = session.backgroundTerminals?.get(taskId);
+            if (!terminal)
+                return;
+            session.backgroundTerminals.delete(taskId);
+            await sendUpdate({
+                sessionId: params.sessionId,
+                update: {
+                    sessionUpdate: "tool_call_update",
+                    toolCallId: terminal.toolCallId,
+                    _meta: {
+                        ...(terminal.parentToolUseId
+                            ? { claudeCode: { parentToolUseId: terminal.parentToolUseId } }
+                            : {}),
+                        terminal_exit: { terminal_id: terminal.toolCallId, exit_code: null, signal: null },
+                    },
+                },
+            });
+        };
+        /** Settles a task. Its request may still be open, and an agent without a
+         *  record no longer blocks the foreground work, so that is checked again. */
+        const settleLiveTask = (taskId) => {
+            settleLiveBackgroundTask(session, taskId);
+            this.syncAwaitingUser(params.sessionId, session);
         };
-        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
@@ -2990,8 +3048,9 @@ export class ClaudeAcpAgent {
             if (session.liveBackgroundTasks.has(taskId))
                 return;
             const settled = session.resumableSubagents?.get(taskId);
+            // Claude Code always resumes a subagent in the background.
             if (settled)
-                registerLiveTask(taskId, settled.parentToolUseId, true);
+                registerLiveTask(taskId, settled.parentToolUseId, true, { backgrounded: true });
         };
         /** Whether any background subagent this turn spawned is still live —
          *  while true, the turn's settlement stays deferred so the subagent's
@@ -3044,6 +3103,8 @@ export class ClaudeAcpAgent {
                 !session.activeTurn.settled &&
                 turnAwaitingSubagents(session.activeTurn)) {
                 session.activeTurn.deferredSettle = outcome;
+                // The hold delays v1's answer; the turn's work ended at its result.
+                this.endForeground(params.sessionId, session.activeTurn, { outcome });
             }
             else {
                 await settleActive(outcome);
@@ -3067,9 +3128,14 @@ export class ClaudeAcpAgent {
                 // Check only this turn's tools. A tool_result removes its id from
                 // emittedToolCalls even when its PostToolUse hook has not arrived yet.
                 const unfinished = [...(turn.foregroundToolCallIds ?? [])].filter((id) => session.emittedToolCalls.has(id) && !backgroundTools.has(id));
-                /** Closes a tool call as failed. Returns false when the turn ended meanwhile. */
-                const failToolCall = async (toolCallId, text) => {
-                    // A late hook must not overwrite the failure we are about to send.
+                const renderer = new AcpToolCallRenderer(this.toolCallCapabilities);
+                /**
+                 * Closes a tool call that the turn ended without a result for
+                 * (`AcpToolCallRenderer.unfinished`). Returns false when the turn
+                 * ended meanwhile.
+                 */
+                const closeUnfinished = async (toolCallId, ran) => {
+                    // A late hook must not overwrite the report we are about to send.
                     unregisterHookCallback(toolCallId);
                     session.emittedToolCalls.delete(toolCallId);
                     delete session.toolUseCache[toolCallId];
@@ -3077,12 +3143,7 @@ export class ClaudeAcpAgent {
                     session.dispatchedToolCalls?.delete(toolCallId);
                     await sendUpdate({
                         sessionId: params.sessionId,
-                        update: {
-                            sessionUpdate: "tool_call_update",
-                            toolCallId,
-                            status: "failed",
-                            content: [{ type: "content", content: { type: "text", text } }],
-                        },
+                        update: renderer.unfinished({ toolCallId, ran }),
                     });
                     // Cancellation can arrive while we await the client update.
                     if (turn.settled || session.activeTurn !== turn)
@@ -3099,7 +3160,7 @@ export class ClaudeAcpAgent {
                 const abandoned = unfinished.filter((id) => !session.dispatchedToolCalls?.has(id));
                 const stuck = unfinished.filter((id) => session.dispatchedToolCalls?.has(id));
                 for (const toolCallId of abandoned) {
-                    if (!(await failToolCall(toolCallId, "Claude stopped this tool call before it ran."))) {
+                    if (!(await closeUnfinished(toolCallId, false))) {
                         return;
                     }
                 }
@@ -3108,7 +3169,7 @@ export class ClaudeAcpAgent {
                     this.logger.error(`Session ${params.sessionId}, turn ${turn.promptUuid}, stopReason=${result.stopReason}: ${message}`);
                     // Fail every unfinished tool before reporting one error for the prompt.
                     for (const toolCallId of stuck) {
-                        if (!(await failToolCall(toolCallId, "Claude ended the turn without returning a result for this tool."))) {
+                        if (!(await closeUnfinished(toolCallId, true))) {
                             return;
                         }
                     }
@@ -3220,6 +3281,7 @@ export class ClaudeAcpAgent {
         /** Reject every in-flight turn — used when the stream dies. */
         const failAllTurns = (error) => {
             disarmForceCancel(session);
+            this.endAutonomousCycle(params.sessionId, { error });
             const turns = session.activeTurn
                 ? [session.activeTurn, ...(session.turnQueue ?? []).filter((t) => t !== session.activeTurn)]
                 : [...(session.turnQueue ?? [])];
@@ -3317,9 +3379,9 @@ export class ClaudeAcpAgent {
                             }
                         }
                         else if (active.commandResultSeen) {
-                            // Its result was already consumed (dropped at the cancelled
-                            // guard); only the terminal frame is outstanding, which no-ops
-                            // with no entry. Nothing to track.
+                            // Its result was already consumed (at the cancelled guard);
+                            // only the terminal frame is outstanding, which no-ops with no
+                            // entry. Nothing to track.
                         }
                         else {
                             // The wedged turn WAS dispatched (it's active), so track it
@@ -3386,6 +3448,9 @@ export class ClaudeAcpAgent {
                     // it), but the stored one is the authoritative source.
                     const inFlight = session.activeTurn;
                     await finishLifecycle(session.cancelled ? "cancelled" : "failed", session.cancelled ? "stopped" : "failed", "at end of stream");
+                    this.endAutonomousCycle(params.sessionId, session.cancelled
+                        ? { outcome: { stopReason: "cancelled" } }
+                        : { error: RequestError.internalError(undefined, SESSION_ENDED_MESSAGE) });
                     await settleActive(session.cancelled
                         ? cancelledOutcome(session, inFlight)
                         : (inFlight?.deferredSettle ?? turnOutcome(session, stopReason)));
@@ -3528,6 +3593,7 @@ export class ClaudeAcpAgent {
                     await this.publishRuntimeGoal(params.sessionId, toGoalSnapshot(activeGoal));
                     continue;
                 }
+                this.startAutonomousCycle(params.sessionId, session, message);
                 switch (message.type) {
                     case "system":
                         switch (message.subtype) {
@@ -3539,6 +3605,9 @@ export class ClaudeAcpAgent {
                                 if (message.capabilities?.includes("msg_lifecycle_v1")) {
                                     session.msgLifecycleV1 = true;
                                 }
+                                if (message.capabilities?.includes("request_marker_lists_v1")) {
+                                    session.requestMarkerListsV1 = true;
+                                }
                                 // A fresh `system`/init (e.g. after reinitialize) can carry an
                                 // updated Fast mode state; reconcile it with what we seeded at
                                 // session creation.
@@ -3574,6 +3643,24 @@ export class ClaudeAcpAgent {
                                 }
                                 break;
                             case "status": {
+                                // A model request that serves none of the prompts a cancel
+                                // stopped is new work, such as Claude Code's follow-up after a
+                                // background command finished. It comes after the stopped
+                                // work's result: Claude Code ends the interrupted turn first,
+                                // then runs any prompt it had already taken off its queue (its
+                                // request names it, so the cancel still drops it), then its own
+                                // follow-ups, whose requests name no prompt.
+                                if (message.status === "requesting" &&
+                                    session.cancelled &&
+                                    session.requestMarkerListsV1 &&
+                                    !servesCancelledWork(session, message)) {
+                                    session.cancelled = false;
+                                    session.cancelledPrompts = undefined;
+                                    // The stopped work's tail has drained, as at activation.
+                                    compaction.resume();
+                                }
+                                if (message.status === "requesting")
+                                    session.modelRequestSinceResult = true;
                                 if (message.status === "compacting") {
                                     await compaction.start(message.uuid);
                                 }
@@ -3665,6 +3752,17 @@ export class ClaudeAcpAgent {
                                     session.owedTrailingIdles = 0;
                                 }
                                 if (message.state === "idle") {
+                                    // A model cycle that Claude Code started on its own normally
+                                    // ends at its result. An idle that no earlier result owes
+                                    // means that result will not come (the stream dropped
+                                    // mid-cycle, as for a turn in issue #825), so the cycle ends
+                                    // here. An owed idle belongs to an earlier result: it can lag
+                                    // past the cycle's first output.
+                                    if (session.owedTrailingIdles === 0) {
+                                        this.endAutonomousCycle(params.sessionId, {
+                                            outcome: { stopReason: session.cancelled ? "cancelled" : "end_turn" },
+                                        });
+                                    }
                                     // A non-cancelled turn normally settled at its terminal
                                     // `result` already (issue #773), and that result recorded an
                                     // owed trailing idle — absorbed here via the decrement. We
@@ -3674,9 +3772,9 @@ export class ClaudeAcpAgent {
                                     // the time it arrives the SDK may have echoed the NEXT turn
                                     // and activated it — settling now would resolve that new
                                     // turn prematurely with end_turn and ~zero usage, dropping
-                                    // its real result. A cancelled turn relies on `idle`: its
-                                    // `result` is dropped at the `session.cancelled` guard, so
-                                    // it never settles at a result and must settle here.
+                                    // its real result. A cancelled turn settles at its
+                                    // interrupted result (at the `session.cancelled` guard); one
+                                    // whose result never came settles here.
                                     //
                                     // An idle that is NOT owed while the active turn is still
                                     // unsettled is the issue #825 signature: `idle` is the SDK's
@@ -3688,12 +3786,9 @@ export class ClaudeAcpAgent {
                                     // the turn NOW so its session/prompt gets a terminal
                                     // response, instead of leaving it hanging until the next
                                     // prompt drains the wreckage.
-                                    // A cancelled turn still consumed tokens: its dropped result
-                                    // already fed the accumulator (the usage tally at the result
-                                    // handler runs before the `session.cancelled` guard), so
-                                    // report it — clients metering spend would otherwise lose
-                                    // the interrupted turn's tokens entirely (issue #844). Zero
-                                    // when the cancel pre-empted the result (wedge/force-cancel).
+                                    // A cancelled turn reaches this with no result of its own,
+                                    // so its usage is zero (wedge/force-cancel), or, for a held
+                                    // turn, the usage its result recorded (issue #844).
                                     if (session.cancelled && session.activeTurn && !session.activeTurn.settled) {
                                         // A held turn's result passed long ago; this idle is the
                                         // trailer of the followup cycle the cancel interrupted,
@@ -3746,8 +3841,11 @@ export class ClaudeAcpAgent {
                                         // Via the subagent gate, not settleActive: a steered turn
                                         // can also have spawned background subagents, which own it
                                         // from here (settles now if none is live, holds otherwise).
+                                        const outcome = session.activeTurn.steeredSettle;
                                         const steered = session.activeTurn;
-                                        steered.deferredSettle = steered.steeredSettle;
+                                        steered.deferredSettle = outcome;
+                                        // A hold delays v1's answer; the turn's work ends here.
+                                        this.endForeground(params.sessionId, steered, { outcome });
                                         leaveSteerLane(steered);
                                         await settleDeferredIfDrained();
                                     }
@@ -3962,7 +4060,10 @@ 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.
-                                registerLiveTask(message.task_id, message.tool_use_id, !!message.subagent_type);
+                                registerLiveTask(message.task_id, message.tool_use_id, !!message.subagent_type, {
+                                    backgrounded: message.is_backgrounded,
+                                    parentTaskId: message.parent_task_id,
+                                });
                                 await subagents.taskStarted({
                                     taskId: message.task_id,
                                     toolUseId: message.tool_use_id,
@@ -4001,6 +4102,7 @@ export class ClaudeAcpAgent {
                                     // The subagent streams no more text under this parent.
                                     streamedBlocksByParent.delete(message.tool_use_id);
                                 }
+                                await endBackgroundTerminal(message.task_id);
                                 settleLiveTask(message.task_id);
                                 break;
                             case "task_updated":
@@ -4009,6 +4111,14 @@ export class ClaudeAcpAgent {
                                     break;
                                 }
                                 await asyncTasks.taskUpdated(message.task_id, message.patch);
+                                // A task moved to the background no longer blocks the tool
+                                // call that spawned it, nor its requests the foreground work.
+                                if (message.patch.is_backgrounded !== undefined) {
+                                    const task = session.liveBackgroundTasks.get(message.task_id);
+                                    if (task)
+                                        task.backgrounded = message.patch.is_backgrounded;
+                                    this.syncAwaitingUser(params.sessionId, session);
+                                }
                                 // terminal-status task_updated patch and a (deduplicated)
                                 // task_notification when a task settles, but only the patch is
                                 // guaranteed per transition — prune on it too so the registry
@@ -4021,6 +4131,7 @@ export class ClaudeAcpAgent {
                                     const parentToolUseId = session.liveBackgroundTasks.get(message.task_id)?.parentToolUseId;
                                     if (parentToolUseId)
                                         streamedBlocksByParent.delete(parentToolUseId);
+                                    await endBackgroundTerminal(message.task_id);
                                     settleLiveTask(message.task_id);
                                 }
                                 else if (message.patch.status === "running" ||
@@ -4230,6 +4341,7 @@ export class ClaudeAcpAgent {
                         }
                         break;
                     case "result": {
+                        session.modelRequestSinceResult = false;
                         // 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();
@@ -4264,7 +4376,7 @@ export class ClaudeAcpAgent {
                             // the map in that case).
                             if (!isAutonomousResult) {
                                 recordResultForOrphanCommands();
-                                await ensureActiveTurn(message.user_message_uuid);
+                                await ensureActiveTurn(message.user_message_uuid, message.user_message_uuids);
                                 // A result that names a steer consumed it (see
                                 // Turn.steeredEchoes), so the steered work is done: retire
                                 // its echo — the CLI may never have replayed it — and, with
@@ -4325,13 +4437,10 @@ export class ClaudeAcpAgent {
                             // orphan skip) and the SDK follows it with a trailing
                             // `session_state_changed: idle` — record the debt so the idle
                             // handler absorbs that idle rather than reading it as a turn the
-                            // SDK abandoned (issue #825). One exclusion: the cancelled ACTIVE
-                            // turn's own result. It is dropped at the `session.cancelled`
-                            // guard, and either the idle itself settles the turn (consuming
-                            // the trailer) or the next echo's hand-off does (which records
-                            // the debt there instead) — counting here too would double it.
-                            // Results skipped while cancelled with NO active turn — orphaned
-                            // queued turns the SDK still ran, or a force-cancelled turn's
+                            // SDK abandoned (issue #825). That includes the result of a
+                            // cancelled turn, which settles it at the `session.cancelled`
+                            // guard below. Results skipped while cancelled with NO active
+                            // turn — orphaned queued turns the SDK still ran, or a force-cancelled turn's
                             // late result after the backstop settled it — get no such settle,
                             // so their trailers must be counted here or they'd later be read
                             // as the next healthy turn being abandoned and false-fail it.
@@ -4344,20 +4453,17 @@ export class ClaudeAcpAgent {
                             // but a held turn settling AT a followup result unblocks the
                             // client at exactly that point, making the race the common
                             // case.
-                            // The cancelled-ACTIVE-turn exclusion applies only to that
-                            // turn's OWN result — a followup result arriving inside the
-                            // cancel window still gets its own trailer and must be counted,
-                            // or that idle would later false-fail the next prompt.
-                            // A second exclusion: a steered turn's own results (see
+                            // One exclusion: a steered turn's own results (see
                             // Turn.steeredEchoes). One idle covers the whole interrupted +
                             // steered sequence and that idle settles the turn, so counting
                             // either result would leave a debt that swallows it. Autonomous
                             // results inside a steered turn keep their own trailers, and so
                             // does a result that named the steer: it took the turn out of the
-                            // steer lane above and settles at the result, not the idle.
-                            const owesTrailingIdle = isAutonomousResult || !isSteering(session.activeTurn);
-                            if (owesTrailingIdle &&
-                                (isAutonomousResult || !session.cancelled || !session.activeTurn)) {
+                            // steer lane above and settles at the result, not the idle. So
+                            // does a cancelled steered turn's result, which settles it at the
+                            // `session.cancelled` guard below.
+                            const owesTrailingIdle = isAutonomousResult || !isSteering(session.activeTurn) || session.cancelled;
+                            if (owesTrailingIdle) {
                                 session.owedTrailingIdles++;
                             }
                             // Accumulate usage into the user turn's tally. Skip autonomous
@@ -4443,6 +4549,26 @@ export class ClaudeAcpAgent {
                                     }),
                                 });
                             }
+                            // A model cycle that Claude Code started on its own ends at its
+                            // result, after its usage, also after a cancel. A turn that
+                            // Claude Code takes in takes the cycle over, so a cycle that
+                            // still runs owns this result, whatever its origin says. A
+                            // placeholder result (`num_turns: 0`, see the autonomous lane
+                            // below) comes before the shared followup runs, so it ends
+                            // nothing. The diagnostic of an ExitPlanMode answer that
+                            // interrupted the cycle ends it `cancelled`, as it ends a turn,
+                            // unless a held turn continues the accepted plan in a fresh
+                            // context: that turn takes the cycle over (see the autonomous
+                            // lane below).
+                            const exitPlanInterruption = pendingExitPlanModeInterruption !== undefined &&
+                                isExitPlanInterruptionResult(message, pendingExitPlanModeInterruption);
+                            const continuesPlan = exitPlanInterruption &&
+                                isHeldOpen(session.activeTurn) &&
+                                pendingExitPlanContextReset?.toolUseId ===
+                                    pendingExitPlanModeInterruption?.toolUseId;
+                            if (!continuesPlan && !(isAutonomousResult && message.num_turns === 0)) {
+                                this.endAutonomousCycle(params.sessionId, autonomousCycleEnd(message, resultModelUsage, session.cancelled || exitPlanInterruption || isAbortedResult(message)));
+                            }
                             if (session.cancelled) {
                                 session.pendingExitPlanModeInterruption = undefined;
                                 session.pendingExitPlanContextReset = undefined;
@@ -4450,6 +4576,21 @@ export class ClaudeAcpAgent {
                                     await clearFailuresFromEarlierTurns();
                                     stopReason = "cancelled";
                                 }
+                                // The cancelled turn ends at the result of the work the
+                                // interrupt stopped: its own result, or for a turn held open
+                                // for its subagents (see Turn.deferredSettle), its follow-up's
+                                // aborted one. A follow-up result that is not aborted, such as
+                                // a placeholder or one that ended before the interrupt landed,
+                                // belongs to other work. Claude Code ends the stopped work
+                                // first, then goes on with its queue, so the idle can come
+                                // much later, after a follow-up. That idle, the next echo's
+                                // hand-off, and the force-cancel backstop settle a turn whose
+                                // result never comes.
+                                const active = session.activeTurn;
+                                const stoppedWork = !isAutonomousResult || (isHeldOpen(active) && isAbortedResult(message));
+                                if (active && !active.settled && stoppedWork) {
+                                    await settleActive(cancelledOutcome(session, active));
+                                }
                                 break;
                             }
                             // A held turn (see Turn.deferredSettle) settles at its
@@ -4486,8 +4627,11 @@ export class ClaudeAcpAgent {
                                             pendingExitPlanModeInterruption.toolUseId) {
                                         // The fresh query has none of this one's background
                                         // tasks, so the hold can never drain there: drop it, and
-                                        // let the continuation's own result settle the turn.
+                                        // let the continuation's own result settle the turn. The
+                                        // continuation is the turn's work again, which takes
+                                        // over the follow-up cycle that planned it.
                                         heldTurn.deferredSettle = undefined;
+                                        this.startForeground(params.sessionId, heldTurn);
                                         await this.exitPlan.restart(params.sessionId, session, pendingExitPlanContextReset);
                                         return;
                                     }
@@ -4754,9 +4898,10 @@ export class ClaudeAcpAgent {
                             // subagent never holds the prompt hostage.
                             //
                             // is_error/auth already settled via failActive (activeTurn is null
-                            // then, so both branches no-op); cancellation is left to the
-                            // idle/abort path. settleActive is idempotent, so a duplicate
-                            // idle is a no-op.
+                            // then, so both branches no-op); a cancelled turn settles at
+                            // the `session.cancelled` guard above, or on the idle/abort
+                            // path when its result never comes. settleActive is idempotent,
+                            // so a duplicate idle is a no-op.
                             //
                             // A result also closes this compaction lifecycle — before the
                             // settle, so a `cancelled` terminal for an entity the runtime
@@ -4955,7 +5100,7 @@ export class ClaudeAcpAgent {
                                 if (session.activeTurn !== queued) {
                                     if (session.activeTurn) {
                                         // Hand off the previous turn. If a cancel is pending for it
-                                        // (its trailing idle hasn't arrived yet), settle it
+                                        // (neither its result nor its idle has arrived), settle it
                                         // "cancelled" per the ACP contract rather than "end_turn" —
                                         // otherwise a cancel followed quickly by the next prompt
                                         // would report the cancelled turn as a normal completion.
@@ -5176,11 +5321,28 @@ export class ClaudeAcpAgent {
                         }
                         const acceptedPlanToolUseId = observeExitPlanToolResults(message, content, session);
                         let backgroundedToolCalls = new Set();
+                        let runningTerminal;
                         if (message.type === "user") {
                             rememberResolvedToolNames(session, content);
                             const backgroundBashTask = backgroundBashTaskFromToolResult(content, message.tool_use_result, session.toolUseCache);
                             if (backgroundBashTask)
                                 await asyncTasks.taskBackgrounded(backgroundBashTask);
+                            // The command's terminal runs until its task ends, unless the
+                            // task has ended already (a fast command can end before the tool
+                            // result comes).
+                            const terminalId = backgroundBashTask?.toolCallId;
+                            if (terminalId &&
+                                this.toolCallCapabilities.terminalOutput &&
+                                !this.toolCallCapabilities.air.client &&
+                                session.liveBackgroundTasks.has(backgroundBashTask.taskId)) {
+                                runningTerminal = terminalId;
+                                (session.backgroundTerminals ??= new Map()).set(backgroundBashTask.taskId, {
+                                    toolCallId: terminalId,
+                                    ...(message.parent_tool_use_id
+                                        ? { parentToolUseId: message.parent_tool_use_id }
+                                        : {}),
+                                });
+                            }
                             await asyncTasks.toolResults(content);
                             backgroundedToolCalls = backgroundedBashToolCallIds(content, session.toolUseCache, asyncTasks, backgroundBashTask);
                             const resumedAgentId = resumedNativeSubagentId(message.tool_use_result);
@@ -5211,7 +5373,7 @@ export class ClaudeAcpAgent {
                             // filtered out of `content` above; blocks that do pass through
                             // (e.g. a subagent image) carry the stamped parentToolUseId
                             // meta and are excluded there.
-                            await sendUpdate(backgroundedBashToolCall(acceptedPlanToolResult(notification, acceptedPlanToolUseId), backgroundedToolCalls, asyncTasks.enabled));
+                            await sendUpdate(withRunningTerminal(backgroundedBashToolCall(acceptedPlanToolResult(notification, acceptedPlanToolUseId), backgroundedToolCalls, asyncTasks.enabled), runningTerminal));
                         }
                         break;
                     }
@@ -5433,6 +5595,16 @@ export class ClaudeAcpAgent {
             return;
         }
         session.cancelled = true;
+        // Before anything awaits, so a model request that the consumer reads in
+        // the meantime is already judged against these prompts.
+        session.cancelledPrompts ??= new Set();
+        for (const turn of session.turnQueue ?? []) {
+            if (turn.settled)
+                continue;
+            session.cancelledPrompts.add(turn.promptUuid);
+            for (const uuid of turn.steeredUuids ?? [])
+                session.cancelledPrompts.add(uuid);
+        }
         for (const turn of session.turnQueue ?? [])
             turn.localCommandAbort?.abort();
         session.pendingExitPlanModeInterruption = undefined;
@@ -5483,9 +5655,10 @@ export class ClaudeAcpAgent {
         // never decrements the count) to miss.
         const lifecycleLane = session.msgLifecycleV1 === true;
         // Settle queued turns that haven't started yet (no echo seen) right away —
-        // they have no in-flight SDK work to interrupt. The active turn is settled
-        // by the consumer when it observes the interrupt's trailing idle (or via the
-        // backstop below). Mirrors the old pendingMessages cancellation.
+        // they have no in-flight SDK work to interrupt. The consumer settles the
+        // active turn at its interrupted result, or at the idle when that never
+        // comes (or via the backstop below). Mirrors the old pendingMessages
+        // cancellation.
         const orphanedTurns = [];
         if (session.turnQueue) {
             for (const turn of session.turnQueue) {
@@ -5571,14 +5744,19 @@ export class ClaudeAcpAgent {
         // whose session sits idle gets no trailing idle (the interrupt emits
         // nothing; with no state events consumed yet, the same is assumed).
         // A held turn whose followup cycle is live (running, or blocked on a
-        // permission request) is left to that idle, like any live turn: the
-        // interrupt still flushes the cycle's output, which must reach the client
-        // before the turn ends cancelled. The captured outcome preserves usage and
-        // metadata (issue #844), while reporter state makes a late checkpoint
-        // response harmless.
+        // permission request) is left to that cycle's interrupted result, like any
+        // live turn, or to the idle when no result comes. The captured outcome
+        // preserves usage and metadata (issue #844), while reporter state makes a
+        // late checkpoint response harmless.
+        // Since CLI 2.1.270, Claude Code reports `running` for as long as
+        // background agents live, so the session state cannot tell a live
+        // followup from a hold. With request markers, a followup is live when one
+        // of its model requests started after the turn's result.
         {
             const active = session.activeTurn;
-            const followupLive = session.lastSessionState === "running" || session.lastSessionState === "requires_action";
+            const followupLive = session.requestMarkerListsV1
+                ? session.modelRequestSinceResult === true
+                : session.lastSessionState === "running" || session.lastSessionState === "requires_action";
             if (active &&
                 (active.settling || (isHeldOpen(active) && !followupLive)) &&
                 (active.deferredSettle ?? active.settlingOutcome)) {
@@ -5618,7 +5796,7 @@ export class ClaudeAcpAgent {
             }
         }
         // A steered active turn (see Turn.steeredEchoes) settles "cancelled" in the
-        // consumer at the interrupt's trailing idle, like any live turn. But the
+        // consumer at its interrupted result, or at the idle, like any live turn. But the
         // steer lane pays for its last result's trailer by settling on it, which
         // this cancel pre-empts, so count that trailer here or it arrives un-owed
         // against the next prompt and false-fails it (issue #825). Over-counting
@@ -5649,6 +5827,10 @@ export class ClaudeAcpAgent {
         }
         // Before the interrupt: once it stops the running turn, Claude Code starts
         // the next queued message right away.
+        // A prompt or steer that arrived while this cancel awaited is abandoned
+        // too, after the record above was taken.
+        for (const uuid of abandoned)
+            (session.cancelledPrompts ??= new Set()).add(uuid);
         this.dropQueuedMessages(params.sessionId, session.query, abandoned);
         const interrupt = session.query.interrupt();
         if (!options.awaitInterrupt) {
@@ -5769,6 +5951,9 @@ export class ClaudeAcpAgent {
         catch (error) {
             this.logger.error(`Session ${sessionId}: cancellation failed during teardown`, error);
         }
+        // The turns end before this returns; so does a model cycle that Claude
+        // Code started on its own, which no turn waits for.
+        this.endAutonomousCycle(sessionId, { outcome: { stopReason: "cancelled" } });
         // cancel() arms the force-cancel floor and interrupts gracefully, but a
         // wedged consumer only wakes when `cancelController` aborts — closeQueryStream
         // below doesn't touch it. Since we're tearing the session down anyway, wake
@@ -6275,43 +6460,104 @@ export class ClaudeAcpAgent {
         const response = await this.client.writeTextFile(params);
         return response;
     }
-    /** Mark a client request as blocking on user input for exactly the lifetime
-     *  of its promise. Steering consults this session-local count synchronously,
-     *  so a message arriving while any permission/elicitation card is open uses
-     *  non-interrupting SDK delivery. The active turn reports that it awaits the
-     *  user while any such request is open (see `syncAwaitingUser`). */
-    async withPendingUserInput(sessionId, request) {
+    /** Mark a client request of the subagent `agentID` (absent for the main
+     *  conversation) as awaiting user input for exactly the lifetime of its
+     *  promise (see `Session.openUserInputs`). Steering consults the open
+     *  requests synchronously, so a message arriving while any permission or
+     *  elicitation card is open uses non-interrupting SDK delivery. */
+    async withPendingUserInput(sessionId, request, agentID) {
         const session = this.sessions[sessionId];
         if (!session)
             return request();
-        session.pendingUserInputCount = (session.pendingUserInputCount ?? 0) + 1;
-        this.syncAwaitingUser(session);
+        const input = agentID !== undefined ? { agentID } : {};
+        (session.openUserInputs ??= new Set()).add(input);
+        this.syncAwaitingUser(sessionId, session);
         try {
             return await request();
         }
         finally {
-            session.pendingUserInputCount = Math.max(0, (session.pendingUserInputCount ?? 1) - 1);
-            this.syncAwaitingUser(session);
-        }
-    }
-    /** Report whether the session's active turn awaits the user: exactly while
-     *  a permission request or question is open in the session. A request does
-     *  not say which prompt it is for, and Claude Code can ask for a queued
-     *  prompt before the consumer activates it, so a request is not tied to the
-     *  turn that was active when it opened. Called when the count changes and
-     *  when a turn activates. */
-    syncAwaitingUser(session) {
-        const turn = session.activeTurn;
-        if (!turn || turn.settled || !turn.insertedReported)
+            session.openUserInputs.delete(input);
+            this.syncAwaitingUser(sessionId, session);
+        }
+    }
+    /** Report whether the session's foreground work awaits the user: exactly
+     *  while a permission request or question that blocks it is open (see
+     *  {@link blocksForeground}). A request does not say which prompt it is for,
+     *  and Claude Code can ask for a queued prompt before the consumer activates
+     *  it, so a request is not tied to the work that was running when it
+     *  opened. Called when a request opens or closes, when a turn activates, and
+     *  when a task registers or moves to the background. */
+    syncAwaitingUser(sessionId, session) {
+        const work = this.foregroundWork.get(sessionId);
+        if (!work)
             return;
-        const waiting = (session.pendingUserInputCount ?? 0) > 0;
-        if (waiting === (turn.awaitingUser ?? false))
+        const waiting = [...(session.openUserInputs ?? [])].some((input) => blocksForeground(session, input.agentID));
+        if (waiting === work.awaitingUser)
             return;
-        turn.awaitingUser = waiting;
+        work.awaitingUser = waiting;
         if (waiting)
-            turn.events.awaitingUser();
+            work.events.awaitingUser();
+        else
+            work.events.running();
+    }
+    /** Make `owner` the foreground work of the session `sessionId` (see
+     *  {@link ForegroundEvents}): it reports `running`, then waits at once if a
+     *  request is open. If work already runs, it goes on under `owner` and
+     *  reports nothing new: a turn takes over a cycle that Claude Code started on
+     *  its own, and only the owner's end ends the work. */
+    startForeground(sessionId, owner) {
+        if (!this.foregroundEvents)
+            return;
+        const current = this.foregroundWork.get(sessionId);
+        if (current) {
+            current.owner = owner;
+            return;
+        }
+        const events = this.foregroundEvents(sessionId);
+        this.foregroundWork.set(sessionId, { owner, events, awaitingUser: false });
+        events.running();
+        const session = this.sessions[sessionId];
+        if (session)
+            this.syncAwaitingUser(sessionId, session);
+    }
+    /** End the foreground work of the session `sessionId` with `outcome`, or as
+     *  failed with `error`, if `owner` is that work. */
+    endForeground(sessionId, owner, end) {
+        const work = this.foregroundWork.get(sessionId);
+        if (work?.owner !== owner)
+            return;
+        this.foregroundWork.delete(sessionId);
+        if ("outcome" in end)
+            work.events.ended(end.outcome);
         else
-            turn.events.resumed();
+            work.events.failed(end.error);
+    }
+    /** Start a model cycle that Claude Code started on its own as the foreground
+     *  work (see {@link ForegroundEvents}) when `message` is its first output:
+     *  model output of the main conversation (not a subagent's) while no work
+     *  runs. That includes a turn that v1 holds for its background subagents,
+     *  whose work ended at its result, so its follow-up is a cycle. Output of
+     *  the work a cancel stopped starts nothing (see Session.cancelled). */
+    startAutonomousCycle(sessionId, session, message) {
+        if (!this.foregroundEvents || this.foregroundWork.has(sessionId) || session.cancelled)
+            return;
+        if (message.type !== "assistant" && message.type !== "stream_event")
+            return;
+        if (message.parent_tool_use_id !== null)
+            return;
+        // A turn that Claude Code started is the foreground work already. Without
+        // lifecycle frames, a queued turn's output can come before its echo, so
+        // output while a turn is queued may be that turn's. With them, a turn that
+        // Claude Code has not started has no output yet.
+        const queued = (session.turnQueue ?? []).some((turn) => !turn.settled && turn !== session.activeTurn);
+        if (queued && !session.msgLifecycleV1)
+            return;
+        this.startForeground(sessionId, AUTONOMOUS_CYCLE);
+    }
+    /** End the session's model cycle that Claude Code started on its own, if one
+     *  runs. */
+    endAutonomousCycle(sessionId, end) {
+        this.endForeground(sessionId, AUTONOMOUS_CYCLE, end);
     }
     /** Forward a permission request to the client, wiring the tool call's
      *  `signal` through as a `cancellationSignal`. When the turn is cancelled
@@ -6319,7 +6565,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, toolInput, previewContent) {
+    async requestPermissionFromClient(params, toolName, signal, parentToolUseId, ownerSessionId, agentID, toolInput, previewContent) {
         if (signal.aborted)
             throw new Error("Tool use aborted");
         // The SDK may invoke `canUseTool` (and therefore this permission request)
@@ -6337,7 +6583,7 @@ export class ClaudeAcpAgent {
         // The request goes to a subagent's child session for a tool call of that
         // subagent, but it blocks the turn of the owner session.
         try {
-            return await this.withPendingUserInput(ownerSessionId, () => raceWithAbort(this.client.requestPermission(params, signal), signal));
+            return await this.withPendingUserInput(ownerSessionId, () => raceWithAbort(this.client.requestPermission(params, signal), signal), agentID);
         }
         catch (error) {
             if (signal.aborted) {
@@ -6404,6 +6650,84 @@ export class ClaudeAcpAgent {
             throw error;
         }
     }
+    /**
+     * The owner of a tool use that Claude Code reports outside the stream, in
+     * `canUseTool` or a hook, for the subagent `agentID` or the root session.
+     * `parentToolUseId` is the Agent/Task tool call that spawned the subagent,
+     * as the streamed subagent path stamps it in `_meta.claudeCode` (see
+     * `liveBackgroundTasks`). `toolCallSessionId` is the session of an eagerly
+     * emitted tool call and of its requests: the subagent's child session once
+     * it is announced, else the root session. In the rare SDK ordering where
+     * the callback beats the spawning Agent/Task frame, the root keeps it; the
+     * later frame announces the child with its correct nested lineage.
+     */
+    toolUseOwner(session, sessionId, agentID) {
+        const parentToolUseId = agentID
+            ? session.liveBackgroundTasks.get(agentID)?.parentToolUseId
+            : undefined;
+        const child = clientSupportsSubagents(this.clientCapabilities) && agentID
+            ? session.nativeSubagentsByTaskId?.get(agentID)
+            : undefined;
+        return {
+            ...(parentToolUseId ? { parentToolUseId } : {}),
+            toolCallSessionId: child?.announced ? child.sessionId : sessionId,
+        };
+    }
+    /**
+     * The PreToolUse hook of a v2 connection, for Edit and Write: the tool call
+     * shows the exact patch of the change before the tool runs.
+     *
+     * A v2 diff cannot hold the input's snippet, so without it an auto-approved
+     * Edit or Write would show its change only once it is done. Claude Code runs
+     * the tool only after the hook returns, so the file is as it was before the
+     * change, as for the approval patch of a permission request (which runs
+     * after this hook, and shows the same patch). The hook makes no permission
+     * decision, and a failure only leaves the preview out.
+     */
+    fileChangePreviewHook(sessionId) {
+        return async (input, toolUseID) => {
+            if (input.hook_event_name === "PreToolUse" && toolUseID) {
+                await this.previewFileChange(sessionId, input, toolUseID).catch((error) => this.logger.error(`Session ${sessionId}: failed to preview ${toolUseID}: ${error}`));
+            }
+            return { continue: true };
+        };
+    }
+    async previewFileChange(sessionId, input, toolUseID) {
+        const session = this.sessions[sessionId];
+        if (!session)
+            return;
+        const toolInput = (input.tool_input ?? {});
+        const content = await previewPatchContent(input.tool_name, toolInput, session.cwd, "v2");
+        if (!content)
+            return;
+        const { parentToolUseId, toolCallSessionId } = this.toolUseOwner(session, sessionId, input.agent_id);
+        // Hook callbacks bypass the stream, so the hook can come before the
+        // streamed tool_use, as `canUseTool` can: then the tool call goes out
+        // with the patch.
+        if (!session.emittedToolCalls.has(toolUseID)) {
+            await this.ensureToolCallEmitted(sessionId, input.tool_name, toolUseID, toolInput, parentToolUseId, undefined, toolCallSessionId, content);
+            return;
+        }
+        const update = {
+            sessionUpdate: "tool_call_update",
+            toolCallId: toolUseID,
+            content,
+        };
+        if (parentToolUseId)
+            stampParentToolUseId(update, parentToolUseId);
+        const fields = toolCallFieldsOf(session);
+        if (!fields.apply(update))
+            return;
+        // The streamed input must not replace the patch, as for an approval patch.
+        fields.pinContent(toolUseID, content);
+        // The stream's router sends it to the session that holds the tool call.
+        if (session.nativeSubagentDeliver) {
+            await session.nativeSubagentDeliver({ sessionId, update });
+        }
+        else {
+            await this.client.sessionUpdate({ sessionId: toolCallSessionId, update });
+        }
+    }
     canUseTool(sessionId) {
         return async (toolName, toolInput, { signal, suggestions, toolUseID, agentID, matchedAskRule, blockedPath, decisionReason, title, displayName, description, defaultToNo, suppressAlwaysAllowRule, mcpServer, }) => {
             const session = this.sessions[sessionId];
@@ -6413,24 +6737,7 @@ export class ClaudeAcpAgent {
                     message: "Session not found",
                 };
             }
-            // When the tool call originates inside a subagent, attribute the eagerly
-            // emitted tool_call (and the permission request itself) to the Agent/Task
-            // tool call that spawned the subagent, mirroring the streamed subagent
-            // path's `_meta.claudeCode.parentToolUseId` (see `liveBackgroundTasks`).
-            const parentToolUseId = agentID
-                ? session.liveBackgroundTasks.get(agentID)?.parentToolUseId
-                : undefined;
-            const permissionSessionId = clientSupportsSubagents(this.clientCapabilities) && agentID
-                ? (() => {
-                    const child = session.nativeSubagentsByTaskId?.get(agentID);
-                    // A request must never target a child session before its
-                    // subagent_spawned notification. In the rare SDK ordering where
-                    // canUseTool beats the spawning Agent/Task frame, keep the
-                    // permission on the root session; the later frame will announce
-                    // the child with correct nested lineage.
-                    return child?.announced ? child.sessionId : sessionId;
-                })()
-                : sessionId;
+            const { parentToolUseId, toolCallSessionId: permissionSessionId } = this.toolUseOwner(session, sessionId, agentID);
             if (agentID && !parentToolUseId) {
                 // The attribution rests on task_started.task_id === canUseTool's
                 // agentID for subagent tasks (documented since SDK 0.3.292, which
@@ -6449,7 +6756,7 @@ export class ClaudeAcpAgent {
                 // Like permission requests, the elicitation references this toolUseID, so
                 // make sure the tool_call has surfaced to the client before we send it.
                 await this.ensureToolCallEmitted(sessionId, toolName, toolUseID, toolInput, parentToolUseId, signal, permissionSessionId);
-                return this.handleAskUserQuestion(sessionId, permissionSessionId, toolInput, toolUseID, signal);
+                return this.handleAskUserQuestion(sessionId, permissionSessionId, toolInput, toolUseID, signal, agentID);
             }
             // Do not auto-allow here based on the session's advertised mode. Claude
             // Code applies bypassPermissions before invoking canUseTool; a request
@@ -6518,7 +6825,7 @@ export class ClaudeAcpAgent {
                 ...presentation,
                 options: permissionOptions,
                 sessionId: permissionSessionId,
-            }, toolName, signal, parentToolUseId, sessionId, toolInput, previewContent);
+            }, toolName, signal, parentToolUseId, sessionId, agentID, toolInput, previewContent);
             if (signal.aborted)
                 throw new Error("Tool use aborted");
             const decodedPermission = decodeClaudePermissionResponse(response, toolName, toolInput, toolUseID, permissionOptions, durableChangeSet);
@@ -6606,7 +6913,7 @@ export class ClaudeAcpAgent {
      * The elicitation goes to `requestSessionId`, a subagent's child session for
      * a question it asks, and blocks the turn of `sessionId`.
      */
-    async handleAskUserQuestion(sessionId, requestSessionId, toolInput, toolUseID, signal) {
+    async handleAskUserQuestion(sessionId, requestSessionId, toolInput, toolUseID, signal, agentID) {
         const questions = extractAskUserQuestions(toolInput);
         if (!questions) {
             return { behavior: "deny", message: "AskUserQuestion called with no valid questions." };
@@ -6614,7 +6921,7 @@ export class ClaudeAcpAgent {
         const createRequest = askUserQuestionsToCreateRequest(questions, requestSessionId, toolUseID, this.toolCallCapabilities.air.client);
         let response;
         try {
-            response = await this.withPendingUserInput(sessionId, () => this.client.createElicitation(createRequest, signal));
+            response = await this.withPendingUserInput(sessionId, () => this.client.createElicitation(createRequest, signal), agentID);
         }
         catch (error) {
             // A cancellation we requested (signal aborted) settles as an aborted tool
@@ -7277,28 +7584,23 @@ export class ClaudeAcpAgent {
         // into the query.
         const resolvedProvider = this.resolveProviderConfig();
         const providerEnv = createEnvForProvider(resolvedProvider);
-        const configuredSettings = userProvidedOptions?.settings ??
-            (modelConfig
-                ? {
-                    ...(modelConfig.modelOverrides && { modelOverrides: modelConfig.modelOverrides }),
-                    ...(modelConfig.availableModels && { availableModels: modelConfig.availableModels }),
-                }
-                : undefined);
-        const configuredSettingsObject = typeof configuredSettings === "string"
-            ? JSON.parse(await fs.readFile(path.resolve(params.cwd, configuredSettings), "utf8"))
-            : configuredSettings;
+        const providedSettings = userProvidedOptions?.settings;
+        const providedSettingsObject = typeof providedSettings === "string"
+            ? JSON.parse(await fs.readFile(path.resolve(params.cwd, providedSettings), "utf8"))
+            : providedSettings;
+        const configuredSettingsObject = modelConfig
+            ? { ...modelConfig, ...providedSettingsObject }
+            : providedSettingsObject;
         // Claude Code applies env from settings.json after the subprocess env. Put
         // an active ACP route in the programmatic settings tier too so user/project
         // settings cannot silently restore a different ANTHROPIC_BASE_URL.
-        let settings = configuredSettings;
-        if (resolvedProvider) {
-            const baseSettings = configuredSettingsObject;
-            settings = {
-                ...baseSettings,
+        const settings = resolvedProvider
+            ? {
+                ...configuredSettingsObject,
                 apiKeyHelper: "",
-                env: { ...baseSettings?.env, ...providerEnv },
-            };
-        }
+                env: { ...configuredSettingsObject?.env, ...providerEnv },
+            }
+            : configuredSettingsObject;
         const env = {
             ...process.env,
             ...userProvidedOptions?.env,
@@ -7365,6 +7667,17 @@ export class ClaudeAcpAgent {
             tools,
             hooks: {
                 ...userProvidedOptions?.hooks,
+                // On v2, an Edit or Write shows its exact patch before it runs, also
+                // when no permission request shows it (`fileChangePreviewHook`): a v2
+                // diff cannot hold the input's snippet.
+                ...(this.v2
+                    ? {
+                        PreToolUse: [
+                            ...(userProvidedOptions?.hooks?.PreToolUse || []),
+                            { matcher: "Edit|Write", hooks: [this.fileChangePreviewHook(sessionId)] },
+                        ],
+                    }
+                    : {}),
                 PostToolUse: [
                     ...(userProvidedOptions?.hooks?.PostToolUse || []),
                     {
@@ -7853,6 +8166,30 @@ function cancelledOutcome(session, turn) {
         ...(recorded._meta ? { _meta: recorded._meta } : {}),
     };
 }
+/** Whether the model request that `status` (a `status: requesting` frame)
+ *  starts may belong to the work a cancel stopped. It may while:
+ *  - a turn is unsettled: the stopped turn, whose result is still to come, or
+ *    a queued prompt, which the cancel abandons (one that arrived while the
+ *    cancel awaited is recorded only when the cancel sweeps the queue) or
+ *    whose echo ends the cancel right after its request anyway;
+ *  - the orphan accounting still expects the result of an abandoned prompt
+ *    that Claude Code may still run, which it can fold into its own
+ *    follow-up after that follow-up's first request;
+ *  - the request serves one of {@link Session.cancelledPrompts}, as an
+ *    abandoned prompt's request does even when the interrupt receipt left it
+ *    out of the orphan accounting. */
+function servesCancelledWork(session, status) {
+    const cancelled = session.cancelledPrompts;
+    if (!cancelled)
+        return false;
+    if ((session.turnQueue ?? []).some((turn) => !turn.settled))
+        return true;
+    if ((session.pendingOrphanResults ?? 0) > 0 || (session.orphanCommands?.size ?? 0) > 0) {
+        return true;
+    }
+    const served = status.user_message_uuids;
+    return (Array.isArray(served) && served.some((uuid) => typeof uuid === "string" && cancelled.has(uuid)));
+}
 /** `_meta.quota` for a prompt response: what the turn spent, shaped like
  *  codex-acp's (snake_case container keys, camelCase counters) so a client
  *  reads one shape from either agent.
@@ -7865,16 +8202,88 @@ function cancelledOutcome(session, turn) {
  *  so the rows can total more than `token_count`. They are the fuller picture,
  *  not a decomposition of it. */
 function turnQuotaMeta(session) {
+    return quotaMeta(session.accumulatedUsage, session.accumulatedModelUsage);
+}
+/** `_meta.quota` for work that spent `usage` in its main agent loop and
+ *  `modelUsage` by model (see {@link turnQuotaMeta}). */
+function quotaMeta(usage, modelUsage) {
     return {
         quota: {
-            token_count: quotaTokenCount(session.accumulatedUsage),
-            model_usage: Object.entries(session.accumulatedModelUsage ?? {}).map(([model, usage]) => ({
+            token_count: quotaTokenCount(usage),
+            model_usage: Object.entries(modelUsage ?? {}).map(([model, usage]) => ({
                 model,
                 token_count: quotaTokenCount(usage),
             })),
         },
     };
 }
+/** Whether a request that awaits the user for the subagent `agentID` (absent
+ *  for the main conversation) blocks the session's foreground work. The main
+ *  conversation's requests do. So do those of a subagent that runs in the
+ *  foreground of the main conversation, since the tool call that spawned it
+ *  waits on it, and so on up a chain of such subagents. A request of a
+ *  subagent in the background, or nested inside one, does not: the main
+ *  conversation goes on without it. Nor does one of an agent without a
+ *  record: a teammate, a settled subagent, or one that Claude Code left out
+ *  of its background tasks and the consumer pruned, which only happens to a
+ *  subagent nested in a background one. A subagent that the main
+ *  conversation waits on has a record by the time it asks, as its
+ *  `task_started` comes first; when the consumer reads the request first, the
+ *  `task_started` checks again. */
+function blocksForeground(session, agentID) {
+    const seen = new Set();
+    for (let id = agentID; id !== undefined && !seen.has(id);) {
+        seen.add(id);
+        const task = session.liveBackgroundTasks.get(id);
+        if (!task)
+            return false;
+        if (task.backgrounded)
+            return false;
+        id = task.parentTaskId;
+    }
+    return true;
+}
+/** Whether Claude Code ended the work of `result` because an interrupt
+ *  stopped it, while the model streamed or while a tool ran. */
+function isAbortedResult(result) {
+    return (result.terminal_reason === "aborted_streaming" || result.terminal_reason === "aborted_tools");
+}
+/** How a model cycle that Claude Code started on its own ended, read from its
+ *  result as a turn's is: a refusal, the token limit, and the turn and budget
+ *  limits are their stop reasons, an error result fails the cycle, and a
+ *  cancel ends it `cancelled`. The usage and `_meta.quota` are the result's
+ *  own, `modelUsage` its increment by model, since autonomous results stay out
+ *  of the turn tally. */
+function autonomousCycleEnd(result, modelUsage, cancelled) {
+    // Typed non-null, but third-party backends have been observed omitting
+    // usage token fields (see snapshotFromUsage).
+    const tally = {
+        inputTokens: result.usage.input_tokens ?? 0,
+        outputTokens: result.usage.output_tokens ?? 0,
+        cachedReadTokens: result.usage.cache_read_input_tokens ?? 0,
+        cachedWriteTokens: result.usage.cache_creation_input_tokens ?? 0,
+    };
+    const ended = (stopReason) => ({
+        outcome: {
+            stopReason,
+            usage: { ...tally, totalTokens: tallyTotal(tally) },
+            _meta: quotaMeta(tally, modelUsage),
+        },
+    });
+    if (cancelled)
+        return ended("cancelled");
+    if (result.stop_reason === "refusal")
+        return ended("refusal");
+    if (result.stop_reason === "max_tokens")
+        return ended("max_tokens");
+    if (result.is_error) {
+        const text = result.subtype === "success" ? result.result : result.errors.join(", ") || result.subtype;
+        return { error: RequestError.internalError(undefined, text) };
+    }
+    return ended(result.subtype === "success" || result.subtype === "error_during_execution"
+        ? "end_turn"
+        : "max_turn_requests");
+}
 /** One `token_count` object. `cachedInputTokens` is cache reads, matching
  *  codex's field; Claude also reports cache writes, which codex has no slot
  *  for, so those ride along in an extra sibling (the same name the ACP `usage`