@lucascouts/claude-agent-acp-plus 0.3.0 → 0.5.0

package/dist/acp-agent.js

@@ -8,7 +8,6 @@ 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 { askUserQuestionFallbackEnabled, handleAskUserQuestionViaPermission, } from "./ask-user-question-fallback.js";
 import { agentName } from "./agent-name.js";
 import { filterDeprecatedModels } from "./model-deprecation.js";
 import { SettingsManager } from "./settings.js";
@@ -63,6 +62,87 @@ const QUERY_RECREATE_INIT_TIMEOUT_MS = 30_000;
  *  completed/stalled without the host turn resolving (issue #825). */
 const TURN_NO_RESULT_MESSAGE = "The turn ended without a result: the agent went idle while this prompt was still in flight " +
     "(e.g. the model stream dropped mid-turn). Any partial output may be incomplete; please retry.";
+/** Custom (extension) request method a client uses to steer the turn that is
+ *  currently running: the message is injected into the in-flight turn rather
+ *  than queued as a separate `session/prompt`. Named `_session/steering` per the
+ *  agreed ACP steering wire protocol; advertised to clients via the top-level
+ *  `InitializeResponse._meta.steering.supported`. */
+const STEER_METHOD = "_session/steering";
+/** How urgently the SDK delivers a steered message relative to the running
+ *  turn — an internal Claude implementation detail, not part of the wire
+ *  contract. `now` pre-empts the current generation and handles the message
+ *  immediately (interrupting a single-shot response, or slotting in between a
+ *  multi-step turn's tool calls). Maps to `SDKUserMessage.priority`; injected
+ *  steering always uses `now` so the running turn adapts as soon as possible. */
+const STEER_PRIORITY = "now";
+/** Validate raw JSON-RPC params into a {@link SteerRequest}. Kept minimal — the
+ *  content blocks are handed to `promptToClaude`, which tolerates unknown block
+ *  types — but `sessionId` and a non-empty `prompt` array are required. */
+function parseSteerRequest(params) {
+    if (!params || typeof params !== "object") {
+        throw RequestError.invalidParams(undefined, "steer params must be an object");
+    }
+    const { sessionId, prompt, _meta } = params;
+    if (typeof sessionId !== "string" || sessionId.length === 0) {
+        throw RequestError.invalidParams(undefined, "steer params require a non-empty sessionId");
+    }
+    if (!Array.isArray(prompt) || prompt.length === 0) {
+        throw RequestError.invalidParams(undefined, "steer params require a non-empty prompt array");
+    }
+    const steering = _meta && typeof _meta === "object" ? _meta.steering : undefined;
+    const idleBehavior = steering && typeof steering === "object"
+        ? steering.idleBehavior
+        : undefined;
+    if (idleBehavior !== undefined && idleBehavior !== "promptRequired") {
+        throw RequestError.invalidParams(undefined, "unsupported steering idleBehavior");
+    }
+    return {
+        sessionId,
+        prompt: prompt,
+        _meta: _meta,
+    };
+}
+/** Result-message origin kinds that mark an AUTONOMOUS cycle — work the
+ *  model did on its own (a task-notification followup, a peer/coordinator/
+ *  observer message it handled) rather than the user's prompt. Absent,
+ *  `human`, and `channel` origins are the user's own turn (this adapter's
+ *  prompts arrive as the ACP channel on some CLI configurations — ALL
+ *  channel servers are treated as user, so a foreign channel integration's
+ *  autonomously-handled result is misclassified as the user's; accepted,
+ *  see below), and `auto-continuation` continues the user's turn, so its
+ *  result is the turn's real terminal.
+ *
+ *  Deliberately fail-OPEN: an unknown future kind defaults to the user
+ *  lane. Misrouting a USER result into the autonomous lane hangs the
+ *  prompt un-detectably (the result is skipped, its trailing idle absorbed
+ *  as owed, so the #825 detector can't fire); misrouting an autonomous
+ *  result into the user lane is the bounded misattribution class this set
+ *  exists to reduce. */
+const AUTONOMOUS_RESULT_ORIGINS = new Set([
+    "task-notification",
+    "peer",
+    "coordinator",
+    "observer",
+    "observer-activity",
+]);
+/** 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
+ *  lanes and cancel(). */
+function isHeldOpen(turn) {
+    return turn != null && turn.deferredSettle !== undefined && !turn.settled;
+}
+/** Disarm the force-cancel backstop (see Session.forceCancelTimer). Every
+ *  path that settles the active turn must run this so a timer can never fire
+ *  on an already-settled turn — and must leave the field undefined, or the
+ *  arm site's !forceCancelTimer guard would refuse to arm the backstop for
+ *  the NEXT turn's cancel. */
+function disarmForceCancel(session) {
+    if (session.forceCancelTimer) {
+        clearTimeout(session.forceCancelTimer);
+        session.forceCancelTimer = undefined;
+    }
+}
 /** Compute a stable fingerprint of the session-defining params so we can
  *  detect when a loadSession/resumeSession call requires tearing down and
  *  recreating the underlying Query process.  MCP servers are sorted by name
@@ -71,6 +151,95 @@ function computeSessionFingerprint(params) {
     const servers = [...(params.mcpServers ?? [])].sort((a, b) => a.name.localeCompare(b.name));
     return JSON.stringify({ cwd: params.cwd, mcpServers: servers });
 }
+/**
+ * The single provider ID this agent exposes via `providers/*`. Claude Code has
+ * one LLM backend selected by protocol (anthropic / bedrock / vertex), so there
+ * is exactly one configurable provider.
+ */
+const PROVIDER_ID = "main";
+/**
+ * Protocols the `main` provider can be configured with. These mirror the
+ * env-var mappings understood by {@link createEnvForProvider}.
+ */
+const SUPPORTED_PROTOCOLS = ["anthropic", "bedrock", "vertex"];
+const SUBAGENT_TRANSCRIPT_CAPABILITY = "subagent-transcript";
+function supportsSubagentTranscript(capabilities) {
+    return capabilities?._meta?.[SUBAGENT_TRANSCRIPT_CAPABILITY] === true;
+}
+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;
+}
+function stripSubagentTextAndThinking(content) {
+    if (!Array.isArray(content))
+        return content;
+    return content.filter((item) => !item ||
+        typeof item !== "object" ||
+        !("type" in item) ||
+        (item.type !== "text" && item.type !== "thinking"));
+}
+/**
+ * Advance the lexer state across the fragment appended since the last delta:
+ * just enough JSON awareness (string/escape, nesting depth) to spot commas
+ * 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.
+ */
+function scanStreamedToolInput(state) {
+    let complete = false;
+    for (let index = state.scannedTo; index < state.partialJson.length; index++) {
+        const character = state.partialJson[index];
+        if (state.inString) {
+            if (state.escaped) {
+                state.escaped = false;
+            }
+            else if (character === "\\") {
+                state.escaped = true;
+            }
+            else if (character === '"') {
+                state.inString = false;
+            }
+            continue;
+        }
+        if (character === '"') {
+            state.inString = true;
+        }
+        else if (character === "{") {
+            state.objectDepth++;
+        }
+        else if (character === "}") {
+            state.objectDepth--;
+            if (state.objectDepth === 0) {
+                complete = true;
+            }
+        }
+        else if (character === "[") {
+            state.arrayDepth++;
+        }
+        else if (character === "]") {
+            state.arrayDepth--;
+        }
+        else if (character === "," && state.objectDepth === 1 && state.arrayDepth === 0) {
+            state.lastTopLevelComma = index;
+        }
+    }
+    state.scannedTo = state.partialJson.length;
+    return complete;
+}
+/** Parse the complete top-level fields before a top-level comma by closing the
+ *  object at that boundary. */
+function recoveredToolInput(prefix) {
+    try {
+        const value = JSON.parse(prefix + "}");
+        return value !== null && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function claudeCliPath() {
     if (process.env.CLAUDE_CODE_EXECUTABLE) {
         return process.env.CLAUDE_CODE_EXECUTABLE;
@@ -203,6 +372,36 @@ export function stripLocalCommandMetadata(content) {
 export function isLocalCommandMetadata(content) {
     return stripLocalCommandMetadata(content) === null;
 }
+/**
+ * True for the synthetic assistant message the CLI injects into the transcript
+ * when a turn fails authentication (e.g. "Not logged in · Please run /login",
+ * "Session expired. Please run /login to sign in again."). The `/login`
+ * instruction is Claude Code TUI-specific and meaningless to ACP clients
+ * (issue #863). The live prompt loop suppresses the text and fails the turn
+ * with `authRequired` so the client can run its own auth flow; replay must
+ * skip it too — both for parity with what the client saw live and because the
+ * message stays in the transcript forever, so it would resurface on every
+ * session/load even after the user has logged back in.
+ *
+ * Takes the API message (`message.message`), which replay only knows as
+ * `unknown`. The persisted record's structured `error: "authentication_failed"`
+ * marker is stripped by `getSessionMessages`, so the synthetic model + text is
+ * all both paths have to match on.
+ */
+export function isSyntheticLoginMessage(apiMessage) {
+    if (!apiMessage || typeof apiMessage !== "object") {
+        return false;
+    }
+    const { model, content } = apiMessage;
+    if (model !== "<synthetic>" || !Array.isArray(content) || content.length !== 1) {
+        return false;
+    }
+    const block = content[0];
+    return (!!block &&
+        block.type === "text" &&
+        typeof block.text === "string" &&
+        block.text.includes("Please run /login"));
+}
 const PERMISSION_MODE_ALIASES = {
     auto: "auto",
     default: "default",
@@ -316,6 +515,10 @@ export class ClaudeAcpAgent {
     clientCapabilities;
     logger;
     gatewayAuthRequest;
+    /** Client-managed LLM routing set via `providers/set`. Process-scoped and
+     *  never persisted to disk (see the Configurable LLM Providers RFD). When
+     *  set, it takes precedence over {@link gatewayAuthRequest}. */
+    providerConfig;
     /** Grace period before a `session/cancel` forces a wedged prompt loop to
      *  return "cancelled". See {@link DEFAULT_FORCE_CANCEL_GRACE_MS}. Mutable so
      *  tests can shrink it. */
@@ -441,6 +644,10 @@ export class ClaudeAcpAgent {
                 auth: {
                     logout: {},
                 },
+                // Client-managed LLM routing via `providers/list`, `providers/set`, and
+                // `providers/disable`. Advertised unconditionally; there is no client
+                // capability prerequisite for the provider methods.
+                providers: {},
                 loadSession: true,
                 sessionCapabilities: {
                     additionalDirectories: {},
@@ -460,6 +667,14 @@ export class ClaudeAcpAgent {
                 ...terminalAuthMethods,
                 ...(supportsGatewayAuth ? [gatewayAuthMethod, gatewayBedrockAuthMethod] : []),
             ],
+            // 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.
+            _meta: {
+                steering: {
+                    supported: true,
+                },
+            },
         };
     }
     async newSession(params) {
@@ -564,11 +779,100 @@ export class ClaudeAcpAgent {
         }
         throw new Error("Method not implemented.");
     }
+    /**
+     * `providers/list` — returns the single client-configurable custom gateway
+     * provider (`main`). `current` carries only non-secret routing (never headers,
+     * which may hold secrets); only `apiType`/`baseUrl` are surfaced for UI
+     * display, and is `null` when the provider is not configured/disabled. The
+     * provider is optional (`required: false`): while disabled/unconfigured the
+     * agent falls back to its own default routing (normal Claude login).
+     */
+    async unstable_listProviders(_params) {
+        const config = this.resolveProviderConfig();
+        const provider = {
+            providerId: PROVIDER_ID,
+            supported: SUPPORTED_PROTOCOLS,
+            required: false,
+            current: config ? { apiType: config.apiType, baseUrl: config.baseUrl } : null,
+        };
+        return { providers: [provider] };
+    }
+    /**
+     * `providers/set` — replace the full configuration for the `main` provider.
+     * Rejects unknown IDs, unsupported protocols, and empty/invalid base URLs with
+     * `invalid_params`. Config is process-scoped and applies to sessions created or
+     * loaded after this call.
+     */
+    async unstable_setProvider(params) {
+        if (params.providerId !== PROVIDER_ID) {
+            throw RequestError.invalidParams({ providerId: params.providerId }, `Unknown provider ID "${params.providerId}"; expected "${PROVIDER_ID}".`);
+        }
+        if (!SUPPORTED_PROTOCOLS.includes(params.apiType)) {
+            throw RequestError.invalidParams({ apiType: params.apiType, supported: SUPPORTED_PROTOCOLS }, `Unsupported apiType "${params.apiType}" for provider "${PROVIDER_ID}".`);
+        }
+        if (!isValidBaseUrl(params.baseUrl)) {
+            throw RequestError.invalidParams({ baseUrl: params.baseUrl }, "baseUrl must be a non-empty absolute http(s) URL.");
+        }
+        const config = {
+            apiType: params.apiType,
+            baseUrl: params.baseUrl,
+            headers: params.headers ?? {},
+        };
+        // Vertex requires project + region, which the standard payload cannot
+        // carry, so they arrive via `_meta.claudeCode.vertex`.
+        if (params.apiType === "vertex") {
+            const vertex = params._meta?.claudeCode?.vertex;
+            if (!vertex ||
+                typeof vertex.projectId !== "string" ||
+                vertex.projectId.trim() === "" ||
+                typeof vertex.region !== "string" ||
+                vertex.region.trim() === "") {
+                throw RequestError.invalidParams(undefined, "vertex apiType requires non-empty `_meta.claudeCode.vertex.projectId` and `_meta.claudeCode.vertex.region`.");
+            }
+            config.vertex = { projectId: vertex.projectId, region: vertex.region };
+        }
+        this.providerConfig = config;
+        return {};
+    }
+    /**
+     * `providers/disable` — disabling the `main` provider clears any client-managed
+     * routing (both a `providers/set` config and the legacy gateway auth request),
+     * so the agent reverts to its own default routing and `providers/list` reports
+     * `current: null`. Disabling any other (unknown) ID is treated as a successful
+     * no-op per the RFD's idempotency rule.
+     */
+    async unstable_disableProvider(params) {
+        if (params.providerId === PROVIDER_ID) {
+            this.providerConfig = undefined;
+            this.gatewayAuthRequest = undefined;
+        }
+        // Unknown provider: idempotent success.
+        return {};
+    }
+    /**
+     * Resolve the effective client-managed routing config. `providers/set` takes
+     * precedence; otherwise fall back to the legacy gateway auth request. Returns
+     * `null` when neither is configured.
+     */
+    resolveProviderConfig() {
+        if (this.providerConfig) {
+            return this.providerConfig;
+        }
+        return gatewayRequestToProviderConfig(this.gatewayAuthRequest);
+    }
     async logout(_params) {
-        // Clear in-memory gateway credentials supplied via `authenticate`. The
-        // gateway method never touches the on-disk credential store, so dropping
-        // this reference is the whole logout for that path.
+        // Clear in-memory gateway credentials supplied via `authenticate` and any
+        // provider routing set via `providers/set`. Neither touches the on-disk
+        // credential store, so dropping these references is the whole logout for
+        // those paths.
         this.gatewayAuthRequest = undefined;
+        this.providerConfig = undefined;
+        // Learned context windows are per-account state too: 1M-context
+        // entitlement is gated per org/tier, and an OAuth re-login is invisible to
+        // the env-derived provider cache key, so windows learned under the old
+        // login must not seed sessions under the next. Worst case of clearing is
+        // re-learning on each model's next turn.
+        contextWindowCache.clear();
         // For the Claude/Console login methods the credentials live in the native
         // CLI's store (keychain or config dir), which only the binary can clear.
         // `claude auth logout` is non-interactive and idempotent.
@@ -719,6 +1023,71 @@ export class ClaudeAcpAgent {
         this.ensureConsumer(session, params.sessionId);
         return response;
     }
+    /** Steer the session per the ACP steering wire protocol: inject a follow-up
+     *  message into the turn that is currently running. If that turn already
+     *  settled, the established default starts a new detached turn; Hosts may opt
+     *  into the host-owned `promptRequired` fallback through request `_meta`.
+     *
+     *  When a turn is in flight this injects (returns `injected`): unlike
+     *  `prompt()`, it does NOT create a Turn or enqueue on `turnQueue`; it pushes
+     *  an `SDKUserMessage` onto the same streaming input, which the SDK routes
+     *  into the in-flight turn. The injected message's echo carries a uuid that
+     *  matches no queued turn, so the consumer drops it as an unrelated replay
+     *  without promoting/settling anything. It is delivered at {@link
+     *  STEER_PRIORITY} (`now`) so it pre-empts the current generation (interrupting
+     *  a single-shot response, or slotting in between a multi-step turn's tool
+     *  calls). The steered message's own output streams via `session/update`, not
+     *  this response.
+     *
+     *  When the session is idle, the opt-in path returns `promptRequired` WITHOUT
+     *  calling `prompt()`, pushing SDK input, or mutating `turnQueue`: the content
+     *  stays Host-owned so the Host can submit it through a standard
+     *  `session/prompt`. Without the opt-in, the existing detached `prompt()` and
+     *  `startedNewTurn` result are preserved for compatibility. */
+    async steer(params) {
+        const sessionId = params.sessionId;
+        const session = this.sessions[sessionId];
+        if (!session) {
+            throw new Error("Session not found");
+        }
+        if (session.queryClosed) {
+            throw RequestError.internalError(undefined, SESSION_ENDED_MESSAGE);
+        }
+        // "A turn is running" = the queue holds an unsettled turn. This covers both
+        // the activated turn and one just submitted but not yet echoed/activated,
+        // which is exactly the window in which steering is meaningful. This check
+        // and the active-path push below stay in one synchronous section so the
+        // turn cannot settle in the gap between deciding to inject and enqueueing.
+        const turnInFlight = (session.turnQueue ?? []).some((turn) => !turn.settled);
+        if (!turnInFlight) {
+            const promptRequest = {
+                sessionId,
+                prompt: params.prompt,
+            };
+            if (params._meta?.steering?.idleBehavior === "promptRequired") {
+                // The opt-in path leaves the content untouched so the Host can retry via
+                // a normal session/prompt whose lifecycle owns the continuation result.
+                return { outcome: "promptRequired", reason: "noRunningTurn" };
+            }
+            // Preserve the established default for Hosts that do not opt in. This is
+            // intentionally detached for compatibility with the existing contract.
+            this.prompt(promptRequest).catch((error) => {
+                this.logger.error(`Session ${sessionId}: steered new turn failed: ${error}`);
+            });
+            return { outcome: "startedNewTurn" };
+        }
+        const promptRequest = {
+            sessionId,
+            prompt: params.prompt,
+        };
+        const userMessage = promptToClaude(promptRequest);
+        userMessage.uuid = randomUUID();
+        // Deliver into the running turn rather than queuing behind it as a fresh
+        // prompt would.
+        userMessage.priority = STEER_PRIORITY;
+        session.input.push(userMessage);
+        return { outcome: "injected" };
+    }
     /** Lazily start the per-session consumer that drains the SDK query stream for
      *  the session's whole life. Idempotent: only the first `prompt()` starts it. */
     ensureConsumer(session, sessionId) {
@@ -778,23 +1147,34 @@ export class ClaudeAcpAgent {
         // 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 = [];
+        // 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
+        // dropped at block/message boundaries; the whole map is swept when a turn
+        // settles, since an interrupted subagent stream (keyed by a
+        // parent_tool_use_id that never recurs) has no boundary event of its own.
+        const streamedToolInputs = new Map();
         // Stop reason accumulated for the active turn (result subtype, refusal,
         // max_tokens, …). Reset per turn; read when the turn settles at idle.
         let stopReason = "end_turn";
-        // How many trailing `session_state_changed: idle` messages are already
-        // accounted for: every user-turn result that terminates a turn (settle,
-        // reject, or orphan skip) is followed by one, as is a cancelled turn
-        // settled by the next turn's echo hand-off. The idle handler absorbs owed
-        // idles; an idle that arrives when NONE is owed while the active turn is
-        // still unsettled means the SDK ended the turn without ever emitting its
-        // result, so the turn will never settle on its own (issue #825).
-        // Stream-level debt, deliberately NOT reset per turn: a lagged idle can
-        // arrive after the next turn has already activated (issue #773), and the
-        // debt is what attributes it to the turn that owed it. Over-counting (an
-        // idle the SDK never emits, e.g. CLI binaries without session-state
-        // events — issue #497) is benign: the counter just absorbs one future
-        // idle, and detection degrades to the status quo rather than misfiring.
-        let owedTrailingIdles = 0;
+        /** The consumer's single send chokepoint: every `sessionUpdate` in this
+         *  loop goes through here (never `this.client.sessionUpdate` directly) so
+         *  answer-delivery tracking is a property of sending, not something each
+         *  emission site must remember. A top-level `agent_message_chunk` marks
+         *  the stretch's answer as delivered; subagent-attributed chunks are
+         *  recognizable by the `parentToolUseId` meta that toAcpNotifications
+         *  stamps from `parent_tool_use_id`, and never reach the top-level feed
+         *  as the turn's answer. */
+        const sendUpdate = async (notification) => {
+            const { update } = notification;
+            if (update.sessionUpdate === "agent_message_chunk") {
+                const claudeMeta = update._meta?.claudeCode;
+                if (!claudeMeta?.parentToolUseId) {
+                    session.emittedAssistantText = true;
+                }
+            }
+            await this.client.sessionUpdate(notification);
+        };
         const resetTurnScratch = () => {
             lastAssistantTotalUsage = null;
             lastAssistantUsage = null;
@@ -830,6 +1210,31 @@ export class ClaudeAcpAgent {
             session.activeTurn = turn;
             session.cancelled = false;
             session.pendingOrphanResults = 0;
+            session.orphanCommands?.clear();
+            // Two-phase sweep of registry entries the level signal ended (see
+            // the endedPerLevel field doc): armed at the first activation,
+            // deleted at the second — the same activation-time self-heal as the
+            // orphan lanes, and the growth bound for leaked entries whose settle
+            // bookends never arrive. The one-activation grace lets a corrective
+            // inclusive level rescue a live async agent that a racing payload
+            // absent-marked (deletion is irreversible: levels never ADD entries).
+            // Local-only commands don't advance the clock: two quick /context
+            // calls would otherwise burn the whole grace in seconds of wall time
+            // while the corrective level is still in flight, and they interact
+            // with no tasks — a later real turn still bounds growth.
+            if (!turn.isLocalOnlyCommand) {
+                for (const [taskId, record] of session.liveBackgroundTasks) {
+                    if (!record.endedPerLevel) {
+                        continue;
+                    }
+                    if (record.endedPerLevel === "sweep-armed") {
+                        session.liveBackgroundTasks.delete(taskId);
+                    }
+                    else {
+                        record.endedPerLevel = "sweep-armed";
+                    }
+                }
+            }
             resetTurnScratch();
         };
         /** Ensure there is an active turn before a user-turn result that carries no
@@ -849,18 +1254,165 @@ export class ClaudeAcpAgent {
          *  result), so we skip those and only promote once the count is drained. */
         const ensureActiveTurn = () => {
             if (session.activeTurn) {
-                return;
-            }
-            const head = (session.turnQueue ?? []).find((t) => !t.settled);
-            if (!head) {
-                return;
+                if (!isHeldOpen(session.activeTurn)) {
+                    return;
+                }
+                // A held turn (Turn.deferredSettle) already produced its result, so
+                // this incoming user-turn result cannot be its — it belongs to the
+                // next queued command (an echo-less one, e.g. `/context` sent while
+                // the hold drains; a normal prompt's echo would have handed the held
+                // turn off before its result). Settle the held turn with its
+                // recorded outcome — the user moving on outranks the hold, same
+                // contract as the echo hand-off — and fall through to promote the
+                // queue head, which this result belongs to. Without this, the head
+                // would never be promoted (echo-less turns have no other promotion
+                // path) and its prompt would hang, while this result's outcome
+                // overwrote the held turn's. Orphan lanes below are necessarily
+                // empty while a turn is held: orphans are seeded by cancel(), which
+                // inline-settles a held turn, and activation cleared older ones.
+                // settleActive also closes the held turn's delivery stretch, so the
+                // promoted command's own delivery decision is not judged against the
+                // held turn's followup text (issue #453) — the caller snapshots the
+                // flag AFTER this runs.
+                settleActive(session.activeTurn.deferredSettle);
             }
+            // 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
+            // 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.
             if ((session.pendingOrphanResults ?? 0) > 0) {
                 session.pendingOrphanResults--;
                 return;
             }
+            // msg_lifecycle_v1 lane. Attribute this echo-less result using the
+            // entries' states — turns run sequentially and frames arrive in stream
+            // order, so at any result: every "zombie" is from an already-dead turn
+            // whose own result already passed before the frame that created the
+            // newest entry (or never existed), every "started" entry was dispatched
+            // into THE turn that emitted this result (an older turn's entries got
+            // their terminal frames before a newer turn's "started" frames), and a
+            // "pending" entry was not dispatched before it. One result therefore
+            // covers ALL started and zombie entries at once (N coalesced commands
+            // share ONE result); their outstanding terminal frames then no-op on
+            // the missing entries. NOTE this ordering argument is asserted from
+            // observed CLI behavior, not a documented wire contract — if a dead
+            // turn's late result could lag past the NEXT turn's dispatch frames,
+            // deleting a zombie and a started entry on one result would
+            // double-consume it. The unexpected-transition logging in the frame
+            // handler is the tripwire for that class of drift.
+            if (session.orphanCommands?.size) {
+                let consumedOrphanResult = false;
+                let oldestPending;
+                for (const [uuid, state] of session.orphanCommands) {
+                    if (state === "started" || state === "zombie") {
+                        consumedOrphanResult = true;
+                        session.orphanCommands.delete(uuid);
+                    }
+                    else {
+                        oldestPending ??= uuid;
+                    }
+                }
+                if (consumedOrphanResult) {
+                    return;
+                }
+                if (oldestPending !== undefined) {
+                    // No dispatch was seen before this result, so it is very likely a
+                    // live turn's — but a lost "started" frame would mean it IS the
+                    // orphan's (dup-over-loss: prefer one wrong skip over
+                    // misattributing a dead turn's outcome to a live prompt). Grant
+                    // each pending entry exactly one skip, like the count lane did.
+                    session.orphanCommands.delete(oldestPending);
+                    return;
+                }
+            }
+            const head = firstUnsettledQueuedTurn();
+            if (!head) {
+                return;
+            }
             activateTurn(head);
         };
+        /** Result-time bookkeeping that must run whether or not the result can be
+         *  attributed to a turn. (1) Latch `commandResultSeen` on every queued
+         *  turn whose command is known dispatched with no terminal frame yet —
+         *  the emitting turn is the one it was dispatched (possibly folded) into,
+         *  so its result has now passed; a later cancel() must not seed an orphan
+         *  entry that waits for it (see Turn.commandResultSeen). (2) When a turn
+         *  is ACTIVE, the result is attributed to it and never reaches
+         *  ensureActiveTurn — but it still covers the map's started entries
+         *  (commands folded into the active turn share its result) and zombies
+         *  (their late results have already passed or never existed), so drain
+         *  them here or they would zombify/linger and swallow a later live
+         *  echo-less result. */
+        const recordResultForOrphanCommands = () => {
+            for (const turn of session.turnQueue ?? []) {
+                if (!turn.settled && turn.commandStarted && !turn.commandFinished) {
+                    turn.commandResultSeen = true;
+                }
+            }
+            if (session.activeTurn && session.orphanCommands?.size) {
+                for (const [uuid, state] of session.orphanCommands) {
+                    if (state === "started" || state === "zombie") {
+                        session.orphanCommands.delete(uuid);
+                    }
+                }
+            }
+        };
+        /** The unsettled in-flight turn owning this prompt uuid, if any. */
+        const findUnsettledTurn = (uuid) => (session.turnQueue ?? []).find((t) => t.promptUuid === uuid && !t.settled);
+        /** The first queued turn still awaiting its outcome, if any — the single
+         *  spelling of "a prompt is pending" shared by the head promotion and
+         *  the autonomous stretch-close guard. */
+        const firstUnsettledQueuedTurn = () => (session.turnQueue ?? []).find((t) => !t.settled);
+        /** 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
+         *  Turn.deferredSettle). */
+        const turnAwaitingSubagents = (turn) => {
+            if (!turn.spawnedTaskIds?.size) {
+                return false;
+            }
+            for (const taskId of turn.spawnedTaskIds) {
+                const record = session.liveBackgroundTasks.get(taskId);
+                // The isSubagent read is defense in depth for the shells-never-defer
+                // contract: spawnedTaskIds only ever holds subagent ids today, but a
+                // future add site must not silently let a long-lived shell hold a
+                // prompt open. endedPerLevel entries are kept for attribution only —
+                // the level signal says the task is gone (or its bookends were
+                // lost), so a hold must not wait on them.
+                if (record?.isSubagent && !record.endedPerLevel) {
+                    return true;
+                }
+            }
+            return false;
+        };
+        /** Settle the active turn's stored deferred outcome once none of its
+         *  spawned subagents is live. The single drain rule shared by the
+         *  followup-result and idle settle sites, so the two lanes can't drift. */
+        const settleDeferredIfDrained = () => {
+            const turn = session.activeTurn;
+            if (isHeldOpen(turn) && !turnAwaitingSubagents(turn)) {
+                settleActive(turn.deferredSettle);
+            }
+        };
+        /** Settle the active turn with `outcome` now — unless subagents it
+         *  spawned are still live, in which case store the outcome and hold the
+         *  turn open (see Turn.deferredSettle). Every result-time settle of a
+         *  turn that can have spawned subagents must route through here: a site
+         *  calling settleActive directly bypasses the hold and re-opens the
+         *  out-of-turn permission deadlock (issue #866) through its lane. */
+        const settleOrDefer = (outcome) => {
+            if (session.activeTurn &&
+                !session.activeTurn.settled &&
+                turnAwaitingSubagents(session.activeTurn)) {
+                session.activeTurn.deferredSettle = outcome;
+            }
+            else {
+                settleActive(outcome);
+            }
+        };
         /** Settle the active turn's deferred exactly once, disarm the force-cancel
          *  backstop (the turn is over), and drop it from the queue. */
         const settleActive = (result) => {
@@ -868,22 +1420,34 @@ export class ClaudeAcpAgent {
             if (!turn || turn.settled) {
                 return;
             }
+            // Captured before the settled flip below (isHeldOpen tests !settled).
+            const wasHeld = isHeldOpen(turn);
             turn.settled = true;
-            if (session.forceCancelTimer) {
-                clearTimeout(session.forceCancelTimer);
-                session.forceCancelTimer = undefined;
-            }
+            disarmForceCancel(session);
             session.turnQueue = (session.turnQueue ?? []).filter((t) => t !== turn);
             session.activeTurn = null;
+            streamedToolInputs.clear();
+            if (wasHeld) {
+                // Settling a held turn is its delivery-stretch boundary: the turn's
+                // answer finished long ago, so text streamed since the last boundary
+                // is normally its followups' — left latched it would suppress a
+                // following replayed turn's issue-#453 result-text fallback (the
+                // common post-hold sequence). Known trade: at the echo hand-off an
+                // incoming turn's pre-echo deltas share this one boolean, so a
+                // STREAMING replay on a usage-omitting backend could re-emit its
+                // answer — the flag cannot attribute text to a turn before its
+                // echo, and the suppression direction is the common one, so the
+                // clear wins. Every held-settle lane inherits this: the drain
+                // settle, both hand-offs, and stream-done; cancel()'s inline mirror
+                // carries its own copy.
+                session.emittedAssistantText = false;
+            }
             turn.resolve(result);
         };
         /** Reject the active turn (auth required, error result, …) without tearing
          *  down the consumer: the stream continues to idle and later turns proceed. */
         const failActive = (error) => {
-            if (session.forceCancelTimer) {
-                clearTimeout(session.forceCancelTimer);
-                session.forceCancelTimer = undefined;
-            }
+            disarmForceCancel(session);
             const turn = session.activeTurn;
             if (!turn || turn.settled) {
                 return;
@@ -891,14 +1455,17 @@ export class ClaudeAcpAgent {
             turn.settled = true;
             session.turnQueue = (session.turnQueue ?? []).filter((t) => t !== turn);
             session.activeTurn = null;
+            streamedToolInputs.clear();
+            // A failed turn's stretch is over, and some failure lanes (the issue
+            // #825 idle-fail) never see the result whose `finally` would close it —
+            // start the next stretch clean, or its stale delivery record would
+            // suppress the next turn's issue-#453 result-text fallback.
+            session.emittedAssistantText = false;
             turn.reject(error);
         };
         /** Reject every in-flight turn — used when the stream dies. */
         const failAllTurns = (error) => {
-            if (session.forceCancelTimer) {
-                clearTimeout(session.forceCancelTimer);
-                session.forceCancelTimer = undefined;
-            }
+            disarmForceCancel(session);
             const turns = session.activeTurn
                 ? [session.activeTurn, ...(session.turnQueue ?? []).filter((t) => t !== session.activeTurn)]
                 : [...(session.turnQueue ?? [])];
@@ -906,8 +1473,18 @@ export class ClaudeAcpAgent {
             session.turnQueue = [];
             for (const turn of turns) {
                 if (!turn.settled) {
+                    const wasHeld = isHeldOpen(turn);
                     turn.settled = true;
-                    turn.reject(error);
+                    if (wasHeld) {
+                        // A held turn's answer already streamed and its outcome is
+                        // recorded — a stream death during the post-answer hold is a
+                        // background failure, not the turn's. Resolve with the real
+                        // outcome, mirroring the stream-done path.
+                        turn.resolve(turn.deferredSettle);
+                    }
+                    else {
+                        turn.reject(error);
+                    }
                 }
             }
         };
@@ -961,9 +1538,45 @@ export class ClaudeAcpAgent {
                     // turn being abandoned. Stale counts self-heal: activation resets
                     // them (see activateTurn).
                     if (session.activeTurn && !session.activeTurn.settled) {
-                        session.pendingOrphanResults = (session.pendingOrphanResults ?? 0) + 1;
+                        // Seed by what the frames already told us, mirroring cancel()'s
+                        // queued-turn sweep — the consumer may have drained the wedged
+                        // turn's result and/or terminal frame before the backstop fired,
+                        // and an entry seeded for a result or frame that is already
+                        // spent would never drain (it would swallow an unrelated later
+                        // echo-less result instead).
+                        const active = session.activeTurn;
+                        if (active.commandFinished === "completed" || active.commandFinished === "discarded") {
+                            // Finished SDK-side; any result already passed. Nothing to
+                            // track.
+                        }
+                        else if (active.commandFinished === "cancelled") {
+                            // Aborted after dispatch: its late result may still come —
+                            // unless it already did.
+                            if (!active.commandResultSeen) {
+                                this.trackOrphanCommand(session, active.promptUuid, "zombie");
+                            }
+                        }
+                        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.
+                        }
+                        else {
+                            // The wedged turn WAS dispatched (it's active), so track it
+                            // "started": its late result (if the SDK recovers) is skipped
+                            // echo-less, and its terminal frame — or that skip plus
+                            // activation's clear when the frame is lost to the wedge — is
+                            // what drains it.
+                            this.trackOrphanCommand(session, active.promptUuid, "started");
+                        }
                     }
                     settleActive({ stopReason: "cancelled", usage: sessionUsage(session) });
+                    // The cancelled turn's result may never come (that's why the
+                    // backstop fired) — close its delivery stretch here so partial
+                    // streamed text can't suppress the next turn's issue-#453 fallback.
+                    // If a late orphan result does arrive, its `finally` clears again;
+                    // FIFO ordering means no live turn's text can have streamed yet.
+                    session.emittedAssistantText = false;
                     // If the session is being torn down — or this consumer was
                     // superseded by a lazy query recreate — abandon the in-flight
                     // next() (swallowing any later rejection so it can't surface as
@@ -999,11 +1612,15 @@ export class ClaudeAcpAgent {
                     // turn's real outcome.
                     //
                     // Settle the turn that was in flight so its prompt() doesn't hang:
-                    // cancelled if a cancel is pending, otherwise the accumulated outcome.
-                    settleActive({
-                        stopReason: session.cancelled ? "cancelled" : stopReason,
-                        usage: sessionUsage(session),
-                    });
+                    // cancelled if a cancel is pending, otherwise the outcome a
+                    // deferred turn already recorded (see Turn.deferredSettle) or the
+                    // accumulated scratch outcome. The scratch currently still equals
+                    // a deferred turn's stored outcome (followup results never mutate
+                    // it), but the stored one is the authoritative source.
+                    const inFlight = session.activeTurn;
+                    settleActive(session.cancelled
+                        ? { stopReason: "cancelled", usage: sessionUsage(session) }
+                        : (inFlight?.deferredSettle ?? { stopReason, usage: sessionUsage(session) }));
                     // Queued turns the SDK never started never ran, so reject them rather
                     // than reporting a success (end_turn) — or a misleading "cancelled" —
                     // for a prompt that produced no output. (A cancel already settled the
@@ -1030,19 +1647,116 @@ export class ClaudeAcpAgent {
                         message: message,
                     });
                 }
+                // CLIs 2.1.206+ (capability msg_lifecycle_v1) report the fate of every
+                // uuid-stamped queued command (queued/started/completed/cancelled/
+                // discarded) as `command_lifecycle` frames — 2-3 per prompt, since
+                // prompt() stamps a uuid on every message. The frame is @internal and
+                // absent from the SDKMessage union, so handle it BEFORE the exhaustive
+                // switch: it must not reach `unreachable`'s error log, and a `case`
+                // for it wouldn't typecheck. It feeds only the orphan accounting (see
+                // Session.orphanCommands); turn settlement stays driven by
+                // echoes/results/idle. (Raw-mode emission above still forwards these
+                // frames.)
+                if (message.type === "command_lifecycle") {
+                    const frame = message;
+                    switch (frame.state) {
+                        case "started": {
+                            // Remember dispatch on the live turn so a cancel() that orphans
+                            // it seeds the right state (see Turn.commandStarted)...
+                            const queued = findUnsettledTurn(frame.command_uuid);
+                            if (queued) {
+                                queued.commandStarted = true;
+                            }
+                            // ...and promote an already-orphaned command: once dispatched,
+                            // a bare `cancelled` no longer means "dropped without running".
+                            const state = session.orphanCommands?.get(frame.command_uuid);
+                            if (state === "pending") {
+                                session.orphanCommands.set(frame.command_uuid, "started");
+                            }
+                            else if (state === "zombie") {
+                                // "started" after the command's terminal frame: the ordering
+                                // the whole lane rests on has been violated (frames are
+                                // per-uuid FIFO). Surface it — a silent drift here degrades
+                                // into swallowed or misattributed results.
+                                this.logger.error(`Session ${params.sessionId}: command_lifecycle "started" for ${frame.command_uuid} after its terminal frame; orphan accounting may be off for this cancel.`);
+                            }
+                            break;
+                        }
+                        case "completed":
+                        case "discarded":
+                        case "cancelled": {
+                            // Terminal frames. Latch the fate on a still-queued turn so a
+                            // later cancel() doesn't seed an orphan entry for a command
+                            // whose one-and-only terminal frame has already been consumed
+                            // (nothing would ever drain that entry).
+                            const queued = findUnsettledTurn(frame.command_uuid);
+                            if (queued) {
+                                queued.commandFinished = frame.state;
+                            }
+                            if (frame.state === "cancelled") {
+                                // Ambiguous by design (dup-over-loss): dropped before
+                                // dispatch (no result will ever come — safe to forget) vs
+                                // consumed into a turn that was aborted/failed. For the
+                                // latter, any result the dead turn managed to emit has
+                                // already deleted the entry (see
+                                // recordResultForOrphanCommands / ensureActiveTurn), so a
+                                // still-"started" entry means no result was seen since
+                                // dispatch — it becomes a zombie for the next
+                                // echo-less-result skip.
+                                const state = session.orphanCommands?.get(frame.command_uuid);
+                                if (state === "pending") {
+                                    session.orphanCommands?.delete(frame.command_uuid);
+                                }
+                                else if (state === "started") {
+                                    session.orphanCommands?.set(frame.command_uuid, "zombie");
+                                }
+                                break;
+                            }
+                            // Exactly-one-terminal: the command is finished. "completed" is
+                            // emitted after any result its turn produced (fresh turn) or the
+                            // command folded into another turn whose result is attributed
+                            // elsewhere — either way no echo-less result remains to skip.
+                            // "discarded" = session ended with it still queued; no result.
+                            session.orphanCommands?.delete(frame.command_uuid);
+                            break;
+                        }
+                        default:
+                            // "queued" carries no fate information. Anything else is a
+                            // state this adapter doesn't know — likely a CLI that grew the
+                            // v1 vocabulary. The entry still drains by result coverage or
+                            // activation's clear (bounded damage), but log it so the
+                            // degradation is visible instead of silent.
+                            if (frame.state !== "queued") {
+                                this.logger.error(`Session ${params.sessionId}: unknown command_lifecycle state "${frame.state}" for ${frame.command_uuid}; treating as uninformative.`);
+                            }
+                            break;
+                    }
+                    continue;
+                }
                 switch (message.type) {
                     case "system":
                         switch (message.subtype) {
                             case "init":
+                                // Latch the lifecycle capability so cancel() routes orphan
+                                // accounting through `orphanCommands` (per-uuid, exact)
+                                // instead of the coalescing-blind count. Never unlatch: init
+                                // re-emits per turn and the capability can't be lost mid-CLI.
+                                if (message.capabilities?.includes("msg_lifecycle_v1")) {
+                                    session.msgLifecycleV1 = 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.
-                                await this.syncFastModeState(message.session_id, session, message.fast_mode_state);
+                                await this.syncFastModeState(message.session_id, session, message.fast_mode_state, message.fast_mode_disabled_reason);
                                 break;
                             case "status": {
+                                // These banners count as delivered text (via sendUpdate), so
+                                // an echo-less turn that only ever emits them (e.g. `/compact`,
+                                // promoted at its own result) doesn't have its result text
+                                // re-emitted by the issue-#453 fallback.
                                 if (message.status === "compacting") {
                                     compactionInProgress = true;
-                                    await this.client.sessionUpdate({
+                                    await sendUpdate({
                                         sessionId: message.session_id,
                                         update: {
                                             sessionUpdate: "agent_message_chunk",
@@ -1055,7 +1769,7 @@ export class ClaudeAcpAgent {
                                     // message carrying `compact_result`, not the `compact_boundary`
                                     // message (which only fires when there's content to compact).
                                     compactionInProgress = false;
-                                    await this.client.sessionUpdate({
+                                    await sendUpdate({
                                         sessionId: message.session_id,
                                         update: {
                                             sessionUpdate: "agent_message_chunk",
@@ -1066,7 +1780,7 @@ export class ClaudeAcpAgent {
                                 else if (message.compact_result === "failed" && compactionInProgress) {
                                     compactionInProgress = false;
                                     const reason = message.compact_error ? `: ${message.compact_error}` : ".";
-                                    await this.client.sessionUpdate({
+                                    await sendUpdate({
                                         sessionId: message.session_id,
                                         update: {
                                             sessionUpdate: "agent_message_chunk",
@@ -1091,9 +1805,9 @@ export class ClaudeAcpAgent {
                                 // dropped dramatically) and replaced within seconds by the next
                                 // result message.
                                 //
-                                // `size` keeps coming from session.contextWindowSize (learned
-                                // from modelUsage / the model heuristic) — getContextUsage's
-                                // window field under-reports extended 1M windows.
+                                // `size` keeps coming from session.contextWindowSize —
+                                // compaction frees occupancy, it doesn't change the model's
+                                // window.
                                 //
                                 // The "Compacting completed." text is emitted from the `status`
                                 // handler (keyed on `compact_result`), not here, so the failure
@@ -1101,7 +1815,7 @@ export class ClaudeAcpAgent {
                                 const usedTokens = await fetchContextUsedTokens(session.query, this.logger);
                                 lastAssistantUsage = null;
                                 lastAssistantTotalUsage = usedTokens ?? 0;
-                                await this.client.sessionUpdate({
+                                await sendUpdate({
                                     sessionId: message.session_id,
                                     update: {
                                         sessionUpdate: "usage_update",
@@ -1112,7 +1826,7 @@ export class ClaudeAcpAgent {
                                 break;
                             }
                             case "local_command_output": {
-                                await this.client.sessionUpdate({
+                                await sendUpdate({
                                     sessionId: message.session_id,
                                     update: {
                                         sessionUpdate: "agent_message_chunk",
@@ -1122,6 +1836,7 @@ export class ClaudeAcpAgent {
                                 break;
                             }
                             case "session_state_changed": {
+                                session.lastSessionState = message.state;
                                 if (message.state === "idle") {
                                     // A non-cancelled turn normally settled at its terminal
                                     // `result` already (issue #773), and that result recorded an
@@ -1154,14 +1869,38 @@ export class ClaudeAcpAgent {
                                     // when the cancel pre-empted the result (wedge/force-cancel).
                                     if (session.cancelled && session.activeTurn && !session.activeTurn.settled) {
                                         settleActive({ stopReason: "cancelled", usage: sessionUsage(session) });
+                                        // An interrupt can pre-empt the turn's result entirely
+                                        // (nothing ran the result-case `finally`), so close the
+                                        // delivery stretch here: idle is the SDK's authoritative
+                                        // turn-over signal, and stale partial-text state would
+                                        // suppress the next turn's issue-#453 fallback.
+                                        session.emittedAssistantText = false;
+                                    }
+                                    else if (isHeldOpen(session.activeTurn)) {
+                                        // A turn held open for its background subagents (see
+                                        // Turn.deferredSettle). Idles keep their normal cadence
+                                        // during the hold — the CLI emits one per processing
+                                        // cycle (the turn's own trailer, then one per followup),
+                                        // NOT one final "all drained" signal — so each one
+                                        // absorbs an outstanding trailer debt, and the turn only
+                                        // settles once none of its spawned subagents is left
+                                        // (the followup-result settle usually got there first;
+                                        // this is the fallback when no followup came). Mid-hold
+                                        // idles never fall through: a held turn HAS its result,
+                                        // so reading its idle as "turn abandoned without a
+                                        // result" (issue #825) would fail a healthy prompt.
+                                        if (session.owedTrailingIdles > 0) {
+                                            session.owedTrailingIdles--;
+                                        }
+                                        settleDeferredIfDrained();
                                     }
-                                    else if (owedTrailingIdles > 0) {
+                                    else if (session.owedTrailingIdles > 0) {
                                         // Absorb a settled turn's trailing idle. Also covers a
                                         // cancel that landed between a turn's counted result and
                                         // this lagged idle (no active turn to settle): the idle
                                         // still belongs to that settled turn, and skipping the
                                         // decrement would leak the debt permanently.
-                                        owedTrailingIdles--;
+                                        session.owedTrailingIdles--;
                                     }
                                     else if (!session.cancelled &&
                                         session.activeTurn &&
@@ -1203,7 +1942,7 @@ export class ClaudeAcpAgent {
                                 const title = isSynthesis
                                     ? "Recalled synthesized memory"
                                     : `Recalled ${count} ${count === 1 ? "memory" : "memories"}`;
-                                await this.client.sessionUpdate({
+                                await sendUpdate({
                                     sessionId: message.session_id,
                                     update: {
                                         sessionUpdate: "tool_call",
@@ -1227,10 +1966,10 @@ export class ClaudeAcpAgent {
                                 // Push the full slash-command list after a mid-session change
                                 // (e.g. skills discovered dynamically as the agent works in a
                                 // subdirectory). The client should REPLACE its cached command
-                                // list with this payload: supportedCommands() is captured once
-                                // at initialize and never reflects mid-session changes, so we
-                                // forward message.commands directly rather than re-querying.
-                                await this.client.sessionUpdate({
+                                // list with this payload. Forward message.commands directly —
+                                // it's authoritative, and re-querying supportedCommands()
+                                // would just return the same list with an extra round-trip.
+                                await sendUpdate({
                                     sessionId: message.session_id,
                                     update: {
                                         sessionUpdate: "available_commands_update",
@@ -1253,8 +1992,30 @@ export class ClaudeAcpAgent {
                                 // already emitted as a `tool_call`, so mark it failed with the
                                 // rejection reason — otherwise the client shows a tool call
                                 // that silently never resolves.
+                                //
+                                // The id is the executing call's own, and the frame lands
+                                // between its `tool_use` and its `tool_result` (the SDK enqueues
+                                // it from inside canUseTool), so the call is normally in flight
+                                // here. Not always: the assistant message carrying the tool_use
+                                // is dropped by the cancelled-turn guard below, and a denial for
+                                // it can still arrive afterwards — the case the `tool_result`
+                                // fallback in `toAcpNotifications` gates on `wasEmitted` for.
+                                // Drop the update rather than reference a tool call the client
+                                // was never given (see `ensureToolCallEmitted`, issue #851).
+                                if (!session.emittedToolCalls.has(message.tool_use_id)) {
+                                    break;
+                                }
+                                // A denial inside a subagent identifies the subagent by
+                                // `agent_id` (as canUseTool does with `agentID`), never by the
+                                // Agent/Task call that spawned it. Resolve it the same way so
+                                // the update lands in the subagent's transcript alongside the
+                                // `tool_call` it resolves, which carries the parent stamped from
+                                // `parent_tool_use_id` (see `liveBackgroundTasks`).
+                                const parentToolUseId = message.agent_id
+                                    ? session.liveBackgroundTasks.get(message.agent_id)?.parentToolUseId
+                                    : undefined;
                                 const reason = message.decision_reason ?? message.message;
-                                await this.client.sessionUpdate({
+                                await sendUpdate({
                                     sessionId: message.session_id,
                                     update: {
                                         sessionUpdate: "tool_call_update",
@@ -1269,6 +2030,7 @@ export class ClaudeAcpAgent {
                                         _meta: {
                                             claudeCode: {
                                                 toolName: message.tool_name,
+                                                ...(parentToolUseId ? { parentToolUseId } : {}),
                                                 toolResponse: {
                                                     decisionReasonType: message.decision_reason_type,
                                                     decisionReason: message.decision_reason,
@@ -1286,10 +2048,14 @@ export class ClaudeAcpAgent {
                                 // instead of a silent stop. ACP's agent_message_chunk has no
                                 // severity field, so fold the level into the text for the more
                                 // prominent levels ('info' is transcript-only noise — leave plain).
+                                // Sending via sendUpdate also marks the notice as this stretch's
+                                // delivered text: a hook-blocked turn's result repeats the block
+                                // reason with zero output tokens, and the issue-#453 fallback
+                                // must not emit it a second time.
                                 const text = message.level === "info"
                                     ? message.content
                                     : `**${message.level[0].toUpperCase()}${message.level.slice(1)}:** ${message.content}`;
-                                await this.client.sessionUpdate({
+                                await sendUpdate({
                                     sessionId: message.session_id,
                                     update: {
                                         sessionUpdate: "agent_message_chunk",
@@ -1302,16 +2068,51 @@ export class ClaudeAcpAgent {
                             case "hook_progress":
                             case "hook_response":
                             case "files_persisted":
+                            case "task_progress":
+                                break;
                             case "task_started":
+                                // For subagent tasks `task_id` is the subagent's agent id (the
+                                // SDK keys its task registry by agent id) and `tool_use_id` is
+                                // the Agent/Task tool_use that spawned it — recorded so the
+                                // subagent's permission requests, which reach canUseTool with
+                                // only `agentID`, can attribute their eagerly-emitted
+                                // tool_call to the parent tool call. Non-subagent tasks (e.g.
+                                // background Bash) land here too; their task_ids never match
+                                // an agentID, so those entries are inert for attribution.
+                                //
+                                // `isSubagent` marks Task/Agent-tool subagents — the tasks
+                                // whose completion wakes the model for a followup, so the
+                                // ones worth deferring turn settlement for. A sync subagent
+                                // is pruned (terminal task_updated) before its turn's result
+                                // can arrive, so registry membership at result time means an
+                                // async subagent. Their spawn is also recorded on the active
+                                // 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,
+                                });
+                                if (message.subagent_type && session.activeTurn && !session.activeTurn.settled) {
+                                    (session.activeTurn.spawnedTaskIds ??= new Set()).add(message.task_id);
+                                }
+                                break;
                             case "task_notification":
-                            case "task_progress":
+                                // The task settled — no further tool calls can originate
+                                // from it, so its registry entry can be dropped.
+                                session.liveBackgroundTasks.delete(message.task_id);
+                                break;
                             case "task_updated":
-                            case "background_tasks_changed":
-                            case "control_request_progress":
-                                // `background_tasks_changed` is a level signal of live background
-                                // tasks; this adapter drives lifecycle off the task edge bookends.
-                                // `control_request_progress` only reports on side_question control
-                                // requests, which this adapter never issues.
+                                // 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
+                                // can't grow for the session's lifetime if a notification is
+                                // skipped.
+                                if (message.patch.status === "completed" ||
+                                    message.patch.status === "failed" ||
+                                    message.patch.status === "killed") {
+                                    session.liveBackgroundTasks.delete(message.task_id);
+                                }
                                 break;
                             case "worker_shutting_down":
                                 // A Remote Control worker announced a graceful teardown. This is a
@@ -1363,7 +2164,7 @@ export class ClaudeAcpAgent {
                                 const outcome = persistent
                                     ? `The session will continue on ${message.fallback_model}.`
                                     : `The session stays on ${message.original_model}.`;
-                                await this.client.sessionUpdate({
+                                await sendUpdate({
                                     sessionId: message.session_id,
                                     update: {
                                         sessionUpdate: "agent_message_chunk",
@@ -1397,183 +2198,357 @@ export class ClaudeAcpAgent {
                                     lastRefusalExplanation = message.api_refusal_explanation ?? message.content;
                                 }
                                 break;
+                            // `control_request_progress` only reports on side_question
+                            // control requests, which this adapter never issues.
+                            case "control_request_progress":
+                                break;
+                            case "background_tasks_changed":
+                                // A level signal: the full live background-task set on every
+                                // membership change, with REPLACE semantics. Used only to
+                                // reconcile `liveBackgroundTasks` — dropping (or, for
+                                // subagent entries, unpinning) any entry whose settle
+                                // bookend (task_notification / terminal task_updated) was
+                                // lost, so a leaked subagent entry can't defer its spawning
+                                // turn's settlement forever. Growth of retained
+                                // (endedPerLevel) subagent entries is bounded by the
+                                // activation-time sweep in activateTurn, not here. It never
+                                // ADDS entries (the payload carries no attribution or
+                                // subagent marker), so the unspecified ordering vs. the edge
+                                // bookends is safe: a level that precedes its task_started
+                                // simply no-ops here.
+                                if (session.liveBackgroundTasks.size > 0) {
+                                    const live = new Set(message.tasks.map((t) => t.task_id));
+                                    for (const [taskId, record] of session.liveBackgroundTasks) {
+                                        if (live.has(taskId)) {
+                                            // The level proves the task live in the background
+                                            // universe (e.g. a foreground agent was backgrounded
+                                            // after an earlier absent-marking, or that marking was
+                                            // a racing payload built before the task registered) —
+                                            // un-end it so a hold waits on it again, and disarm
+                                            // the activation sweep.
+                                            record.endedPerLevel = undefined;
+                                            continue;
+                                        }
+                                        if (record.isSubagent) {
+                                            // The level's universe is BACKGROUND tasks only, so a
+                                            // live sync (foreground) subagent is legitimately
+                                            // absent — deleting its entry would strand its
+                                            // permission attribution (#859). Keep the entry but
+                                            // stop any hold from waiting on the id: an absent id
+                                            // can equally be a leaked async entry whose settle
+                                            // bookends were lost.
+                                            record.endedPerLevel ??= "ended";
+                                        }
+                                        else {
+                                            session.liveBackgroundTasks.delete(taskId);
+                                        }
+                                    }
+                                }
+                                break;
                             default:
                                 unreachable(message, this.logger);
                                 break;
                         }
                         break;
                     case "result": {
-                        // Task-notification followups are autonomous work triggered by a
-                        // task-notification system message, not by the user's prompt.
-                        // They should not influence the user-turn lifecycle (stop reason,
-                        // slash-command output forwarding) but their cost is real.
-                        const isTaskNotification = message.origin?.kind === "task-notification";
-                        // Reconcile the Fast mode toggle with the SDK's reported state.
-                        // Gated to user-driven turns like every other side effect below; a
-                        // background followup's state lands on the next user turn's result.
-                        // Runs even when the turn errors or was cancelled.
-                        if (!isTaskNotification) {
-                            await this.syncFastModeState(params.sessionId, session, message.fast_mode_state);
-                        }
-                        // A user-turn result needs an active turn so its stop reason is
-                        // attributed and the turn settles at idle. Local-only commands carry
-                        // no user-message echo to promote them, so do it here from the head.
-                        // Promote BEFORE accumulating usage, since activation resets the
-                        // accumulator — promoting after would discard this result's tokens.
-                        if (!isTaskNotification) {
-                            ensureActiveTurn();
-                        }
-                        // Every user-turn result terminates a turn (settle, reject, or
-                        // 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
-                        // 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.
-                        if (!isTaskNotification && (!session.cancelled || !session.activeTurn)) {
-                            owedTrailingIdles++;
-                        }
-                        // Accumulate usage into the user turn's tally. Skip task-notification
-                        // followups: their cost is real but is reported separately via the
-                        // usage_update below, and `session.accumulatedUsage` is only reset on
-                        // turn activation — so folding a task-notification result that lands
-                        // after the next turn is active (but before it settles) would leak
-                        // those tokens into that turn's PromptResponse.usage.
-                        if (!isTaskNotification) {
-                            session.accumulatedUsage.inputTokens += message.usage.input_tokens;
-                            session.accumulatedUsage.outputTokens += message.usage.output_tokens;
-                            session.accumulatedUsage.cachedReadTokens += message.usage.cache_read_input_tokens;
-                            session.accumulatedUsage.cachedWriteTokens +=
-                                message.usage.cache_creation_input_tokens;
-                        }
-                        const matchingModelUsage = lastAssistantModel
-                            ? getMatchingModelUsage(message.modelUsage, lastAssistantModel)
-                            : null;
-                        // Only overwrite when we have an authoritative value — a miss
-                        // (e.g. a turn with no top-level assistant message) would
-                        // otherwise discard the window learned on a prior turn and
-                        // leave the next prompt's mid-stream updates reporting 200k.
-                        if (matchingModelUsage) {
-                            session.contextWindowSize = matchingModelUsage.contextWindow;
-                        }
-                        // Send usage_update notification
-                        if (lastAssistantTotalUsage !== null) {
-                            await this.client.sessionUpdate({
-                                sessionId: params.sessionId,
-                                update: {
-                                    sessionUpdate: "usage_update",
-                                    used: lastAssistantTotalUsage,
-                                    size: session.contextWindowSize,
-                                    cost: {
-                                        amount: message.total_cost_usd,
-                                        currency: "USD",
-                                    },
-                                    ...(message.origin && {
-                                        _meta: { "_claude/origin": message.origin },
-                                    }),
-                                },
-                            });
-                        }
-                        if (session.cancelled) {
-                            if (!isTaskNotification) {
-                                stopReason = "cancelled";
+                        // 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
+                        // the user's prompt's. Autonomous results must never touch the
+                        // user-turn lifecycle (stop reason, settles, failActive,
+                        // slash-command output forwarding), though their cost is real.
+                        const isAutonomousResult = message.origin != null && AUTONOMOUS_RESULT_ORIGINS.has(message.origin.kind);
+                        try {
+                            // Reconcile the Fast mode toggle with the SDK's reported state.
+                            // Gated to user-driven turns like every other side effect below;
+                            // an autonomous cycle's state lands on the next user turn's
+                            // result. Runs even when the turn errors or was cancelled.
+                            if (!isAutonomousResult) {
+                                await this.syncFastModeState(params.sessionId, session, message.fast_mode_state, message.fast_mode_disabled_reason);
                             }
-                            break;
-                        }
-                        // A refusal can arrive on any result subtype (and may even set
-                        // is_error), so handle it before the subtype switch — otherwise the
-                        // is_error throw below would surface it as an internal error. The
-                        // refused assistant message carries no visible content, so surface
-                        // the classifier's explanation (when available) and report ACP's
-                        // dedicated `refusal` stop reason.
-                        if (message.stop_reason === "refusal" && !isTaskNotification) {
-                            if (lastRefusalExplanation) {
-                                await this.client.sessionUpdate({
+                            // A user-turn result needs an active turn so its stop reason is
+                            // attributed and the turn settles at idle. Local-only commands carry
+                            // no user-message echo to promote them, so do it here from the head.
+                            // Promote BEFORE accumulating usage, since activation resets the
+                            // accumulator — promoting after would discard this result's tokens.
+                            // The orphan bookkeeping runs first: it covers folded/zombie
+                            // commands whose shared or late result this is, even when the
+                            // result is the ACTIVE turn's (ensureActiveTurn never looks at
+                            // the map in that case).
+                            if (!isAutonomousResult) {
+                                recordResultForOrphanCommands();
+                                ensureActiveTurn();
+                            }
+                            // A result closes the stretch of output it terminates: snapshot
+                            // the delivery record — AFTER ensureActiveTurn, whose held-turn
+                            // hand-off closes the held stretch, so an echo-less command
+                            // promoted here is judged on its own delivery, not on the held
+                            // turn's followup text — and before the handling below can emit
+                            // anything of its own; the `finally` then clears it so every
+                            // exit from this case (the cancelled-guard and refusal breaks
+                            // included) starts the next stretch clean. Clearing up front
+                            // instead would let result-time emissions (refusal explanation,
+                            // result-text forwarding) taint the next stretch and suppress a
+                            // following replayed turn's fallback. Autonomous cycles run
+                            // alongside a user turn and must not clear its flag (they exit
+                            // through the early break below, which the gated `finally`
+                            // leaves alone).
+                            const deliveredAssistantText = session.emittedAssistantText;
+                            // Every user-turn result terminates a turn (settle, reject, or
+                            // 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
+                            // 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.
+                            // Autonomous results (followups, peer/channel/coordinator
+                            // cycles) are counted too: each is its own processing cycle with
+                            // its own trailing idle, and that idle can lag past the next
+                            // prompt's echo — which, un-owed, would be read as the fresh
+                            // turn being abandoned (#825 false-fail). That lag was mostly
+                            // unreachable when such cycles only ran with no pending turn,
+                            // 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.
+                            if (isAutonomousResult || !session.cancelled || !session.activeTurn) {
+                                session.owedTrailingIdles++;
+                            }
+                            // Accumulate usage into the user turn's tally. Skip autonomous
+                            // results: their cost is real but is reported separately via the
+                            // usage_update below, and `session.accumulatedUsage` is only reset on
+                            // turn activation — so folding an autonomous result that lands
+                            // after the next turn is active (but before it settles) would leak
+                            // those tokens into that turn's PromptResponse.usage.
+                            if (!isAutonomousResult) {
+                                session.accumulatedUsage.inputTokens += message.usage.input_tokens;
+                                session.accumulatedUsage.outputTokens += message.usage.output_tokens;
+                                session.accumulatedUsage.cachedReadTokens += message.usage.cache_read_input_tokens;
+                                session.accumulatedUsage.cachedWriteTokens +=
+                                    message.usage.cache_creation_input_tokens;
+                            }
+                            const matchingModelUsage = lastAssistantModel
+                                ? getMatchingModelUsage(message.modelUsage, lastAssistantModel)
+                                : null;
+                            // Only overwrite when we have an authoritative, sane value. A miss
+                            // (e.g. a turn with no top-level assistant message), or a
+                            // nonsensical non-positive/NaN window (observed from third-party
+                            // backends), would otherwise discard the window learned on a prior
+                            // turn and leave the next prompt's mid-stream updates reporting a
+                            // wrong size. `cacheContextWindow` applies the same `> 0` guard, so
+                            // a bad value never reaches the cross-session cache either.
+                            if (matchingModelUsage &&
+                                typeof matchingModelUsage.usage.contextWindow === "number" &&
+                                matchingModelUsage.usage.contextWindow > 0) {
+                                session.contextWindowSize = matchingModelUsage.usage.contextWindow;
+                                session.contextWindowAuthoritative = true;
+                                // Authoritative: fold it into the cross-session cache keyed on
+                                // (this session's provider, the resolved model id —
+                                // matchingModelUsage.key, e.g. "claude-sonnet-5[1m]") so a later
+                                // session/new or switch on the same provider that resolves to
+                                // this model seeds the correct window synchronously, with no
+                                // getContextUsage IPC.
+                                cacheContextWindow(contextWindowCacheKey(session.providerCacheKey, matchingModelUsage.key), matchingModelUsage.usage.contextWindow);
+                                // Also cache under the assistant message's own (bare) spelling.
+                                // Seed-time reads fall back to a picker value / verbatim live id
+                                // when a row carries no resolvedModel (the synthesized
+                                // out-of-allowlist resume row sets it undefined on purpose), and
+                                // those spellings match `.model` from the assistant message, not
+                                // the decorated modelUsage key — without this entry such rows
+                                // could never hit the cache.
+                                if (lastAssistantModel && lastAssistantModel !== matchingModelUsage.key) {
+                                    cacheContextWindow(contextWindowCacheKey(session.providerCacheKey, lastAssistantModel), matchingModelUsage.usage.contextWindow);
+                                }
+                            }
+                            // Send usage_update notification
+                            if (lastAssistantTotalUsage !== null) {
+                                await sendUpdate({
                                     sessionId: params.sessionId,
                                     update: {
-                                        sessionUpdate: "agent_message_chunk",
-                                        content: { type: "text", text: lastRefusalExplanation },
+                                        sessionUpdate: "usage_update",
+                                        used: lastAssistantTotalUsage,
+                                        size: session.contextWindowSize,
+                                        cost: {
+                                            amount: message.total_cost_usd,
+                                            currency: "USD",
+                                        },
+                                        ...(message.origin && {
+                                            _meta: { "_claude/origin": message.origin },
+                                        }),
                                     },
                                 });
                             }
-                            stopReason = "refusal";
-                            settleActive({ stopReason: "refusal", usage: sessionUsage(session) });
-                            break;
-                        }
-                        switch (message.subtype) {
-                            case "success": {
-                                if (message.result.includes("Please run /login")) {
-                                    failActive(RequestError.authRequired());
-                                    break;
-                                }
-                                if (message.stop_reason === "max_tokens") {
-                                    if (!isTaskNotification) {
-                                        stopReason = "max_tokens";
-                                    }
-                                    break;
+                            if (session.cancelled) {
+                                if (!isAutonomousResult) {
+                                    stopReason = "cancelled";
                                 }
-                                if (message.is_error) {
-                                    failActive(RequestError.internalError(errorKindData(lastAssistantError), message.result));
-                                    break;
+                                break;
+                            }
+                            // A held turn (see Turn.deferredSettle) settles at its
+                            // followup's terminal result: this is the earliest point at which
+                            // the promised summary has fully streamed — the trailing idle
+                            // would work too, but a client should not wait out another idle
+                            // round-trip for a response whose content is already complete.
+                            // (While the turn still awaits another of its subagents —
+                            // parallel spawns — the helper holds; the next notification's
+                            // followup settles it instead. Other autonomous origins — peer/
+                            // channel/coordinator cycles — reach here too: settling a
+                            // drained hold at their results is as good as the idle
+                            // fallback.) Then stop: everything below is user-turn
+                            // lifecycle, and an autonomous outcome must never touch it —
+                            // its is_error or "Please run /login" text would otherwise
+                            // failActive a live turn (the held one, or the user's next
+                            // prompt) whose own result recorded a different outcome.
+                            if (isAutonomousResult) {
+                                settleDeferredIfDrained();
+                                // With no turn in flight OR QUEUED (also after the settle
+                                // above), the stretch holds only autonomous prose — close
+                                // it, so a replayed next prompt isn't silently suppressed by
+                                // the issue-#453 delivery check. A live turn's flag may
+                                // guard the USER's already-streamed text — and so may a
+                                // QUEUED turn's: with mid-message echo lag its deltas stream
+                                // before the echo activates it (activeTurn still null), and
+                                // clearing then would re-emit that answer via the fallback,
+                                // the duplicate direction the flag's doc forbids.
+                                if (!session.activeTurn && !firstUnsettledQueuedTurn()) {
+                                    session.emittedAssistantText = false;
                                 }
-                                // For local-only commands (no model invocation), the result
-                                // text is the command output — forward it to the client.
-                                // Task-notification followups never originate from a user
-                                // slash command, so skip the forwarding for them.
-                                if (session.activeTurn?.isLocalOnlyCommand && !isTaskNotification) {
-                                    for (const notification of toAcpNotifications(message.result, "assistant", params.sessionId, session.toolUseCache, this.client, this.logger)) {
-                                        await this.client.sessionUpdate(notification);
-                                    }
+                                break;
+                            }
+                            // A refusal can arrive on any result subtype (and may even set
+                            // is_error), so handle it before the subtype switch — otherwise the
+                            // is_error throw below would surface it as an internal error. The
+                            // refused assistant message carries no visible content, so surface
+                            // the classifier's explanation (when available) and report ACP's
+                            // dedicated `refusal` stop reason.
+                            if (message.stop_reason === "refusal") {
+                                if (lastRefusalExplanation) {
+                                    await sendUpdate({
+                                        sessionId: params.sessionId,
+                                        update: {
+                                            sessionUpdate: "agent_message_chunk",
+                                            content: { type: "text", text: lastRefusalExplanation },
+                                        },
+                                    });
                                 }
+                                stopReason = "refusal";
+                                // Through the deferral gate, not settleActive: a refusal can
+                                // land on a turn whose spawned subagents are still live, and
+                                // settling it out from under them would strand their output
+                                // and permission requests out-of-turn (issue #866's deadlock,
+                                // through the refusal lane).
+                                settleOrDefer({ stopReason: "refusal", usage: sessionUsage(session) });
                                 break;
                             }
-                            case "error_during_execution": {
-                                if (message.stop_reason === "max_tokens") {
-                                    if (!isTaskNotification) {
+                            switch (message.subtype) {
+                                case "success": {
+                                    if (message.result.includes("Please run /login")) {
+                                        failActive(RequestError.authRequired());
+                                        break;
+                                    }
+                                    if (message.stop_reason === "max_tokens") {
                                         stopReason = "max_tokens";
+                                        break;
+                                    }
+                                    if (message.is_error) {
+                                        failActive(RequestError.internalError(errorKindData(lastAssistantError), message.result));
+                                        break;
+                                    }
+                                    // The result text is forwarded in two cases. Local-only
+                                    // commands (no model invocation): the result IS the command
+                                    // output. Otherwise the result is normally a trailing copy of
+                                    // text that already streamed — but a cache-replayed turn
+                                    // generates no tokens, and some CLIs then skip streaming
+                                    // entirely and answer on the `result` alone: no `stream_event`
+                                    // deltas, no consolidated `assistant` message (issue #453).
+                                    // Forward it rather than end the turn silently:
+                                    // `deliveredAssistantText` covers whatever already reached the
+                                    // client (a turn that showed its answer cannot emit it twice),
+                                    // and the output-token check keeps the fallback to the
+                                    // replayed turns it was reported for. `?? 0`: typed non-null,
+                                    // but third-party backends have been observed omitting usage
+                                    // token fields (see snapshotFromUsage), and the replay lane
+                                    // was reported from exactly such a backend — treat a missing
+                                    // count as the replay signature rather than silently disabling
+                                    // the fallback there. (Autonomous results never get here —
+                                    // they exit at the early break above — so no background
+                                    // prose can be injected into the feed.)
+                                    if (session.activeTurn?.isLocalOnlyCommand ||
+                                        (!deliveredAssistantText && (message.usage.output_tokens ?? 0) === 0)) {
+                                        for (const notification of toAcpNotifications(message.result, "assistant", params.sessionId, session.toolUseCache, this.client, this.logger)) {
+                                            await sendUpdate(notification);
+                                        }
                                     }
                                     break;
                                 }
-                                if (message.is_error) {
-                                    failActive(RequestError.internalError(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype));
-                                    break;
-                                }
-                                if (!isTaskNotification) {
+                                case "error_during_execution": {
+                                    if (message.stop_reason === "max_tokens") {
+                                        stopReason = "max_tokens";
+                                        break;
+                                    }
+                                    if (message.is_error) {
+                                        failActive(RequestError.internalError(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype));
+                                        break;
+                                    }
                                     stopReason = "end_turn";
-                                }
-                                break;
-                            }
-                            case "error_max_budget_usd":
-                            case "error_max_turns":
-                            case "error_max_structured_output_retries":
-                                if (message.is_error) {
-                                    failActive(RequestError.internalError(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype));
                                     break;
                                 }
-                                if (!isTaskNotification) {
+                                case "error_max_budget_usd":
+                                case "error_max_turns":
+                                case "error_max_structured_output_retries":
+                                    if (message.is_error) {
+                                        failActive(RequestError.internalError(errorKindData(lastAssistantError), message.errors.join(", ") || message.subtype));
+                                        break;
+                                    }
                                     stopReason = "max_turn_requests";
-                                }
-                                break;
-                            default:
-                                unreachable(message, this.logger);
-                                break;
+                                    break;
+                                default:
+                                    unreachable(message, this.logger);
+                                    break;
+                            }
+                            // Settle the user turn at its terminal result so the client unlocks
+                            // as soon as the answer is done, rather than waiting for the SDK's
+                            // trailing `idle` (which can lag while background work runs — issue
+                            // #773). The consumer keeps draining afterward (absorbing idle and
+                            // forwarding any background output).
+                            //
+                            // One exception: while background subagents this turn spawned are
+                            // still live, settling now would strand their remaining work
+                            // outside any turn — ACP allows out-of-turn session/update, but
+                            // many clients stop consuming at the prompt response, and a
+                            // subagent's permission request would block on an RPC nobody
+                            // answers (issues #864/#866). Hold the turn open instead: store
+                            // the outcome and settle with it once the subagents are done —
+                            // at their followup's terminal result (see the deferred-settle
+                            // block above the subtype switch) or at an idle with none of
+                            // them left — so the subagents' streamed output, their
+                            // permission requests, and the model's promised summary all land
+                            // inside the turn. `session/cancel` and the next prompt's echo
+                            // hand-off still settle a deferred turn early, so a long-running
+                            // 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.
+                            if (!session.cancelled) {
+                                settleOrDefer({ stopReason, usage: sessionUsage(session) });
+                            }
                         }
-                        // Settle the user turn at its terminal result so the client unlocks
-                        // as soon as the answer is done, rather than waiting for the SDK's
-                        // trailing `idle` (which can lag while background work runs — issue
-                        // #773). The consumer keeps draining afterward (absorbing idle and
-                        // forwarding any background output). is_error/auth already settled
-                        // via failActive; cancellation is left to the idle/abort path.
-                        // settleActive is idempotent, so a duplicate idle is a no-op.
-                        if (!isTaskNotification && !session.cancelled) {
-                            settleActive({ stopReason, usage: sessionUsage(session) });
+                        finally {
+                            if (!isAutonomousResult) {
+                                session.emittedAssistantText = false;
+                            }
                         }
                         break;
                     }
@@ -1636,12 +2611,16 @@ export class ClaudeAcpAgent {
                                 const model = message.event.message.model;
                                 if (model && model !== "<synthetic>") {
                                     lastAssistantModel = model;
-                                    // Only upgrade from the default — once a `result` has given
-                                    // us an authoritative window, trust it over the heuristic.
-                                    // Model switches invalidate the cached window via
-                                    // `syncSessionConfigState`, which resets us back to the
-                                    // default so this branch runs again for the new model.
-                                    if (session.contextWindowSize === DEFAULT_CONTEXT_WINDOW) {
+                                    // Only upgrade from the heuristic default — once we have an
+                                    // authoritative window (cache-seeded at session creation or
+                                    // on a model switch, read from the resumed session on
+                                    // session/load, confirmed by each `result`), trust it over
+                                    // the heuristic. The flag, not the value, is the sentinel: an
+                                    // authoritative window can legitimately equal
+                                    // DEFAULT_CONTEXT_WINDOW (e.g. a backend serving a 200k lane
+                                    // under a "[1m]"-spelled id) and must not be clobbered.
+                                    if (!session.contextWindowAuthoritative &&
+                                        session.contextWindowSize === DEFAULT_CONTEXT_WINDOW) {
                                         const inferred = inferContextWindowFromModel(model);
                                         if (inferred !== null) {
                                             session.contextWindowSize = inferred;
@@ -1666,7 +2645,7 @@ export class ClaudeAcpAgent {
                             const nextUsage = totalTokens(lastAssistantUsage);
                             if (nextUsage !== lastAssistantTotalUsage) {
                                 lastAssistantTotalUsage = nextUsage;
-                                await this.client.sessionUpdate({
+                                await sendUpdate({
                                     sessionId: params.sessionId,
                                     update: {
                                         sessionUpdate: "usage_update",
@@ -1682,8 +2661,11 @@ export class ClaudeAcpAgent {
                             taskState: session.taskState,
                             emittedToolCalls: session.emittedToolCalls,
                             messageId: currentStreamMessageId,
+                            streamedToolInputs,
                         })) {
-                            await this.client.sessionUpdate(notification);
+                            // sendUpdate records delivery; a subagent stream's chunks carry
+                            // the stamped parentToolUseId meta and are excluded there.
+                            await sendUpdate(notification);
                         }
                         break;
                     }
@@ -1704,7 +2686,7 @@ export class ClaudeAcpAgent {
                         // is still promoted — activateTurn() clears the flag. The turn's own
                         // echo is then dropped from the feed (the client already shows it).
                         if (message.type === "user" && "uuid" in message && message.uuid) {
-                            const queued = (session.turnQueue ?? []).find((t) => t.promptUuid === message.uuid && !t.settled);
+                            const queued = findUnsettledTurn(message.uuid);
                             if (queued) {
                                 // Only (re)activate if this isn't already the active turn — a
                                 // turn promoted early (e.g. by a result that preceded its echo)
@@ -1722,15 +2704,38 @@ export class ClaudeAcpAgent {
                                             // debt so that lagged idle is absorbed rather than read
                                             // as the freshly-activated turn ending without a result
                                             // (which would false-fail a healthy turn — issue #825).
-                                            owedTrailingIdles++;
+                                            // Counted for a DEFERRED turn too, even though its own
+                                            // result already recorded a debt that may still be
+                                            // outstanding: the interrupt can produce a trailer of
+                                            // its own, and over-counting is benign (absorbs one
+                                            // future idle) while under-counting risks the false
+                                            // fail this debt exists to prevent.
+                                            session.owedTrailingIdles++;
                                             // Before activateTurn resets the accumulator, so the
                                             // usage still belongs to the cancelled turn.
                                             settleActive({ stopReason: "cancelled", usage: sessionUsage(session) });
                                         }
+                                        else if (isHeldOpen(session.activeTurn)) {
+                                            // A turn held open for its background subagents (see
+                                            // Turn.deferredSettle) hands off with the real outcome
+                                            // its result recorded, not a guessed end_turn — the
+                                            // user moving on must not block behind a long-running
+                                            // subagent, but it must not rewrite the stop reason
+                                            // either. Its trailing-idle debt stands and is absorbed
+                                            // when the drain idle eventually arrives.
+                                            settleActive(session.activeTurn.deferredSettle);
+                                        }
                                         else {
                                             settleActive({ stopReason: "end_turn", usage: sessionUsage(session) });
                                         }
                                     }
+                                    // Unlike the no-result teardown lanes, this hand-off must
+                                    // NOT clear emittedAssistantText for a NON-held previous
+                                    // turn (a held one's settleActive above closes its own
+                                    // stretch): the echo can land
+                                    // mid-message, so deltas already streamed belong to the turn
+                                    // being activated — clearing would forget them and let its
+                                    // result re-emit the answer.
                                     activateTurn(queued);
                                 }
                                 break;
@@ -1783,7 +2788,7 @@ export class ClaudeAcpAgent {
                                     taskState: session.taskState,
                                     messageId: messageIdForGrouping(message),
                                 })) {
-                                    await this.client.sessionUpdate(notification);
+                                    await sendUpdate(notification);
                                 }
                             }
                             else {
@@ -1807,12 +2812,7 @@ export class ClaudeAcpAgent {
                         if (message.message.role === "system") {
                             break;
                         }
-                        if (message.type === "assistant" &&
-                            message.message.model === "<synthetic>" &&
-                            Array.isArray(message.message.content) &&
-                            message.message.content.length === 1 &&
-                            message.message.content[0].type === "text" &&
-                            message.message.content[0].text.includes("Please run /login")) {
+                        if (message.type === "assistant" && isSyntheticLoginMessage(message.message)) {
                             failActive(RequestError.authRequired());
                             break;
                         }
@@ -1878,11 +2878,13 @@ export class ClaudeAcpAgent {
                             // the record stays bounded to the in-flight message.
                             streamedBlocks.length = 0;
                         }
-                        else if (message.type === "assistant") {
-                            // Subagent assistant message (`parent_tool_use_id !== null`). It is
-                            // never streamed live and its text/thinking is internal to the tool
-                            // call — keep dropping it so subagent prose doesn't leak into the
-                            // top-level feed.
+                        else if (message.type === "assistant" &&
+                            !(session.forwardSubagentText || supportsSubagentTranscript(this.clientCapabilities))) {
+                            // Legacy clients don't understand nested transcripts. Keep the
+                            // historical behavior for them: subagent text/thinking remains
+                            // internal to the tool call instead of leaking into the top-level
+                            // feed. Capable clients opt into the branch above unchanged, with
+                            // `parentToolUseId` stamped by toAcpNotifications.
                             content = message.message.content.filter((item) => item.type !== "text" && item.type !== "thinking");
                         }
                         else {
@@ -1895,22 +2897,64 @@ export class ClaudeAcpAgent {
                             taskState: session.taskState,
                             emittedToolCalls: session.emittedToolCalls,
                             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
+                            // type, hence the cast. Validated by parseToolResultMeta.
+                            toolResultMeta: message.type === "user"
+                                ? message.tool_result_meta
+                                : undefined,
                         })) {
-                            await this.client.sessionUpdate(notification);
+                            // sendUpdate records delivery. Subagent text/thinking is
+                            // 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(notification);
                         }
                         break;
                     }
                     case "tool_progress": {
-                        await this.client.sessionUpdate({
+                        // Not every beat reports under the id of a tool call the client has
+                        // seen: heartbeats derive `<tool_use_id>-heartbeat-<n>`, and the
+                        // `agent_api_retry` beats behind `subagentRetry` report under
+                        // `agent_<assistant_message_id>`. Forwarding those verbatim leaves the
+                        // client resolving an id it has never been told about (the same trap
+                        // `ensureToolCallEmitted` documents for #851). The SDK stamps
+                        // `parent_tool_use_id` with the executing tool's real id whenever the
+                        // beat doesn't carry one of its own, so fall back to it rather than
+                        // pattern-matching each synthetic id shape. Beats that do report a real
+                        // id (a subagent's `bash_progress`, whose parent is the spawning Agent
+                        // call) keep resolving to that id.
+                        const toolCallId = session.emittedToolCalls.has(message.tool_use_id)
+                            ? message.tool_use_id
+                            : message.parent_tool_use_id;
+                        // Ids leave `emittedToolCalls` at `tool_result`, so this also stops a
+                        // beat that races past completion from reopening a finished call.
+                        if (toolCallId === null || !session.emittedToolCalls.has(toolCallId)) {
+                            break;
+                        }
+                        await sendUpdate({
                             sessionId: message.session_id,
                             update: {
                                 sessionUpdate: "tool_call_update",
-                                toolCallId: message.tool_use_id,
+                                toolCallId,
                                 status: "in_progress",
                                 _meta: {
                                     claudeCode: {
                                         toolName: message.tool_name,
-                                        toolResponse: { elapsedTimeSeconds: message.elapsed_time_seconds },
+                                        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,
+                                            }),
+                                        },
                                     },
                                 },
                             },
@@ -1919,7 +2963,7 @@ export class ClaudeAcpAgent {
                     }
                     case "rate_limit_event": {
                         if (lastAssistantTotalUsage !== null) {
-                            await this.client.sessionUpdate({
+                            await sendUpdate({
                                 sessionId: message.session_id,
                                 update: {
                                     sessionUpdate: "usage_update",
@@ -1940,7 +2984,7 @@ export class ClaudeAcpAgent {
                     case "conversation_reset":
                         break;
                     default:
-                        unreachable(message);
+                        unreachable(message, this.logger);
                         break;
                 }
             }
@@ -1984,6 +3028,30 @@ export class ClaudeAcpAgent {
             }
         }
     }
+    /** Route one orphaned command into the session's orphan-accounting lane:
+     *  the per-uuid map on msg_lifecycle_v1 CLIs (drained by the command's own
+     *  terminal lifecycle frame and the echo-less-result skip), the plain count
+     *  elsewhere (the count lane can't express per-command states, so `state`
+     *  only matters on the map lane). Both orphan-producing paths — cancel()'s
+     *  queued-turn sweep and the consumer's force-cancel wedge path — must seed
+     *  through here so the lane split stays a single mechanism.
+     *
+     *  Known window: `msgLifecycleV1` is only learnable from the stream's first
+     *  `system`/init (the control-channel initialize carries no capabilities),
+     *  so a cancel that beats that drain seeds the COUNT lane on a
+     *  lifecycle-capable CLI — where command coalescing can leave the count
+     *  stale by N-1 (the pre-map bug, confined to this sub-second window and
+     *  still healed by the next activation's reset). Structural until the SDK
+     *  exposes capabilities before the stream starts. */
+    trackOrphanCommand(session, uuid, state) {
+        if (session.msgLifecycleV1) {
+            session.orphanCommands ??= new Map();
+            session.orphanCommands.set(uuid, state);
+        }
+        else {
+            session.pendingOrphanResults = (session.pendingOrphanResults ?? 0) + 1;
+        }
+    }
     async cancel(params) {
         const session = this.sessions[params.sessionId];
         if (!session) {
@@ -2006,11 +3074,18 @@ export class ClaudeAcpAgent {
             return;
         }
         session.cancelled = true;
+        // Capture the orphan-accounting lane before anything can await: the
+        // consumer latches msgLifecycleV1 when it drains the first system/init,
+        // which can happen DURING the awaited interrupt() below — the receipt
+        // reconciliation must act on the same lane the seeding used, or a
+        // count-lane orphan would be left for the map-lane receipt path (which
+        // 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.
-        const orphanedUuids = [];
+        const orphanedTurns = [];
         if (session.turnQueue) {
             for (const turn of session.turnQueue) {
                 if (turn !== session.activeTurn && !turn.settled) {
@@ -2018,16 +3093,98 @@ export class ClaudeAcpAgent {
                     // Deliberately no `usage`: a queued turn never ran, so the session
                     // accumulator (the active turn's tally) is not its spend.
                     turn.resolve({ stopReason: "cancelled" });
-                    orphanedUuids.push(turn.promptUuid);
+                    orphanedTurns.push(turn);
                 }
             }
             // Each removed queued turn's user message was already pushed to the SDK,
             // which processes input FIFO and will still emit a result for it with no
-            // uuid to match. Count those so the consumer skips them (see
+            // uuid to match. Track those so the consumer skips them (see
             // ensureActiveTurn) rather than misattributing them to the head.
-            session.pendingOrphanResults = (session.pendingOrphanResults ?? 0) + orphanedUuids.length;
+            // msg_lifecycle_v1 CLIs get per-uuid tracking drained by the command's
+            // own terminal lifecycle frame — exact under command coalescing, where
+            // N queued commands fold into ONE turn emitting one result and a plain
+            // count would go stale by N-1 and swallow a later echo-less result.
+            // Older CLIs keep the count and its activation-time self-heal (they
+            // never see lifecycle frames, so commandStarted/commandFinished stay
+            // unset and every turn takes the plain-seed path below).
+            for (const turn of orphanedTurns) {
+                if (turn.commandFinished === "completed" || turn.commandFinished === "discarded") {
+                    // The command already finished SDK-side and its terminal frame was
+                    // consumed while the turn sat queued — nothing is left to skip, and
+                    // a seeded entry would never drain.
+                    continue;
+                }
+                if (turn.commandFinished === "cancelled") {
+                    // Terminal frame already consumed. Dispatched-then-aborted: the
+                    // dead turn's late result may still come — seed the zombie the
+                    // frame handler would have made — unless that result already
+                    // passed pre-cancel (commandResultSeen: e.g. the command folded
+                    // into the active turn and their shared result was attributed
+                    // there), in which case a zombie would be a phantom that swallows
+                    // an unrelated later result. Never dispatched: dropped, no result
+                    // coming, nothing to track.
+                    if (turn.commandStarted && !turn.commandResultSeen) {
+                        this.trackOrphanCommand(session, turn.promptUuid, "zombie");
+                    }
+                    continue;
+                }
+                if (turn.commandStarted && turn.commandResultSeen) {
+                    // Dispatched and its turn's result already passed; only its
+                    // terminal frame is outstanding, which no-ops with no entry.
+                    continue;
+                }
+                this.trackOrphanCommand(session, turn.promptUuid, turn.commandStarted ? "started" : "pending");
+            }
             session.turnQueue = session.turnQueue.filter((turn) => turn === session.activeTurn && !turn.settled);
         }
+        // A deferred active turn (see Turn.deferredSettle) already has its
+        // result — it is only held open for its background subagents, which the
+        // interrupt below tears down. Settle it "cancelled" NOW: during the hold
+        // the session is typically already in state idle (the CLI's trailer
+        // fired at the result), so the interrupt may produce no fresh idle for
+        // the consumer's cancelled-settle path to run on, and the cancel would
+        // otherwise stall until the force-cancel backstop. Any outstanding
+        // trailer debt is absorbed by the idle handler when its idle does come.
+        // The turn's own usage snapshot is reported per the cancelled-usage
+        // contract (issue #844).
+        {
+            const active = session.activeTurn;
+            if (isHeldOpen(active)) {
+                active.settled = true;
+                // Mirror settleActive's invariants (it is consumer-scoped and
+                // unreachable from here): disarm the backstop — none should be
+                // armed for a held turn, but a drift here must not leave a timer
+                // firing on a settled turn — and drop the turn from the queue.
+                disarmForceCancel(session);
+                session.turnQueue = (session.turnQueue ?? []).filter((t) => t !== active);
+                session.activeTurn = null;
+                // Settling a held turn closes its delivery stretch: any streamed
+                // text since the last boundary was its followups', and left latched
+                // it would suppress a following replayed turn's issue-#453 fallback.
+                session.emittedAssistantText = false;
+                // When the interrupt below pre-empts a live cycle — running, or
+                // blocked on a permission request (requires_action, the #866 shape
+                // users cancel out of) — it produces a trailer idle with no counted
+                // result; with the hold's own trailer typically already absorbed,
+                // that idle would be un-owed and could lag past the next prompt's
+                // echo — read as the fresh turn ending without a result (issue #825
+                // false-fail). Pre-count it unless the session sits idle: there the
+                // interrupt emits nothing, and a debt that never drains would mask
+                // one future #825 detection. (lastSessionState is last-CONSUMED, so
+                // both stale reads exist and both are accepted one-cycle windows: a
+                // running transition still in the backlog reads as stale idle and
+                // under-counts — that false-fail additionally needs the trailer to
+                // lag past the next echo — while a cycle already completed into the
+                // backlog reads as stale non-idle and over-counts, masking one
+                // future #825 detection. Undefined — no state event consumed —
+                // pre-counts; that only occurs on CLIs whose missing idle events
+                // also disable the detector the debt could mask.)
+                if (session.lastSessionState !== "idle") {
+                    session.owedTrailingIdles++;
+                }
+                active.resolve({ stopReason: "cancelled", usage: active.deferredSettle.usage });
+            }
+        }
         // Arm a backstop before interrupting: if a turn is actively consuming the
         // query and interrupt() doesn't make the SDK yield (e.g. a wedged TaskOutput
         // block — issue #680), force the consumer to settle the active turn
@@ -2065,11 +3222,30 @@ export class ClaudeAcpAgent {
         // receipt, so a bare `{}` success from a gateway can't read as "everything
         // was dropped") — keep the count-everything behavior and its
         // activation-time self-heal.
-        if (Array.isArray(receipt?.still_queued) && orphanedUuids.length > 0) {
+        if (Array.isArray(receipt?.still_queued) && orphanedTurns.length > 0) {
             const stillQueued = new Set(receipt.still_queued);
-            const dropped = orphanedUuids.filter((uuid) => !stillQueued.has(uuid)).length;
-            if (dropped > 0) {
-                session.pendingOrphanResults = Math.max(0, (session.pendingOrphanResults ?? 0) - dropped);
+            if (lifecycleLane) {
+                // Lifecycle lane: forget dropped orphans by uuid. Only entries still
+                // "pending" — an orphan absent from `still_queued` because it was
+                // DISPATCHED before the interrupt (not dropped) has usually been
+                // promoted to "started" by its lifecycle frame by now, and its own
+                // terminal frame must stay in charge of its fate. (If that frame is
+                // still in the consumer's backlog we mis-forget — the same exposure
+                // the count lane has always had for a dropped-then-run command.)
+                // Mostly redundant with the "cancelled"-frame removal, but a receipt
+                // survives paths where that frame was never emitted.
+                for (const turn of orphanedTurns) {
+                    if (!stillQueued.has(turn.promptUuid) &&
+                        session.orphanCommands?.get(turn.promptUuid) === "pending") {
+                        session.orphanCommands.delete(turn.promptUuid);
+                    }
+                }
+            }
+            else {
+                const dropped = orphanedTurns.filter((turn) => !stillQueued.has(turn.promptUuid)).length;
+                if (dropped > 0) {
+                    session.pendingOrphanResults = Math.max(0, (session.pendingOrphanResults ?? 0) - dropped);
+                }
             }
         }
     }
@@ -2117,10 +3293,7 @@ export class ClaudeAcpAgent {
         // after the floor, and clear the timer so it can't outlive the deleted
         // session (it isn't unref'd and would otherwise keep the event loop alive
         // until it fires).
-        if (session.forceCancelTimer) {
-            clearTimeout(session.forceCancelTimer);
-            session.forceCancelTimer = undefined;
-        }
+        disarmForceCancel(session);
         session.cancelController?.abort();
         this.closeQueryStream(session);
         // Abort the SDK abort signal only on explicit destroy. closeQueryStream
@@ -2328,6 +3501,8 @@ export class ClaudeAcpAgent {
     async replaySessionHistory(sessionId) {
         const toolUseCache = {};
         const messages = await getSessionMessages(sessionId);
+        const forwardSubagentText = this.sessions[sessionId]?.forwardSubagentText ??
+            supportsSubagentTranscript(this.clientCapabilities);
         for (const message of messages) {
             // Backfill the ACP messageId -> SDK uuid mapping for messages we didn't
             // observe live (resumed/loaded sessions), so rewind/resume can translate
@@ -2338,8 +3513,18 @@ export class ClaudeAcpAgent {
             if (replaySession && replayMessageId && message.uuid) {
                 replaySession.messageIdToUuid.set(replayMessageId, message.uuid);
             }
+            // The live prompt loop converts the synthetic "Please run /login"
+            // 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;
+            }
             // @ts-expect-error - untyped in SDK but we handle all of these
             let content = message.message.content;
+            const parentToolUseId = parentToolUseIdOf(message);
+            if (message.type === "assistant" && parentToolUseId && !forwardSubagentText) {
+                content = stripSubagentTextAndThinking(content);
+            }
             // @ts-expect-error - untyped in SDK but we handle all of these
             if (message.message.role === "user") {
                 content = stripLocalCommandMetadata(content);
@@ -2356,6 +3541,7 @@ export class ClaudeAcpAgent {
                 cwd: this.sessions[sessionId]?.cwd,
                 taskState: this.sessions[sessionId]?.taskState,
                 messageId: replayMessageId,
+                parentToolUseId,
             })) {
                 await this.client.sessionUpdate(notification);
             }
@@ -2376,14 +3562,14 @@ export class ClaudeAcpAgent {
      *  outcome or a `requestCancelled` rejection). Either way we surface the same
      *  "Tool use aborted" the callers already expect, so a cancelled dialog no
      *  longer leaves the `await` hanging. */
-    async requestPermissionFromClient(params, toolName, signal) {
+    async requestPermissionFromClient(params, toolName, signal, parentToolUseId) {
         // The SDK may invoke `canUseTool` (and therefore this permission request)
         // before the assistant message's tool_use block streams to us. Some ACP clients
         // expect the `tool_call` a permission request references to already exist,
         // 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(params.sessionId, toolName, params.toolCall.toolCallId, params.toolCall.rawInput);
+        await this.ensureToolCallEmitted(params.sessionId, toolName, params.toolCall.toolCallId, params.toolCall.rawInput, parentToolUseId);
         try {
             return await this.client.requestPermission(params, signal);
         }
@@ -2400,10 +3586,15 @@ export class ClaudeAcpAgent {
      *  instead of emitting a duplicate (see `emittedToolCalls`). Built via the same
      *  `toolCallNotification` helper as the streamed path so the two are identical.
      *  Tools the stream renders as a plan (TodoWrite) or suppresses (Task*) are
-     *  skipped so a permission prompt for them never surfaces a stray tool_call. */
-    async ensureToolCallEmitted(sessionId, toolName, toolCallId, toolInput) {
+     *  emitted too: a permission request referencing a tool call the client has
+     *  never seen can trip strict clients (issue #851), so the reference must
+     *  always resolve. Since the streamed path never completes those calls, they
+     *  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) {
         const session = this.sessions[sessionId];
-        if (!session || !shouldEmitToolCall(toolName)) {
+        if (!session) {
             return;
         }
         if (session.emittedToolCalls.has(toolCallId)) {
@@ -2411,13 +3602,20 @@ export class ClaudeAcpAgent {
         }
         session.emittedToolCalls.add(toolCallId);
         const supportsTerminalOutput = this.clientCapabilities?._meta?.["terminal_output"] === true;
-        await this.client.sessionUpdate({
-            sessionId,
-            update: toolCallNotification({ id: toolCallId, name: toolName, input: toolInput }, toolInput, supportsTerminalOutput, session.cwd),
-        });
+        const update = toolCallNotification({ id: toolCallId, name: toolName, input: toolInput }, toolInput, supportsTerminalOutput, session.cwd);
+        if (parentToolUseId) {
+            update._meta = {
+                ...update._meta,
+                claudeCode: {
+                    ...(update._meta?.claudeCode || {}),
+                    parentToolUseId,
+                },
+            };
+        }
+        await this.client.sessionUpdate({ sessionId, update });
     }
     canUseTool(sessionId) {
-        return async (toolName, toolInput, { signal, suggestions, toolUseID }) => {
+        return async (toolName, toolInput, { signal, suggestions, toolUseID, agentID, matchedAskRule }) => {
             const alwaysAllowLabel = describeAlwaysAllow(suggestions, toolName);
             const supportsTerminalOutput = this.clientCapabilities?._meta?.["terminal_output"] === true;
             const session = this.sessions[sessionId];
@@ -2427,6 +3625,23 @@ 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;
+            if (agentID && !parentToolUseId) {
+                // The attribution rests on an undocumented SDK invariant
+                // (task_started.task_id === canUseTool's agentID for subagent tasks;
+                // verified against the bundled CLI). Should an SDK bump break it — or
+                // the consumer lose the race with task_started — the lookup misses and
+                // the request goes out unattributed; log it so the regression is
+                // observable rather than silent.
+                this.logger.log(`[claude-agent-acp] No parent tool_use recorded for subagent ${agentID}; ` +
+                    `sending the ${toolName} permission request unattributed`);
+            }
             // AskUserQuestion is surfaced to us as a normal permission check (the SDK
             // routes it through canUseTool whenever a callback is registered, rather
             // than the interactive dialog). Present it as an ACP form elicitation and
@@ -2434,44 +3649,9 @@ export class ClaudeAcpAgent {
             if (toolName === "AskUserQuestion" && this.clientCapabilities?.elicitation?.form) {
                 // 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);
+                await this.ensureToolCallEmitted(sessionId, toolName, toolUseID, toolInput, parentToolUseId);
                 return this.handleAskUserQuestion(sessionId, toolInput, toolUseID, signal);
             }
-            // Fallback for clients WITHOUT `elicitation.form`: route each question
-            // through ACP `session/request_permission` dialogs (gated by
-            // ACP_ASKUSERQUESTION_FALLBACK). Placed before ExitPlanMode and the
-            // bypassPermissions early-allow so a question is always asked, even in
-            // bypass mode.
-            if (toolName === "AskUserQuestion" && askUserQuestionFallbackEnabled(process.env)) {
-                // Emit the tool_call before the first permission request (R3.1).
-                await this.ensureToolCallEmitted(sessionId, toolName, toolUseID, toolInput);
-                // Logger has no `debug`; `.error` reaches stderr in all contexts (the CLI
-                // entrypoint also remaps console.log/debug -> stderr), so it never
-                // corrupts the stdout ndJSON protocol. Used by story 002 validation.
-                this.logger.error("AskUserQuestion: routing via permission fallback (client lacks elicitation.form).");
-                return handleAskUserQuestionViaPermission(toolInput, async ({ question, options }) => {
-                    const response = await this.requestPermissionFromClient({
-                        options,
-                        sessionId,
-                        toolCall: {
-                            toolCallId: toolUseID,
-                            rawInput: toolInput,
-                            ...toolInfoFromToolUse({ name: toolName, input: toolInput, id: toolUseID }, supportsTerminalOutput, session?.cwd),
-                            // Per-question title so the user sees which question they are
-                            // answering; placed AFTER the spread so it wins over the
-                            // tool-derived title.
-                            title: question.question,
-                        },
-                    }, toolName, signal);
-                    // RequestPermissionResponse has a DOUBLE-nested outcome (see the
-                    // ExitPlanMode usage below): response.outcome?.outcome is
-                    // "selected" | "cancelled".
-                    if (response.outcome?.outcome === "selected") {
-                        return { outcome: "selected", optionId: response.outcome.optionId };
-                    }
-                    return { outcome: "cancelled" };
-                }, signal);
-            }
             if (toolName === "ExitPlanMode") {
                 const optionsAll = [
                     { kind: "allow_always", name: 'Yes, and use "auto" mode', optionId: "auto" },
@@ -2503,8 +3683,13 @@ export class ClaudeAcpAgent {
                         toolCallId: toolUseID,
                         rawInput: toolInput,
                         ...toolInfoFromToolUse({ name: toolName, input: toolInput, id: toolUseID }, supportsTerminalOutput, session?.cwd),
+                        // `claudeCode` metas always carry `toolName` (see ToolUpdateMeta),
+                        // so clients can rely on one shape everywhere.
+                        ...(parentToolUseId
+                            ? { _meta: { claudeCode: { toolName, parentToolUseId } } }
+                            : {}),
                     },
-                }, toolName, signal);
+                }, toolName, signal, parentToolUseId);
                 if (signal.aborted || response.outcome?.outcome === "cancelled") {
                     throw new Error("Tool use aborted");
                 }
@@ -2538,7 +3723,14 @@ export class ClaudeAcpAgent {
                     };
                 }
             }
-            if (session.modes.currentModeId === "bypassPermissions") {
+            // In bypass mode the CLI skips permission checks itself; the asks that
+            // still reach canUseTool are the ones it insists on prompting for even
+            // under --dangerously-skip-permissions. Keep auto-allowing those —
+            // bypass means bypass — EXCEPT rule-forced asks (`matchedAskRule`): the
+            // user explicitly configured a permissions.ask rule for this tool, and
+            // the SDK's guidance is that hosts running auto-approval must treat such
+            // asks as a human prompt. Fall through to the normal request below.
+            if (session.modes.currentModeId === "bypassPermissions" && !matchedAskRule) {
                 return {
                     behavior: "allow",
                     updatedInput: toolInput,
@@ -2562,8 +3754,13 @@ export class ClaudeAcpAgent {
                     toolCallId: toolUseID,
                     rawInput: toolInput,
                     ...toolInfoFromToolUse({ name: toolName, input: toolInput, id: toolUseID }, supportsTerminalOutput, session?.cwd),
+                    // `claudeCode` metas always carry `toolName` (see ToolUpdateMeta),
+                    // so clients can rely on one shape everywhere.
+                    ...(parentToolUseId
+                        ? { _meta: { claudeCode: { toolName, parentToolUseId } } }
+                        : {}),
                 },
-            }, toolName, signal);
+            }, toolName, signal, parentToolUseId);
             if (signal.aborted || response.outcome?.outcome === "cancelled") {
                 throw new Error("Tool use aborted");
             }
@@ -2739,12 +3936,21 @@ export class ClaudeAcpAgent {
             // carries no "1m" token.
             const newModelInfo = session.modelInfos.find((m) => m.value === value);
             if (session.models.currentModelId !== value) {
-                // The cached context window was learned for the previous model; reset
-                // to the new model's heuristic so mid-stream updates between now and
-                // the next `result` reflect the user's selection instead of the old
-                // model's window.
-                session.contextWindowSize =
-                    inferContextWindowFromModel(value, newModelInfo?.displayName, newModelInfo?.description) ?? DEFAULT_CONTEXT_WINDOW;
+                // Seed the new model's context window WITHOUT any IPC on the switch
+                // path: cached authoritative value if we've already learned it (from a
+                // prior turn's `result.modelUsage`), else the text heuristic, else the
+                // default. We deliberately do NOT call `getContextUsage` here — before
+                // a fresh session's first prompt turn that control request is not
+                // serviced (~15s stall, issues #886/#880), and (because SDK control
+                // requests are serialized over one channel) it would drag the awaited
+                // `setModel` down with it. The authoritative window arrives on the
+                // first `result.modelUsage` for the model and is cached from there;
+                // until then a switched-to alias that has never run a turn shows the
+                // heuristic/default window, which self-corrects on its first response
+                // (matches pre-0.59.0 behavior).
+                const seeded = immediateContextWindow(session.providerCacheKey, value, newModelInfo);
+                session.contextWindowSize = seeded.size;
+                session.contextWindowAuthoritative = seeded.authoritative;
             }
             session.models = { ...session.models, currentModelId: value };
             // Recompute availableModes for the new model and clamp the current
@@ -2782,6 +3988,13 @@ export class ClaudeAcpAgent {
             else {
                 session.modes = { ...session.modes, availableModes: newAvailableModes };
             }
+            // `model_not_allowed` described the model we just left, so it must not
+            // follow us onto the new one; the remaining reasons are account- or
+            // environment-scoped and stay true across a switch. Either way the next
+            // init/result report refreshes this.
+            if (session.fastModeDisabledReason === "model_not_allowed") {
+                session.fastModeDisabledReason = undefined;
+            }
             // Rebuild config options since effort levels depend on the selected model
             const effortOpt = session.configOptions.find((o) => o.id === EFFORT_CONFIG_ID);
             const currentEffort = typeof effortOpt?.currentValue === "string" ? effortOpt.currentValue : undefined;
@@ -2791,6 +4004,7 @@ export class ClaudeAcpAgent {
                 // intent) when a supporting model is selected again.
                 supported: newModelInfo?.supportsFastMode ?? false,
                 enabled: session.fastModeEnabled,
+                disabledReason: session.fastModeDisabledReason,
             }, 
             // Thinking is model-independent: re-render the retained tri-state
             // intent so the row survives this rebuild (an option not threaded
@@ -2876,12 +4090,13 @@ export class ClaudeAcpAgent {
         }
     }
     /** Replace the Fast mode option in `session.configOptions` so it reflects
-     *  `enabled`. A no-op when the option isn't present, so callers must confirm
-     *  the current model surfaces it first. Rebuilds through the single-parameter
-     *  {@link createFastModeConfigOption} — the one source of the option's shape —
-     *  so the shape can't drift from what `buildConfigOptions` first emitted. */
+     *  `enabled` (and the session's current disabled reason). A no-op when the
+     *  option isn't present, so callers must confirm the current model surfaces
+     *  it first. Rebuilds through {@link createFastModeConfigOption} — the one
+     *  source of the option's shape — so the shape can't drift from what
+     *  `buildConfigOptions` first emitted. */
     refreshFastModeOption(session, enabled) {
-        const refreshed = createFastModeConfigOption(enabled);
+        const refreshed = createFastModeConfigOption(enabled, session.fastModeDisabledReason);
         session.configOptions = session.configOptions.map((o) => o.id === FAST_MODE_CONFIG_ID ? refreshed : o);
     }
     /** Toggle Fast mode for a session: push the SDK flag, record the user's
@@ -3165,8 +4380,15 @@ export class ClaudeAcpAgent {
      *     here).
      *   - `cooldown`: a transient suspension of an already-enabled fast mode.
      *     Leave the toggle as-is rather than flapping it — and never let a stray
-     *     cooldown spuriously enable a toggle the user has off. */
-    async syncFastModeState(sessionId, session, state) {
+     *     cooldown spuriously enable a toggle the user has off.
+     *
+     *  `reason` is the SDK's `fast_mode_disabled_reason`, reported alongside the
+     *  state. Only explainable reasons are retained (see
+     *  {@link normalizeFastModeDisabledReason}), so the comparison below tracks
+     *  exactly what the user can see: a routine `sdk_opt_in_required` report on
+     *  every turn's result can't churn the option, while a real blocker updates
+     *  the description even when the toggle's own value is unchanged. */
+    async syncFastModeState(sessionId, session, state, reason) {
         if (state === undefined) {
             return;
         }
@@ -3177,11 +4399,31 @@ export class ClaudeAcpAgent {
             return;
         }
         const enabled = state === "on";
-        if (enabled === session.fastModeEnabled) {
+        // A reason only describes an off state; drop any that rides an `on` report
+        // so it can't decorate the option the next time fast mode goes off.
+        const nextReason = enabled ? undefined : normalizeFastModeDisabledReason(reason);
+        if (enabled === session.fastModeEnabled && nextReason === session.fastModeDisabledReason) {
             return;
         }
+        // The user asked for Fast mode and the SDK is telling us it can't serve it.
+        // The description carries the same explanation, but a toggle silently
+        // snapping back is the case worth saying out loud once, at the flip.
+        const explain = session.fastModeEnabled && !enabled && nextReason !== undefined;
         session.fastModeEnabled = enabled;
+        session.fastModeDisabledReason = nextReason;
         this.refreshFastModeOption(session, enabled);
+        if (explain) {
+            await this.client.sessionUpdate({
+                sessionId,
+                update: {
+                    sessionUpdate: "agent_message_chunk",
+                    content: {
+                        type: "text",
+                        text: `**Fast mode turned off:** ${FAST_MODE_UNAVAILABLE_EXPLANATIONS[nextReason]}.`,
+                    },
+                },
+            });
+        }
         await this.client.sessionUpdate({
             sessionId,
             update: {
@@ -3313,6 +4555,8 @@ export class ClaudeAcpAgent {
         // Extract options from _meta if provided
         const sessionMeta = params._meta;
         const userProvidedOptions = sessionMeta?.claudeCode?.options;
+        const forwardSubagentText = supportsSubagentTranscript(this.clientCapabilities) ||
+            userProvidedOptions?.forwardSubagentText === true;
         // Configure thinking behavior through the same single code path query
         // recreation uses (`recreateSessionQuery`). A fresh session's Thinking
         // intent is untouched (`undefined`), so this resolves to exactly the
@@ -3328,13 +4572,9 @@ export class ClaudeAcpAgent {
             url: !!this.clientCapabilities?.elicitation?.url,
         };
         // AskUserQuestion surfaces as a `permission_ask_user_question` dialog that
-        // we render as a form elicitation. Without form-elicitation support we fall
-        // back to sequential ACP `session/request_permission` dialogs when the
-        // fallback gate is on (the default); set ACP_ASKUSERQUESTION_FALLBACK=0 to
-        // keep it disabled, exactly as upstream does.
-        const disallowedTools = elicitationSupport.form || askUserQuestionFallbackEnabled(process.env)
-            ? []
-            : ["AskUserQuestion"];
+        // we render as a form elicitation. Without form-elicitation support there
+        // is no way to present it over ACP, so keep it disabled in that case.
+        const disallowedTools = elicitationSupport.form ? [] : ["AskUserQuestion"];
         // Resolve which built-in tools to expose.
         // Explicit tools array from _meta.claudeCode.options takes precedence.
         // disableBuiltInTools is a legacy shorthand for tools: [] — kept for
@@ -3346,6 +4586,28 @@ export class ClaudeAcpAgent {
         // below) so the TaskCreated/TaskCompleted hook callbacks can close over
         // the same Map that the streaming message handler will read from.
         const taskState = new Map();
+        // The exact env the query will be created with. Built (and the provider
+        // cache key derived from it, below) in one place so the key always
+        // describes the backend this query actually talks to: `providers/set`,
+        // `providers/disable`, and `logout` mutate the process-wide provider
+        // config concurrently, so re-resolving it after any of the awaits between
+        // here and the session registration could disagree with the env baked
+        // into the query.
+        const env = {
+            ...process.env,
+            ...userProvidedOptions?.env,
+            // Client-managed LLM routing: `providers/set` config wins, else the
+            // legacy gateway auth request. Baked into the query at creation, so it
+            // only affects sessions started after the change (matching the RFD).
+            ...createEnvForProvider(this.resolveProviderConfig()),
+            // Opt-in to session state events like when the agent is idle
+            CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS: "1",
+        };
+        // Scopes the context-window cache to this query's backend (see
+        // `contextWindowCache`). Derived from the same `env` object handed to the
+        // SDK, so per-session `_meta` env routing and ambient process-env routing
+        // are distinguished exactly as the CLI will see them.
+        const providerCacheKey = providerCacheKeyFor(env);
         const options = {
             systemPrompt,
             settingSources: ["user", "project", "local"],
@@ -3366,16 +4628,11 @@ export class ClaudeAcpAgent {
                     ...(modelConfig.availableModels && { availableModels: modelConfig.availableModels }),
                 },
             }),
-            env: {
-                ...process.env,
-                ...userProvidedOptions?.env,
-                ...createEnvForGateway(this.gatewayAuthRequest),
-                // Opt-in to session state events like when the agent is idle
-                CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS: "1",
-            },
+            env,
             // Override certain fields that must be controlled by ACP
             cwd: params.cwd,
             includePartialMessages: true,
+            forwardSubagentText,
             mcpServers: { ...(userProvidedOptions?.mcpServers || {}), ...mcpServers },
             // If we want bypassPermissions to be an option, we have to allow it here.
             // But it doesn't work in root mode, so we only activate it if it will work.
@@ -3414,7 +4671,7 @@ export class ClaudeAcpAgent {
                     ...(userProvidedOptions?.hooks?.PostToolUse || []),
                     {
                         hooks: [
-                            createPostToolUseHook(this.logger, {
+                            createPostToolUseHook({
                                 onEnterPlanMode: async () => {
                                     await this.client.sessionUpdate({
                                         sessionId,
@@ -3536,7 +4793,7 @@ export class ClaudeAcpAgent {
         const allowedModels = Array.isArray(settingsAvailableModels)
             ? applyAvailableModelsAllowlist(initializationResult.models, settingsAvailableModels, settingsModelOverrides, this.logger)
             : hideDeprecatedModels(initializationResult.models, this.logger);
-        const models = await getAvailableModels(q, catalogModels, allowedModels, initializationResult.models, settingsManager, this.logger, creationOpts.resume !== undefined);
+        const { modelState: models, resumedContextWindow } = await getAvailableModels(q, catalogModels, allowedModels, initializationResult.models, settingsManager, this.logger, creationOpts.resume !== undefined);
         // Gate `auto` (and future model-specific modes) on the resolved model's
         // `ModelInfo`. See `buildAvailableModes` for the canonical SDK signal.
         // Looked up in the UNfiltered catalog: a session honoring a persisted
@@ -3627,9 +4884,17 @@ export class ClaudeAcpAgent {
         // the resolved model advertises `supportsFastMode`.
         const fastModeEnabled = initializationResult.fast_mode_state !== undefined &&
             fastModeStateEnabled(initializationResult.fast_mode_state);
+        // `fast_mode_disabled_reason` reflects the post-switch model since SDK
+        // 0.3.219 (the initialize response used to answer from the spawn-time
+        // model). A fresh SDK session reports `sdk_opt_in_required` — the toggle IS
+        // the opt-in — which normalizes away, so only real blockers are retained.
+        const fastModeDisabledReason = fastModeEnabled
+            ? undefined
+            : normalizeFastModeDisabledReason(initializationResult.fast_mode_disabled_reason);
         const fastMode = {
             supported: currentModelInfo?.supportsFastMode ?? false,
             enabled: fastModeEnabled,
+            disabledReason: fastModeDisabledReason,
         };
         const configOptions = buildConfigOptions(modes, models, 
         // Catalog-based (see `modelInfos` above), matching the model-switch
@@ -3651,9 +4916,40 @@ export class ClaudeAcpAgent {
             typeof initialEffort.currentValue === "string" &&
             initialEffort.currentValue !== "default") {
             await q.applyFlagSettings({
-                effortLevel: initialEffort.currentValue,
+                effortLevel: toSdkEffortLevel(initialEffort.currentValue),
             });
         }
+        // Seed the context window WITHOUT any extra IPC on the session/new path.
+        // On session/load, the resumed session's own `getContextUsage` report — a
+        // response `getAvailableModels` already awaited to learn the live model
+        // (resumed sessions ARE serviced pre-turn, unlike fresh ones) — is
+        // authoritative and wins. Otherwise: the cached authoritative window if a
+        // prior turn has learned it for this model (`result.modelUsage`,
+        // cross-session), else the text heuristic, else the default. We
+        // deliberately do NOT issue a getContextUsage call here: on a fresh
+        // session that control request is not serviced until the first prompt
+        // turn runs, so awaiting it — as 0.59.0 did — made session/new take ~15s
+        // (issues #886/#880). The authoritative window arrives on the first
+        // `result.modelUsage` and is cached from there.
+        //
+        // Text inference alone misses aliases that resolve to extended-context
+        // models with no "1m" token anywhere in their id or description (e.g.
+        // `sonnet` → claude-sonnet-5, natively ~1M): those stream
+        // `usage_update.size: 200000` until the first result's modelUsage corrects
+        // it — but the cache means only the FIRST session to ever run a turn on such
+        // a model eats that window, not every fresh session after a process
+        // restart (issue #596; a post-restart session/load is covered by the
+        // resumed report above).
+        //
+        // The inference fallback is deliberately keyed to the catalog entry (the
+        // fork's unfiltered lookup, see `catalogModelInfo` above): a
+        // fallback-resolved sibling's resolvedModel/displayName/description can
+        // describe a different context lane than the verbatim live id (e.g. an
+        // "opus[1m]" row matched for a bare 200k id), so on the fallback path only
+        // the id itself is a trustworthy window signal.
+        const seededWindow = resumedContextWindow !== null
+            ? { size: resumedContextWindow, authoritative: true }
+            : immediateContextWindow(providerCacheKey, models.currentModelId, catalogModelInfo);
         this.sessions[sessionId] = {
             query: q,
             input: input,
@@ -3681,18 +4977,19 @@ export class ClaudeAcpAgent {
             agents,
             currentAgent,
             fastModeEnabled,
+            fastModeDisabledReason,
             abortController,
             emitRawSDKMessages: sessionMeta?.claudeCode?.emitRawSDKMessages ?? false,
-            contextWindowSize: 
-            // Deliberately keyed to the catalog entry: a fallback-resolved
-            // sibling's displayName/description can describe a different context
-            // lane than the verbatim live id (e.g. an "opus[1m]" row matched for
-            // a bare 200k id), so on the fallback path only the id itself is a
-            // trustworthy window signal.
-            inferContextWindowFromModel(models.currentModelId, catalogModelInfo?.displayName, catalogModelInfo?.description) ?? DEFAULT_CONTEXT_WINDOW,
+            forwardSubagentText,
+            contextWindowSize: seededWindow.size,
+            contextWindowAuthoritative: seededWindow.authoritative,
+            providerCacheKey,
             taskState,
             toolUseCache: {},
             emittedToolCalls: new Set(),
+            liveBackgroundTasks: new Map(),
+            emittedAssistantText: false,
+            owedTrailingIdles: 0,
             messageIdToUuid: new Map(),
         };
         return {
@@ -3762,27 +5059,76 @@ function snapshotFromUsage(usage) {
         cache_creation_input_tokens: usage.cache_creation_input_tokens ?? 0,
     };
 }
-function createEnvForGateway(request) {
+/**
+ * Adapt a legacy gateway `authenticate` request into the shared
+ * {@link ProviderConfig} shape. Returns `null` when no gateway request is
+ * present. `methodId` selects the protocol: `gateway-bedrock` → bedrock,
+ * otherwise anthropic.
+ */
+function gatewayRequestToProviderConfig(request) {
     if (!request?._meta) {
+        return null;
+    }
+    return {
+        apiType: request.methodId === "gateway-bedrock" ? "bedrock" : "anthropic",
+        baseUrl: request._meta.gateway.baseUrl,
+        headers: request._meta.gateway.headers,
+    };
+}
+/**
+ * Map a resolved provider config into the Claude Code env vars that redirect API
+ * traffic and inject headers. Returns an empty object when routing is
+ * unconfigured. The token/bypass placeholders (`" "`) are required so the CLI
+ * skips its normal login/credential checks when a gateway is in use.
+ */
+function createEnvForProvider(config) {
+    if (!config) {
         return {};
     }
-    const customHeaders = Object.entries(request._meta.gateway.headers)
+    const customHeaders = Object.entries(config.headers)
         .map(([key, value]) => `${key}: ${value}`)
         .join("\n");
-    if (request.methodId === "gateway-bedrock") {
+    if (config.apiType === "bedrock") {
         return {
             CLAUDE_CODE_USE_BEDROCK: "1",
             AWS_BEARER_TOKEN_BEDROCK: " ", // Must be non-empty to bypass pass configuration check
-            ANTHROPIC_BEDROCK_BASE_URL: request._meta.gateway.baseUrl,
+            ANTHROPIC_BEDROCK_BASE_URL: config.baseUrl,
+            ANTHROPIC_CUSTOM_HEADERS: customHeaders,
+        };
+    }
+    if (config.apiType === "vertex") {
+        // `config.vertex` is guaranteed present for vertex by `unstable_setProvider`
+        // validation; fall back to empty strings defensively.
+        return {
+            CLAUDE_CODE_USE_VERTEX: "1",
+            ANTHROPIC_VERTEX_BASE_URL: config.baseUrl,
+            ANTHROPIC_VERTEX_PROJECT_ID: config.vertex?.projectId ?? "",
+            CLOUD_ML_REGION: config.vertex?.region ?? "",
             ANTHROPIC_CUSTOM_HEADERS: customHeaders,
         };
     }
     return {
-        ANTHROPIC_BASE_URL: request._meta.gateway.baseUrl,
+        ANTHROPIC_BASE_URL: config.baseUrl,
         ANTHROPIC_CUSTOM_HEADERS: customHeaders,
         ANTHROPIC_AUTH_TOKEN: " ", // Must be specified to bypass claude login requirement
     };
 }
+/**
+ * Validate a provider base URL: must be a non-empty absolute http(s) URL.
+ */
+function isValidBaseUrl(baseUrl) {
+    if (typeof baseUrl !== "string" || baseUrl.trim() === "") {
+        return false;
+    }
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        return false;
+    }
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+}
 /**
  * Build the list of permission modes the agent will advertise for the given
  * model. `auto` is gated by `ModelInfo.supportsAutoMode === true`, which is
@@ -3832,7 +5178,10 @@ function buildAvailableModes(modelInfo) {
 // and only clears a key when an explicit `null` is sent — see
 // `applyFlagSettings` in @anthropic-ai/claude-agent-sdk. Mapping both the
 // `"default"` sentinel and `undefined` (effort option absent for the model) to
-// `null` ensures any previously-applied flag is actually cleared.
+// `null` ensures any previously-applied flag is actually cleared. Typed as
+// `EffortLevel` (not `Settings["effortLevel"]`): the picker offers whatever
+// `supportedEffortLevels` reports, which includes the session-scoped `"max"`
+// that the persisted Settings shape deliberately excludes.
 function toSdkEffortLevel(value) {
     return value === undefined || value === "default" ? null : value;
 }
@@ -3890,17 +5239,58 @@ const FAST_MODE_DESCRIPTION = "Faster responses on supported models";
 export function fastModeStateEnabled(state) {
     return state !== "off";
 }
+/** User-facing explanations for the SDK's `fast_mode_disabled_reason` values
+ *  that a user can act on (or at least wants to know about). Deliberately
+ *  partial — the omitted reasons are not worth surfacing:
+ *   - `sdk_opt_in_required`: every SDK session starts here (the toggle IS the
+ *     opt-in), so it describes the default, not a problem.
+ *   - `preference`: the user turned Fast mode off themselves.
+ *   - `pending`: eligibility is still resolving; the next report supersedes it.
+ *   - `unknown`: nothing meaningful to say.
+ *  Unknown future reasons fall through the same way (open set — the SDK's docs
+ *  say to ignore values you don't handle). */
+const FAST_MODE_UNAVAILABLE_EXPLANATIONS = {
+    free: "not available on the free plan",
+    extra_usage_disabled: "requires extra usage to be enabled for this account",
+    model_not_allowed: "not available for the selected model",
+    not_first_party: "not available on this API provider",
+    disabled_by_env: "disabled by environment configuration",
+    network_error: "eligibility could not be verified (network error)",
+};
+/** Normalize an SDK-reported `fast_mode_disabled_reason` to the one we retain:
+ *  a reason we have an explanation for, else `undefined`. Keeping only
+ *  explainable reasons means state comparisons (see `syncFastModeState`) track
+ *  exactly what the user can see, so routine reports like
+ *  `sdk_opt_in_required` never churn the config option. */
+export function normalizeFastModeDisabledReason(reason) {
+    return reason && FAST_MODE_UNAVAILABLE_EXPLANATIONS[reason] ? reason : undefined;
+}
 /** Build the Fast mode config option as a two-value on/off `select`. Emitted
- *  for EVERY Client — the boolean option shape is gone (story 006, R2.1). Only
- *  the emitted SHAPE is fixed to a select; boolean VALUES are still honored on
- *  set (see {@link resolveFastModeEnabled}). This factory is the single source
- *  of the option's shape, re-rendered by `refreshFastModeOption` /
- *  `syncFastModeState` so the shape can never desync. */
-export function createFastModeConfigOption(enabled) {
+ *  for EVERY Client — the boolean option shape is gone (story 006, R2.1;
+ *  retained through the v0.64.0 sync by story 008 R3.4). Only the emitted SHAPE
+ *  is fixed to a select; boolean VALUES are still honored on set (see
+ *  {@link resolveFastModeEnabled}). This factory is the single source of the
+ *  option's shape, re-rendered by `refreshFastModeOption` / `syncFastModeState`
+ *  so the shape can never desync.
+ *
+ *  `disabledReason` (the SDK's `fast_mode_disabled_reason`, upstream v0.64.0) is
+ *  folded into the description while the toggle reads off, so a user whose
+ *  account or provider can't serve Fast mode sees why instead of a switch that
+ *  silently refuses to stay on. Ignored while enabled: a reason reported
+ *  alongside an `on`/`cooldown` state isn't blocking anything right now.
+ *
+ *  Upstream's second parameter (`useBooleanOption`) is deliberately absent: the
+ *  shape is unconditionally a select, so there is no branch to select. What
+ *  guards that is behavioural, not structural — `tests/fast-mode-select-only.
+ *  test.ts` proves no argument combination can yield the boolean shape. */
+export function createFastModeConfigOption(enabled, disabledReason) {
+    const explanation = enabled
+        ? undefined
+        : disabledReason && FAST_MODE_UNAVAILABLE_EXPLANATIONS[disabledReason];
     return {
         id: FAST_MODE_CONFIG_ID,
         name: "Fast mode",
-        description: FAST_MODE_DESCRIPTION,
+        description: explanation ? `${FAST_MODE_DESCRIPTION} — ${explanation}` : FAST_MODE_DESCRIPTION,
         category: "model_config",
         type: "select",
         currentValue: enabled ? FAST_MODE_ON : FAST_MODE_OFF,
@@ -3993,7 +5383,7 @@ thinkingEnabled) {
     // option is always emitted as a two-value on/off select for every Client
     // (R2.1); boolean values remain accepted on set for boolean-era clients.
     if (fastMode?.supported) {
-        options.push(createFastModeConfigOption(fastMode.enabled));
+        options.push(createFastModeConfigOption(fastMode.enabled, fastMode.disabledReason));
     }
     // Surface the Thinking toggle whenever the caller supplies its display
     // state. Unlike Fast mode it is model-independent — no `supported` gate —
@@ -4334,17 +5724,26 @@ export function applyAvailableModelsAllowlist(sdkModels, allowlist, settingsMode
 }
 /** Read the model a resumed session is actually running (via the
  *  `getContextUsage` control request — the same source `/context` prints) and
- *  map it onto the picker. Best-effort: a control-request failure is logged
- *  and returns null so callers keep their current choice; failing the whole
- *  session/load over an unreadable report would be worse. */
+ *  map it onto the picker, along with the report's authoritative context
+ *  window (`rawMaxTokens`). Resumed sessions get this request serviced before
+ *  any turn runs in the new process — unlike fresh sessions, where it stalls
+ *  until the first prompt turn (issues #886/#880) — so the same response that
+ *  restores the live model (issue #845) also seeds the window for free,
+ *  covering post-restart reloads of models the text heuristic misses (issue
+ *  #596). Best-effort: a control-request failure is logged and returns nulls
+ *  so callers keep their current choice; failing the whole session/load over
+ *  an unreadable report would be worse. */
 async function readResumedLiveModel(query, models, logger) {
     try {
-        const liveModel = (await query.getContextUsage()).model;
-        return liveModel ? matchResumedModel(models, liveModel) : null;
+        const usage = await query.getContextUsage();
+        return {
+            model: usage.model ? matchResumedModel(models, usage.model) : null,
+            contextWindow: usage.rawMaxTokens > 0 ? usage.rawMaxTokens : null,
+        };
     }
     catch (error) {
         logger.error("Failed to read the resumed session's live model:", error);
-        return null;
+        return { model: null, contextWindow: null };
     }
 }
 async function getAvailableModels(query, 
@@ -4360,6 +5759,11 @@ pickerModels, sdkModels, settingsManager, logger, isResumedSession) {
     const settings = settingsManager.getSettings();
     let currentModel = models[0];
     let resolvedFromInput;
+    // The context window reported alongside a resumed session's live model.
+    // Only ever non-null on the paths where `currentModel` IS the live model
+    // (no override, or a failed override re-assert), so the window always
+    // describes the model the session actually runs.
+    let resumedContextWindow = null;
     // Model priority (highest to lowest):
     // 1. ANTHROPIC_MODEL environment variable
     // 2. settings.model (user configuration)
@@ -4387,7 +5791,9 @@ pickerModels, sdkModels, settingsManager, logger, isResumedSession) {
     // the SDK is already running this model, and pushing a picker alias back
     // (e.g. "opus[1m]") could change the live model rather than describe it.
     if (resolvedFromInput === undefined && isResumedSession) {
-        currentModel = (await readResumedLiveModel(query, models, logger)) ?? currentModel;
+        const live = await readResumedLiveModel(query, models, logger);
+        currentModel = live.model ?? currentModel;
+        resumedContextWindow = live.contextWindow;
     }
     // Skip the setModel round-trip when we can prove the SDK has already landed
     // on the same model. Two cases qualify:
@@ -4420,16 +5826,25 @@ pickerModels, sdkModels, settingsManager, logger, isResumedSession) {
             if (!isResumedSession)
                 throw error;
             logger.error(`Failed to re-assert model "${currentModel.value}" on resume:`, error);
-            currentModel = (await readResumedLiveModel(query, models, logger)) ?? currentModel;
+            const live = await readResumedLiveModel(query, models, logger);
+            currentModel = live.model ?? currentModel;
+            resumedContextWindow = live.contextWindow;
         }
     }
     return {
-        availableModels: pickerModels.map((model) => ({
-            modelId: model.value,
-            name: model.displayName,
-            description: model.description,
-        })),
-        currentModelId: currentModel.value,
+        modelState: {
+            // Picker rows come from the DEPRECATION-FILTERED list (`pickerModels`),
+            // not the raw catalog upstream maps here: the filter is visibility-only,
+            // so preference resolution and capability lookups elsewhere keep reading
+            // the unfiltered catalog (R4.3).
+            availableModels: pickerModels.map((model) => ({
+                modelId: model.value,
+                name: model.displayName,
+                description: model.description,
+            })),
+            currentModelId: currentModel.value,
+        },
+        resumedContextWindow,
     };
 }
 function getAvailableSlashCommands(commands) {
@@ -4567,6 +5982,12 @@ export function promptToClaude(prompt) {
         },
         session_id: prompt.sessionId,
         parent_tool_use_id: null,
+        // ACP prompts are the user's own input relayed by the client. Stamp the
+        // provenance explicitly: per the SDK, a host wrapping keyboard input must
+        // send `{kind: "human"}` — an absent `origin` is treated as unattributed
+        // and fails closed at the CLI's strict isHuman() trust gates (e.g. the
+        // ultracode keyword opt-in honors only human-originated turns).
+        origin: { kind: "human" },
     };
 }
 /**
@@ -4614,13 +6035,33 @@ function isTaskTool(toolName) {
         toolName === "TaskList" ||
         toolName === "TaskGet");
 }
-/** Whether a tool's tool_use surfaces to the client as a standalone
+/** Whether the streamed tool_use path surfaces this tool as a standalone
  *  `tool_call`. TodoWrite is rendered as a `plan` and Task* tools are
  *  suppressed (their plan snapshot is emitted at tool_result time), so neither
- *  produces a tool_call. */
+ *  produces a streamed tool_call/tool_call_update — which means a
+ *  permission-surfaced tool_call for them (see `ensureToolCallEmitted`) must be
+ *  resolved explicitly at tool_result time. */
 function shouldEmitToolCall(toolName) {
     return toolName !== "TodoWrite" && !isTaskTool(toolName);
 }
+/** Build the Claude Code-specific metadata for a tool call. Bash 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) {
+    const description = toolUse.name === "Bash" &&
+        toolUse.input !== null &&
+        typeof toolUse.input === "object" &&
+        "description" in toolUse.input &&
+        typeof toolUse.input.description === "string"
+        ? toolUse.input.description
+        : undefined;
+    return {
+        toolName: toolUse.name,
+        ...(description ? { title: description } : {}),
+        ...((toolUse.name === "Agent" || toolUse.name === "Task") && { subagent: true }),
+    };
+}
 /** 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 →
@@ -4631,7 +6072,7 @@ function shouldEmitToolCall(toolName) {
 function toolCallNotification(toolUse, rawInput, supportsTerminalOutput, cwd, refine = false) {
     if (refine) {
         return {
-            _meta: { claudeCode: { toolName: toolUse.name } },
+            _meta: { claudeCode: claudeCodeMetaFromToolUse(toolUse) },
             toolCallId: toolUse.id,
             sessionUpdate: "tool_call_update",
             rawInput,
@@ -4640,7 +6081,7 @@ function toolCallNotification(toolUse, rawInput, supportsTerminalOutput, cwd, re
     }
     return {
         _meta: {
-            claudeCode: { toolName: toolUse.name },
+            claudeCode: claudeCodeMetaFromToolUse(toolUse),
             ...(toolUse.name === "Bash" && supportsTerminalOutput
                 ? { terminal_info: { terminal_id: toolUse.id } }
                 : {}),
@@ -4652,6 +6093,57 @@ function toolCallNotification(toolUse, rawInput, supportsTerminalOutput, cwd, re
         ...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 }),
+        },
+        toolCallId: toolUse.id,
+        sessionUpdate: "tool_call_update",
+        rawInput: input,
+        title,
+        kind,
+        ...(locations ? { locations } : {}),
+    };
+}
+/** Validates the SDK user message's `tool_result_meta` sidecar (emitted on the
+ *  wire by CLI ≥ 2.1.216 but absent from sdk.d.ts, hence unknown-typed) into a
+ *  by-tool_use_id lookup. Each entry explains why an is_error tool_result
+ *  carries harness prose instead of the tool's own output — "user-rejected",
+ *  "permission-rule", "interrupted", "cancelled", … (open set: new kinds ship
+ *  on the wire ahead of schema updates, so no enum check). Malformed entries
+ *  are skipped rather than failing the message. */
+function parseToolResultMeta(raw) {
+    if (!Array.isArray(raw)) {
+        return undefined;
+    }
+    let byToolUseId;
+    for (const entry of raw) {
+        if (typeof entry !== "object" || entry === null) {
+            continue;
+        }
+        const { id, non_execution_kind, user_feedback } = entry;
+        if (typeof id !== "string" || typeof non_execution_kind !== "string") {
+            continue;
+        }
+        (byToolUseId ??= new Map()).set(id, {
+            nonExecutionKind: non_execution_kind,
+            ...(typeof user_feedback === "string" ? { userFeedback: user_feedback } : {}),
+        });
+    }
+    return byToolUseId;
+}
 /**
  * Convert an SDKAssistantMessage (Claude) to a SessionNotification (ACP).
  * Only handles text, image, and thinking chunks for now.
@@ -4683,6 +6175,18 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
         }
         return [{ sessionId, update }];
     }
+    // `tool_use_result` is message-level and carries no tool_use_id of its own:
+    // it describes "the" tool_result block of the message it rode in on. If
+    // several tool_result blocks were ever batched into one message it couldn't
+    // be attributed, so it is only honored when the message carries exactly one.
+    const toolUseResult = options?.toolUseResult !== undefined &&
+        content.filter((c) => typeof c === "object" && c !== null && c.type === "tool_result")
+            .length === 1
+        ? options.toolUseResult
+        : undefined;
+    // Unlike `tool_use_result`, entries carry their own tool_use_id, so batched
+    // messages need no single-block guard.
+    const toolResultMeta = parseToolResultMeta(options?.toolResultMeta);
     const output = [];
     // Only handle the first chunk for streaming; extend as needed for batching
     for (const chunk of content) {
@@ -4824,12 +6328,66 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
             case "bash_code_execution_tool_result":
             case "text_editor_code_execution_tool_result":
             case "mcp_tool_result": {
+                const wasEmitted = options?.emittedToolCalls?.has(chunk.tool_use_id) === true;
                 options?.emittedToolCalls?.delete(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
+                // untracked-tool fallback can't carry it (claudeCode metas always
+                // carry `toolName`, which is unknown there).
+                const nonExecution = toolResultMeta?.get(chunk.tool_use_id);
                 const toolUse = toolUseCache[chunk.tool_use_id];
                 if (!toolUse) {
+                    // The permission flow may have surfaced this tool_call even though
+                    // its tool_use never reached the cache (e.g. the assistant message
+                    // carrying it was dropped by the cancelled-turn guard and a straggler
+                    // result landed later). Resolve the surfaced call anyway so it can't
+                    // stay pending in the client forever; without the cache entry the
+                    // tool name is unknown, so no claudeCode meta is attached.
+                    if (wasEmitted) {
+                        output.push({
+                            sessionId,
+                            update: {
+                                toolCallId: chunk.tool_use_id,
+                                sessionUpdate: "tool_call_update",
+                                status: "is_error" in chunk && chunk.is_error
+                                    ? "failed"
+                                    : "completed",
+                                rawOutput: chunk.content,
+                            },
+                        });
+                    }
                     logger.error(`[claude-agent-acp] Got a tool result for tool use that wasn't tracked: ${chunk.tool_use_id}`);
                     break;
                 }
+                // A permission request may have surfaced a plan-rendered (TodoWrite) or
+                // suppressed (Task*) tool as a real tool_call so the request referenced
+                // a tool call the client knows about (see `ensureToolCallEmitted`,
+                // issue #851). The branches below never emit a tool_call_update for
+                // those tools, which would leave the surfaced call pending in the
+                // client forever — resolve it here. `wasEmitted` is only ever true for
+                // these tools via the permission flow: the streamed plan/suppressed
+                // branches don't record emissions.
+                if (wasEmitted && !shouldEmitToolCall(toolUse.name)) {
+                    output.push({
+                        sessionId,
+                        update: {
+                            _meta: {
+                                claudeCode: {
+                                    toolName: toolUse.name,
+                                    ...(nonExecution ?? {}),
+                                    ...(options?.parentToolUseId ? { parentToolUseId: options.parentToolUseId } : {}),
+                                },
+                            },
+                            toolCallId: chunk.tool_use_id,
+                            sessionUpdate: "tool_call_update",
+                            status: "is_error" in chunk && chunk.is_error
+                                ? "failed"
+                                : "completed",
+                            rawOutput: chunk.content,
+                        },
+                    });
+                }
                 if (isTaskTool(toolUse.name)) {
                     // Headless/SDK sessions emit Task* tools instead of TodoWrite.
                     // TaskCreate / TaskUpdate mutate the accumulated task list; TaskList
@@ -4853,7 +6411,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                     }
                 }
                 else if (toolUse.name !== "TodoWrite") {
-                    const { _meta: toolMeta, ...toolUpdate } = toolUpdateFromToolResult(chunk, toolUseCache[chunk.tool_use_id], supportsTerminalOutput);
+                    const { _meta: toolMeta, ...toolUpdate } = toolUpdateFromToolResult(chunk, toolUseCache[chunk.tool_use_id], supportsTerminalOutput, toolUseResult);
                     // When terminal output is supported, send terminal_output as a
                     // separate notification to match codex-acp's streaming lifecycle:
                     //   1. tool_call       → _meta.terminal_info  (already sent above)
@@ -4878,6 +6436,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                         _meta: {
                             claudeCode: {
                                 toolName: toolUse.name,
+                                ...(nonExecution ?? {}),
                             },
                             ...(toolMeta?.terminal_exit ? { terminal_exit: toolMeta.terminal_exit } : {}),
                         },
@@ -4930,35 +6489,105 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
 }
 export function streamEventToAcpNotifications(message, sessionId, toolUseCache, client, logger, options) {
     const event = message.event;
+    const streamKey = message.parent_tool_use_id ?? "";
+    const streamedToolInputs = options?.streamedToolInputs;
+    const forwardedOptions = {
+        clientCapabilities: options?.clientCapabilities,
+        parentToolUseId: message.parent_tool_use_id,
+        cwd: options?.cwd,
+        taskState: options?.taskState,
+        emittedToolCalls: options?.emittedToolCalls,
+        messageId: options?.messageId,
+    };
     switch (event.type) {
-        case "content_block_start":
-            return toAcpNotifications([event.content_block], "assistant", sessionId, toolUseCache, client, logger, {
-                clientCapabilities: options?.clientCapabilities,
-                parentToolUseId: message.parent_tool_use_id,
-                cwd: options?.cwd,
-                taskState: options?.taskState,
-                emittedToolCalls: options?.emittedToolCalls,
-                messageId: options?.messageId,
-            });
-        case "content_block_delta":
-            return toAcpNotifications([event.delta], "assistant", sessionId, toolUseCache, client, logger, {
-                clientCapabilities: options?.clientCapabilities,
-                parentToolUseId: message.parent_tool_use_id,
-                cwd: options?.cwd,
-                taskState: options?.taskState,
-                emittedToolCalls: options?.emittedToolCalls,
-                messageId: options?.messageId,
-            });
+        case "content_block_start": {
+            const block = event.content_block;
+            if (streamedToolInputs &&
+                (block.type === "tool_use" ||
+                    block.type === "server_tool_use" ||
+                    block.type === "mcp_tool_use")) {
+                let inputsForMessage = streamedToolInputs.get(streamKey);
+                if (!inputsForMessage) {
+                    inputsForMessage = new Map();
+                    streamedToolInputs.set(streamKey, inputsForMessage);
+                }
+                inputsForMessage.set(event.index, {
+                    id: block.id,
+                    name: block.name,
+                    partialJson: "",
+                    scannedTo: 0,
+                    inString: false,
+                    escaped: false,
+                    objectDepth: 0,
+                    arrayDepth: 0,
+                    lastTopLevelComma: -1,
+                    emittedThroughComma: -1,
+                });
+            }
+            return toAcpNotifications([block], "assistant", sessionId, toolUseCache, client, logger, forwardedOptions);
+        }
+        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)) {
+                    // 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.
+                    const inputsForMessage = streamedToolInputs?.get(streamKey);
+                    inputsForMessage?.delete(event.index);
+                    if (inputsForMessage?.size === 0)
+                        streamedToolInputs?.delete(streamKey);
+                    return [];
+                }
+                if (streamedInput.lastTopLevelComma <= streamedInput.emittedThroughComma) {
+                    return [];
+                }
+                streamedInput.emittedThroughComma = streamedInput.lastTopLevelComma;
+                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)
+                    return [];
+                if (message.parent_tool_use_id) {
+                    update._meta = {
+                        ...update._meta,
+                        claudeCode: {
+                            ...(update._meta?.claudeCode || {}),
+                            parentToolUseId: message.parent_tool_use_id,
+                        },
+                    };
+                }
+                applyMessageId(update, options?.messageId);
+                return [{ sessionId, update }];
+            }
+            return toAcpNotifications([event.delta], "assistant", sessionId, toolUseCache, client, logger, forwardedOptions);
+        }
         // No content. `ping` is a Messages-API keep-alive event that the SDK's
         // `BetaRawMessageStreamEvent` union doesn't include even though the
         // wire format emits it; the `as never` cast lets us no-op it here
         // instead of letting it fall through to `unreachable`.
         case "ping":
-        case "message_start":
         case "message_delta":
+            return [];
+        // A message boundary ends every input stream on this lane: message_stop is
+        // the normal end, and a message_start clears anything a prior message on
+        // the lane left behind (e.g. a stream cut short mid-block).
+        case "message_start":
         case "message_stop":
-        case "content_block_stop":
+            streamedToolInputs?.delete(streamKey);
             return [];
+        case "content_block_stop": {
+            const inputsForMessage = streamedToolInputs?.get(streamKey);
+            inputsForMessage?.delete(event.index);
+            if (inputsForMessage?.size === 0)
+                streamedToolInputs?.delete(streamKey);
+            return [];
+        }
         default:
             unreachable(event, logger);
             return [];
@@ -5016,9 +6645,13 @@ export function runAcp() {
         .onRequest(methods.agent.session.setMode, (ctx) => agent.setSessionMode(ctx.params))
         .onRequest(methods.agent.session.setConfigOption, (ctx) => agent.setSessionConfigOption(ctx.params))
         .onRequest(methods.agent.authenticate, (ctx) => agent.authenticate(ctx.params))
+        .onRequest(methods.agent.providers.list, (ctx) => agent.unstable_listProviders(ctx.params))
+        .onRequest(methods.agent.providers.set, (ctx) => agent.unstable_setProvider(ctx.params))
+        .onRequest(methods.agent.providers.disable, (ctx) => agent.unstable_disableProvider(ctx.params))
         .onRequest(methods.agent.logout, (ctx) => agent.logout(ctx.params))
         .onRequest(methods.agent.session.prompt, (ctx) => runPromptWithCancellation(agent, ctx.params, ctx.signal))
         .onNotification(methods.agent.session.cancel, (ctx) => agent.cancel(ctx.params))
+        .onRequest(STEER_METHOD, { parse: parseSteerRequest }, (ctx) => agent.steer(ctx.params))
         .connect(stream);
     agent = new ClaudeAcpAgent(new ClientConnection(connection.client));
     return { connection, agent };
@@ -5030,19 +6663,24 @@ function commonPrefixLength(a, b) {
     }
     return i;
 }
-/** Best-effort first guess of a model's context window, used only as a
- *  fallback when the SDK's authoritative `getContextUsage` is unavailable (and
- *  until a `result` message arrives with the `modelUsage` value).
+/** Best-effort first guess of a model's context window, used to seed the
+ *  window synchronously (via `immediateContextWindow`) until a `result` message
+ *  arrives with the authoritative `modelUsage` value.
  *
  *  Anthropic 1M-context variants encode "1m" as a distinct token in the SDK
  *  model ID (e.g., "claude-opus-4-6-1m"), which `\b1m\b` catches without also
  *  matching things like "10m" or embedded substrings. Semantic aliases like
- *  `default` carry no such token in the ID, but the SDK's human-facing
- *  `displayName`/`description` do (e.g. "Opus 4.7 (1M context)"), so callers
- *  pass those too — the same `\b1m\b` token appears in "1M context". The SDK's
- *  `ModelInfo` exposes no structured context-window field, so this text scan is
- *  the only pre-`result` signal available. A miss falls back to the default
- *  window and is corrected by `result.modelUsage` within one turn. */
+ *  `default` carry no such token in the ID, but their `resolvedModel` and the
+ *  SDK's human-facing `displayName`/`description` can (e.g.
+ *  "claude-opus-4-8[1m]", "Opus 4.7 (1M context)"), so callers pass those too.
+ *  This text scan can't catch every model — some resolve to extended-context
+ *  models with no "1m" anywhere (e.g. `sonnet` → claude-sonnet-5, natively
+ *  ~1M). Such a miss falls back to the default window and is corrected by
+ *  `result.modelUsage` (and cached) within one turn. We do NOT consult the
+ *  SDK's `getContextUsage` to close that gap: on a fresh session it is not
+ *  serviced before the first prompt turn (issues #886/#880, see
+ *  `contextWindowCache`; resumed sessions do get it, via
+ *  `readResumedLiveModel`). */
 function inferContextWindowFromModel(...texts) {
     if (texts.some((text) => text != null && /\b1m\b/i.test(text)))
         return 1_000_000;
@@ -5052,12 +6690,7 @@ function inferContextWindowFromModel(...texts) {
  *  `getContextUsage` control request. Unlike the per-message API usage numbers
  *  (which only count message tokens), this `totalTokens` includes the system
  *  prompt, tool schemas, MCP tools, and memory-file overhead — the real
- *  occupancy the user sees. Returns `null` on any control-request failure.
- *
- *  Note: we deliberately do NOT use this response's window fields for `size`.
- *  They have been observed to under-report extended (1M) context windows, so
- *  the window keeps coming from `modelUsage` / `inferContextWindowFromModel`,
- *  which handle the 1M variants correctly. */
+ *  occupancy the user sees. Returns `null` on any control-request failure. */
 async function fetchContextUsedTokens(query, logger) {
     try {
         const usage = await query.getContextUsage();
@@ -5068,6 +6701,95 @@ async function fetchContextUsedTokens(query, logger) {
         return null;
     }
 }
+/** Cross-session cache of authoritative context windows, keyed by
+ *  `${providerCacheKey}\0${modelId}` (see {@link contextWindowCacheKey}).
+ *  The window is a property of (model id, backend): the same resolved model id
+ *  (e.g. "claude-sonnet-5[1m]", the spelling of the `result.modelUsage` keys)
+ *  can name different context lanes behind different base URLs, routing
+ *  headers, or credentials, so the key carries both. Caching it module-level
+ *  lets a later session/new or switch that resolves to the same (backend,
+ *  model) — in this session or any other, within the adapter's lifetime — seed
+ *  the correct window synchronously with no IPC. Keying on the resolved id
+ *  (rather than the picker value) means aliases that resolve to the same
+ *  concrete model share one entry; the result handler additionally writes the
+ *  bare assistant-message spelling so seed-time reads that fall back to a
+ *  verbatim live id (rows without `resolvedModel`) can hit too.
+ *
+ *  Populated authoritatively by each `result.modelUsage` a turn confirms (see
+ *  the consumer's result handler). We deliberately never populate it from a
+ *  fresh session's `getContextUsage`: before that session's first prompt turn
+ *  has run the control request is not serviced (it stalls ~15s, and serializes
+ *  ahead of an awaited `setModel` — issues #886/#880, regressed in 0.59.0), so
+ *  it can neither beat the first `result` nor be issued cheaply before one.
+ *  Resumed sessions are the exception — their report IS serviced pre-turn, and
+ *  the session/load path seeds (but does not cache) the window from the same
+ *  response that restores the live model, see `readResumedLiveModel`.
+ *  Cleared on `logout`: 1M-context entitlement can differ per account/tier, so
+ *  windows learned under one login must not seed sessions under the next. */
+const contextWindowCache = new Map();
+/** The env vars that determine which LLM backend — and which context lane on
+ *  it — a query's API traffic reaches: endpoint selection (base URLs and the
+ *  Bedrock/Vertex switches with their project/region), routing/beta headers
+ *  (an `anthropic-beta: context-1m-…` header flips the same model id at the
+ *  same endpoint between context lanes), and credential identity (extended
+ *  context is entitlement-gated per account). Used to derive the
+ *  provider-cache key from the exact env a query is created with, so
+ *  `providers/set` config, per-session `_meta` env overrides, and ambient
+ *  process env are all distinguished exactly as the CLI will see them. */
+const PROVIDER_ROUTING_ENV_VARS = [
+    "ANTHROPIC_BASE_URL",
+    "ANTHROPIC_BEDROCK_BASE_URL",
+    "ANTHROPIC_VERTEX_BASE_URL",
+    "CLAUDE_CODE_USE_BEDROCK",
+    "CLAUDE_CODE_USE_VERTEX",
+    "ANTHROPIC_VERTEX_PROJECT_ID",
+    "CLOUD_ML_REGION",
+    "AWS_REGION",
+    "ANTHROPIC_CUSTOM_HEADERS",
+    "ANTHROPIC_API_KEY",
+    "ANTHROPIC_AUTH_TOKEN",
+];
+/** Stable identifier for the LLM backend a session's query is created against,
+ *  used to scope {@link contextWindowCache} per backend. Positional `\0`-join
+ *  of {@link PROVIDER_ROUTING_ENV_VARS} values, so no segment can masquerade
+ *  as another and unset vars everywhere yield one stable "default" bucket.
+ *  Header/credential values can be secrets; the key only ever lives as an
+ *  in-memory Map key and is never logged or surfaced. Over-keying is the safe
+ *  side: a var change that didn't really change the backend costs one cache
+ *  miss (heuristic seed until the next result), while under-keying would serve
+ *  one backend's window for another's. */
+function providerCacheKeyFor(env) {
+    return PROVIDER_ROUTING_ENV_VARS.map((name) => env[name] ?? "").join("\0");
+}
+/** Compose the `contextWindowCache` key from a session's provider key and a
+ *  model id. `\0`-joined so the model segment can't collide with a provider
+ *  segment. */
+function contextWindowCacheKey(providerCacheKey, modelId) {
+    return `${providerCacheKey}\0${modelId}`;
+}
+function cacheContextWindow(modelKey, window) {
+    if (window > 0) {
+        contextWindowCache.set(modelKey, window);
+    }
+}
+/** The context window to report *right now* for a model, with NO IPC on the
+ *  critical path: the cached authoritative value if we've learned it (from a
+ *  prior turn's `result.modelUsage`, this or any session on the same backend),
+ *  else the text heuristic over the model row's identity strings, else the
+ *  default. Derives the cache key itself — `modelInfo?.resolvedModel ?? modelId`,
+ *  the same rule at every seed site — so read keys can't drift from the write
+ *  site's spelling. `authoritative` reports whether the value came from the
+ *  cache: an authoritative window can legitimately equal
+ *  DEFAULT_CONTEXT_WINDOW, so the value alone can't tell the caller. */
+function immediateContextWindow(providerCacheKey, modelId, modelInfo) {
+    const cached = contextWindowCache.get(contextWindowCacheKey(providerCacheKey, modelInfo?.resolvedModel ?? modelId));
+    if (cached !== undefined)
+        return { size: cached, authoritative: true };
+    return {
+        size: inferContextWindowFromModel(modelId, modelInfo?.resolvedModel, modelInfo?.displayName, modelInfo?.description) ?? DEFAULT_CONTEXT_WINDOW,
+        authoritative: false,
+    };
+}
 function parseModelConfig(raw) {
     if (!raw)
         return undefined;
@@ -5093,6 +6815,12 @@ function getMatchingModelUsage(modelUsage, currentModel) {
         }
     }
     if (bestKey) {
-        return modelUsage[bestKey];
+        // `bestKey` is the SDK's resolved model id (e.g. "claude-sonnet-5[1m]"),
+        // the same spelling as ModelInfo.resolvedModel — the primary key the
+        // window is cached under. `currentModel` (the assistant message's
+        // `.model`) can be the bare form (e.g. "claude-sonnet-5"); the result
+        // handler caches under that spelling too, for seed-time reads that fall
+        // back to a bare id (rows without `resolvedModel`).
+        return { key: bestKey, usage: modelUsage[bestKey] };
     }
 }