claude-code-acp-ts 0.53.0 → 0.57.0-beta.2

package/dist/acp-agent.js

@@ -7,7 +7,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { promisify } from "node:util";
 import packageJson from "../package.json" with { type: "json" };
-import { applyAskElicitationResponse, askUserQuestionsToCreateRequest, createElicitationResponseToElicitResult, extractAskUserQuestions, mcpElicitationToCreateRequest, } from "./elicitation.js";
+import { applyAskElicitationResponse, askUserQuestionsToCreateRequest, createElicitationResponseToElicitResult, extractAskUserQuestions, extractRefusalFallbackPrompt, mcpElicitationToCreateRequest, REFUSAL_FALLBACK_DIALOG_KIND, refusalFallbackResultFromResponse, refusalFallbackToCreateRequest, } from "./elicitation.js";
 import { SettingsManager } from "./settings.js";
 import { applyTaskCreate, applyTaskUpdate, createPostToolUseHook, createTaskHook, parseTaskCreateOutput, planEntries, registerHookCallback, taskStateToPlanEntries, toolInfoFromToolUse, toolUpdateFromDiffToolResponse, toolUpdateFromToolResult, } from "./tools.js";
 import { nodeToWebReadable, nodeToWebWritable, Pushable, unreachable } from "./utils.js";
@@ -42,6 +42,12 @@ const DEFAULT_CONTEXT_WINDOW = 200000;
  *  "obviously stuck" ceiling, not a guess at interrupt latency, so it can't
  *  pre-empt a slow-but-healthy interrupt. */
 const DEFAULT_FORCE_CANCEL_GRACE_MS = 30_000;
+/** Error surfaced when the SDK declares a turn over (`session_state_changed:
+ *  idle`, its authoritative turn-over signal) without ever emitting the turn's
+ *  `result` — a model stream that dropped mid-turn, or an async agent that
+ *  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.";
 /** 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
@@ -185,6 +191,9 @@ export function isLocalCommandMetadata(content) {
 const PERMISSION_MODE_ALIASES = {
     auto: "auto",
     default: "default",
+    // Claude Code 2.1.200 renamed the "default" mode to "Manual" and accepts
+    // `"defaultMode": "manual"` in settings.json; honor the same alias here.
+    manual: "default",
     acceptedits: "acceptEdits",
     dontask: "dontAsk",
     plan: "plan",
@@ -660,6 +669,20 @@ export class ClaudeAcpAgent {
         // 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;
         const resetTurnScratch = () => {
             lastAssistantTotalUsage = null;
             lastAssistantUsage = null;
@@ -780,9 +803,19 @@ export class ClaudeAcpAgent {
         // settle "cancelled" even when query.next() is wedged (issue #680). Re-armed
         // after each fire so the consumer keeps serving later turns.
         let cancelController = session.cancelController;
+        // The in-flight query.next(), kept across abort wake-ups that don't
+        // consume a message, so no yielded message is ever dropped — async
+        // generators serialize next() calls, so racing a SECOND next() while one
+        // is pending would make the abandoned one swallow a message (e.g. a
+        // force-cancelled turn's late result, whose orphan accounting below
+        // depends on actually seeing it).
+        let pendingNext = null;
         try {
             while (true) {
-                const nextMessage = session.query.next();
+                pendingNext ??= session.query
+                    .next()
+                    .then((result) => ({ kind: "message", result }));
+                const nextMessage = pendingNext;
                 // Fresh abort listener per iteration, removed when next() wins, so a
                 // long-lived session doesn't accumulate listeners on one signal.
                 let onAbort;
@@ -790,25 +823,36 @@ export class ClaudeAcpAgent {
                     onAbort = () => resolve("abort");
                     cancelController.signal.addEventListener("abort", onAbort, { once: true });
                 });
-                const raced = await Promise.race([
-                    nextMessage.then((result) => ({ kind: "message", result })),
-                    abortRace,
-                ]);
+                const raced = await Promise.race([nextMessage, abortRace]);
                 cancelController.signal.removeEventListener("abort", onAbort);
                 if (raced === "abort") {
-                    // cancel()/teardown woke us. Abandon the in-flight next() (swallowing
-                    // any later rejection so it can't surface as unhandled) and settle the
-                    // active turn "cancelled" per the ACP contract. If the session is
-                    // being torn down, stop; otherwise re-arm and keep consuming.
-                    void nextMessage.catch(() => { });
-                    settleActive({ stopReason: "cancelled" });
+                    // cancel()/teardown woke us: settle the active turn "cancelled" per
+                    // the ACP contract. The SDK never acknowledged this turn (that's why
+                    // the force-cancel backstop fired), so if it later recovers from the
+                    // wedge it will still emit the turn's result — with no live turn to
+                    // match — followed by its trailing idle. Pre-count it as an orphan
+                    // so that late result is skipped (not promoted onto the next queued
+                    // prompt) and its trailer is recorded as owed, not read as the next
+                    // turn being abandoned. Stale counts self-heal: activation resets
+                    // them (see activateTurn).
+                    if (session.activeTurn && !session.activeTurn.settled) {
+                        session.pendingOrphanResults = (session.pendingOrphanResults ?? 0) + 1;
+                    }
+                    settleActive({ stopReason: "cancelled", usage: sessionUsage(session) });
+                    // If the session is being torn down, abandon the in-flight next()
+                    // (swallowing any later rejection so it can't surface as unhandled)
+                    // and stop; otherwise re-arm and keep consuming — `pendingNext`
+                    // stays in flight so its eventual message is processed, not dropped.
                     if (!this.sessions[params.sessionId]) {
+                        void nextMessage.catch(() => { });
                         return;
                     }
                     cancelController = new AbortController();
                     session.cancelController = cancelController;
                     continue;
                 }
+                // A message arrived: this next() is consumed; arm a fresh one next pass.
+                pendingNext = null;
                 const { value: message, done } = raced.result;
                 if (done || !message) {
                     // The stream ended. Settle the in-flight turns FIRST, then release the
@@ -819,9 +863,10 @@ export class ClaudeAcpAgent {
                     //
                     // Settle the turn that was in flight so its prompt() doesn't hang:
                     // cancelled if a cancel is pending, otherwise the accumulated outcome.
-                    settleActive(session.cancelled
-                        ? { stopReason: "cancelled" }
-                        : { stopReason, usage: sessionUsage(session) });
+                    settleActive({
+                        stopReason: session.cancelled ? "cancelled" : 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
@@ -852,6 +897,10 @@ export class ClaudeAcpAgent {
                     case "system":
                         switch (message.subtype) {
                             case "init":
+                                // 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);
                                 break;
                             case "status": {
                                 if (message.status === "compacting") {
@@ -937,19 +986,60 @@ export class ClaudeAcpAgent {
                             }
                             case "session_state_changed": {
                                 if (message.state === "idle") {
-                                    // A non-cancelled turn already settled at its terminal
-                                    // `result` (issue #773), so this trailing `idle` is just
-                                    // absorbed. We must NOT settle `activeTurn` here in that case:
-                                    // `idle` carries no turn identity, and it can lag (the SDK
-                                    // flushes held-back results / drains background agents first),
-                                    // so by the time it arrives the SDK may have echoed the NEXT
-                                    // turn and activated it — settling now would resolve that new
-                                    // turn prematurely with end_turn and ~zero usage, dropping its
-                                    // real result. Only a cancelled turn relies on `idle`: its
-                                    // `result` is dropped at the `session.cancelled` guard, so it
-                                    // never settles at a result and must settle here.
-                                    if (session.cancelled) {
-                                        settleActive({ stopReason: "cancelled" });
+                                    // A non-cancelled turn normally settled at its terminal
+                                    // `result` already (issue #773), and that result recorded an
+                                    // owed trailing idle — absorbed here via the decrement. We
+                                    // must NOT settle `activeTurn` on an owed idle: `idle`
+                                    // carries no turn identity, and it can lag (the SDK flushes
+                                    // held-back results / drains background agents first), so by
+                                    // the time it arrives the SDK may have echoed the NEXT turn
+                                    // and activated it — settling now would resolve that new
+                                    // turn prematurely with end_turn and ~zero usage, dropping
+                                    // its real result. A cancelled turn relies on `idle`: its
+                                    // `result` is dropped at the `session.cancelled` guard, so
+                                    // it never settles at a result and must settle here.
+                                    //
+                                    // An idle that is NOT owed while the active turn is still
+                                    // unsettled is the issue #825 signature: `idle` is the SDK's
+                                    // authoritative turn-over signal (it fires after held-back
+                                    // results flush and background agents drain), so a turn that
+                                    // reaches it without a result will never get one — the model
+                                    // stream dropped mid-turn, or an async agent
+                                    // completed/stalled without the host turn resolving. Fail
+                                    // the turn NOW so its session/prompt gets a terminal
+                                    // response, instead of leaving it hanging until the next
+                                    // prompt drains the wreckage.
+                                    // A cancelled turn still consumed tokens: its dropped result
+                                    // already fed the accumulator (the usage tally at the result
+                                    // handler runs before the `session.cancelled` guard), so
+                                    // report it — clients metering spend would otherwise lose
+                                    // the interrupted turn's tokens entirely (issue #844). Zero
+                                    // when the cancel pre-empted the result (wedge/force-cancel).
+                                    if (session.cancelled && session.activeTurn && !session.activeTurn.settled) {
+                                        settleActive({ stopReason: "cancelled", usage: sessionUsage(session) });
+                                    }
+                                    else if (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--;
+                                    }
+                                    else if (!session.cancelled &&
+                                        session.activeTurn &&
+                                        !session.activeTurn.settled) {
+                                        // Deliberately only the ACTIVE turn: a queued turn that
+                                        // was never echoed is NOT failed here, because an idle
+                                        // can legitimately precede the SDK picking up freshly
+                                        // pushed input (the idle was emitted before the SDK read
+                                        // it) — failing the queue head on that race would reject
+                                        // a prompt the SDK is about to run. A turn abandoned
+                                        // before its echo therefore still hangs until cancel or
+                                        // the next prompt; only a timer could tell those apart.
+                                        this.logger.error(`Session ${params.sessionId}: SDK went idle without emitting a result ` +
+                                            `for the active turn; failing the in-flight prompt (issue #825)`);
+                                        failActive(RequestError.internalError(errorKindData("no_result"), TURN_NO_RESULT_MESSAGE));
                                     }
                                     // The SDK generates the session title in a background task and
                                     // persists it to the session file; `idle` is the turn-over
@@ -1105,9 +1195,65 @@ export class ClaudeAcpAgent {
                             case "notification":
                             case "api_retry":
                             case "thinking_tokens":
-                            case "model_refusal_fallback":
                                 // Todo: process via status api: https://docs.claude.com/en/docs/claude-code/hooks#hook-output
                                 break;
+                            case "model_refusal_fallback": {
+                                // The SDK retried a refused turn on the fallback model and made
+                                // the swap persistent for the session. Without a notice the
+                                // user just sees regenerated output; without the state sync the
+                                // client's model picker (and the model-dependent options
+                                // rebuilt from it) keeps advertising a model the session is no
+                                // longer running.
+                                //
+                                // Current CLIs only emit direction "retry" (persistent swap).
+                                // "revert"/"sticky" are retained in the SDK enum for older
+                                // CLIs, where "revert" marked a turn-only fallback — for that
+                                // direction the session stays on the original model, so skip
+                                // the persistent-swap claim and the state sync.
+                                const persistent = message.direction !== "revert";
+                                const category = message.api_refusal_category
+                                    ? ` (${message.api_refusal_category})`
+                                    : "";
+                                const explanation = message.api_refusal_explanation
+                                    ? `\n\n${message.api_refusal_explanation}`
+                                    : "";
+                                const outcome = persistent
+                                    ? `The session will continue on ${message.fallback_model}.`
+                                    : `The session stays on ${message.original_model}.`;
+                                await this.client.sessionUpdate({
+                                    sessionId: message.session_id,
+                                    update: {
+                                        sessionUpdate: "agent_message_chunk",
+                                        content: {
+                                            type: "text",
+                                            text: `**Model fallback:** ${message.original_model} declined this request${category}; retried with ${message.fallback_model}. ${outcome}${explanation}`,
+                                        },
+                                    },
+                                });
+                                if (persistent) {
+                                    await this.syncModelAfterRefusalFallback(params.sessionId, session, message.fallback_model);
+                                }
+                                break;
+                            }
+                            case "model_refusal_no_fallback":
+                                // The refusal ends the turn as an error; the terminal `result`
+                                // handler settles it with ACP's `refusal` stop reason and
+                                // streams `lastRefusalExplanation`. The assistant frame's
+                                // stop_details is the primary source for that explanation —
+                                // this structured banner is the backup source when the frame
+                                // carried none (older CLIs, gateways that drop stop_details).
+                                //
+                                // `refused_user_message_uuid` is explicitly null when the
+                                // refused turn was not human-authored (a background
+                                // task-notification followup or auto-continuation) — don't
+                                // let those pollute the user turn's explanation. `undefined`
+                                // (older CLIs that omit the field) can't be attributed either
+                                // way, so keep seeding — the same exposure the assistant-frame
+                                // capture already has.
+                                if (!lastRefusalExplanation && message.refused_user_message_uuid !== null) {
+                                    lastRefusalExplanation = message.api_refusal_explanation ?? message.content;
+                                }
+                                break;
                             default:
                                 unreachable(message, this.logger);
                                 break;
@@ -1119,6 +1265,13 @@ export class ClaudeAcpAgent {
                         // 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.
@@ -1127,6 +1280,23 @@ export class ClaudeAcpAgent {
                         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
@@ -1305,7 +1475,7 @@ export class ClaudeAcpAgent {
                             // create a block the consolidated handler's `text.length > 0`
                             // guard can never consume, stalling the diff cursor and
                             // re-emitting the next block as a duplicate.
-                            if (chunk && chunk.text.length > 0) {
+                            if (chunk?.text) {
                                 const index = message.event.index;
                                 const last = streamedBlocks[streamedBlocks.length - 1];
                                 if (last && last.index === index && last.type === chunk.type) {
@@ -1367,6 +1537,7 @@ export class ClaudeAcpAgent {
                             clientCapabilities: this.clientCapabilities,
                             cwd: session.cwd,
                             taskState: session.taskState,
+                            emittedToolCalls: session.emittedToolCalls,
                             messageId: currentStreamMessageId,
                         })) {
                             await this.client.sessionUpdate(notification);
@@ -1402,9 +1573,20 @@ export class ClaudeAcpAgent {
                                         // "cancelled" per the ACP contract rather than "end_turn" —
                                         // otherwise a cancel followed quickly by the next prompt
                                         // would report the cancelled turn as a normal completion.
-                                        settleActive(session.cancelled
-                                            ? { stopReason: "cancelled" }
-                                            : { stopReason: "end_turn", usage: sessionUsage(session) });
+                                        if (session.cancelled) {
+                                            // The cancelled turn settles here, but the trailing idle
+                                            // its interrupt produces is still in flight — record the
+                                            // 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++;
+                                            // Before activateTurn resets the accumulator, so the
+                                            // usage still belongs to the cancelled turn.
+                                            settleActive({ stopReason: "cancelled", usage: sessionUsage(session) });
+                                        }
+                                        else {
+                                            settleActive({ stopReason: "end_turn", usage: sessionUsage(session) });
+                                        }
                                     }
                                     activateTurn(queued);
                                 }
@@ -1432,7 +1614,13 @@ export class ClaudeAcpAgent {
                                 lastAssistantError = message.error;
                             }
                             if (message.message.stop_reason === "refusal") {
-                                lastRefusalExplanation = message.message.stop_details?.explanation ?? null;
+                                // Keep any explanation already seeded by a
+                                // `model_refusal_no_fallback` banner — the banner/frame
+                                // ordering is CLI-dependent, and a frame whose stop_details
+                                // was dropped (the case the banner backup exists for) must
+                                // not clobber the seed back to null.
+                                lastRefusalExplanation =
+                                    message.message.stop_details?.explanation ?? lastRefusalExplanation;
                             }
                         }
                         // Strip <command-*>/<local-command-stdout> markers and render any
@@ -1562,6 +1750,7 @@ export class ClaudeAcpAgent {
                             parentToolUseId: message.parent_tool_use_id,
                             cwd: session.cwd,
                             taskState: session.taskState,
+                            emittedToolCalls: session.emittedToolCalls,
                             messageId: messageIdForGrouping(message),
                         })) {
                             await this.client.sessionUpdate(notification);
@@ -1599,9 +1788,16 @@ export class ClaudeAcpAgent {
                         }
                         break;
                     }
+                    // `conversation_reset` (from `/clear`, plan-mode exit, fresh-session
+                    // flows) is safe to drop: turn lifecycle here is driven by
+                    // results/idle, and the client owns its own transcript view.
+                    // `control_request_progress` only reports on side_question control
+                    // requests, which this adapter never issues.
                     case "tool_use_summary":
                     case "auth_status":
                     case "prompt_suggestion":
+                    case "conversation_reset":
+                    case "control_request_progress":
                         break;
                     default:
                         unreachable(message);
@@ -1663,6 +1859,8 @@ export class ClaudeAcpAgent {
             for (const turn of session.turnQueue) {
                 if (turn !== session.activeTurn && !turn.settled) {
                     turn.settled = true;
+                    // 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" });
                     orphaned++;
                 }
@@ -1786,7 +1984,7 @@ export class ClaudeAcpAgent {
             throw RequestError.internalError(undefined, SESSION_ENDED_MESSAGE);
         }
         await this.applySessionMode(params.sessionId, params.modeId);
-        await this.updateConfigOption(params.sessionId, "mode", params.modeId);
+        await this.updateConfigOption(params.sessionId, MODE_CONFIG_ID, params.modeId);
         return {};
     }
     async setSessionConfigOption(params) {
@@ -1801,29 +1999,54 @@ export class ClaudeAcpAgent {
         if (session.queryClosed) {
             throw RequestError.internalError(undefined, SESSION_ENDED_MESSAGE);
         }
-        if (typeof params.value !== "string") {
-            throw new Error(`Invalid value for config option ${params.configId}: ${params.value}`);
-        }
         const option = session.configOptions.find((o) => o.id === params.configId);
         if (!option) {
             throw new Error(`Unknown config option: ${params.configId}`);
         }
+        // Fast mode carries a boolean value (for Clients that opted into boolean
+        // config options) or the "on"/"off" select fallback, so it bypasses the
+        // string-only validation the select-style options below rely on.
+        if (params.configId === FAST_MODE_CONFIG_ID) {
+            await this.applyFastMode(session, resolveFastModeEnabled(params));
+            return { configOptions: session.configOptions };
+        }
+        if (typeof params.value !== "string") {
+            throw new Error(`Invalid value for config option ${params.configId}: ${params.value}`);
+        }
         const allValues = "options" in option && Array.isArray(option.options)
             ? option.options.flatMap((o) => ("options" in o ? o.options : [o]))
             : [];
         let validValue = allValues.find((o) => o.value === params.value);
+        // The option's reported currentValue is always a valid target, even when
+        // it has no options entry: a session running an out-of-picker model
+        // (resumed onto an allowlist-excluded model, or a refusal fallback)
+        // reports a currentValue that isn't selectable, and a client
+        // round-tripping it must not get "Invalid value". It flows through the
+        // normal apply path below — re-asserting an already-current value is
+        // harmless and can repair SDK drift.
+        if (!validValue && option.currentValue === params.value) {
+            validValue = { value: params.value, name: params.value };
+        }
         // For model options, fall back to resolveModelPreference when the exact
         // value doesn't match.  This lets callers use human-friendly aliases like
         // "opus" or "sonnet" instead of full model IDs like "claude-opus-4-6".
-        if (!validValue && params.configId === "model") {
-            const modelInfos = allValues.map((o) => ({
-                value: o.value,
-                displayName: o.name,
-                description: o.description ?? "",
-            }));
-            const resolved = resolveModelPreference(modelInfos, params.value);
-            if (resolved) {
-                validValue = allValues.find((o) => o.value === resolved.value);
+        // Resolve against session.modelInfos first: those entries carry
+        // `resolvedModel`, so a full model id (in either hint spelling) lands on
+        // the right row via the exact tier instead of a fuzzier one picking a
+        // same-family sibling from a different context lane. The options-derived
+        // list (which never carries `resolvedModel`) remains as a fallback for
+        // resolutions that don't map back onto a selectable option (e.g. a fuzzy
+        // hit on an out-of-picker verbatim entry).
+        if (!validValue && params.configId === MODEL_CONFIG_ID) {
+            const toOptionValue = (resolved) => resolved ? allValues.find((o) => o.value === resolved.value) : undefined;
+            validValue = toOptionValue(resolveModelPreference(session.modelInfos, params.value));
+            if (!validValue) {
+                const optionInfos = allValues.map((o) => ({
+                    value: o.value,
+                    displayName: o.name,
+                    description: o.description ?? "",
+                }));
+                validValue = toOptionValue(resolveModelPreference(optionInfos, params.value));
             }
         }
         if (!validValue) {
@@ -1832,7 +2055,7 @@ export class ClaudeAcpAgent {
         // Use the canonical option value so downstream code always receives the
         // model ID rather than the caller-supplied alias.
         const resolvedValue = validValue.value;
-        if (params.configId === "mode") {
+        if (params.configId === MODE_CONFIG_ID) {
             await this.applySessionMode(params.sessionId, resolvedValue);
             await this.client.sessionUpdate({
                 sessionId: params.sessionId,
@@ -1842,7 +2065,7 @@ export class ClaudeAcpAgent {
                 },
             });
         }
-        else if (params.configId === "model") {
+        else if (params.configId === MODEL_CONFIG_ID) {
             await this.sessions[params.sessionId].query.setModel(resolvedValue);
         }
         // Effort SDK sync is handled inside applyConfigOptionValue so that direct
@@ -1937,7 +2160,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, signal) {
+    async requestPermissionFromClient(params, toolName, signal) {
+        // 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);
         try {
             return await this.client.requestPermission(params, signal);
         }
@@ -1948,6 +2178,28 @@ export class ClaudeAcpAgent {
             throw error;
         }
     }
+    /** Emit the `tool_call` a permission request references if it hasn't been sent
+     *  yet, so the client has the tool call before being asked to approve it. The
+     *  matching streamed tool_use chunk later refines it with a `tool_call_update`
+     *  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) {
+        const session = this.sessions[sessionId];
+        if (!session || !shouldEmitToolCall(toolName)) {
+            return;
+        }
+        if (session.emittedToolCalls.has(toolCallId)) {
+            return;
+        }
+        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),
+        });
+    }
     canUseTool(sessionId) {
         return async (toolName, toolInput, { signal, suggestions, toolUseID }) => {
             const alwaysAllowLabel = describeAlwaysAllow(suggestions, toolName);
@@ -1964,6 +2216,9 @@ export class ClaudeAcpAgent {
             // than the interactive dialog). Present it as an ACP form elicitation and
             // feed the answers back as updatedInput for the tool's own call() to read.
             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);
                 return this.handleAskUserQuestion(sessionId, toolInput, toolUseID, signal);
             }
             if (toolName === "ExitPlanMode") {
@@ -1998,7 +2253,7 @@ export class ClaudeAcpAgent {
                         rawInput: toolInput,
                         ...toolInfoFromToolUse({ name: toolName, input: toolInput, id: toolUseID }, supportsTerminalOutput, session?.cwd),
                     },
-                }, signal);
+                }, toolName, signal);
                 if (signal.aborted || response.outcome?.outcome === "cancelled") {
                     throw new Error("Tool use aborted");
                 }
@@ -2016,7 +2271,7 @@ export class ClaudeAcpAgent {
                             currentModeId: selectedMode,
                         },
                     });
-                    await this.updateConfigOption(sessionId, "mode", selectedMode);
+                    await this.updateConfigOption(sessionId, MODE_CONFIG_ID, selectedMode);
                     return {
                         behavior: "allow",
                         updatedInput: toolInput,
@@ -2057,7 +2312,7 @@ export class ClaudeAcpAgent {
                     rawInput: toolInput,
                     ...toolInfoFromToolUse({ name: toolName, input: toolInput, id: toolUseID }, supportsTerminalOutput, session?.cwd),
                 },
-            }, signal);
+            }, toolName, signal);
             if (signal.aborted || response.outcome?.outcome === "cancelled") {
                 throw new Error("Tool use aborted");
             }
@@ -2157,6 +2412,44 @@ export class ClaudeAcpAgent {
         }
         return { behavior: "allow", updatedInput: outcome.updatedInput };
     }
+    /**
+     * Handle `request_user_dialog` control requests — blocking dialogs the CLI
+     * asks the host to render. Only kinds declared in `supportedDialogKinds`
+     * are ever emitted; everything unexpected is answered `cancelled` (the
+     * required answer for unrecognized kinds), which applies the dialog's
+     * default behavior CLI-side. Today the only declared kind is the
+     * refusal-fallback consent prompt, rendered as an ACP form elicitation.
+     */
+    handleUserDialog(sessionId) {
+        return async (request, { signal }) => {
+            if (request.dialogKind !== REFUSAL_FALLBACK_DIALOG_KIND) {
+                return { behavior: "cancelled" };
+            }
+            const prompt = extractRefusalFallbackPrompt(request.payload);
+            if (!prompt) {
+                this.logger.error(`refusal_fallback_prompt payload had an unexpected shape; cancelling the dialog: ${JSON.stringify(request.payload)}`);
+                return { behavior: "cancelled" };
+            }
+            let response;
+            try {
+                response = await this.client.unstable_createElicitation(refusalFallbackToCreateRequest(prompt, sessionId), signal);
+            }
+            catch (error) {
+                // A cancellation we requested (signal aborted) is expected teardown;
+                // anything else is a client failure. Either way the safe answer is
+                // `cancelled` — the CLI applies the dialog's default (keep the
+                // refusal) rather than switching models without consent.
+                if (!signal.aborted) {
+                    this.logger.error(`Failed to present refusal fallback elicitation: ${error}`);
+                }
+                return { behavior: "cancelled" };
+            }
+            if (signal.aborted) {
+                return { behavior: "cancelled" };
+            }
+            return { behavior: "completed", result: refusalFallbackResultFromResponse(response) };
+        };
+    }
     async sendAvailableCommandsUpdate(sessionId) {
         const session = this.sessions[sessionId];
         if (!session)
@@ -2184,11 +2477,11 @@ export class ClaudeAcpAgent {
         });
     }
     async applyConfigOptionValue(sessionId, session, configId, value) {
-        if (configId === "mode") {
+        if (configId === MODE_CONFIG_ID) {
             session.modes = { ...session.modes, currentModeId: value };
             session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
         }
-        else if (configId === "model") {
+        else if (configId === MODEL_CONFIG_ID) {
             // `ModelInfo.supportsAutoMode` is the canonical SDK signal for clamping
             // modes below; its `displayName`/`description` also let us infer the
             // context window for semantic aliases (e.g. `default`) whose ID alone
@@ -2204,8 +2497,16 @@ export class ClaudeAcpAgent {
             }
             session.models = { ...session.models, currentModelId: value };
             // Recompute availableModes for the new model and clamp the current
-            // mode if the SDK no longer offers it (today: "auto" on Haiku).
-            const newAvailableModes = buildAvailableModes(newModelInfo);
+            // mode if the SDK no longer offers it (today: "auto" on Haiku). An
+            // unknown model (an SDK-initiated refusal fallback to a model outside
+            // the user's `availableModels` allowlist — user-driven switches are
+            // validated against the options first) tells us nothing about its
+            // capabilities, so keep the current modes rather than spuriously
+            // downgrading (e.g. kicking the user out of "auto" for a model that
+            // does support it).
+            const newAvailableModes = newModelInfo
+                ? buildAvailableModes(newModelInfo)
+                : session.modes.availableModes;
             // Capture BEFORE mutating session.modes so the log message reflects
             // the invalidated mode rather than "default".
             const previousModeId = session.modes.currentModeId;
@@ -2231,11 +2532,18 @@ export class ClaudeAcpAgent {
                 session.modes = { ...session.modes, availableModes: newAvailableModes };
             }
             // Rebuild config options since effort levels depend on the selected model
-            const effortOpt = session.configOptions.find((o) => o.id === "effort");
+            const effortOpt = session.configOptions.find((o) => o.id === EFFORT_CONFIG_ID);
             const currentEffort = typeof effortOpt?.currentValue === "string" ? effortOpt.currentValue : undefined;
-            session.configOptions = buildConfigOptions(session.modes, session.models, session.modelInfos, currentEffort, session.agents, session.currentAgent);
+            session.configOptions = buildConfigOptions(session.modes, session.models, session.modelInfos, currentEffort, session.agents, session.currentAgent, {
+                // The toggle follows the newly selected model: it disappears when the
+                // model lacks fast support and reappears (with the retained user
+                // intent) when a supporting model is selected again.
+                supported: newModelInfo?.supportsFastMode ?? false,
+                enabled: session.fastModeEnabled,
+                useBooleanOption: clientSupportsBooleanConfigOptions(this.clientCapabilities),
+            });
             // Sync effort with the SDK if it changed after the model switch
-            const newEffortOpt = session.configOptions.find((o) => o.id === "effort");
+            const newEffortOpt = session.configOptions.find((o) => o.id === EFFORT_CONFIG_ID);
             const newEffort = typeof newEffortOpt?.currentValue === "string" ? newEffortOpt.currentValue : undefined;
             if (newEffort !== currentEffort) {
                 await session.query.applyFlagSettings({
@@ -2258,7 +2566,7 @@ export class ClaudeAcpAgent {
                 });
             }
         }
-        else if (configId === "agent") {
+        else if (configId === AGENT_CONFIG_ID) {
             // Live agent switch — no subprocess restart needed. Apply the SDK flag
             // first so a rejected control request leaves both `currentAgent` and the
             // config option untouched (no UI/SDK desync). Passing `null` clears the
@@ -2272,13 +2580,102 @@ export class ClaudeAcpAgent {
         }
         else {
             session.configOptions = session.configOptions.map((o) => o.id === configId && typeof o.currentValue === "string" ? { ...o, currentValue: value } : o);
-            if (configId === "effort") {
+            if (configId === EFFORT_CONFIG_ID) {
                 await session.query.applyFlagSettings({
                     effortLevel: toSdkEffortLevel(value),
                 });
             }
         }
     }
+    /** Reconcile adapter model state after the SDK persistently swapped the
+     *  session's model out from under us (refusal fallback). The SDK already
+     *  made the switch, so this must NOT call `query.setModel` — it only
+     *  updates our bookkeeping (currentModelId, context window, mode clamping,
+     *  effort/Fast-mode options) via the same `applyConfigOptionValue` path a
+     *  user-driven model change takes, then notifies the client. */
+    async syncModelAfterRefusalFallback(sessionId, session, fallbackModel) {
+        // Map the SDK-reported model onto one of the session's model options
+        // (handles display names and `resolvedModel` ids). The fallback model may
+        // not be among the options — e.g. excluded by the user's
+        // `availableModels` allowlist — in which case we track the raw id: the
+        // picker shows no selection, but the model-dependent bookkeeping and any
+        // later `setModel` round-trip stay truthful to what the SDK is running.
+        const resolved = resolveModelPreference(session.modelInfos, fallbackModel);
+        const value = resolved?.value ?? fallbackModel;
+        if (session.models.currentModelId === value)
+            return;
+        try {
+            await this.updateConfigOption(sessionId, MODEL_CONFIG_ID, value);
+        }
+        catch (err) {
+            // This runs on the consumer loop: a throw here tears down the query
+            // stream (failAllTurns + closeQueryStream) and bricks the session —
+            // far worse than stale bookkeeping. The user-driven RPC path lets the
+            // same errors propagate to fail just that request; here we log and
+            // move on, matching the setPermissionMode containment inside
+            // applyConfigOptionValue.
+            this.logger.error(`Failed to reconcile model state after refusal fallback to "${fallbackModel}":`, err);
+        }
+    }
+    /** Replace the Fast mode option in `session.configOptions` so it reflects
+     *  `enabled` (and the client's current boolean-capability). A no-op when the
+     *  option isn't present, so callers must confirm the current model surfaces
+     *  it first. */
+    refreshFastModeOption(session, enabled) {
+        const refreshed = createFastModeConfigOption(enabled, clientSupportsBooleanConfigOptions(this.clientCapabilities));
+        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
+     *  intent, and refresh the Fast mode config option in place. Only reached
+     *  once the option exists (i.e. the current model supports fast mode), so the
+     *  option is guaranteed to be present in `configOptions`. */
+    async applyFastMode(session, enabled) {
+        // Apply the SDK flag first so a rejected control request leaves both the
+        // session state and the config option untouched (no UI/SDK desync).
+        await session.query.applyFlagSettings({ fastMode: enabled });
+        session.fastModeEnabled = enabled;
+        this.refreshFastModeOption(session, enabled);
+    }
+    /** Reconcile the session's Fast mode toggle with an SDK-reported
+     *  `fast_mode_state` (delivered on `system`/init and on user-turn `result`s).
+     *  The SDK can flip fast mode independently of the user — e.g. back to `on`
+     *  once a rate-limit `cooldown` clears — so we mirror definitive on/off
+     *  changes into the config option and notify the client.
+     *
+     *  Guards, in order:
+     *   - absent state: nothing to reconcile.
+     *   - no Fast mode option: the current model doesn't support fast mode, so the
+     *     reported state reflects capability, not the user's intent. Leave the
+     *     retained setting untouched so it's correct when a supporting model is
+     *     reselected (the source of the earlier intent-clobber bug was mutating it
+     *     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) {
+        if (state === undefined) {
+            return;
+        }
+        if (!session.configOptions.some((o) => o.id === FAST_MODE_CONFIG_ID)) {
+            return;
+        }
+        if (state === "cooldown") {
+            return;
+        }
+        const enabled = state === "on";
+        if (enabled === session.fastModeEnabled) {
+            return;
+        }
+        session.fastModeEnabled = enabled;
+        this.refreshFastModeOption(session, enabled);
+        await this.client.sessionUpdate({
+            sessionId,
+            update: {
+                sessionUpdate: "config_option_update",
+                configOptions: session.configOptions,
+            },
+        });
+    }
     async getOrCreateSession(params) {
         const existingSession = this.sessions[params.sessionId];
         if (existingSession) {
@@ -2464,6 +2861,18 @@ export class ClaudeAcpAgent {
             ...(elicitationSupport.form || elicitationSupport.url
                 ? { onElicitation: this.handleMcpElicitation(sessionId, elicitationSupport) }
                 : {}),
+            // Render the CLI's refusal-fallback consent prompt ("<model> declined —
+            // retry with <fallback>?") as an ACP form elicitation. Declaring the
+            // kind is the opt-in: the CLI never emits an undeclared dialog, and the
+            // flow instead degrades to the classic refusal error ending the turn.
+            // Gated on form elicitation since that's the only ACP surface that can
+            // present a choice outside a tool call.
+            ...(elicitationSupport.form
+                ? {
+                    onUserDialog: this.handleUserDialog(sessionId),
+                    supportedDialogKinds: [REFUSAL_FALLBACK_DIALOG_KIND],
+                }
+                : {}),
             pathToClaudeCodeExecutable: process.env.CLAUDE_CODE_EXECUTABLE ?? (await claudeCliPath()),
             extraArgs: {
                 ...userProvidedOptions?.extraArgs,
@@ -2486,7 +2895,7 @@ export class ClaudeAcpAgent {
                                             currentModeId: "plan",
                                         },
                                     });
-                                    await this.updateConfigOption(sessionId, "mode", "plan");
+                                    await this.updateConfigOption(sessionId, MODE_CONFIG_ID, "plan");
                                 },
                             }),
                         ],
@@ -2579,13 +2988,46 @@ export class ClaudeAcpAgent {
         // configOptions, the current-model resolver, and the stored modelInfos
         // consistent with what the user configured.
         const settingsAvailableModels = settingsManager.getSettings().availableModels;
+        const settingsModelOverrides = settingsManager.getSettings().modelOverrides;
         const allowedModels = Array.isArray(settingsAvailableModels)
-            ? applyAvailableModelsAllowlist(initializationResult.models, settingsAvailableModels)
+            ? applyAvailableModelsAllowlist(initializationResult.models, settingsAvailableModels, settingsModelOverrides)
             : initializationResult.models;
-        const models = await getAvailableModels(q, allowedModels, initializationResult.models, settingsManager, this.logger);
+        const models = await getAvailableModels(q, 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.
-        const currentModelInfo = allowedModels.find((m) => m.value === models.currentModelId);
+        // A resumed session can be running a model outside the `availableModels`
+        // allowlist (currentModelId is then the verbatim live id, see
+        // `matchResumedModel`); its capabilities are still known to the SDK's
+        // unfiltered list, so fall back to that before treating the model as
+        // unknown — otherwise auto mode would be spuriously clamped and the
+        // Fast-mode/Effort options hidden for a model that supports them.
+        const allowlistedModelInfo = allowedModels.find((m) => m.value === models.currentModelId);
+        const fallbackModelInfo = allowlistedModelInfo
+            ? undefined
+            : (resolveModelPreference(initializationResult.models, models.currentModelId) ?? undefined);
+        const currentModelInfo = allowlistedModelInfo ?? fallbackModelInfo;
+        // Register the fallback-resolved capabilities under the verbatim live id
+        // so every modelInfos consumer (buildConfigOptions' effort lookup, later
+        // rebuilds via session.modelInfos) agrees with the gating below. The
+        // picker options themselves come from `models.availableModels`, so this
+        // adds no selectable entry. The spread keeps every capability flag
+        // (current and future); the identity fields are overridden because the
+        // fuzzy-matched sibling's resolvedModel/displayName/description can
+        // describe a different context lane and would poison later resolvedModel
+        // matching (syncModelAfterRefusalFallback) and context-window inference
+        // (applyConfigOptionValue) if they traveled under this id.
+        const modelInfos = fallbackModelInfo
+            ? [
+                ...allowedModels,
+                {
+                    ...fallbackModelInfo,
+                    value: models.currentModelId,
+                    displayName: models.currentModelId,
+                    description: "",
+                    resolvedModel: undefined,
+                },
+            ]
+            : allowedModels;
         const availableModes = buildAvailableModes(currentModelInfo);
         // Clamp `permissionMode` if the resolved session does not offer it. The
         // common case is `permissions.defaultMode: "auto"` resolving to a model
@@ -2628,9 +3070,20 @@ export class ClaudeAcpAgent {
         const currentAgent = requestedAgent && agents.some((a) => a.name === requestedAgent)
             ? requestedAgent
             : DEFAULT_AGENT_ID;
-        const configOptions = buildConfigOptions(modes, models, allowedModels, settingsManager.getSettings().effortLevel, agents, currentAgent);
+        // Seed Fast mode from the SDK's reported state so the UI reflects reality
+        // (the CLI may start a session with fast mode already on, or force it off
+        // when `fastModePerSessionOptIn` is set). The toggle is only surfaced while
+        // the resolved model advertises `supportsFastMode`.
+        const fastModeEnabled = initializationResult.fast_mode_state !== undefined &&
+            fastModeStateEnabled(initializationResult.fast_mode_state);
+        const fastMode = {
+            supported: currentModelInfo?.supportsFastMode ?? false,
+            enabled: fastModeEnabled,
+            useBooleanOption: clientSupportsBooleanConfigOptions(this.clientCapabilities),
+        };
+        const configOptions = buildConfigOptions(modes, models, modelInfos, settingsManager.getSettings().effortLevel, agents, currentAgent, fastMode);
         // Apply the initial effort level to the SDK so it matches the UI default
-        const initialEffort = configOptions.find((o) => o.id === "effort");
+        const initialEffort = configOptions.find((o) => o.id === EFFORT_CONFIG_ID);
         if (initialEffort &&
             typeof initialEffort.currentValue === "string" &&
             initialEffort.currentValue !== "default") {
@@ -2653,15 +3106,23 @@ export class ClaudeAcpAgent {
             },
             modes,
             models,
-            modelInfos: allowedModels,
+            modelInfos,
             configOptions,
             agents,
             currentAgent,
+            fastModeEnabled,
             abortController,
             emitRawSDKMessages: sessionMeta?.claudeCode?.emitRawSDKMessages ?? false,
-            contextWindowSize: inferContextWindowFromModel(models.currentModelId, currentModelInfo?.displayName, currentModelInfo?.description) ?? DEFAULT_CONTEXT_WINDOW,
+            contextWindowSize: 
+            // Deliberately keyed to the allowlisted 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, allowlistedModelInfo?.displayName, allowlistedModelInfo?.description) ?? DEFAULT_CONTEXT_WINDOW,
             taskState,
             toolUseCache: {},
+            emittedToolCalls: new Set(),
             messageIdToUuid: new Map(),
         };
         return {
@@ -2704,9 +3165,9 @@ function totalTokens(usage) {
 }
 /**
  * Build the `data` payload attached to a `RequestError.internalError` when we
- * have a categorical error from the Claude SDK. Returns `undefined` when no
- * categorical error is available, matching the previous behavior of passing
- * `undefined` to `RequestError.internalError`.
+ * have a categorical error — from the Claude SDK, or one of the adapter's own
+ * kinds. Returns `undefined` when no categorical error is available, matching
+ * the previous behavior of passing `undefined` to `RequestError.internalError`.
  *
  * The `errorKind` field is a convention for ACP clients to dispatch on
  * without having to pattern-match the human-readable message text. Clients
@@ -2769,8 +3230,10 @@ function buildAvailableModes(modelInfo) {
         });
     }
     modes.push({
+        // Claude Code 2.1.200 renamed this mode to "Manual" across its surfaces;
+        // the wire id stays "default" ("manual" is only an accepted input alias).
         id: "default",
-        name: "Default",
+        name: "Manual",
         description: "Standard behavior, prompts for dangerous operations",
     }, {
         id: "acceptEdits",
@@ -2835,10 +3298,78 @@ export async function discoverCustomAgents(q) {
         return [];
     }
 }
-export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel, agents = [], currentAgent = DEFAULT_AGENT_ID) {
+/** Stable ids for the session config options surfaced via `configOptions`.
+ *  Centralized so the option declarations in `buildConfigOptions` and the
+ *  handlers in `setSessionConfigOption`/`applyConfigOptionValue` reference the
+ *  same identifiers and can't drift apart. */
+export const MODE_CONFIG_ID = "mode";
+export const MODEL_CONFIG_ID = "model";
+export const EFFORT_CONFIG_ID = "effort";
+export const AGENT_CONFIG_ID = "agent";
+export const FAST_MODE_CONFIG_ID = "fast";
+/** Select-fallback values used when the client has not opted into boolean
+ *  config options (see {@link createFastModeConfigOption}). */
+export const FAST_MODE_ON = "on";
+export const FAST_MODE_OFF = "off";
+const FAST_MODE_DESCRIPTION = "Faster responses on supported models";
+/** Map the SDK's tri-state `fast_mode_state` onto the boolean config toggle.
+ *  `cooldown` (fast mode temporarily suspended after a rate limit, per the SDK
+ *  docs) keeps the toggle on so it reflects the user's intent — only an
+ *  explicit `off` clears it. */
+export function fastModeStateEnabled(state) {
+    return state !== "off";
+}
+/** Whether the Client advertised support for boolean session config options
+ *  (`session.configOptions.boolean`). Agents MUST only send `type: "boolean"`
+ *  config options to Clients that opt in; otherwise we fall back to a `select`.
+ *  See https://agentclientprotocol.com/rfds/boolean-config-option. */
+export function clientSupportsBooleanConfigOptions(clientCapabilities) {
+    return clientCapabilities?.session?.configOptions?.boolean != null;
+}
+/** Build the Fast mode config option. When the Client supports boolean config
+ *  options we expose a native `type: "boolean"` toggle; otherwise we degrade to
+ *  a two-value `select` ("on"/"off") so older Clients still get a usable
+ *  control. */
+export function createFastModeConfigOption(enabled, useBooleanOption) {
+    const base = {
+        id: FAST_MODE_CONFIG_ID,
+        name: "Fast mode",
+        description: FAST_MODE_DESCRIPTION,
+        category: "model_config",
+    };
+    if (useBooleanOption) {
+        return { ...base, type: "boolean", currentValue: enabled };
+    }
+    return {
+        ...base,
+        type: "select",
+        currentValue: enabled ? FAST_MODE_ON : FAST_MODE_OFF,
+        options: [
+            { value: FAST_MODE_ON, name: "On" },
+            { value: FAST_MODE_OFF, name: "Off" },
+        ],
+    };
+}
+/** Resolve the requested Fast mode value from a `session/set_config_option`
+ *  request. Accepts a native boolean (boolean-capable Clients) or the
+ *  "on"/"off" select-fallback strings. */
+export function resolveFastModeEnabled(params) {
+    const value = params.value;
+    if (typeof value === "boolean") {
+        return value;
+    }
+    if (value === FAST_MODE_ON) {
+        return true;
+    }
+    if (value === FAST_MODE_OFF) {
+        return false;
+    }
+    throw new Error(`Invalid value for config option ${FAST_MODE_CONFIG_ID}: ${value}`);
+}
+export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel, agents = [], currentAgent = DEFAULT_AGENT_ID, fastMode) {
     const options = [
         {
-            id: "mode",
+            id: MODE_CONFIG_ID,
             name: "Mode",
             description: "Session permission mode",
             category: "mode",
@@ -2851,7 +3382,7 @@ export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel
             })),
         },
         {
-            id: "model",
+            id: MODEL_CONFIG_ID,
             name: "Model",
             description: "AI model to use",
             category: "model",
@@ -2883,7 +3414,7 @@ export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel
         const includes = (l) => l === "default" || supportedLevels.includes(l);
         const validEffort = currentEffortLevel && includes(currentEffortLevel) ? currentEffortLevel : "default";
         options.push({
-            id: "effort",
+            id: EFFORT_CONFIG_ID,
             name: "Effort",
             description: "Available effort levels for this model",
             category: "thought_level",
@@ -2892,13 +3423,19 @@ export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel
             options: effortOptions,
         });
     }
+    // Surface the Fast mode toggle only when the current model supports it. The
+    // option renders as a native boolean toggle for Clients that opted in, and a
+    // two-value select otherwise.
+    if (fastMode?.supported) {
+        options.push(createFastModeConfigOption(fastMode.enabled, fastMode.useBooleanOption));
+    }
     // Only surface the Agent picker when there's a real choice — i.e. the user
     // has configured at least one custom agent (built-ins are filtered out in
     // discoverCustomAgents). With none configured, "Default" would be the only
     // entry, so we omit the option entirely.
     if (agents.length > 0) {
         options.push({
-            id: "agent",
+            id: AGENT_CONFIG_ID,
             name: "Agent",
             description: "Main-thread agent persona",
             type: "select",
@@ -2918,13 +3455,35 @@ export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel
 // Claude Code CLI persists display strings like "opus[1m]" in settings,
 // but the SDK model list uses IDs like "claude-opus-4-6-1m".
 const MODEL_CONTEXT_HINT_PATTERN = /\[(\d+m)\]$/i;
-// Captures a model family version such as `4-6` or `4.7` so we can keep
-// `claude-opus-4-6` from being copied onto the SDK's `opus` alias when that
-// alias currently resolves to a different family version (e.g. Opus 4.7).
-const MODEL_FAMILY_VERSION_PATTERN = /\b(\d+)[-.](\d+)\b/;
+// The id-suffix spelling of a context hint ("-1m" in "claude-opus-4-6-1m");
+// shared by the strip and canonicalize helpers below so the two can't drift.
+const CONTEXT_HINT_SUFFIX_PATTERN = /-(\d+m)$/i;
+/** Remove context-window hints — the display form "[1m]" and the SDK id
+ *  suffix form "-1m" — from a model string. Those digits describe context
+ *  size, not model identity or generation version. */
+function stripContextHints(s) {
+    return s.replace(/\[\d+m\]/gi, "").replace(CONTEXT_HINT_SUFFIX_PATTERN, "");
+}
+/** Canonicalize a model id for exact comparison: trimmed, lowercased, with
+ *  the id-suffix hint spelling unified to the bracket form ("-1m" → "[1m]").
+ *  The hint itself is kept — bare and 1M ids must stay distinct. */
+function canonicalizeModelId(s) {
+    return s.trim().toLowerCase().replace(CONTEXT_HINT_SUFFIX_PATTERN, "[$1]");
+}
+/** The context hint a model string carries ("1m" for either spelling), or
+ *  null for a bare id. */
+function contextHintOf(s) {
+    return canonicalizeModelId(s).match(MODEL_CONTEXT_HINT_PATTERN)?.[1] ?? null;
+}
+// Captures a model family version: `4-6`/`4.7` for dated generations, or a
+// bare `5` for single-number ones like "Sonnet 5". Used to keep a pinned
+// `claude-opus-4-6` from matching the `opus` alias once it points at 4.7.
+const MODEL_FAMILY_VERSION_PATTERN = /\b(\d+)(?:[-.](\d+))?\b/;
 function extractModelFamilyVersion(s) {
-    const match = s.match(MODEL_FAMILY_VERSION_PATTERN);
-    return match ? `${match[1]}.${match[2]}` : null;
+    const match = stripContextHints(s).match(MODEL_FAMILY_VERSION_PATTERN);
+    if (!match)
+        return null;
+    return match[2] ? `${match[1]}.${match[2]}` : match[1];
 }
 function modelVersionsCompatible(preference, candidate) {
     const preferred = extractModelFamilyVersion(preference);
@@ -2969,21 +3528,43 @@ function scoreModelMatch(model, tokens, contextHint) {
         return 0;
     return score;
 }
-function resolveModelPreference(models, preference) {
+export function resolveModelPreference(models, preference) {
     const trimmed = preference.trim();
     if (!trimmed)
         return null;
     const lower = trimmed.toLowerCase();
-    // Exact match on value or display name
+    // Exact match on value or display name. Values compare on the canonical
+    // hint spelling so "opus-1m" hits an "opus[1m]" row (and vice versa).
+    const canonicalPreference = canonicalizeModelId(trimmed);
     const directMatch = models.find((model) => model.value === trimmed ||
-        model.value.toLowerCase() === lower ||
+        canonicalizeModelId(model.value) === canonicalPreference ||
         model.displayName.toLowerCase() === lower);
     if (directMatch)
         return directMatch;
-    // Substring match
+    // Exact match on the alias's canonical resolved id (e.g. a pinned
+    // "claude-sonnet-5" against the "sonnet" row's `resolvedModel`). SDK-
+    // reported and unambiguous, so it's tried before the fuzzier tiers below.
+    // Compared on the canonical hint spelling so a "-1m"-suffix pin matches a
+    // "[1m]"-spelled resolvedModel instead of falling into the substring tier
+    // (which would land on the bare 200k sibling). "default" is skipped first
+    // since it shares a resolvedModel with whichever alias the CLI currently
+    // recommends — a specific pin should land on that named alias, not
+    // "default".
+    const matchesResolved = (model) => model.resolvedModel != null && canonicalizeModelId(model.resolvedModel) === canonicalPreference;
+    const resolvedMatch = models.find((model) => model.value !== "default" && matchesResolved(model)) ??
+        models.find(matchesResolved);
+    if (resolvedMatch)
+        return resolvedMatch;
+    // Substring match. Skips candidates whose context hint disagrees with the
+    // preference's — a bare row must not absorb a 1M-hinted preference (nor
+    // vice versa); such pairs fall through to the tokenized tier, which
+    // weighs hints in its scoring and still finds the best same-family row.
+    const preferenceHint = contextHintOf(trimmed);
     const includesMatch = models.find((model) => {
         if (!modelVersionsCompatible(trimmed, model))
             return false;
+        if (contextHintOf(model.value) !== preferenceHint)
+            return false;
         const value = model.value.toLowerCase();
         const display = model.displayName.toLowerCase();
         return value.includes(lower) || display.includes(lower) || lower.includes(value);
@@ -3007,6 +3588,51 @@ function resolveModelPreference(models, preference) {
     }
     return bestMatch;
 }
+/** Map the live model reported by a resumed session onto the picker's model
+ *  list. The CLI restores a resumed session's model from the transcript's
+ *  last assistant message, which records the concrete API id (e.g.
+ *  "claude-opus-4-6") with any "[1m]" context hint dropped. Tiers, in order:
+ *  1. Exact match with the Default entry's resolution — when a named alias
+ *     shares Default's resolvedModel verbatim, the live id can't tell the
+ *     two apart, and a never-customized session should stay on Default.
+ *  2. Exact resolvedModel match on a named row. Checked before the
+ *     hint-stripped Default comparison so a live "claude-sonnet-5[1m]" lands
+ *     on the "sonnet[1m]" row rather than a Default that resolves to the
+ *     bare "claude-sonnet-5" — the two rows differ in context window, which
+ *     drives `contextWindowSize` and capability gating downstream.
+ *  3. Hint-stripped match with Default's resolution — a session that never
+ *     left the default resumes as the bare transcript id, and shouldn't show
+ *     a concrete picker entry.
+ *  4. `resolveModelPreference` over the picker entries.
+ *  5. A model with no picker counterpart (e.g. excluded by an
+ *     `availableModels` allowlist) is tracked verbatim, mirroring
+ *     `syncModelAfterRefusalFallback`: the picker shows no selection, but the
+ *     model-dependent bookkeeping stays truthful to what the SDK is running. */
+export function matchResumedModel(models, liveModel) {
+    const live = canonicalizeModelId(liveModel);
+    const defaultEntry = models.find((m) => m.value === "default");
+    const defaultResolved = defaultEntry?.resolvedModel
+        ? canonicalizeModelId(defaultEntry.resolvedModel)
+        : undefined;
+    if (defaultEntry && defaultResolved === live) {
+        return defaultEntry;
+    }
+    // No default-row exclusion needed: a default row matching `live` exactly
+    // already returned at the tier above.
+    const exactMatch = models.find((m) => m.resolvedModel && canonicalizeModelId(m.resolvedModel) === live);
+    if (exactMatch)
+        return exactMatch;
+    if (defaultEntry &&
+        defaultResolved &&
+        stripContextHints(defaultResolved) === stripContextHints(live)) {
+        return defaultEntry;
+    }
+    return (resolveModelPreference(models, liveModel) ?? {
+        value: liveModel,
+        displayName: liveModel,
+        description: "",
+    });
+}
 function resolveSettingsModel(models, settingsModel, logger) {
     if (settingsModel === undefined) {
         return null;
@@ -3034,7 +3660,7 @@ function resolveSettingsModel(models, settingsModel, logger) {
  * - The Default option is unaffected by `availableModels` — it always remains
  *   available, even when the allowlist is `[]`.
  */
-function applyAvailableModelsAllowlist(sdkModels, allowlist) {
+export function applyAvailableModelsAllowlist(sdkModels, allowlist, settingsModelOverrides) {
     // Default is always preserved per the docs. Synthesize one if the SDK
     // didn't surface it so downstream code (e.g. `getAvailableModels` picking
     // `models[0]` as a fallback) still has something to work with.
@@ -3046,18 +3672,29 @@ function applyAvailableModelsAllowlist(sdkModels, allowlist) {
     const result = [defaultModel];
     const seen = new Set([defaultModel.value]);
     const sdkModelsWithoutDefault = sdkModels.filter((m) => m.value !== "default");
+    // Bedrock/Vertex deployments enforce short aliases (e.g. "claude-opus-4-6")
+    // in availableModels but require provider-specific IDs at the API. We still
+    // resolve `sdkMatch` against the alias (`trimmed`) — that's what the
+    // matching heuristics above are built for, and override targets (ARNs,
+    // opaque provider IDs) often won't textually resemble anything in
+    // `sdkModelsWithoutDefault`. Only the entry's surfaced `value` becomes the
+    // override target, so it's what `setModel` ends up passing to the API.
     for (const entry of allowlist) {
         const trimmed = entry.trim();
         if (!trimmed || seen.has(trimmed))
             continue;
+        const overridden = settingsModelOverrides?.[trimmed];
+        const effective = overridden ?? trimmed;
+        if (seen.has(effective))
+            continue;
         const sdkMatch = resolveModelPreference(sdkModelsWithoutDefault, trimmed);
         if (sdkMatch) {
-            result.push({ ...sdkMatch, value: trimmed });
+            result.push({ ...sdkMatch, value: effective });
         }
         else {
-            result.push({ value: trimmed, displayName: trimmed, description: "" });
+            result.push({ value: effective, displayName: trimmed, description: "" });
         }
-        seen.add(trimmed);
+        seen.add(effective);
     }
     // The custom model option (ANTHROPIC_CUSTOM_MODEL_OPTION) is exempt from the
     // allowlist, the same way Default is. Per the model-config docs it adds an
@@ -3075,14 +3712,30 @@ function applyAvailableModelsAllowlist(sdkModels, allowlist) {
     }
     return result;
 }
-async function getAvailableModels(query, models, sdkModels, settingsManager, logger) {
+/** 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. */
+async function readResumedLiveModel(query, models, logger) {
+    try {
+        const liveModel = (await query.getContextUsage()).model;
+        return liveModel ? matchResumedModel(models, liveModel) : null;
+    }
+    catch (error) {
+        logger.error("Failed to read the resumed session's live model:", error);
+        return null;
+    }
+}
+async function getAvailableModels(query, models, sdkModels, settingsManager, logger, isResumedSession) {
     const settings = settingsManager.getSettings();
     let currentModel = models[0];
     let resolvedFromInput;
     // Model priority (highest to lowest):
     // 1. ANTHROPIC_MODEL environment variable
     // 2. settings.model (user configuration)
-    // 3. models[0] (default first model)
+    // 3. the resumed session's live model (resumed sessions only)
+    // 4. models[0] (default first model)
     if (process.env.ANTHROPIC_MODEL) {
         const match = resolveModelPreference(models, process.env.ANTHROPIC_MODEL);
         if (match) {
@@ -3097,21 +3750,49 @@ async function getAvailableModels(query, models, sdkModels, settingsManager, log
             resolvedFromInput = settings.model;
         }
     }
+    // A resumed session restores the model it was previously running (the CLI
+    // re-reads it from the transcript), so without an env/settings override the
+    // freshly-computed default above can disagree with what the session actually
+    // runs — session/load then reports a model the session isn't using (issue
+    // #845). Ask the CLI for the live model and reflect it. No `setModel` here:
+    // 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;
+    }
     // Skip the setModel round-trip when we can prove the SDK has already landed
     // on the same model. Two cases qualify:
-    //  (a) No override applied — currentModel stayed at models[0]; the SDK is on
-    //      its own default and we have nothing to sync.
+    //  (a) No override applied — currentModel is the SDK's own default (or, on
+    //      resume, the live model read back from the SDK above); nothing to sync.
     //  (b) The resolver returned the user's input verbatim AND that value exists
     //      in the SDK's original model list — meaning no fuzzy match or
     //      allowlist rewrite was involved, and the SDK (which reads the same
     //      ANTHROPIC_MODEL / settings.json) will have arrived at the same entry.
+    //      This only holds for fresh sessions: a resumed session lands on the
+    //      transcript's model regardless of env/settings, so the override must
+    //      be re-asserted to keep the reported model truthful.
     // Anything else (fuzzy match, allowlist-synthesized value, alias) gets a
     // setModel call so we don't drift from the user's intended pin.
     const sdkSawSameValue = sdkModels.some((m) => m.value === currentModel.value);
     const skipSetModel = resolvedFromInput === undefined ||
-        (currentModel.value === resolvedFromInput && sdkSawSameValue);
+        (!isResumedSession && currentModel.value === resolvedFromInput && sdkSawSameValue);
     if (!skipSetModel) {
-        await query.setModel(currentModel.value);
+        try {
+            await query.setModel(currentModel.value);
+        }
+        catch (error) {
+            // On a fresh session the pin is a defining option — fail loudly. A
+            // resumed session already runs fine on the transcript's model, so
+            // failing the whole session/load over the re-assert would be worse
+            // than loading with the pin unapplied (mirrors the setPermissionMode
+            // containment in createSession). The SDK then stayed on the
+            // transcript's model, so read that back rather than reporting the
+            // pin the session isn't running.
+            if (!isResumedSession)
+                throw error;
+            logger.error(`Failed to re-assert model "${currentModel.value}" on resume:`, error);
+            currentModel = (await readResumedLiveModel(query, models, logger)) ?? currentModel;
+        }
     }
     return {
         availableModels: models.map((model) => ({
@@ -3284,6 +3965,53 @@ function applyMessageId(update, messageId) {
         update.messageId = messageId;
     }
 }
+/** Built-in tools that drive the task list (headless/SDK sessions use these
+ *  instead of TodoWrite). Their tool_use/tool_result are surfaced as `plan`
+ *  snapshots rather than as tool_calls. */
+function isTaskTool(toolName) {
+    return (toolName === "TaskCreate" ||
+        toolName === "TaskUpdate" ||
+        toolName === "TaskList" ||
+        toolName === "TaskGet");
+}
+/** Whether a tool's tool_use surfaces to the client 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. */
+function shouldEmitToolCall(toolName) {
+    return toolName !== "TodoWrite" && !isTaskTool(toolName);
+}
+/** Build the `tool_call` (or, with `refine`, the `tool_call_update`)
+ *  notification for a tool_use. Shared by every site that surfaces a tool call:
+ *  the streamed tool_use path (first encounter → tool_call, later encounter →
+ *  refine) and the permission flow (`ensureToolCallEmitted`), so they can't
+ *  drift. The initial `tool_call` carries `status: "pending"` and, for Bash, the
+ *  `terminal_info` _meta that the later `terminal_output`/`terminal_exit`
+ *  updates key off of; a refining `tool_call_update` carries neither. */
+function toolCallNotification(toolUse, rawInput, supportsTerminalOutput, cwd, refine = false) {
+    if (refine) {
+        return {
+            _meta: { claudeCode: { toolName: toolUse.name } },
+            toolCallId: toolUse.id,
+            sessionUpdate: "tool_call_update",
+            rawInput,
+            ...toolInfoFromToolUse(toolUse, supportsTerminalOutput, cwd),
+        };
+    }
+    return {
+        _meta: {
+            claudeCode: { toolName: toolUse.name },
+            ...(toolUse.name === "Bash" && supportsTerminalOutput
+                ? { terminal_info: { terminal_id: toolUse.id } }
+                : {}),
+        },
+        toolCallId: toolUse.id,
+        sessionUpdate: "tool_call",
+        rawInput,
+        status: "pending",
+        ...toolInfoFromToolUse(toolUse, supportsTerminalOutput, cwd),
+    };
+}
 /**
  * Convert an SDKAssistantMessage (Claude) to a SessionNotification (ACP).
  * Only handles text, image, and thinking chunks for now.
@@ -3293,6 +4021,9 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
     const registerHooks = options?.registerHooks !== false;
     const supportsTerminalOutput = options?.clientCapabilities?._meta?.["terminal_output"] === true;
     if (typeof content === "string") {
+        if (content.length === 0) {
+            return [];
+        }
         const update = {
             sessionUpdate: role === "assistant" ? "agent_message_chunk" : "user_message_chunk",
             content: {
@@ -3318,15 +4049,18 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
         let update = null;
         switch (chunk.type) {
             case "text":
-            case "text_delta":
-                update = {
-                    sessionUpdate: role === "assistant" ? "agent_message_chunk" : "user_message_chunk",
-                    content: {
-                        type: "text",
-                        text: chunk.text,
-                    },
-                };
+            case "text_delta": {
+                if (chunk.text) {
+                    update = {
+                        sessionUpdate: role === "assistant" ? "agent_message_chunk" : "user_message_chunk",
+                        content: {
+                            type: "text",
+                            text: chunk.text,
+                        },
+                    };
+                }
                 break;
+            }
             case "image":
                 update = {
                     sessionUpdate: role === "assistant" ? "agent_message_chunk" : "user_message_chunk",
@@ -3339,10 +4073,10 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                 };
                 break;
             case "thinking":
-            case "thinking_delta":
+            case "thinking_delta": {
                 // Recent models default `thinking.display` to "omitted", which streams
                 // signature-only thinking blocks whose text is empty.
-                if (chunk.thinking.length > 0) {
+                if (chunk.thinking) {
                     update = {
                         sessionUpdate: "agent_thought_chunk",
                         content: {
@@ -3352,6 +4086,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                     };
                 }
                 break;
+            }
             case "tool_use":
             case "server_tool_use":
             case "mcp_tool_use": {
@@ -3366,10 +4101,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                         };
                     }
                 }
-                else if (chunk.name === "TaskCreate" ||
-                    chunk.name === "TaskUpdate" ||
-                    chunk.name === "TaskList" ||
-                    chunk.name === "TaskGet") {
+                else if (isTaskTool(chunk.name)) {
                     // Task* tool_use is suppressed; the plan update is emitted at
                     // tool_result time once we have the task ID (for TaskCreate) and
                     // confirmation that the change took effect.
@@ -3421,40 +4153,25 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                     catch {
                         // ignore if we can't turn it to JSON
                     }
-                    if (alreadyCached) {
-                        // Second encounter (full assistant message after streaming) —
-                        // send as tool_call_update to refine the existing tool_call
-                        // rather than emitting a duplicate tool_call.
-                        update = {
-                            _meta: {
-                                claudeCode: {
-                                    toolName: chunk.name,
-                                },
-                            },
-                            toolCallId: chunk.id,
-                            sessionUpdate: "tool_call_update",
-                            rawInput,
-                            ...toolInfoFromToolUse(chunk, supportsTerminalOutput, options?.cwd),
-                        };
+                    // Emit a `tool_call` only the first time this id surfaces to the
+                    // client; afterwards refine it with a `tool_call_update`. The first
+                    // surface may be this stream chunk OR an earlier permission request
+                    // (see `ensureToolCallEmitted`), so emission is tracked separately
+                    // from `toolUseCache`. Without an `emittedToolCalls` set we fall back
+                    // to cache presence — the historical streaming-only behavior.
+                    const emittedToolCalls = options?.emittedToolCalls;
+                    const alreadyEmitted = emittedToolCalls ? emittedToolCalls.has(chunk.id) : alreadyCached;
+                    emittedToolCalls?.add(chunk.id);
+                    if (alreadyEmitted) {
+                        // Already surfaced (full assistant message after streaming, or a
+                        // permission request emitted it first) — refine with a
+                        // tool_call_update rather than emitting a duplicate tool_call.
+                        update = toolCallNotification(chunk, rawInput, supportsTerminalOutput, options?.cwd, true);
                     }
                     else {
-                        // First encounter (streaming content_block_start or replay) —
-                        // send as tool_call with terminal_info for Bash tools.
-                        update = {
-                            _meta: {
-                                claudeCode: {
-                                    toolName: chunk.name,
-                                },
-                                ...(chunk.name === "Bash" && supportsTerminalOutput
-                                    ? { terminal_info: { terminal_id: chunk.id } }
-                                    : {}),
-                            },
-                            toolCallId: chunk.id,
-                            sessionUpdate: "tool_call",
-                            rawInput,
-                            status: "pending",
-                            ...toolInfoFromToolUse(chunk, supportsTerminalOutput, options?.cwd),
-                        };
+                        // First surface (streaming content_block_start or replay) — send as
+                        // tool_call (with terminal_info for Bash).
+                        update = toolCallNotification(chunk, rawInput, supportsTerminalOutput, options?.cwd);
                     }
                 }
                 break;
@@ -3467,15 +4184,13 @@ 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": {
+                options?.emittedToolCalls?.delete(chunk.tool_use_id);
                 const toolUse = toolUseCache[chunk.tool_use_id];
                 if (!toolUse) {
                     logger.error(`[claude-agent-acp] Got a tool result for tool use that wasn't tracked: ${chunk.tool_use_id}`);
                     break;
                 }
-                if (toolUse.name === "TaskCreate" ||
-                    toolUse.name === "TaskUpdate" ||
-                    toolUse.name === "TaskList" ||
-                    toolUse.name === "TaskGet") {
+                if (isTaskTool(toolUse.name)) {
                     // Headless/SDK sessions emit Task* tools instead of TodoWrite.
                     // TaskCreate / TaskUpdate mutate the accumulated task list; TaskList
                     // and TaskGet are read-only so we just suppress their tool_call /
@@ -3582,6 +4297,7 @@ export function streamEventToAcpNotifications(message, sessionId, toolUseCache,
                 parentToolUseId: message.parent_tool_use_id,
                 cwd: options?.cwd,
                 taskState: options?.taskState,
+                emittedToolCalls: options?.emittedToolCalls,
                 messageId: options?.messageId,
             });
         case "content_block_delta":
@@ -3590,6 +4306,7 @@ export function streamEventToAcpNotifications(message, sessionId, toolUseCache,
                 parentToolUseId: message.parent_tool_use_id,
                 cwd: options?.cwd,
                 taskState: options?.taskState,
+                emittedToolCalls: options?.emittedToolCalls,
                 messageId: options?.messageId,
             });
         // No content. `ping` is a Messages-API keep-alive event that the SDK's