openmausbot 0.1.90 → 0.1.92

package/dist-server/server/drivers/claude.js

@@ -8,7 +8,7 @@
 //   - Composio Sessions (connected apps → tools) over streamable HTTP
 //   - the bot's cloud computer (boat.dev) via server/computer-proxy.ts
 //     — screenshot/exec/open_url, the CUA-on-the-boat bridge
-import { createHash, randomBytes } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import { createServer as createNetServer } from "node:net";
 import { homedir, tmpdir } from "node:os";
@@ -150,7 +150,7 @@ function claudeEnvironment(model, source = process.env, configDir, instanceEnvir
     // env-injected at boot); none of them are this CLI's to see.
     stripWorkspaceCredentialEnv(env);
     const applied = applyClaudeInject(env, model);
-    // A key set on purpose for this workspace (Settings → Connections, carried
+    // A key set on purpose for this workspace (Settings → API keys, carried
     // in the instance environment) stays. One riding along in the parent's
     // env never does: it would flip a subscription login to pay-as-you-go.
     if (!applied.injected && !instanceEnvironment.ANTHROPIC_API_KEY)
@@ -279,11 +279,38 @@ export const CLAUDE_FLAG_FLOORS = {
     // 2.1.267 is the first CLI that accepts it; below that the recorded prompt
     // simply is not refreshed, which is the pre-existing behaviour.
     "--system-prompt-snapshot": [2, 1, 267],
+    // A guest's turn on a Cloud home (GUEST_CLAUDE_TOOLS): 2.1.248 takes
+    // --restricted, 2.1.257 honours blockReadsOutsideWorkingDirectories.
+    "--restricted": [2, 1, 257],
+};
+/** The only built-in tools a guest's turn on a Cloud home gets
+ * (SendTurnInput.guestConfined): no Bash, PowerShell or WebFetch, so nothing
+ * runs a command, and with --restricted plus the settings below every read
+ * outside its own folder is refused outright, never asked. Probed against
+ * Claude Code 2.1.284 in `default` mode: without this, a built-in list of
+ * "read-only" Bash commands runs unasked, and `xargs head` reads any file. */
+/** A refusal of a confined turn, and why it is confined (SendTurnInput.confinedWhy). */
+const withWhy = (refusal, why) => why ? `${refusal} ${why}` : refusal;
+export const GUEST_CLAUDE_TOOLS = ["Read", "Grep", "Glob", "Edit", "Write", "WebSearch"];
+/** Tools a guest's session must never report in its init frame. */
+const GUEST_FORBIDDEN_TOOLS = new Set(["Bash", "PowerShell", "WebFetch", "BashOutput", "KillShell", "KillBash", "NotebookEdit", "Task", "Agent"]);
+/** The permission block a guest's session runs under, as a second layer. */
+export const GUEST_CLAUDE_PERMISSIONS = {
+    blockReadsOutsideWorkingDirectories: true,
+    deny: ["Bash", "PowerShell", "WebFetch", "Read(//proc/**)"],
 };
 /** The newest floor above: a CLI at or past it accepts everything the
  * harness sends. Below it the engine still works, minus the flags the CLI
  * predates, and the Engines page suggests an update. */
 export const CLAUDE_CONTEXT_CONTROL_MIN_VERSION = CLAUDE_FLAG_FLOORS["--system-prompt-snapshot"];
+/** The first CLI this driver has seen echo a stdin user message, with the
+ * uuid it was sent with, as a model call takes it in (`--replay-user-messages`,
+ * checked on 2.1.282): a steer written during a tool call is echoed right
+ * after that tool's result, one written during the turn's last model call
+ * only after the turn's `result`, as its own turn starts. That tells a folded
+ * steer from one that runs next. Below it, every steer holds its turn's
+ * result for the grace. */
+export const CLAUDE_REPLAY_FLOOR = [2, 1, 282];
 /** `claude --version` prints "2.1.232 (Claude Code)"; the first dotted triple
  * is the version. Null when nothing parses, e.g. a wrapper that prints its
  * own banner first — see claudeCliSupports for how that is treated. */
@@ -320,6 +347,7 @@ export function claudeCliUpdate(version, cli) {
     };
 }
 const DRIVER_KIND = "claudeAgent";
+const NO_ANTHROPIC_KEY = "No Anthropic API key — open Settings → API keys.";
 // model catalog ported from upstream packages/contracts/src/model.ts
 export const STATIC_CLAUDE_MODELS = {
     default: "claude-sonnet-5",
@@ -328,11 +356,14 @@ export const STATIC_CLAUDE_MODELS = {
         { id: "claude-fable-5", label: "Claude Fable 5" },
         { id: "claude-opus-5-5", label: "Claude Opus 5.5", contextWindow: 1_000_000 },
         { id: "claude-opus-5", label: "Claude Opus 5" },
+        { id: "claude-sonnet-5-5", label: "Claude Sonnet 5.5", contextWindow: 1_000_000 },
         { id: "claude-sonnet-5", label: "Claude Sonnet 5" },
         { id: "claude-haiku-4-5", label: "Claude Haiku 4.5" },
     ],
 };
 const CLAUDE_MODEL_ID = /^[a-z0-9][a-z0-9._:/-]*$/i;
+/** Official Anthropic model ids, e.g. claude-sonnet-5-5 (no host:: inject prefix). */
+const OFFICIAL_CLAUDE_ID = /^claude-[a-z0-9.-]+$/;
 /** Rewrite a leftover API slug (`orcarouter/Qwen…`) to `host::model` when a
  *  local host is serving it, so the turn injects instead of asking for /login.
  *  Official cloud ids and already-encoded inject ids skip the probe. */
@@ -359,7 +390,7 @@ function extrasFromUnknown(value) {
         return [{ id, label: label || id }];
     });
 }
-/** Extra ids from ~/.claude/settings.json. Official cloud rows stay untagged.
+/** Extra ids from ~/.claude/settings.json. Official extraModels stay untagged.
  *  `model` is Claude Code's last-used slug, not a catalog — listing it as
  *  Custom put a non-inject id in the picker and the turn then had no
  *  ANTHROPIC_API_KEY ("Not logged in · Please run /login"). Live injects
@@ -376,21 +407,25 @@ export function readClaudeModelCatalog(env = process.env) {
         settings = {};
     }
     const extras = [
-        ...extrasFromUnknown(settings.availableModels),
-        ...extrasFromUnknown(settings.customModels),
-        ...extrasFromUnknown(settings.extraModels),
+        ...extrasFromUnknown(settings.availableModels).map((extra) => ({ ...extra, custom: true })),
+        ...extrasFromUnknown(settings.customModels).map((extra) => ({ ...extra, custom: true })),
+        ...extrasFromUnknown(settings.extraModels).map((extra) => ({ ...extra, custom: !OFFICIAL_CLAUDE_ID.test(extra.id) })),
     ];
     const nestedEnv = settings.env && typeof settings.env === "object" ? settings.env : {};
     const envModel = nestedEnv.ANTHROPIC_MODEL ?? env.ANTHROPIC_MODEL;
     if (typeof envModel === "string")
-        extras.push(...extrasFromUnknown([envModel]));
+        extras.push(...extrasFromUnknown([envModel]).map((extra) => ({ ...extra, custom: true })));
     const options = STATIC_CLAUDE_MODELS.options.map((option) => ({ ...option }));
     const seen = new Set(options.map((option) => option.id));
     for (const extra of extras) {
         if (seen.has(extra.id))
             continue;
         seen.add(extra.id);
-        options.push({ id: extra.id, label: extra.label, custom: true });
+        // Only extraModels adds official cloud rows. An explicit endpoint model
+        // override stays custom even when its id also appears in that list.
+        options.push(extra.custom || extra.id === envModel
+            ? { id: extra.id, label: extra.label, custom: true }
+            : { id: extra.id, label: extra.label });
     }
     return { default: STATIC_CLAUDE_MODELS.default, options };
 }
@@ -438,6 +473,51 @@ function askSummary(ask) {
         return askQuestionSummary(questions);
     return askInputSummary(ask.input) ?? ask.tool ?? "tool";
 }
+/** A logical turn made of several native turns: any failed half fails it,
+ * the last stop reason stands, per-turn token usage adds up, and the cost is
+ * the latest figure — the CLI reports total_cost_usd as the process's running
+ * total ("cumulative across turns in streaming-input sessions … read the
+ * latest result rather than summing", 2.1.282), so adding would double-bill.
+ * A figure missing on one side leaves the other side's alone. */
+export function sumNativeTurnResults(earlier, latest) {
+    if (!earlier)
+        return latest;
+    const usage = earlier.usage && latest.usage
+        ? {
+            input: earlier.usage.input + latest.usage.input,
+            output: earlier.usage.output + latest.usage.output,
+            ...(earlier.usage.cachedInput !== undefined || latest.usage.cachedInput !== undefined
+                ? { cachedInput: (earlier.usage.cachedInput ?? 0) + (latest.usage.cachedInput ?? 0) }
+                : {}),
+        }
+        : latest.usage ?? earlier.usage;
+    return {
+        ok: earlier.ok && latest.ok,
+        stopReason: latest.stopReason ?? earlier.stopReason,
+        cost: latest.cost ?? earlier.cost,
+        ...(usage ? { usage } : {}),
+    };
+}
+/** How long after a native `result` the CLI gets to announce, with `init`,
+ * the turn it starts for a user message steered in after this turn's last
+ * model call. The message is already buffered on its stdin, so this takes
+ * milliseconds (about 60 ms on 2.1.282). If nothing comes, the message was
+ * folded into one of this turn's model calls after all, and the held result
+ * is the turn's: every result with a steer outstanding waits this long. */
+export const STEERED_CONTINUATION_GRACE_MS = 2_000;
+/** How long a steered continuation may stay silent after its `init` before
+ * the driver stops waiting and closes the turn on the held result. 2.1.282
+ * follows `init` with a `status` frame within milliseconds and every CLI
+ * streams once the model answers; a continuation that never speaks would
+ * otherwise keep the turn — and its internal tool pass — open until the
+ * stall watchdog. */
+export const STEERED_CONTINUATION_SILENCE_MS = 30_000;
+/** Tests scale each steer timer on its own, the way FAKE_CLAUDE_RETRY_SCALE
+ * scales the retry backoff — a test that shortens the silence bound must not
+ * also shorten the grace `init` has to arrive in. Production runs at 1. */
+const fakeTimerScale = (name) => Number(process.env[name] ?? "1") || 1;
+const steerGraceScale = () => fakeTimerScale("FAKE_CLAUDE_STEER_GRACE_SCALE");
+const steerSilenceScale = () => fakeTimerScale("FAKE_CLAUDE_STEER_SILENCE_SCALE");
 /** Where the hook helper reads this thread's current turn token. Stable per
  * thread (so the CLI's environment can name it once) and private. */
 export function hookTokenFile(threadId, botId) {
@@ -739,6 +819,7 @@ function decodeConfig(raw) {
         permissionMode: mode ?? "acceptEdits",
         ...(tools !== undefined ? { tools } : {}),
         ...(disallowedTools !== undefined ? { disallowedTools } : {}),
+        ...(o.requireApiKey === true ? { requireApiKey: true } : {}),
     };
 }
 function firstText(content) {
@@ -1041,6 +1122,8 @@ export const ClaudeDriver = {
         const sendTurn = async (turn, logicalTurnId) => {
             if (config.managedModels && (!turn.model || !config.managedModels.includes(turn.model)))
                 throw new Error("This model is not assigned to this workspace.");
+            if (config.requireApiKey && !input.environment.ANTHROPIC_API_KEY)
+                throw new Error(NO_ANTHROPIC_KEY);
             if (config.managed && (!turn.model || turn.model.includes("::") || !config.configDir ||
                 !input.environment.ANTHROPIC_API_KEY || !input.environment.ANTHROPIC_BASE_URL)) {
                 throw new Error("Company model access is unavailable. Reconnect your organization; personal billing will not be used.");
@@ -1097,19 +1180,34 @@ export const ClaudeDriver = {
                 "--include-partial-messages",
                 "--permission-mode", permissionMode,
             ];
-            if (config.tools !== undefined)
+            // A guest's turn: no command-running tool at all, and no read outside
+            // its own folder (GUEST_CLAUDE_TOOLS). It only ever runs in Ask.
+            if (turn.guestConfined && permissionMode !== "default") {
+                throw new Error("A guest's turn on this Cloud runs only in Ask.");
+            }
+            if (turn.guestConfined)
+                args.push("--restricted", "--tools", GUEST_CLAUDE_TOOLS.join(","));
+            else if (config.tools !== undefined)
                 args.push("--tools", config.tools.join(","));
             if (config.disallowedTools?.length) {
                 args.push("--disallowedTools", config.disallowedTools.join(","));
             }
             const turnEnvironment = environment();
-            if (turn.refreshSystemPrompt && !cliVersionChecked) {
+            if ((turn.refreshSystemPrompt || turn.guestConfined) && !cliVersionChecked) {
                 const version = await readCliVersion(turnEnvironment);
                 if (version) {
                     cliVersion = parseClaudeCliVersion(version);
                     cliVersionChecked = true;
                 }
             }
+            if (turn.guestConfined && !claudeCliSupports(cliVersion, "--restricted")) {
+                throw new Error(withWhy("This Claude Code is too old to run this turn without a shell. Update Claude Code.", turn.confinedWhy));
+            }
+            // Each stdin message echoed as a model call takes it in: how a turn
+            // tells a folded steer from one that runs next (CLAUDE_REPLAY_FLOOR).
+            const replaysUserMessages = cliVersion === null || versionAtLeast(cliVersion, CLAUDE_REPLAY_FLOOR);
+            if (replaysUserMessages)
+                args.push("--replay-user-messages");
             const isolated = !inheritsUserConfig(turnEnvironment);
             if (isolated) {
                 // A bot gets the tools and instructions its owner gave it, not
@@ -1227,7 +1325,9 @@ export const ClaudeDriver = {
             // of MCP servers, so a server the bot's OWN project declares would
             // otherwise vanish with the machine's. Merge it last: a project file
             // can add servers but never shadow a harness-owned mount.
-            if (isolated && turn.cwd) {
+            // Never for a guest's turn: its folder is its own to write, and a
+            // server declared there would run a command.
+            if (isolated && turn.cwd && !turn.guestConfined) {
                 for (const [name, server] of Object.entries(projectMcpServers(turn.cwd))) {
                     if (Object.hasOwn(mcpServers, name))
                         continue;
@@ -1257,6 +1357,10 @@ export const ClaudeDriver = {
             }
             mcpServers.ogb = { command: process.execPath, args: [PERM_PROXY_PATH, socketPath], env: { ...NODE_ENV_FLAG }, alwaysLoad: true };
             allowed.push("mcp__ogb");
+            // A guest's turn pre-allows only the harness's own tools: anything
+            // else (the browser can open a file: address) asks the owner first.
+            if (turn.guestConfined)
+                allowed.splice(0, allowed.length, ...allowed.filter((name) => name === "mcp__ogb" || name === "mcp__agents"));
             // The MCP config carries credentials — a Composio consumer key in a
             // header, the boat token in the computer proxy's env, the comms token in
             // the agents proxy's env. On argv every one of those is world-readable
@@ -1293,6 +1397,8 @@ export const ClaudeDriver = {
             const settings = { ...authSettings };
             if (hooks)
                 settings.hooks = claudeHookSettings(HOOK_HELPER_PATH);
+            if (turn.guestConfined)
+                settings.permissions = GUEST_CLAUDE_PERMISSIONS;
             const authSettingsPath = mcpConfigPath && Object.keys(settings).length
                 ? join(dirname(mcpConfigPath), "auth-settings.json") : null;
             if (authSettingsPath)
@@ -1332,7 +1438,7 @@ export const ClaudeDriver = {
             if (!turn.sessionReset && live && !live.turn && !live.closing && live.child.exitCode === null && live.argsKey === argsKey && (!sessionId || sessionId === live.sessionId)) {
                 if (live.idleTimer)
                     clearTimeout(live.idleTimer);
-                live.turn = { turnId, input: turn, retryAbort, settled: false, sawStreamDelta: false };
+                live.turn = { turnId, input: turn, retryAbort, settled: false, sawStreamDelta: false, pendingSteers: new Set(), deferred: null, continuationGrace: null, continuationSilence: null };
                 active.set(threadId, { stop: () => {
                         if (live.turn)
                             live.turn.stopRequested = true;
@@ -1513,7 +1619,8 @@ export const ClaudeDriver = {
                 sessionId: sessionId ?? newSessionId,
                 sawInit: false,
                 nativePermissionMode: null,
-                turn: { turnId, input: turn, retryAbort, settled: false, sawStreamDelta: false },
+                replaysUserMessages,
+                turn: { turnId, input: turn, retryAbort, settled: false, sawStreamDelta: false, pendingSteers: new Set(), deferred: null, continuationGrace: null, continuationSilence: null },
                 idleTimer: null,
                 closing: false,
                 stderr: "",
@@ -1527,6 +1634,14 @@ export const ClaudeDriver = {
                 if (!t || t.settled)
                     return;
                 t.settled = true;
+                if (t.continuationGrace) {
+                    clearTimeout(t.continuationGrace);
+                    t.continuationGrace = null;
+                }
+                if (t.continuationSilence) {
+                    clearTimeout(t.continuationSilence);
+                    t.continuationSilence = null;
+                }
                 // Resolve any ask still open for this turn, but keep the broker
                 // listening for the next turn on the retained process. Between turns
                 // isActive() rejects late background asks without creating cards.
@@ -1563,6 +1678,7 @@ export const ClaudeDriver = {
                 if (session.child.exitCode === null && !session.closing)
                     armIdle(threadId);
             };
+            const settleResult = (result) => settle(result.ok, result.stopReason, result.cost, result.usage);
             const currentTurnId = () => session.turn?.turnId ?? turnId;
             // The process's first result with a cost says what --resume restored,
             // which its turns are measured from; every result is kept for a later
@@ -1589,14 +1705,58 @@ export const ClaudeDriver = {
                 catch {
                     return;
                 }
-                appendNative(threadId, { dir: "in", source: "claude.sdk.message", msg: o });
+                // A stdin message echoed back (--replay-user-messages) carries its
+                // images again: keep their bytes out of the log, as when it was sent.
+                appendNative(threadId, { dir: "in", source: "claude.sdk.message", msg: o?.type === "user" && o.isReplay === true && o.message ? diagnosticClaudeUserMessage(o) : o });
+                // The continuation a held result waits for has spoken: any frame
+                // after its `init` — status, thinking, text, its own result. The
+                // echo of its own message is not speech: it comes before the call.
+                if (session.turn?.continuationSilence && !(o.type === "system" && o.subtype === "init") && !(o.type === "user" && o.isReplay === true)) {
+                    clearTimeout(session.turn.continuationSilence);
+                    session.turn.continuationSilence = null;
+                }
                 switch (o.type) {
                     case "system":
                         if (o.subtype === "init") {
+                            // A guest's session proves its tool set before it does anything:
+                            // a CLI that kept a command-running tool is stopped here.
+                            const tools = Array.isArray(o.tools) ? o.tools : [];
+                            if (session.turn?.input.guestConfined && (o.permissionMode !== "default" || tools.some((tool) => typeof tool === "string" && GUEST_FORBIDDEN_TOOLS.has(tool)))) {
+                                emit({ ...base(threadId, currentTurnId()), type: "runtime.error", message: withWhy("This Claude Code kept its shell, so it can't run this turn. Update Claude Code.", session.turn?.input.confinedWhy) });
+                                session.closing = true;
+                                stopSession(session);
+                                break;
+                            }
                             session.sawInit = true;
                             session.nativePermissionMode = typeof o.permissionMode === "string" ? o.permissionMode : null;
                             if (typeof o.session_id === "string")
                                 session.sessionId = o.session_id;
+                            // The turn the CLI starts for a steered message it could not
+                            // fold (see `result`): the held result now waits for this one's
+                            // — bounded, so a continuation that announces itself and then
+                            // never speaks cannot keep the turn's pass open indefinitely.
+                            const held = session.turn;
+                            if (held?.continuationGrace) {
+                                clearTimeout(held.continuationGrace);
+                                held.continuationGrace = null;
+                                if (held.continuationSilence)
+                                    clearTimeout(held.continuationSilence);
+                                held.continuationSilence = setTimeout(() => {
+                                    if (session.turn !== held || held.settled || !held.deferred)
+                                        return;
+                                    // A Stop or a close settles the turn in finalizeClose.
+                                    if (held.stopRequested || session.closing)
+                                        return;
+                                    held.continuationSilence = null;
+                                    emit({
+                                        ...base(threadId, held.turnId),
+                                        type: "runtime.error",
+                                        message: "Claude began a steered message but went silent; the turn was closed.",
+                                    });
+                                    settleResult(held.deferred);
+                                }, STEERED_CONTINUATION_SILENCE_MS * steerSilenceScale());
+                                held.continuationSilence.unref?.();
+                            }
                             emit({ ...base(threadId, currentTurnId()), type: "session.started", sessionId: o.session_id, model: o.model, ...(retry.rebuilt ? { rebuilt: true } : {}) });
                         }
                         else if (o.subtype === "thinking_tokens") {
@@ -1683,7 +1843,14 @@ export const ClaudeDriver = {
                         }
                         break;
                     }
-                    case "user":
+                    case "user": {
+                        // --replay-user-messages: a model call took this stdin message in.
+                        // A steer echoed before its turn's `result` was folded into it.
+                        if (o.isReplay === true) {
+                            if (typeof o.uuid === "string")
+                                session.turn?.pendingSteers.delete(o.uuid);
+                            break;
+                        }
                         for (const b of Array.isArray(o.message?.content) ? o.message.content : []) {
                             if (b.type === "tool_result") {
                                 emit({ ...base(threadId, currentTurnId()), type: "item.completed", itemType: "tool", itemId: b.tool_use_id, ok: !b.is_error, output: toolDetailPreview(b.content) });
@@ -1693,7 +1860,8 @@ export const ClaudeDriver = {
                             }
                         }
                         break;
-                    case "result":
+                    }
+                    case "result": {
                         // A synthetic background completion is not the result of the
                         // submitted user turn. Settling it would revoke browser access
                         // and deny approvals while that user turn is still running.
@@ -1712,20 +1880,84 @@ export const ClaudeDriver = {
                             cacheWrite: o.usage?.cache_creation_input_tokens || 0,
                             output: o.usage?.output_tokens || 0,
                         });
-                        settle(o.is_error !== true, session.turn?.authFailed
-                            ? "auth_required"
-                            : session.turn?.updateRequired
-                                ? "update_required"
-                                : o.stop_reason ?? o.terminal_reason ?? null, o.total_cost_usd ?? null, o.usage
-                            ? {
-                                input: (o.usage.input_tokens || 0) + (o.usage.cache_read_input_tokens || 0) + (o.usage.cache_creation_input_tokens || 0),
-                                output: o.usage.output_tokens || 0,
-                                ...(typeof o.usage.cache_read_input_tokens === "number"
-                                    ? { cachedInput: o.usage.cache_read_input_tokens }
-                                    : {}),
-                            }
-                            : undefined);
+                        const native = {
+                            ok: o.is_error !== true,
+                            stopReason: session.turn?.authFailed
+                                ? "auth_required"
+                                : session.turn?.updateRequired
+                                    ? "update_required"
+                                    : o.stop_reason ?? o.terminal_reason ?? null,
+                            cost: o.total_cost_usd ?? null,
+                            ...(o.usage
+                                ? {
+                                    usage: {
+                                        input: (o.usage.input_tokens || 0) + (o.usage.cache_read_input_tokens || 0) + (o.usage.cache_creation_input_tokens || 0),
+                                        output: o.usage.output_tokens || 0,
+                                        ...(typeof o.usage.cache_read_input_tokens === "number"
+                                            ? { cachedInput: o.usage.cache_read_input_tokens }
+                                            : {}),
+                                    },
+                                }
+                                : {}),
+                        };
+                        const t = session.turn;
+                        // Does another user turn follow this result without more input?
+                        // The CLI says so itself when it can: queued_turn_count ("greater
+                        // than 0 means at least one more user turn (and result) follows",
+                        // 2.1.282) counts its command queue. A message steered in over
+                        // stdin is not in that queue when the result is written — the
+                        // incident's result said 0 and the CLI ran the message 58 ms later
+                        // — so 0, like an absent field, decides nothing; the steers the
+                        // driver has not seen taken in do. With --replay-user-messages the
+                        // CLI echoes a steer as a model call takes it in, so one still
+                        // pending here runs next. Without it (an older CLI), nothing says
+                        // whether a steer was folded in or runs next (the time a tool
+                        // result is read proves nothing about when stdin was taken), so
+                        // any steer holds the result: if no `init` follows within the
+                        // grace, it was folded, and the held result is the turn's. A steer
+                        // landing while a result is held extends the hold.
+                        const queuedTurns = typeof o.queued_turn_count === "number" ? o.queued_turn_count : 0;
+                        if (t && !t.settled && (queuedTurns > 0 || t.pendingSteers.size > 0)) {
+                            // The CLI runs the queued message next, in this process, with
+                            // this turn's tools, and the harness recorded it as part of this
+                            // turn. A `turn.completed` now would revoke the turn's
+                            // capabilities under that continuation (its internal tools would
+                            // answer 401) and show the bot idle while it works. Hold this
+                            // result until the continuation's own arrives.
+                            // Echoed steers leave the set as their turn takes them in;
+                            // without the echo, this hold answers for every steer so far.
+                            if (!session.replaysUserMessages)
+                                t.pendingSteers.clear();
+                            t.deferred = sumNativeTurnResults(t.deferred, native);
+                            t.armGrace = () => {
+                                if (t.continuationGrace)
+                                    clearTimeout(t.continuationGrace);
+                                t.continuationGrace = setTimeout(() => {
+                                    // No `init` came: the message was folded into the call that
+                                    // just finished after all (or a queued send was cancelled),
+                                    // and the held result is the turn's.
+                                    if (session.turn !== t || t.settled)
+                                        return;
+                                    // A Stop or a close settles the turn in finalizeClose: as
+                                    // interrupted after a Stop, else on the held result, which
+                                    // the grace still being set tells it the turn owns. (taskkill
+                                    // is asynchronous on Windows, so the CLI can outlive a Stop
+                                    // by longer than this grace.)
+                                    if (t.stopRequested || session.closing)
+                                        return;
+                                    t.continuationGrace = null;
+                                    if (t.deferred)
+                                        settleResult(t.deferred);
+                                }, STEERED_CONTINUATION_GRACE_MS * steerGraceScale());
+                                t.continuationGrace.unref?.();
+                            };
+                            t.armGrace();
+                            appendNative(threadId, { dir: "out", source: "claude.session", msg: { hold: `result: a steered message is still queued (queued_turn_count ${o.queued_turn_count ?? "absent"})` } });
+                            break;
+                        }
+                        settleResult(sumNativeTurnResults(t?.deferred ?? null, native));
                         break;
+                    }
                 }
             };
             let buf = "";
@@ -1773,6 +2005,24 @@ export const ClaudeDriver = {
                 if (session.turn?.stopRequested && !session.turn.settled) {
                     settle(false, "interrupted");
                 }
+                else if (session.turn?.deferred && !session.turn.settled) {
+                    // The prompt was answered — a native result is held for a steered
+                    // continuation — and the process went away. Never relaunch: the
+                    // prompt already ran. Before the continuation announced itself the
+                    // held result is the turn's; once it had begun, its words are lost.
+                    const held = session.turn.deferred;
+                    if (session.turn.continuationGrace) {
+                        settleResult(held);
+                    }
+                    else {
+                        emit({
+                            ...base(threadId, currentTurnId()),
+                            type: "runtime.error",
+                            message: `claude exited ${code} before result${session.stderr ? `: ${session.stderr.trim().slice(-300)}` : ""}`,
+                        });
+                        settleResult({ ...held, ok: false, stopReason: "exit_before_result" });
+                    }
+                }
                 else if (session.turn && !session.turn.settled) {
                     // A retained process may be running a later user turn. Its close
                     // handler must retry that request, not the process's first prompt.
@@ -1979,13 +2229,29 @@ export const ClaudeDriver = {
             return { turnId };
         };
         /** A user message into the running turn: the CLI delivers it before its
-         * next model call. "refused" when nothing is running here to steer or
-         * the stdin write provably failed; the caller queues those words. */
+         * next model call, or — when no call is left in this turn — as its next
+         * native turn, which this driver keeps inside the same logical turn.
+         * "refused" when nothing is running here to steer or the stdin write
+         * provably failed; the caller queues those words. */
         const steer = async (threadId, text) => {
             const s = sessions.get(threadId);
             if (!s || !s.turn || s.turn.settled || s.closing || s.child.exitCode !== null)
                 return "refused";
-            return (await writeUser(s, threadId, claudeUserMessage(text, undefined))) ? "steered" : "refused";
+            const turn = s.turn;
+            // Counted before the write: a `result` read while the words are still
+            // on their way must hold for them too. A failed write takes it back.
+            // The uuid is what the CLI's echo names when a model call takes it in.
+            const id = randomUUID();
+            turn.pendingSteers.add(id);
+            if (!(await writeUser(s, threadId, { ...claudeUserMessage(text, undefined), uuid: id }))) {
+                turn.pendingSteers.delete(id);
+                return "refused";
+            }
+            // Written while a held result waits for a continuation's `init`: these
+            // words get the whole grace to be announced too.
+            if (!turn.settled && turn.continuationGrace)
+                turn.armGrace?.();
+            return "steered";
         };
         // Sign in from Settings: the unmodified CLI's own login, driven over pipes
         // (server/drivers/claude-login-auth.ts). Same environment as every turn.
@@ -1997,12 +2263,18 @@ export const ClaudeDriver = {
                 return { state: "unavailable", reason: `\`${config.cli}\` CLI not found` };
             cliVersion = parseClaudeCliVersion(version);
             cliVersionChecked = true;
+            const update = claudeCliUpdate(version, config.cli);
+            const warning = claudeInheritWarning(env);
+            if (config.requireApiKey) {
+                // Never falls back to a login: without the key it is not set up.
+                if (!input.environment.ANTHROPIC_API_KEY)
+                    return { state: "unavailable", version, reason: NO_ANTHROPIC_KEY };
+                return { state: "available", version, authenticated: true, account: { method: "api-key" }, ...(update ? { update } : {}), ...(warning ? { warning } : {}), billing: "metered" };
+            }
             const auth = await claudeAuthStatus(config.cli, env);
             // claudeEnvironment strips ANTHROPIC_API_KEY, so turns run on the
             // CLI's own login (Pro/Max): the cost it reports is what the call
             // WOULD bill, not a charge
-            const update = claudeCliUpdate(version, config.cli);
-            const warning = claudeInheritWarning(env);
             return { state: "available", version, ...auth, ...(update ? { update } : {}), ...(warning ? { warning } : {}), billing: "subscription" };
         };
         /** One-shot Claude call with the prompt on stdin, never argv. Approval
@@ -2010,6 +2282,10 @@ export const ClaudeDriver = {
          * `claude -p "prompt"` shape is not safe for review. No tools or MCP
          * servers are mounted in this isolated process. */
         const generateReview = (prompt, signal, onUsage) => new Promise((resolve, reject) => {
+            if (config.requireApiKey && !input.environment.ANTHROPIC_API_KEY) {
+                reject(new Error(NO_ANTHROPIC_KEY));
+                return;
+            }
             const model = config.managedModels?.[0] ?? "claude-haiku-4-5";
             const child = spawnCli(config.cli, ["-p", "--model", model, "--output-format", onUsage ? "json" : "text"], {
                 stdio: ["pipe", "pipe", "pipe"],
@@ -2114,6 +2390,9 @@ export const ClaudeDriver = {
                 provider: DRIVER_KIND,
                 capabilities: {
                     sessionModelSwitch: "in-session",
+                    // A guest's turn runs with no command-running tool and no read
+                    // outside its folder (guestConfined, GUEST_CLAUDE_TOOLS).
+                    guestTurns: "confined",
                     agentsMcp: true,
                     customMcp: true,
                     computerMcp: true,