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

package/dist/acp-agent.js

@@ -10,7 +10,10 @@ import packageJson from "../package.json" with { type: "json" };
 import { applyAskElicitationResponse, askUserQuestionsToCreateRequest, createElicitationResponseToElicitResult, extractAskUserQuestions, extractRefusalFallbackPrompt, mcpElicitationToCreateRequest, REFUSAL_FALLBACK_DIALOG_KIND, refusalFallbackResultFromResponse, refusalFallbackToCreateRequest, } from "./elicitation.js";
 import { askUserQuestionFallbackEnabled, handleAskUserQuestionViaPermission, } from "./ask-user-question-fallback.js";
 import { agentName } from "./agent-name.js";
+import { filterDeprecatedModels } from "./model-deprecation.js";
 import { SettingsManager } from "./settings.js";
+import { createThinkingConfigOption, effectiveThinkingConfig, resolveThinkingSelection, THINKING_CONFIG_ID, } from "./thinking-option.js";
+import { handleRewindCommand, parseRewindInvocation } from "./rewind-command.js";
 import { applyTaskCreate, applyTaskUpdate, createPostToolUseHook, createTaskHook, parseTaskCreateOutput, planEntries, registerHookCallback, taskStateToPlanEntries, toolInfoFromToolUse, toolUpdateFromDiffToolResponse, toolUpdateFromToolResult, } from "./tools.js";
 import { nodeToWebReadable, nodeToWebWritable, Pushable, unreachable } from "./utils.js";
 export const CLAUDE_CONFIG_DIR = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
@@ -44,6 +47,16 @@ 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;
+/** Ceiling on the lazy query recreate's initialization phase (see
+ *  `recreateSessionQuery`). A wedged replacement subprocess could hang
+ *  `initializationResult()` forever (same wedge class as issue #680), and
+ *  every join on `queryRecreateInFlight` — prompt/cancel/the config setters,
+ *  and closeSession/deleteSession/dispose via `teardownSession → cancel()` —
+ *  would inherit that hang. Expiry routes to the recreate's failure path (the
+ *  replacement is closed, the old query stays live, the pending flag is
+ *  retained), bounding every join. Same "obviously stuck" rationale as
+ *  DEFAULT_FORCE_CANCEL_GRACE_MS. */
+const QUERY_RECREATE_INIT_TIMEOUT_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
@@ -581,6 +594,103 @@ export class ClaudeAcpAgent {
         if (session.queryClosed) {
             throw RequestError.internalError(undefined, SESSION_ENDED_MESSAGE);
         }
+        // `/rewind` is served fully locally (story 006, R3.2/R3.3): it lists or
+        // restores file checkpoints via the SDK file-rewind API and streams its own
+        // messages. It must be intercepted BEFORE the lazy query-recreate below (a
+        // `/rewind` must not consume this session's pending recreate — that belongs
+        // to the next real turn) and must never enqueue a turn. handleRewindCommand
+        // emits every user-facing update before it resolves, so returning end_turn
+        // here leaves Zed with a complete turn rather than an empty/hung one.
+        const commandText = params.prompt[0]?.type === "text" ? params.prompt[0].text : "";
+        const rewindInvocation = parseRewindInvocation(commandText);
+        if (rewindInvocation) {
+            // A lazy Thinking recreate may be swapping the session's query right
+            // now; join it first (mirroring cancel()) so the RewindDeps below
+            // capture the live replacement query — not the old one mid-close — and
+            // so the active-turn guard next evaluates the post-recreate queue
+            // state. Safe: `recreateSessionQuery` never rejects.
+            if (session.queryRecreateInFlight) {
+                await session.queryRecreateInFlight;
+            }
+            // Never touch checkpoints while a turn is active or queued (same idleness
+            // predicate as the lazy query-recreate trigger below). The turn FIFO
+            // exists precisely so work lands in submission order; `/rewind` bypassing
+            // it would let `query.rewindFiles()` restore files that the active turn
+            // is editing at that very moment — a mixed workspace state — and would
+            // interleave the rewind's output with the turn's. Refuse, explain, and
+            // leave the checkpoints untouched.
+            if (session.turnQueue?.length || session.activeTurn) {
+                await this.client.sessionUpdate({
+                    sessionId: params.sessionId,
+                    update: {
+                        sessionUpdate: "agent_message_chunk",
+                        content: {
+                            type: "text",
+                            text: "A turn is still running in this session, so `/rewind` was not executed " +
+                                "(files may be under active edit). Stop the current turn first, then run " +
+                                "`/rewind` again.",
+                        },
+                    },
+                });
+                return { stopReason: "end_turn" };
+            }
+            const deps = {
+                sessionId: params.sessionId,
+                client: this.client,
+                query: session.query,
+                // getSessionMessages resolves the SDK's SessionMessage[] (a loosely
+                // typed transcript-row shape that listCheckpoints reads structurally);
+                // reinterpret it as the RewindDeps SDKMessage[] contract.
+                getSessionMessages: async (sessionId) => {
+                    const messages = await getSessionMessages(sessionId);
+                    return messages;
+                },
+            };
+            // Flag the restore for its whole duration (see Session.rewindInFlight):
+            // a rewind holds no Turn, so without it a concurrent real prompt would
+            // pass the recreate trigger's idleness check below and close the query
+            // under `rewindFiles`.
+            session.rewindInFlight = true;
+            try {
+                await handleRewindCommand(deps, rewindInvocation);
+            }
+            catch (error) {
+                // handleRewindCommand catches its own dep failures; only a rejection
+                // of the client's sessionUpdate channel itself propagates here. Guard
+                // it and report locally instead of surfacing a failed turn.
+                this.logger.error(`Session ${params.sessionId}: /rewind command failed: ${error}`);
+            }
+            finally {
+                session.rewindInFlight = false;
+            }
+            return { stopReason: "end_turn" };
+        }
+        // Lazy Thinking application (R1.3): a pending config change is applied by
+        // recreating the SDK query with session resume BEFORE this turn is
+        // enqueued — never mid-turn, so only when no other prompt is in flight. A
+        // concurrent prompt() joins the in-flight recreate rather than racing a
+        // second one (or pushing onto the old query mid-swap). On recreate failure
+        // the flag stays set (retried by the next prompt) and this turn proceeds
+        // on the old query; `recreateSessionQuery` never rejects.
+        if (session.queryRecreateInFlight) {
+            await session.queryRecreateInFlight;
+        }
+        else if (session.pendingQueryRecreate &&
+            !session.turnQueue?.length &&
+            !session.activeTurn &&
+            // An in-flight `/rewind` restore holds no Turn, so the queue checks
+            // above can't see it; recreating now would close the query underneath
+            // `rewindFiles` (see Session.rewindInFlight).
+            !session.rewindInFlight) {
+            const recreate = this.recreateSessionQuery(params.sessionId, session);
+            session.queryRecreateInFlight = recreate;
+            try {
+                await recreate;
+            }
+            finally {
+                session.queryRecreateInFlight = undefined;
+            }
+        }
         const userMessage = promptToClaude(params);
         const promptUuid = randomUUID();
         userMessage.uuid = promptUuid;
@@ -805,6 +915,13 @@ 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 query this consumer serves, bound at start: the lazy Thinking
+        // recreate (`recreateSessionQuery`) can swap `session.query` for a fresh
+        // one while this consumer is parked on the OLD query's next(). A
+        // superseded consumer must abdicate — a fresh consumer owns the new
+        // query — WITHOUT running its end-of-stream/error cleanup, which would
+        // close the session's LIVE (replacement) resources.
+        const myQuery = session.query;
         // 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
@@ -814,9 +931,15 @@ export class ClaudeAcpAgent {
         let pendingNext = null;
         try {
             while (true) {
-                pendingNext ??= session.query
-                    .next()
-                    .then((result) => ({ kind: "message", result }));
+                // Superseded by a lazy query recreate: a fresh consumer owns
+                // `session.query` now. Abandon the stale in-flight next() (swallowing
+                // its eventual settlement so it can't surface as unhandled) and exit
+                // without touching the session's turns or resources.
+                if (session.query !== myQuery) {
+                    void pendingNext?.catch(() => { });
+                    return;
+                }
+                pendingNext ??= myQuery.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.
@@ -840,12 +963,16 @@ export class ClaudeAcpAgent {
                     if (session.activeTurn && !session.activeTurn.settled) {
                         session.pendingOrphanResults = (session.pendingOrphanResults ?? 0) + 1;
                     }
-                    settleActive({ stopReason: "cancelled" });
-                    // 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]) {
+                    settleActive({ stopReason: "cancelled", usage: sessionUsage(session) });
+                    // If the session is being torn down — or this consumer was
+                    // superseded by a lazy query recreate — abandon the in-flight
+                    // next() (swallowing any later rejection so it can't surface as
+                    // unhandled) and stop; otherwise re-arm and keep consuming —
+                    // `pendingNext` stays in flight so its eventual message is
+                    // processed, not dropped. The supersession check also keeps a
+                    // superseded consumer from clobbering `session.cancelController`
+                    // (re-armed below) under the replacement consumer.
+                    if (!this.sessions[params.sessionId] || session.query !== myQuery) {
                         void nextMessage.catch(() => { });
                         return;
                     }
@@ -857,6 +984,14 @@ export class ClaudeAcpAgent {
                 pendingNext = null;
                 const { value: message, done } = raced.result;
                 if (done || !message) {
+                    // A superseded consumer (the lazy query recreate closed the OLD
+                    // query out from under it) must NOT run end-of-stream cleanup: the
+                    // session's query/input/settings now belong to the replacement and
+                    // `closeQueryStream` would tear the LIVE ones down. The recreate
+                    // path owns the whole transition; just exit.
+                    if (session.query !== myQuery) {
+                        return;
+                    }
                     // The stream ended. Settle the in-flight turns FIRST, then release the
                     // stream resources — same order as the error paths (failAllTurns before
                     // closeQueryStream). Settling is the user-facing contract; resource
@@ -865,9 +1000,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
@@ -1010,8 +1146,14 @@ export class ClaudeAcpAgent {
                                     // the turn NOW so its session/prompt gets a terminal
                                     // response, instead of leaving it hanging until the next
                                     // prompt drains the wreckage.
+                                    // A cancelled turn still consumed tokens: its dropped result
+                                    // already fed the accumulator (the usage tally at the result
+                                    // handler runs before the `session.cancelled` guard), so
+                                    // report it — clients metering spend would otherwise lose
+                                    // the interrupted turn's tokens entirely (issue #844). Zero
+                                    // when the cancel pre-empted the result (wedge/force-cancel).
                                     if (session.cancelled && session.activeTurn && !session.activeTurn.settled) {
-                                        settleActive({ stopReason: "cancelled" });
+                                        settleActive({ stopReason: "cancelled", usage: sessionUsage(session) });
                                     }
                                     else if (owedTrailingIdles > 0) {
                                         // Absorb a settled turn's trailing idle. Also covers a
@@ -1476,7 +1618,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) {
@@ -1581,7 +1723,9 @@ export class ClaudeAcpAgent {
                                             // as the freshly-activated turn ending without a result
                                             // (which would false-fail a healthy turn — issue #825).
                                             owedTrailingIdles++;
-                                            settleActive({ stopReason: "cancelled" });
+                                            // 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) });
@@ -1804,6 +1948,13 @@ export class ClaudeAcpAgent {
             // below, so there is no normal fall-through here.
         }
         catch (error) {
+            // A superseded consumer's stale next() may reject when the lazy query
+            // recreate closes the old query; the session's live turns and resources
+            // belong to the replacement consumer, so exit without failing turns or
+            // releasing anything.
+            if (session.query !== myQuery) {
+                return;
+            }
             // The query stream itself died (a transport/process error surfaced from
             // query.next()). Turn-level failures (auth, error results) are handled
             // inline via failActive and never reach here. Reject every in-flight turn;
@@ -1838,6 +1989,15 @@ export class ClaudeAcpAgent {
         if (!session) {
             return;
         }
+        // A lazy Thinking recreate may be swapping the session's query right now;
+        // join it (mirroring prompt()) so `interrupt()` below targets the live
+        // replacement query instead of racing the old one's close — an interrupt
+        // control request killed by that close would reject out of this
+        // fire-and-forget notification. Safe: `recreateSessionQuery` never
+        // rejects.
+        if (session.queryRecreateInFlight) {
+            await session.queryRecreateInFlight;
+        }
         // The stream already ended (see closeQueryStream): every in-flight turn was
         // settled when it closed, and there is no live query to interrupt. Calling
         // query.interrupt() on a finished iterator could reject and surface from
@@ -1850,20 +2010,22 @@ export class ClaudeAcpAgent {
         // they have no in-flight SDK work to interrupt. The active turn is settled
         // by the consumer when it observes the interrupt's trailing idle (or via the
         // backstop below). Mirrors the old pendingMessages cancellation.
+        const orphanedUuids = [];
         if (session.turnQueue) {
-            let orphaned = 0;
             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++;
+                    orphanedUuids.push(turn.promptUuid);
                 }
             }
             // Each removed queued turn's user message was already pushed to the SDK,
             // which processes input FIFO and will still emit a result for it with no
             // uuid to match. Count those so the consumer skips them (see
             // ensureActiveTurn) rather than misattributing them to the head.
-            session.pendingOrphanResults = (session.pendingOrphanResults ?? 0) + orphaned;
+            session.pendingOrphanResults = (session.pendingOrphanResults ?? 0) + orphanedUuids.length;
             session.turnQueue = session.turnQueue.filter((turn) => turn === session.activeTurn && !turn.settled);
         }
         // Arm a backstop before interrupting: if a turn is actively consuming the
@@ -1887,7 +2049,29 @@ export class ClaudeAcpAgent {
                 cancelController.abort();
             }, this.forceCancelGraceMs);
         }
-        await session.query.interrupt();
+        const receipt = await session.query.interrupt();
+        // On CLIs advertising `interrupt_receipt_v1`, the receipt's `still_queued`
+        // lists exactly which queued messages survive the interrupt and will still
+        // run. An orphaned turn whose uuid is absent was dropped by the interrupt
+        // and will never emit a result — uncount it now instead of leaving a stale
+        // skip that activateTurn's reset only clears once a later live ECHO
+        // arrives: an echo-less result in between (a local-only command like
+        // `/context`) would be wrongly swallowed by the leftover count. Subtracting
+        // a count (rather than tracking uuids) stays race-safe against the
+        // consumer draining concurrently: dropped uuids produce no results, so the
+        // consumer's decrements only ever consume the still-queued share. Unknown
+        // uuids in the receipt (internally-enqueued messages) are ignored, per its
+        // contract. Older CLIs resolve `undefined` (guard the FIELD, not just the
+        // receipt, so a bare `{}` success from a gateway can't read as "everything
+        // was dropped") — keep the count-everything behavior and its
+        // activation-time self-heal.
+        if (Array.isArray(receipt?.still_queued) && orphanedUuids.length > 0) {
+            const stillQueued = new Set(receipt.still_queued);
+            const dropped = orphanedUuids.filter((uuid) => !stillQueued.has(uuid)).length;
+            if (dropped > 0) {
+                session.pendingOrphanResults = Math.max(0, (session.pendingOrphanResults ?? 0) - dropped);
+            }
+        }
     }
     /** Mark a session's SDK query stream as permanently ended and release the
      *  resources tied to it: drop the consumer handle, dispose the settings
@@ -1971,6 +2155,14 @@ export class ClaudeAcpAgent {
         if (!session) {
             throw new Error("Session not found");
         }
+        // A lazy Thinking recreate may be swapping the session's query right now;
+        // join it (mirroring prompt()) so `setPermissionMode` below lands on the
+        // replacement query after cutover instead of an about-to-close one — and
+        // so the mode isn't silently dropped from a query built from the
+        // pre-await state snapshot. Safe: `recreateSessionQuery` never rejects.
+        if (session.queryRecreateInFlight) {
+            await session.queryRecreateInFlight;
+        }
         // The SDK query stream already ended (see closeQueryStream); the session is
         // a husk and `query.setPermissionMode` below would act on a closed query.
         // Fail with the same clear message prompt()/cancel() give for a dead stream.
@@ -1986,6 +2178,16 @@ export class ClaudeAcpAgent {
         if (!session) {
             throw new Error("Session not found");
         }
+        // A lazy Thinking recreate may be swapping the session's query right now;
+        // join it (mirroring prompt()) so the model/mode/effort/fast SDK calls
+        // below land on the replacement query after cutover instead of an
+        // about-to-close one — and so their state updates aren't silently
+        // dropped from a query built from the pre-await state snapshot. The
+        // THINKING branch only arms the pending flag, so joining first is
+        // harmless for it. Safe: `recreateSessionQuery` never rejects.
+        if (session.queryRecreateInFlight) {
+            await session.queryRecreateInFlight;
+        }
         // The SDK query stream already ended (see closeQueryStream); the session is
         // a husk and the `query.setModel`/`setPermissionMode`/`applyFlagSettings`
         // calls this triggers would act on a closed query. Fail with the same clear
@@ -1997,13 +2199,29 @@ export class ClaudeAcpAgent {
         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.
+        // Fast mode is always emitted as an "on"/"off" select, but a native
+        // boolean set value is still accepted for compatibility (R2.3), 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 };
         }
+        // The Thinking toggle only records the session's intent — the SDK query
+        // swap is deferred to the next prompt() start (lazy recreate, sub-task
+        // 1.3), so there is no SDK call to fail here and the config option is
+        // refreshed and acked immediately, mirroring Fast mode. An unrecognized
+        // value deliberately falls through to the shared invalid-option-value
+        // validation below rather than growing a bespoke error shape.
+        if (params.configId === THINKING_CONFIG_ID) {
+            const enabled = resolveThinkingSelection(params.value);
+            if (enabled !== null) {
+                session.thinkingEnabled = enabled;
+                session.pendingQueryRecreate = true;
+                session.configOptions = session.configOptions.map((o) => o.id === THINKING_CONFIG_ID ? createThinkingConfigOption(enabled) : o);
+                return { configOptions: session.configOptions };
+            }
+        }
         if (typeof params.value !== "string") {
             throw new Error(`Invalid value for config option ${params.configId}: ${params.value}`);
         }
@@ -2011,18 +2229,40 @@ export class ClaudeAcpAgent {
             ? 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".
+        // 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).
+        // No deprecation filter here (R4.2, no double work): this list is rebuilt
+        // from the RENDERED option rows, which flow from the already-filtered
+        // picker list (`hideDeprecatedModels` at every session-creation branch) —
+        // so hidden rows are not selectable via aliases either.
         if (!validValue && params.configId === MODEL_CONFIG_ID) {
-            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);
+            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) {
@@ -2551,8 +2791,15 @@ export class ClaudeAcpAgent {
                 // intent) when a supporting model is selected again.
                 supported: newModelInfo?.supportsFastMode ?? false,
                 enabled: session.fastModeEnabled,
-                useBooleanOption: clientSupportsBooleanConfigOptions(this.clientCapabilities),
-            });
+            }, 
+            // Thinking is model-independent: re-render the retained tri-state
+            // intent so the row survives this rebuild (an option not threaded
+            // through here silently drops from the picker on every model switch,
+            // R1.7). Untouched sessions keep displaying the env-driven state
+            // (R1.6).
+            session.thinkingEnabled ??
+                effectiveThinkingConfig(undefined, process.env.MAX_THINKING_TOKENS, this.logger) !==
+                    undefined);
             // Sync effort with the SDK if it changed after the model switch
             const newEffortOpt = session.configOptions.find((o) => o.id === EFFORT_CONFIG_ID);
             const newEffort = typeof newEffortOpt?.currentValue === "string" ? newEffortOpt.currentValue : undefined;
@@ -2629,11 +2876,12 @@ export class ClaudeAcpAgent {
         }
     }
     /** 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. */
+     *  `enabled`. A no-op when the option isn't present, so callers must confirm
+     *  the current model surfaces it first. Rebuilds through the single-parameter
+     *  {@link createFastModeConfigOption} — the one source of the option's shape —
+     *  so the shape can't drift from what `buildConfigOptions` first emitted. */
     refreshFastModeOption(session, enabled) {
-        const refreshed = createFastModeConfigOption(enabled, clientSupportsBooleanConfigOptions(this.clientCapabilities));
+        const refreshed = createFastModeConfigOption(enabled);
         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
@@ -2647,6 +2895,261 @@ export class ClaudeAcpAgent {
         session.fastModeEnabled = enabled;
         this.refreshFastModeOption(session, enabled);
     }
+    /** Lazily swap a session's SDK query for a fresh one so a Thinking change
+     *  takes effect on the next turn (R1.3): thinking has no live flag-settings
+     *  path in the SDK, so mid-session application goes through query recreation
+     *  with session resume. The replacement resumes the SAME conversation
+     *  (`{ resume: sessionId }` — the adapter's session ids ARE the SDK's, see
+     *  `getOrCreateSession`) and is assembled from the creation-time
+     *  `queryOptions` plus the live-tracked session state (model, permission
+     *  mode, agent, effort, Fast mode), with thinking routed through
+     *  `effectiveThinkingConfig` — the same single code path query creation
+     *  uses (R1.5/R1.6).
+     *
+     *  Deliberately NOT `teardownSession`: that aborts `session.abortController`
+     *  (possibly client-supplied and reused) and evicts the session from the
+     *  map. This path keeps the Session object registered and every controller
+     *  alive; only the query subprocess is replaced.
+     *
+     *  Ordering is what makes the swap safe:
+     *  1. Build + initialize the NEW query first, time-bounded
+     *     (QUERY_RECREATE_INIT_TIMEOUT_MS) so a wedged replacement cannot hang
+     *     the joins on `queryRecreateInFlight`. Any failure leaves the old
+     *     query untouched and usable: the user is told via agent_message_chunk,
+     *     `pendingQueryRecreate` stays set (retried on the next prompt), and the
+     *     caller's turn proceeds on the OLD query. Never rejects.
+     *  2. Re-check, synchronously, session liveness and model/mode drift: if
+     *     the OLD stream died (or the session was evicted) while step 1
+     *     awaited — or a straggler setter moved the model/mode again after the
+     *     delta re-apply — abandon the replacement instead of installing it.
+     *  3. Cut over synchronously — swap `session.query`/`input`, drop the
+     *     consumer handle (so `ensureConsumer` starts a fresh consumer for the
+     *     new query), clear the pending flag — THEN end the old stream. Swapping
+     *     before closing is load-bearing: the superseded consumer only wakes
+     *     after this microtask completes, sees `session.query !== myQuery`, and
+     *     exits via its supersession guards instead of running end-of-stream
+     *     cleanup (which would close the NEW query and dispose live resources).
+     *
+     *  Only called from `prompt()` while the turn queue is idle (concurrent
+     *  RPC entry points join `queryRecreateInFlight`), so there are no in-flight
+     *  turns to migrate and the old query has nothing left to say. */
+    async recreateSessionQuery(sessionId, session) {
+        const newInput = new Pushable();
+        let newQuery;
+        try {
+            if (!session.queryOptions) {
+                // Only reachable for hand-built sessions (tests): createSession always
+                // records the options. Routed through the failure path below so the
+                // old query stays usable.
+                throw new Error("session has no recorded query options to rebuild from");
+            }
+            // ONE thinking code path for creation and recreation: the session's
+            // tri-state intent beats the env var once set ("off" wins even with
+            // MAX_THINKING_TOKENS present, R1.5); untouched sessions keep the
+            // env-driven behavior (R1.6).
+            const thinking = effectiveThinkingConfig(session.thinkingEnabled, process.env.MAX_THINKING_TOKENS, this.logger);
+            // Snapshot of the live-tracked model/mode the replacement is built
+            // with. A setter that was ALREADY awaiting its control request on the
+            // old query when this recreate started (i.e. past its
+            // `queryRecreateInFlight` join) can land its state update after this
+            // snapshot; the post-init delta re-apply below reconciles the NEW
+            // query, and the synchronous pre-swap check abandons the recreate if
+            // the state moves yet again.
+            let appliedModelId = session.models.currentModelId;
+            let appliedModeId = session.modes.currentModeId;
+            const options = {
+                ...session.queryOptions,
+                // Live-tracked state that may have drifted from creation time via
+                // setSessionMode/setModel. `availableModes` ids are the SDK's own
+                // permission modes (see `applySessionMode`'s validation), so the cast
+                // is sound.
+                permissionMode: appliedModeId,
+                model: appliedModelId,
+                // Resume THIS conversation in the replacement subprocess.
+                resume: sessionId,
+                // Same controller: a client-supplied abort must keep governing the
+                // session across the swap.
+                abortController: session.abortController,
+            };
+            // `sessionId` is mutually exclusive with `resume` (and this is never a
+            // fork); stale creation-time values would make the SDK reject or fork.
+            delete options.sessionId;
+            delete options.forkSession;
+            // Route the fresh resolution in (a stale creation-time `thinking` must
+            // not leak through when the fresh resolution is `undefined`).
+            delete options.thinking;
+            if (thinking !== undefined) {
+                options.thinking = thinking;
+            }
+            if (session.currentAgent === DEFAULT_AGENT_ID) {
+                delete options.agent;
+            }
+            else {
+                options.agent = session.currentAgent;
+            }
+            newQuery = query({ prompt: newInput, options });
+            const replacement = newQuery;
+            // Everything the replacement needs before it may serve a turn, grouped
+            // into one phase so it can be time-bounded below.
+            const initPhase = (async () => {
+                // Fail fast while the OLD query is still intact: a spawn/resume
+                // problem surfaces here, not after the cutover.
+                await replacement.initializationResult();
+                // Flag-layer settings don't survive into a new subprocess; re-apply
+                // the session's current effort and Fast mode before any turn runs on
+                // it (mirrors createSession's initial-effort application). Both are
+                // read post-init, so a setter update that landed during the init
+                // await is already included.
+                const effortOpt = session.configOptions.find((o) => o.id === EFFORT_CONFIG_ID);
+                const effortLevel = typeof effortOpt?.currentValue === "string"
+                    ? toSdkEffortLevel(effortOpt.currentValue)
+                    : null;
+                if (effortLevel !== null) {
+                    await replacement.applyFlagSettings({ effortLevel });
+                }
+                const supportsFastMode = session.modelInfos.find((m) => m.value === session.models.currentModelId)
+                    ?.supportsFastMode ?? false;
+                if (session.fastModeEnabled && supportsFastMode) {
+                    await replacement.applyFlagSettings({ fastMode: true });
+                }
+                // Delta re-apply: a model/mode setter that was already in flight on
+                // the OLD query when this recreate snapshotted the session state may
+                // have landed its update during the awaits above — the client was
+                // acked for a value the replacement wasn't built with. Reconcile via
+                // the new query's live controls (the same calls the setters use), and
+                // keep `options` truthful for the stored `queryOptions` snapshot. (A
+                // setter that instead resolves AFTER the swap applies to the closed
+                // old query and surfaces as a visible rejection to the client — not a
+                // silent desync — which is acceptable.)
+                if (session.models.currentModelId !== appliedModelId) {
+                    appliedModelId = session.models.currentModelId;
+                    options.model = appliedModelId;
+                    await replacement.setModel(appliedModelId);
+                }
+                if (session.modes.currentModeId !== appliedModeId) {
+                    appliedModeId = session.modes.currentModeId;
+                    options.permissionMode = appliedModeId;
+                    await replacement.setPermissionMode(appliedModeId);
+                }
+            })();
+            // Bound the whole phase (a wedged replacement subprocess can hang
+            // initializationResult() forever — the issue #680 wedge class). Every
+            // join on `queryRecreateInFlight` — prompt/cancel/the setters, and
+            // teardown/dispose via cancel() — would inherit such a hang, so expiry
+            // rejects into the failure path below (replacement closed, old query
+            // untouched, pending flag retained). The timer is cleared on every
+            // path; if the timeout wins, the losing initPhase's later settlement is
+            // absorbed by Promise.race's own subscription, so no rejection can
+            // surface as unhandled.
+            let initTimer;
+            try {
+                await Promise.race([
+                    initPhase,
+                    new Promise((_, reject) => {
+                        initTimer = setTimeout(() => {
+                            reject(new Error(`recreate timed out: the replacement query did not finish initializing ` +
+                                `within ${QUERY_RECREATE_INIT_TIMEOUT_MS}ms`));
+                        }, QUERY_RECREATE_INIT_TIMEOUT_MS);
+                    }),
+                ]);
+            }
+            finally {
+                clearTimeout(initTimer);
+            }
+            // Liveness re-check: the awaits above are a long window in which the
+            // OLD query's stream can die on its own — its (still-bound, not yet
+            // superseded) consumer then runs closeQueryStream (queryClosed = true,
+            // settings disposed) and, for a dead process, evicts the session.
+            // Installing the new query anyway would brick the session (queryClosed
+            // blocks prompt/cancel/setSessionMode/setSessionConfigOption) or, in
+            // the eviction case, leak the fresh subprocess where no teardown could
+            // ever reach it. Treat it as a failed recreate: release the new
+            // resources and keep the pending flag. Deliberately NO client note
+            // here — "retried on the next prompt" would be false for a dead
+            // session (and meaningless for an evicted one); the authoritative
+            // signal stays the existing SESSION_ENDED flow.
+            if (session.queryClosed || this.sessions[sessionId] !== session) {
+                const reason = this.sessions[sessionId] !== session
+                    ? "the session was evicted while the replacement query initialized"
+                    : "the session's query stream ended while the replacement query initialized";
+                this.logger.error(`Session ${sessionId}: abandoning Thinking query recreate: ${reason}.`);
+                newInput.end();
+                try {
+                    newQuery.close();
+                }
+                catch (closeError) {
+                    this.logger.error(`Session ${sessionId}: failed to close abandoned replacement query:`, closeError);
+                }
+                return;
+            }
+            // Reverse-interleaving re-check (synchronous — nothing may await
+            // between here and the swap): if a straggler setter moved the model or
+            // permission mode yet again after the delta re-apply in `initPhase`,
+            // abandon the replacement rather than install it stale. The pending
+            // flag is retained, so the next prompt rebuilds from fresh state.
+            if (session.models.currentModelId !== appliedModelId ||
+                session.modes.currentModeId !== appliedModeId) {
+                this.logger.error(`Session ${sessionId}: abandoning Thinking query recreate: the session's model ` +
+                    `or permission mode changed while the replacement initialized; retrying on ` +
+                    `the next prompt.`);
+                newInput.end();
+                try {
+                    newQuery.close();
+                }
+                catch (closeError) {
+                    this.logger.error(`Session ${sessionId}: failed to close abandoned replacement query:`, closeError);
+                }
+                return;
+            }
+            // Cutover. Synchronous from here through the old-stream close: the
+            // superseded consumer can only wake in a later microtask, so it never
+            // observes an intermediate state.
+            const oldQuery = session.query;
+            const oldInput = session.input;
+            session.query = newQuery;
+            session.input = newInput;
+            session.queryOptions = options;
+            // The superseded consumer exits via its guards without touching the
+            // session; drop its handle so the caller's ensureConsumer starts a
+            // fresh consumer for the new query.
+            session.consumer = undefined;
+            session.pendingQueryRecreate = false;
+            // End the old stream last; its consumer wakes on the final next() only
+            // after the swap above is complete.
+            oldInput.end();
+            oldQuery.close();
+        }
+        catch (error) {
+            // Keep the OLD query fully usable and the pending flag set (the next
+            // prompt retries); the current turn proceeds with the previous thinking
+            // config. Everything is contained here — never an unhandled rejection.
+            this.logger.error(`Session ${sessionId}: failed to recreate query for Thinking change:`, error);
+            newInput.end();
+            try {
+                newQuery?.close();
+            }
+            catch (closeError) {
+                this.logger.error(`Session ${sessionId}: failed to close abandoned replacement query:`, closeError);
+            }
+            try {
+                await this.client.sessionUpdate({
+                    sessionId,
+                    update: {
+                        sessionUpdate: "agent_message_chunk",
+                        content: {
+                            type: "text",
+                            text: "Note: the updated Thinking setting could not be applied to this turn " +
+                                "(recreating the session's query failed), so it continues with the previous " +
+                                "setting. The change will be retried on the next prompt.",
+                        },
+                    },
+                });
+            }
+            catch (notifyError) {
+                this.logger.error(`Session ${sessionId}: failed to notify the client about the Thinking recreate failure:`, notifyError);
+            }
+        }
+    }
     /** 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`
@@ -2810,8 +3313,11 @@ export class ClaudeAcpAgent {
         // Extract options from _meta if provided
         const sessionMeta = params._meta;
         const userProvidedOptions = sessionMeta?.claudeCode?.options;
-        // Configure thinking behavior from environment variable
-        const thinking = resolveThinkingConfig(process.env.MAX_THINKING_TOKENS, this.logger);
+        // Configure thinking behavior through the same single code path query
+        // recreation uses (`recreateSessionQuery`). A fresh session's Thinking
+        // intent is untouched (`undefined`), so this resolves to exactly the
+        // legacy env-driven MAX_THINKING_TOKENS behavior (R1.6).
+        const thinking = effectiveThinkingConfig(undefined, process.env.MAX_THINKING_TOKENS, this.logger);
         // Parse model configuration from environment (e.g. Bedrock model overrides)
         const modelConfig = parseModelConfig(process.env.CLAUDE_MODEL_CONFIG);
         // Elicitation modes the connected client advertised. We only forward
@@ -2844,6 +3350,10 @@ export class ClaudeAcpAgent {
             systemPrompt,
             settingSources: ["user", "project", "local"],
             ...(thinking !== undefined && { thinking }),
+            // File checkpointing on by default so `/rewind N` can restore files
+            // (story 006, R3.3). Placed before the user spread so an explicit user
+            // `enableFileCheckpointing` still wins.
+            enableFileCheckpointing: true,
             ...userProvidedOptions,
             // CLAUDE_MODEL_CONFIG env var is a fallback for model
             // configuration (e.g. Bedrock model ID overrides). When the caller
@@ -3007,13 +3517,68 @@ export class ClaudeAcpAgent {
         // 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, settingsModelOverrides)
+        // The CATALOG: allowlist-applied (when configured) but deprecation-
+        // UNfiltered. Preference resolution (`resolveModelPreference`) and
+        // capability lookups read this list, so a persisted preference pointing at
+        // a deprecated model keeps resolving with full capabilities (R4.3 — the
+        // deprecation filter is visibility-only, never a forced migration).
+        const catalogModels = Array.isArray(settingsAvailableModels)
+            ? buildAllowlistedModels(initializationResult.models, settingsAvailableModels, settingsModelOverrides)
             : initializationResult.models;
-        const models = await getAvailableModels(q, allowedModels, initializationResult.models, settingsManager, this.logger);
+        // The PICKER list: same pipeline plus the deprecation visibility filter
+        // (R4.2). With an allowlist this goes through the exported boundary
+        // `applyAvailableModelsAllowlist` (the filter lives inside it — pinned by
+        // model-picker-filter.test.ts); the small allowlist recompute vs.
+        // `catalogModels` is deliberate so the boundary stays the single place
+        // filter and allowlist compose. Without an allowlist the raw SDK list is
+        // the one list-building site that never crosses that boundary, so it
+        // applies the SAME `hideDeprecatedModels` helper directly.
+        const allowedModels = Array.isArray(settingsAvailableModels)
+            ? applyAvailableModelsAllowlist(initializationResult.models, settingsAvailableModels, settingsModelOverrides, this.logger)
+            : hideDeprecatedModels(initializationResult.models, this.logger);
+        const models = await getAvailableModels(q, catalogModels, allowedModels, initializationResult.models, settingsManager, this.logger, creationOpts.resume !== undefined);
         // 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);
+        // Looked up in the UNfiltered catalog: a session honoring a persisted
+        // deprecated preference must keep that model's real capabilities (R4.3).
+        // A resumed session can also 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 catalogModelInfo = catalogModels.find((m) => m.value === models.currentModelId);
+        const fallbackModelInfo = catalogModelInfo
+            ? undefined
+            : (resolveModelPreference(initializationResult.models, models.currentModelId) ?? undefined);
+        const currentModelInfo = catalogModelInfo ?? 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.
+        // Built on the UNfiltered catalog, NOT the picker list: `modelInfos` is
+        // never rendered (picker rows come from `models.availableModels`) — it
+        // feeds capability lookups and `resolveModelPreference` (refusal
+        // fallback), which must keep seeing deprecated rows (R4.3,
+        // visibility-only filter).
+        const modelInfos = fallbackModelInfo
+            ? [
+                ...catalogModels,
+                {
+                    ...fallbackModelInfo,
+                    value: models.currentModelId,
+                    displayName: models.currentModelId,
+                    description: "",
+                    resolvedModel: undefined,
+                },
+            ]
+            : catalogModels;
         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
@@ -3065,9 +3630,21 @@ export class ClaudeAcpAgent {
         const fastMode = {
             supported: currentModelInfo?.supportsFastMode ?? false,
             enabled: fastModeEnabled,
-            useBooleanOption: clientSupportsBooleanConfigOptions(this.clientCapabilities),
         };
-        const configOptions = buildConfigOptions(modes, models, allowedModels, settingsManager.getSettings().effortLevel, agents, currentAgent, fastMode);
+        const configOptions = buildConfigOptions(modes, models, 
+        // Catalog-based (see `modelInfos` above), matching the model-switch
+        // rebuild (which passes `session.modelInfos`): `buildConfigOptions`
+        // reads this argument only for the current model's effort capabilities
+        // — picker rows come from `models.availableModels` — so a deprecated
+        // current model keeps its effort option without leaking hidden rows
+        // (R4.3).
+        modelInfos, settingsManager.getSettings().effortLevel, agents, currentAgent, fastMode, 
+        // A fresh session's Thinking intent is untouched (undefined), so the
+        // display follows the env-driven state. `thinking` already holds
+        // effectiveThinkingConfig(undefined, MAX_THINKING_TOKENS) from above, so
+        // reusing it avoids re-parsing (and re-logging an invalid) env var —
+        // exactly one error log per query creation.
+        thinking !== undefined);
         // Apply the initial effort level to the SDK so it matches the UI default
         const initialEffort = configOptions.find((o) => o.id === EFFORT_CONFIG_ID);
         if (initialEffort &&
@@ -3082,6 +3659,9 @@ export class ClaudeAcpAgent {
             input: input,
             cancelled: false,
             cwd: params.cwd,
+            // Recorded so `recreateSessionQuery` (lazy Thinking application, R1.3)
+            // can rebuild an equivalent query without re-running this assembly.
+            queryOptions: options,
             sessionFingerprint: computeSessionFingerprint(params),
             settingsManager,
             accumulatedUsage: {
@@ -3092,14 +3672,24 @@ export class ClaudeAcpAgent {
             },
             modes,
             models,
-            modelInfos: allowedModels,
+            // Catalog-based, NOT the picker list: `modelInfos` is never rendered
+            // (picker rows come from `models.availableModels`) — it feeds
+            // capability lookups and `resolveModelPreference` (refusal fallback),
+            // which must keep seeing deprecated rows (R4.3, visibility-only filter).
+            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 catalog entry: a fallback-resolved
+            // sibling's displayName/description can describe a different context
+            // lane than the verbatim live id (e.g. an "opus[1m]" row matched for
+            // a bare 200k id), so on the fallback path only the id itself is a
+            // trustworthy window signal.
+            inferContextWindowFromModel(models.currentModelId, catalogModelInfo?.displayName, catalogModelInfo?.description) ?? DEFAULT_CONTEXT_WINDOW,
             taskState,
             toolUseCache: {},
             emittedToolCalls: new Set(),
@@ -3255,6 +3845,7 @@ function toSdkEffortLevel(value) {
 export const BUILTIN_AGENT_NAMES = new Set([
     "claude",
     "general-purpose",
+    "claude-code-guide",
     "Explore",
     "Plan",
     "statusline-setup",
@@ -3287,8 +3878,8 @@ 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}). */
+/** Select values for the Fast mode on/off option
+ *  (see {@link createFastModeConfigOption}). */
 export const FAST_MODE_ON = "on";
 export const FAST_MODE_OFF = "off";
 const FAST_MODE_DESCRIPTION = "Faster responses on supported models";
@@ -3299,29 +3890,18 @@ const FAST_MODE_DESCRIPTION = "Faster responses on supported models";
 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 = {
+/** Build the Fast mode config option as a two-value on/off `select`. Emitted
+ *  for EVERY Client — the boolean option shape is gone (story 006, R2.1). Only
+ *  the emitted SHAPE is fixed to a select; boolean VALUES are still honored on
+ *  set (see {@link resolveFastModeEnabled}). This factory is the single source
+ *  of the option's shape, re-rendered by `refreshFastModeOption` /
+ *  `syncFastModeState` so the shape can never desync. */
+export function createFastModeConfigOption(enabled) {
+    return {
         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: [
@@ -3331,8 +3911,8 @@ export function createFastModeConfigOption(enabled, useBooleanOption) {
     };
 }
 /** 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. */
+ *  request. Accepts the select's "on"/"off" strings or a native boolean,
+ *  kept for backward compatibility (R2.3). */
 export function resolveFastModeEnabled(params) {
     const value = params.value;
     if (typeof value === "boolean") {
@@ -3346,7 +3926,13 @@ export function resolveFastModeEnabled(params) {
     }
     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) {
+export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel, agents = [], currentAgent = DEFAULT_AGENT_ID, fastMode, 
+/** Display state for the Thinking toggle: the session's tri-state intent
+ *  already collapsed to a boolean by the caller
+ *  (`intent ?? (effectiveThinkingConfig(undefined, env, logger) !== undefined)`).
+ *  Both session call sites always supply it (R1.1); `undefined` (direct
+ *  callers/tests) omits the row. */
+thinkingEnabled) {
     const options = [
         {
             id: MODE_CONFIG_ID,
@@ -3404,10 +3990,16 @@ export function buildConfigOptions(modes, models, modelInfos, currentEffortLevel
         });
     }
     // 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.
+    // option is always emitted as a two-value on/off select for every Client
+    // (R2.1); boolean values remain accepted on set for boolean-era clients.
     if (fastMode?.supported) {
-        options.push(createFastModeConfigOption(fastMode.enabled, fastMode.useBooleanOption));
+        options.push(createFastModeConfigOption(fastMode.enabled));
+    }
+    // Surface the Thinking toggle whenever the caller supplies its display
+    // state. Unlike Fast mode it is model-independent — no `supported` gate —
+    // and select-only ("on"/"off"), so every session shows it (R1.1).
+    if (thinkingEnabled !== undefined) {
+        options.push(createThinkingConfigOption(thinkingEnabled));
     }
     // 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
@@ -3435,14 +4027,32 @@ 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;
+// 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) {
-    // Strip "[1m]"-style context hints first — that digit is context window
-    // size, not a model generation version.
-    const match = s.replace(/\[\d+m\]/gi, "").match(MODEL_FAMILY_VERSION_PATTERN);
+    const match = stripContextHints(s).match(MODEL_FAMILY_VERSION_PATTERN);
     if (!match)
         return null;
     return match[2] ? `${match[1]}.${match[2]}` : match[1];
@@ -3495,25 +4105,38 @@ export function resolveModelPreference(models, preference) {
     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;
     // 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.
-    // "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 resolvedMatch = models.find((model) => model.value !== "default" && model.resolvedModel?.toLowerCase() === lower) ?? models.find((model) => model.resolvedModel?.toLowerCase() === lower);
+    // 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
+    // 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);
@@ -3537,6 +4160,51 @@ export 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;
@@ -3549,7 +4217,8 @@ function resolveSettingsModel(models, settingsModel, logger) {
     return resolveModelPreference(models, settingsModel);
 }
 /**
- * Restrict the SDK's model list to the user's `availableModels` allowlist
+ * Deprecation-UNfiltered core of {@link applyAvailableModelsAllowlist}:
+ * restrict the SDK's model list to the user's `availableModels` allowlist
  * (already merged-and-deduped across settings sources by `SettingsManager`).
  * The user's exact entries become the model IDs surfaced via configOptions
  * and passed to `setModel`, which prevents Claude Code from silently
@@ -3559,12 +4228,16 @@ function resolveSettingsModel(models, settingsModel, logger) {
  * Display info and capability flags are copied from the closest SDK match so
  * the UI still renders sensible names and effort levels.
  *
+ * Kept separate from the exported boundary so session creation can obtain the
+ * allowlist-applied-but-unfiltered CATALOG that preference resolution and
+ * capability lookups read (R4.3 — the deprecation filter is visibility-only).
+ *
  * Semantics from https://code.claude.com/docs/en/model-config#restrict-model-selection:
  * - `undefined` is handled by the caller (no allowlist applied).
  * - The Default option is unaffected by `availableModels` — it always remains
  *   available, even when the allowlist is `[]`.
  */
-export function applyAvailableModelsAllowlist(sdkModels, allowlist, settingsModelOverrides) {
+function buildAllowlistedModels(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.
@@ -3616,14 +4289,82 @@ export function applyAvailableModelsAllowlist(sdkModels, allowlist, settingsMode
     }
     return result;
 }
-async function getAvailableModels(query, models, sdkModels, settingsManager, logger) {
+/**
+ * Visibility filter for PICKER-bound model lists (R4.2): drop rows
+ * {@link filterDeprecatedModels} flags as deprecated/legacy. Every
+ * list-building site applies this same helper — via
+ * {@link applyAvailableModelsAllowlist} when an allowlist is configured, or
+ * directly on the raw SDK list otherwise — so the picker never renders a
+ * deprecated row regardless of configuration.
+ *
+ * This is visibility-only: preference resolution and capability lookups keep
+ * reading the UNfiltered catalog (R4.3), so a persisted preference pointing at
+ * a deprecated model is still honored.
+ *
+ * Edge: if the filter would hide EVERY row, fall back to the unfiltered input
+ * so config-option building never receives an empty model list, and log it.
+ * The logger is optional because this is also reached from the free exported
+ * boundary (tests, library callers) where no agent logger exists.
+ */
+function hideDeprecatedModels(models, logger) {
+    const visible = filterDeprecatedModels(models);
+    if (visible.length === 0 && models.length > 0) {
+        logger?.error("Deprecation filter would hide every available model; showing the unfiltered list instead.");
+        return models;
+    }
+    return visible;
+}
+/**
+ * The exported picker-list boundary: {@link buildAllowlistedModels} (the
+ * user's `availableModels` allowlist semantics — see its doc) composed with
+ * {@link hideDeprecatedModels} (the deprecation visibility filter, R4.2).
+ *
+ * The filter runs on the allowlist RESULT, not on `sdkModels`: allowlisted
+ * entries copy `displayName`/`description` from their closest SDK match, so a
+ * deprecated row is hidden even when the allowlist names it explicitly.
+ * Entries with no SDK match copy the entry text itself into `displayName`
+ * ({@link buildAllowlistedModels}), so the heuristic DOES read user-authored
+ * text: a custom entry containing "legacy"/"deprecated" is hidden from the
+ * picker (rare, accepted false positive — the model stays reachable via
+ * `settings.model` / `ANTHROPIC_MODEL`, which resolve over the unfiltered
+ * catalog).
+ */
+export function applyAvailableModelsAllowlist(sdkModels, allowlist, settingsModelOverrides, logger) {
+    return hideDeprecatedModels(buildAllowlistedModels(sdkModels, allowlist, settingsModelOverrides), 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, 
+/** Deprecation-UNfiltered catalog (allowlist-applied when configured):
+ *  preference resolution and the default pick read this list so a persisted
+ *  deprecated preference still resolves (R4.3). */
+models, 
+/** Deprecation-filtered picker list: becomes the rendered `availableModels`
+ *  rows (R4.2). The resolved `currentModelId` may legitimately be absent
+ *  from these rows (deprecated persisted preference) — the picker then
+ *  shows no selection, mirroring the refusal-fallback bookkeeping. */
+pickerModels, 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) {
@@ -3638,24 +4379,52 @@ 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) => ({
+        availableModels: pickerModels.map((model) => ({
             modelId: model.value,
             name: model.displayName,
             description: model.description,
@@ -3674,7 +4443,7 @@ function getAvailableSlashCommands(commands) {
         "release-notes",
         "todos",
     ];
-    return commands
+    const advertised = commands
         .map((command) => {
         const input = command.argumentHint
             ? {
@@ -3694,6 +4463,17 @@ function getAvailableSlashCommands(commands) {
         };
     })
         .filter((command) => !UNSUPPORTED_COMMANDS.includes(command.name));
+    // `/rewind` is handled fully locally by the adapter (story 006, R3.1), so it
+    // is absent from the SDK command list; advertise it here with an input hint.
+    // Deduped by name so a same-named SDK command (should one ever appear) wins.
+    if (!advertised.some((command) => command.name === "rewind")) {
+        advertised.push({
+            name: "rewind",
+            description: "List file checkpoints, or restore files to one with `/rewind <n>`.",
+            input: { hint: "checkpoint number (omit to list)" },
+        });
+    }
+    return advertised;
 }
 function formatUriAsLink(uri) {
     try {
@@ -3909,8 +4689,8 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
         let update = null;
         switch (chunk.type) {
             case "text":
-            case "text_delta":
-                if (chunk.text.length > 0) {
+            case "text_delta": {
+                if (chunk.text) {
                     update = {
                         sessionUpdate: role === "assistant" ? "agent_message_chunk" : "user_message_chunk",
                         content: {
@@ -3920,6 +4700,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                     };
                 }
                 break;
+            }
             case "image":
                 update = {
                     sessionUpdate: role === "assistant" ? "agent_message_chunk" : "user_message_chunk",
@@ -3932,10 +4713,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: {
@@ -3945,6 +4726,7 @@ export function toAcpNotifications(content, role, sessionId, toolUseCache, clien
                     };
                 }
                 break;
+            }
             case "tool_use":
             case "server_tool_use":
             case "mcp_tool_use": {
@@ -4286,22 +5068,6 @@ async function fetchContextUsedTokens(query, logger) {
         return null;
     }
 }
-/** Translate the legacy `MAX_THINKING_TOKENS` env var into the SDK's `thinking`
- *  option. The `maxThinkingTokens` option it used to feed is deprecated and
- *  reduced to on/off on current models, so map the value to explicit thinking
- *  config instead: unset → `undefined` (SDK default, adaptive on models that
- *  support it); `0` → disabled; a positive integer → a fixed token budget.
- *  Anything else is ignored with a warning. */
-function resolveThinkingConfig(raw, logger) {
-    if (raw === undefined)
-        return undefined;
-    const parsed = Number.parseInt(raw, 10);
-    if (Number.isNaN(parsed) || parsed < 0) {
-        logger.error(`Ignoring MAX_THINKING_TOKENS: expected a non-negative integer, got '${raw}'.`);
-        return undefined;
-    }
-    return parsed === 0 ? { type: "disabled" } : { type: "enabled", budgetTokens: parsed };
-}
 function parseModelConfig(raw) {
     if (!raw)
         return undefined;