tumwater 0.2.0 → 0.4.0

package/dist/src/agent/claude/claude-args.js

@@ -1,5 +1,4 @@
-// vocabulary: plain
-/** Building the claude command line for one tick (plans/agent-backends.md "The claude
+/** Building the claude command line for one run (plans/agent-backends.md "The claude
  * invocation") — pure argv construction plus the prompt-on-stdin pairing, with no subprocess,
  * backend registration, or session ledger. Part 3c supplies the session decision (which
  * `--session-id` or `--resume` to pass); this module turns those inputs into the invocation's
@@ -17,13 +16,14 @@
 import fs from "node:fs";
 import path from "node:path";
 import { appendPassthroughArgs } from "../agent-args.js";
+import { writeGuardSettings } from "./claude-write-guard.js";
 /** Flags the harness passes itself. A passthrough arg equal to one of these is appended AFTER
  * the harness's own copy, and claude's argument parser is last-wins — so it would silently
  * override the isolation flags, the session choice, or the model the harness resolved. Each is
  * rejected by claudeArgs with the offending arg named. This is exactly the design's reserved
- * set (plans/agent-backends.md "Config"); config validation (config-validation.ts) mirrors this
- * set for `backends.claude.args`, so a value that passes validation is never accepted by
- * validation and then thrown here. */
+ * set (plans/agent-backends.md "Config"); config validation (config-validation-agents.ts)
+ * mirrors this set for `backends.claude.args`, so a value that passes validation is never
+ * accepted by validation and then thrown here. */
 export const HARNESS_CLAUDE_FLAGS = new Set([
     "-p",
     "--print",
@@ -39,6 +39,7 @@ export const HARNESS_CLAUDE_FLAGS = new Set([
     "--permission-mode",
     "--tools",
     "--setting-sources",
+    "--settings",
     "--strict-mcp-config",
     "--mcp-config",
     "--disable-slash-commands",
@@ -89,7 +90,9 @@ export function claudeArgs(opts) {
         args.push("--session-id", opts.sessionId);
     else
         args.push("--resume", opts.resumeSessionId);
-    args.push("--permission-mode", "bypassPermissions", "--tools", "Bash,Read,Edit,Write,Glob,Grep", "--setting-sources", "project", "--strict-mcp-config");
+    args.push("--permission-mode", "bypassPermissions", "--tools", "Bash,Read,Edit,Write,Glob,Grep", "--setting-sources", "project", 
+    // The write guard's PreToolUse hook (claude-write-guard.ts).
+    "--settings", writeGuardSettings(opts.cwd), "--strict-mcp-config");
     args.push("--disable-slash-commands", "--exclude-dynamic-system-prompt-sections");
     if (shouldAppendAgents(opts.cwd))
         args.push("--append-system-prompt-file", "AGENTS.md");

package/dist/src/agent/claude/claude-backend.js

@@ -17,11 +17,11 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
-import { resolvedAgentConfig } from "../../config/config-views.js";
+import { resolvedBackendConfig } from "../../config/config-views.js";
 import { MODEL_TIERS } from "../../config/config-schema.js";
 import { routeModel } from "../../config/model-selector.js";
-import { agentBaseEnv, withNotesPath } from "../../process/run-marker.js";
-import { resolveBackendBin } from "../../pi/pi-bin.js";
+import { backendRunEnv } from "../../process/run-marker.js";
+import { resolveBinForBackend } from "../../pi/pi-bin.js";
 import { expandHomeTilde } from "../../files/files.js";
 import { claudeArgs } from "./claude-args.js";
 import { claudeEnv, claudeThirdPartyProvider } from "./claude-env.js";
@@ -58,7 +58,7 @@ export function claudeTranscriptPath(cwd, id, env = process.env, homeDir = os.ho
 /** The CLI version every gated claude model needs (plans/agent-backends.md finding 9): on
  * 2.1.216 Opus 5.5 is refused outright and Haiku 5.5 is mispriced about 250×, and team runs
  * set DISABLE_AUTOUPDATER so they never update themselves. The gated models are the three
- * tier defaults, derived from AGENT_DEFAULT_MODELS through the same routing the config uses
+ * tier defaults, derived from BACKEND_DEFAULT_MODELS through the same routing the config uses
  * rather than listed again, so this table cannot drift from the models a seam resolves. */
 const CLAUDE_MIN_VERSION = "2.1.280";
 const CLAUDE_GATED_MODELS = new Set(MODEL_TIERS.map((tier) => routeModel(undefined, undefined, "claude", tier).model).filter((model) => model !== undefined));
@@ -114,7 +114,7 @@ export const claudeBackend = {
     binEnv: "TUMWATER_CLAUDE_BIN",
     minVersion: claudeMinVersion,
     resolveBin(config) {
-        return resolveBackendBin(config, this);
+        return resolveBinForBackend(config, this);
     },
     invocation(run) {
         // Part 4b/7's config routing fills a claude tier default before the seam, so a nameless
@@ -124,7 +124,7 @@ export const claudeBackend = {
         }
         // The configured team config dir (plans/notes-command.md "Keeping funes out of team runs"):
         // the run's env, its resume lookup, and the account seed all follow it; unset, nothing changes.
-        const claudeCfg = resolvedAgentConfig(run.config, "claude");
+        const claudeCfg = resolvedBackendConfig(run.config, "claude");
         const configDir = claudeCfg.configDir;
         const expandedConfigDir = configDir !== undefined ? claudeConfigDir(process.env, os.homedir(), configDir) : undefined;
         const { sessionId, resumeSessionId } = resolveClaudeSession(run, configDir);
@@ -134,7 +134,7 @@ export const claudeBackend = {
             thinking: run.config.thinking,
             ...(resumeSessionId !== undefined ? { resumeSessionId } : { sessionId }),
             // The operator's `backends.claude.args` passthrough, appended after the harness flags (the
-            // builder rejects any entry that repeats a harness-managed flag). resolvedAgentConfig
+            // builder rejects any entry that repeats a harness-managed flag). resolvedBackendConfig
             // owns the view so a caller cannot mutate the loaded config through the returned array.
             args: claudeCfg.args,
             prompt: run.prompt,
@@ -142,12 +142,12 @@ export const claudeBackend = {
             // adapter forwards it; a subscription run or the director passes none (part 7a/7).
             ...(run.maxBudgetUsd !== undefined ? { maxBudgetUsd: run.maxBudgetUsd } : {}),
         });
-        // agentBaseEnv applies the run marker and the macOS preload (shared with the pi adapter);
-        // claudeEnv layers the backend's own scrub-and-set on top. The notebook path rides beside
+        // backendBaseEnv applies the run marker and the macOS preload (shared with the pi adapter);
+        // claudeEnv layers the backend's own scrub-and-set on top. The notes path rides beside
         // the marker the same way pi's adapter carries it (withNotesPath); from part 2/4 the run
         // saves its note through the `tumwater-notes` command on PATH, so no MCP server reaches the
         // run and `--strict-mcp-config` (always in claude-args.ts) keeps it that way.
-        const base = withNotesPath(agentBaseEnv(run.runMarker, undefined, run.binDir), run.notesPath);
+        const base = backendRunEnv(run);
         const env = claudeEnv(base, {
             quietTimeoutSeconds: run.config.quietTimeoutSeconds,
             ...(expandedConfigDir !== undefined ? { configDir: expandedConfigDir } : {}),

package/dist/src/agent/claude/claude-env.js

@@ -1,7 +1,7 @@
 /** Building the environment for one claude run (plans/agent-backends.md "The claude
  * invocation", "Findings" 2 and 4) — pure scrub-and-set over a base environment, with no
  * subprocess. The caller layers the run-marker, the macOS LaunchServices preload, and the
- * notebook on first (src/process/run-marker.ts's `withNotesPath`), then hands the result here.
+ * notes on first (src/process/run-marker.ts's `withNotesPath`), then hands the result here.
  *
  * Inherited Claude Code session variables break auth: spawned from inside a Claude Code
  * session, a child that keeps `CLAUDECODE`, `CLAUDE_CODE_*`, `CLAUDE_AGENT_SDK_*` or the host's

package/dist/src/agent/claude/claude-stream.js

@@ -14,6 +14,8 @@
  * on the seam's optional `warnings()` — src/agent/run-agent.ts forwards each as an
  * `agent_unknown_event` warning after the run. `cost_unknown` is recorded the same way when a
  * run produced no authoritative `run_cost`. */
+import { joinParts } from "../../text/text.js";
+import { secondsUntil } from "../../text/datetime.js";
 import { canonicalUsageBlock, isJsonObject, objectOrEmpty, nonNegativeNumber, parseJsonObject } from "../../files/json-object.js";
 /** claude's tool names → the canonical pi names the readers already know. Glob/Grep are kept
  * lower-cased; MultiEdit collapses onto edit (pi has one edit tool). Anything else is
@@ -86,7 +88,7 @@ function classifyResult(result) {
         return {};
     if (terminal === "error_max_budget_usd")
         return { kind: "budgetCapped" };
-    const text = [str(result.result), str(result.error)].filter(Boolean).join(" ");
+    const text = joinParts([str(result.result), str(result.error)], " ");
     if (/error_max_budget_usd/i.test(text))
         return { kind: "budgetCapped" };
     const status = nonNegativeNumber(result.api_error_status, undefined);
@@ -193,7 +195,7 @@ export function claudeTranslator(opts = {}) {
                     const maxAttempts = nonNegativeNumber(event.max_retries, undefined);
                     const status = nonNegativeNumber(event.error_status, undefined);
                     const error = str(event.error) ?? "";
-                    const errorMessage = [status !== undefined ? `status ${status}` : "", error].filter(Boolean).join(": ");
+                    const errorMessage = joinParts([status !== undefined ? `status ${status}` : "", error], ": ");
                     return [
                         JSON.stringify({
                             type: "auto_retry_start",
@@ -294,8 +296,8 @@ export function claudeTranslator(opts = {}) {
                 if (info.isUsingOverage === true)
                     out.isUsingOverage = true;
                 if (status === "rejected" && resetsAt !== undefined) {
-                    // resetsAt is a unix-seconds stamp; retryAfterSeconds is the wait the loop honors.
-                    out.retryAfterSeconds = Math.max(0, Math.round(resetsAt - Date.now() / 1000));
+                    // resetsAt is a unix-seconds stamp; secondsUntil folds it (×1000) to whole seconds.
+                    out.retryAfterSeconds = secondsUntil(resetsAt * 1000, Date.now());
                 }
                 return [JSON.stringify(out), ...windows];
             }

package/dist/src/agent/claude/claude-write-guard.js

@@ -0,0 +1,49 @@
+/** claude's half of the write guard (src/agent/write-guard.ts holds the rule): a PreToolUse hook on
+ * the file-writing tools, passed to each run through `--settings`, refuses a write under the team
+ * root but outside the run's worktree.
+ *
+ * Hooks run under `--permission-mode bypassPermissions` too, and a hook's `deny` decision blocks
+ * the call and hands its reason to the model (checked live with claude 2.1.295 on 2026-10-23).
+ * `--setting-sources project` leaves the operator's own hooks out of a run, while `--settings`
+ * still loads this one. The hook gets the run's worktree as an argument rather than reading
+ * claude's `cwd`, which follows the Bash tool's `cd` into subdirectories. The entry point is
+ * write-guard-hook.ts beside this file. */
+import { fileURLToPath } from "node:url";
+import { shellQuote, strayWriteRefusal } from "../write-guard.js";
+/** claude's file-writing tools a team run has: claude-args.ts's `--tools` allows only these two,
+ * and `--tools` is a reserved flag, so no passthrough can add another. */
+const WRITE_TOOLS = ["Edit", "Write"];
+/** Seconds claude waits for the hook before running the tool anyway. */
+const HOOK_TIMEOUT_SECONDS = 30;
+/** The `--settings` value for a run in `cwd`: one PreToolUse hook on the file-writing tools that
+ * runs the compiled write-guard-hook.js with this process's node, falling back to `node` on PATH
+ * when that binary has moved (as the notes shim does), and the run's worktree as its argument. The
+ * hook path resolves from this module, so a staged build (.tumwater/build/<sha>) runs its own
+ * copy. */
+export function writeGuardSettings(cwd, nodeBin = process.execPath) {
+    const hook = fileURLToPath(new URL("./write-guard-hook.js", import.meta.url));
+    const command = `n=${shellQuote(nodeBin)}; [ -x "$n" ] || n=node; exec "$n" ${shellQuote(hook)} ${shellQuote(cwd)}`;
+    return JSON.stringify({
+        hooks: {
+            PreToolUse: [
+                { matcher: WRITE_TOOLS.join("|"), hooks: [{ type: "command", command, timeout: HOOK_TIMEOUT_SECONDS }] },
+            ],
+        },
+    });
+}
+/** The refusal for one PreToolUse payload (claude's hook stdin, parsed) from a run in `runDir`, or
+ * null to let the call run. A relative path resolves from the payload's `cwd`, where claude's
+ * tools would resolve it. */
+export function claudeWriteRefusal(payload, runDir) {
+    if (typeof payload !== "object" || payload === null)
+        return null;
+    const { tool_name: tool, tool_input: input, cwd } = payload;
+    if (typeof tool !== "string" || !WRITE_TOOLS.includes(tool))
+        return null;
+    if (typeof input !== "object" || input === null)
+        return null;
+    const target = input.file_path;
+    if (typeof target !== "string" || target === "")
+        return null;
+    return strayWriteRefusal(target, runDir, typeof cwd === "string" && cwd !== "" ? cwd : runDir);
+}

package/dist/src/agent/claude/write-guard-hook.js

@@ -0,0 +1,13 @@
+/** The PreToolUse hook claude runs before each file write in a team run (claude-write-guard.ts
+ * installs it through `--settings`): `node write-guard-hook.js <worktree>` with claude's hook
+ * payload on stdin. To block the write it prints a `deny` decision with the refusal as its reason:
+ * the model reads only the reason, where a refusal by exit 2 would also quote the whole hook
+ * command. It prints nothing to let the write run. Any failure of its own lets the write run, so a
+ * broken hook cannot stop every edit of a run; the stray-write warning in runner-run.ts still sees
+ * a write that slips through. The stdin read and the deny-decision printing are runGuardHook's
+ * (src/agent/write-guard.ts), shared with the codex PreToolUse hook; only the refusal computation
+ * differs, and it needs the run's checkout, which this process receives as its first argument. */
+import { runGuardHook } from "../write-guard.js";
+import { claudeWriteRefusal } from "./claude-write-guard.js";
+const runDir = process.argv[2];
+runGuardHook((payload) => (runDir ? claudeWriteRefusal(payload, runDir) : null));

package/dist/src/agent/codex/codex-account.js

@@ -0,0 +1,119 @@
+/** The codex account state: the codex backend's subscription account (src/agent/
+ * subscription-account.ts) — which billing pays for codex runs, and the newest subscription
+ * usage-window reading each run reported (plans/codex-backend.md §7 "Spend, free-ness, window,
+ * images"). Persisted at `.tumwater/state/codex-account.json`, written only by the
+ * orchestrator process, so the sibling parts that throttle or display the subscription window
+ * read one answer instead of re-deriving it per surface.
+ *
+ * Everything here is a thin wrapper over the generic per-backend store
+ * (grounds/codex-backend.md "Groundwork: the subscription account is per backend", item 1),
+ * specialized to the backend id "codex", plus the codex-only seed (the `codex login status`
+ * probe that decides subscription vs API-key billing) that no other backend shares. A Codex
+ * run's billing and window readings reach the store through the generic observeAccount call
+ * the run finalizers make (run.agent === "codex"); the seed only fills the billing answer in
+ * before the first run so the budget gate and the API-key refusal can act on it. The file is a
+ * cache, never a source of truth: a run that reports billing overwrites it, and a missing or
+ * unreadable file reads as "no subscription". */
+import { spawnSync } from "node:child_process";
+import { resolvedBackendConfig } from "../../config/config-views.js";
+import { observeAccount, readAccount, writeAccount, } from "../subscription-account.js";
+import { codexBackend } from "./codex-backend.js";
+import { codexEnv } from "./codex-env.js";
+import { codexHome } from "./codex-catalog.js";
+/** Read the persisted codex account state, or null when it is absent or unreadable. A file
+ * without a usable top-level `observedAt` reads as absent (the plan's torn-file rule). */
+export function readCodexAccount(root, now = Date.now()) {
+    return readAccount(root, "codex", now);
+}
+/** Fold one run's billing and rate-window readings into the codex account file — the store's
+ * generic observeAccount for the "codex" backend, so a run's rollout feeding (plans/
+ * codex-backend.md "Spend, free-ness, window, images") lands under the codex id. */
+export function observeCodexAccount(root, run, now = Date.now()) {
+    return observeAccount(root, "codex", run, now);
+}
+/** Seed the codex account file before the first run (plans/codex-backend.md §7): `codex login
+ * status` decides — a ChatGPT login is subscription billing, an API key is API billing.
+ * An existing non-api file is left alone, and a probe that cannot run or is not logged in (or
+ * prints something else) leaves the file absent (readCodexAccount then reads "no subscription")
+ * unless it must clear a sticky api refusal: an "api" answer is re-probed so the operator's
+ * remedy (`codex login --device-auth`) clears it next startup, and a re-probe that cannot
+ * decide keeps the api file so the refusal does not fail open.
+ * Plan and windows arrive with the first run's rollout, so the seed writes no window readings.
+ * Returns the account written, or null. A failed write also returns null and never throws, so
+ * the first codex run's observation fills the file in. */
+export function seedCodexAccount(root, config, now = Date.now()) {
+    const existing = readCodexAccount(root, now);
+    // Leave an existing answer alone — a run's observation is fresher than this probe — except
+    // an "api" answer: the startup gate refuses on that, so it must never be sticky. Re-probe
+    // then, so an API-key login the operator has since fixed to a subscription (the refusal's
+    // named remedy, `codex login --device-auth`) clears the refusal on the next startup instead
+    // of a stale file refusing forever.
+    if (existing !== null && existing.billing !== "api")
+        return existing;
+    const billing = seedBilling(config);
+    if (billing === null) {
+        // A re-probe that cannot decide must not fail open: without an existing answer it seeds
+        // nothing, but a stale api answer keeps refusing — the persisted api file stays and the
+        // gate still reads it as a refusal rather than quietly passing (review objection 2).
+        return existing;
+    }
+    const account = {
+        billing,
+        observedAt: now,
+        windows: {},
+    };
+    try {
+        writeAccount(root, "codex", account);
+    }
+    catch {
+        return null;
+    }
+    return account;
+}
+/** Parse `codex login status` stdout into the billing it names: a ChatGPT login is a
+ * subscription, an API-key login is API billing, and anything else (not logged in, an unknown
+ * string, an IP firewall prompt) is null — the seed then stays silent and the run's rollout
+ * decides. Shared by seedBilling below and (from part 9/9) doctor's codex auth check, so the
+ * two cannot disagree about what a login means. */
+export function parseCodexLoginStatus(stdout) {
+    if (typeof stdout !== "string" || stdout === "")
+        return null;
+    if (stdout.includes("ChatGPT"))
+        return "subscription";
+    if (stdout.includes("API key"))
+        return "api";
+    return null;
+}
+/** The billing the login probe names, or null when it cannot be decided. */
+function seedBilling(config) {
+    const status = probeLoginStatus(config);
+    if (status === null)
+        return null;
+    if (status === "api")
+        return "api";
+    if (status === "subscription")
+        return "subscription";
+    return null;
+}
+/** Run `codex login status` under the same scrubbed environment a real run gets (a team
+ * config dir's login is what it reports), bounded by a short deadline. Null when the probe
+ * could not run or its stdout was unreadable. */
+function probeLoginStatus(config) {
+    const resolved = codexBackend.resolveBin(config);
+    const home = codexHome(resolvedBackendConfig(config, "codex"));
+    const env = codexEnv(process.env, home !== undefined ? { home } : {});
+    try {
+        const result = spawnSync(resolved.bin, ["login", "status"], {
+            env,
+            encoding: "utf8",
+            timeout: 10_000,
+            killSignal: "SIGKILL",
+        });
+        if (result.status !== 0)
+            return null;
+        return parseCodexLoginStatus(typeof result.stdout === "string" ? result.stdout : null);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/agent/codex/codex-args.js

@@ -0,0 +1,181 @@
+/** The Codex run's reserved flags and config keys plus the effort mapping — the pure,
+ * build-agnostic half of the codex invocation (plans/codex-backend.md "Config and routing" §2
+ * and "The invocation" §3). Part 4/9 owns these constants so config validation and the traits
+ * layer can screen a `backends.codex.args` passthrough before the adapter registered; part 5/9
+ * adds the `codexArgs` argv builder beside them, and 6/9 the stream translator. Pure — imports
+ * no runtime registry, config or subprocess — so config-validation.ts can import it without
+ * dragging the adapter in.
+ *
+ * Everything here is proved against Codex 0.163.0: every flag exists on that build, and every
+ * `-c` key passes the `--strict-config` device (design finding 20). */
+/** Flags the harness invocation sets itself (§3): the output and model flags, the sandbox and
+ * approval switches, the isolation switches, and the where-and-what-it-runs switches. A
+ * passthrough arg equal to one of these is appended AFTER the harness's own copy and Codex's
+ * parser is last-wins, so it would silently override the model, the isolation or the run
+ * location the harness resolved. Each is rejected with the offending arg named. This is the
+ * design's reserved set (§2 "Reserved passthrough flags"); config validation
+ * (config-validation-agents.ts) mirrors it for `backends.codex.args`, so a value that passes
+ * validation is never accepted there and then thrown in the builder.
+ *
+ * Operators keep `-c`, `--enable` and `--disable` for their own settings — those keys are
+ * screened separately (HARNESS_CODEX_CONFIG_KEYS). */
+import { appendPassthroughArgs } from "../agent-args.js";
+export const HARNESS_CODEX_FLAGS = new Set([
+    // Output and model: tumwater forces JSON output, the resolved model, and a normal color for
+    // the transcript log.
+    "--json",
+    "-m",
+    "--model",
+    "-o",
+    "--output-last-message",
+    "--output-schema",
+    "--color",
+    // Sandbox and approvals: tumwater runs every job with bypass approval and no sandbox
+    // (decision 2), so an operator cannot re-arm an approval prompt or a sandbox mid-run.
+    "-s",
+    "--sandbox",
+    "--dangerously-bypass-approvals-and-sandbox",
+    "--approve-for-me",
+    "--dangerously-bypass-hook-trust",
+    // Isolation: tumwater ignores the user's config, rules and persistent state so one team run
+    // cannot read a personal hook, skill or trust entry.
+    "--ignore-user-config",
+    "--ignore-rules",
+    "--ephemeral",
+    // Where and what it runs: tumwater pins the cwd and the worktree and refuses `--oss` /
+    // `--local-provider` so a run can never target something other than the resolved backend.
+    "-C",
+    "--cd",
+    "--worktree",
+    "--add-dir",
+    "--skip-git-repo-check",
+    "-p",
+    "--profile",
+    "--oss",
+    "--local-provider",
+]);
+/** The keys tumwater sets on every run via `-c <key>=…` (§3), so an operator's `-c` passthrough
+ * whose key is one of these would silently override the model, the effort, the sandbox mode, or
+ * the telemetry/state settings the harness already passed. A `-c` or `--config` passthrough whose
+ * key names one of these is refused; any other key is the operator's own and passes. */
+export const HARNESS_CODEX_CONFIG_KEYS = new Set([
+    "model",
+    "model_reasoning_effort",
+    "sandbox_mode",
+    "project_doc_fallback_filenames",
+    "web_search",
+    "agents.enabled",
+    "check_for_update_on_startup",
+    "analytics.enabled",
+    "feedback.enabled",
+    "history.persistence",
+]);
+/** Config-key prefixes an operator's `-c`/`--config` passthrough may not set: the write guard's
+ * own `hooks.*` keys (part 3/9). Codex is last-wins, so a `-c hooks.PreToolUse=…` or
+ * `-c hooks.state=…` passthrough would otherwise replace the guard or its trust after the
+ * harness's. Written beside HARNESS_CODEX_CONFIG_KEYS so both it and config validation screen
+ * against one predicate. */
+const HARNESS_CODEX_CONFIG_KEY_PREFIXES = ["hooks"];
+/** Whether `key` is a config key tumwater sets or reserves, so an operator's `-c`/`--config`
+ * passthrough naming it would silently override the harness. True for every
+ * HARNESS_CODEX_CONFIG_KEYS key and for the `hooks` key or any `hooks.<…>` subkey, which the
+ * write guard owns. */
+export function isHarnessCodexConfigKey(key) {
+    if (HARNESS_CODEX_CONFIG_KEYS.has(key))
+        return true;
+    return HARNESS_CODEX_CONFIG_KEY_PREFIXES.some((p) => key === p || key.startsWith(`${p}.`));
+}
+/** Thinking → `model_reasoning_effort`. `off` and `minimal` clamp to `low` (Codex has no lower
+ * setting; doctor notes the clamp), `low` through `max` map 1:1. `ultra` is not a value Codex
+ * can receive — tumwater never sends it (it delegates to sub-agents). This is claude's
+ * EFFORT_BY_THINKING rule moved to codex, where the level the model's catalog lists also gates
+ * the result (part 5/9's `codexEffort`). */
+export const EFFORT_BY_THINKING = {
+    off: "low",
+    minimal: "low",
+    low: "low",
+    medium: "medium",
+    high: "high",
+    xhigh: "xhigh",
+    max: "max",
+};
+/** The effort values tumwater will ever send as `model_reasoning_effort`: the set
+ * EFFORT_BY_THINKING can produce. `ultra` (which some models add for sub-agent delegation) is
+ * deliberately not here —
+ * tumwater never sends it, so `codexArgs` rejects it rather than let a whole agent hierarchy
+ * spawn on a model that lists it. */
+const KNOWN_EFFORTS = new Set(Object.values(EFFORT_BY_THINKING));
+/** Map a thinking level to the Codex `model_reasoning_effort` it means, gated by the model's own
+ * catalog. `levels` is the model's `supported_reasoning_levels` (design finding 14), which a
+ * stream-minted catalog (part 8/9) supplies; until then the caller passes `undefined`, and the
+ * result is returned unclamped. An unknown thinking level returns `undefined` (no effort flag) —
+ * the level simply has no Codex effort, unlike a thinking level that maps but the model does not
+ * support, which is also `undefined`. */
+export function codexEffort(thinking, levels) {
+    if (!Object.hasOwn(EFFORT_BY_THINKING, thinking))
+        return undefined;
+    const result = EFFORT_BY_THINKING[thinking];
+    if (levels !== undefined && !levels.includes(result))
+        return undefined;
+    return result;
+}
+/** Build one run's codex argv and stdin. The prompt is never an argv element (codex reads `-`
+ * input from stdin). Throws on an unknown effort, or a passthrough arg that repeats a harness
+ * flag, since each would otherwise silently change what the harness asked for. */
+export function codexArgs(opts) {
+    if (opts.effort !== undefined && !KNOWN_EFFORTS.has(opts.effort)) {
+        throw new Error(`codexArgs: unknown effort ${JSON.stringify(opts.effort)} (known: ${[...KNOWN_EFFORTS].join(", ")})`);
+    }
+    // Isolation flags, then the `--disable` list (design finding 7), then the `-c` keys (finding
+    // 20), then the model and effort, then the operator's passthrough, then the closing `-`.
+    const head = [
+        "--json",
+        "--dangerously-bypass-approvals-and-sandbox",
+        "--ignore-user-config",
+        "--ignore-rules",
+        "--disable",
+        "plugins",
+        "--disable",
+        "apps",
+        "--disable",
+        "goals",
+        "--disable",
+        "image_generation",
+        "--disable",
+        "browser_use",
+        "--disable",
+        "computer_use",
+        "--disable",
+        "tool_suggest",
+        "--disable",
+        "skill_search",
+        "-c",
+        "agents.enabled=false",
+        "-c",
+        'web_search="disabled"',
+        "-c",
+        "check_for_update_on_startup=false",
+        "-c",
+        "analytics.enabled=false",
+        "-c",
+        "feedback.enabled=false",
+        "-c",
+        'history.persistence="none"',
+        "-c",
+        'project_doc_fallback_filenames=["CLAUDE.md"]',
+        // The write guard's hook and trust ride the same `-c` layer, after the harness's own
+        // keys and before `-m` (plans/codex-write-guard.md "Runs (part 6)"); an untrusted hook
+        // would be skipped silently, so a backend with no trust passes nothing here.
+        ...(opts.guardArgs ?? []),
+        "-m",
+        opts.model,
+    ];
+    if (opts.effort !== undefined)
+        head.push("-c", `model_reasoning_effort=${opts.effort}`);
+    const args = opts.resumeId === undefined
+        ? ["exec", ...head]
+        : ["exec", "resume", opts.resumeId, ...head];
+    appendPassthroughArgs(args, opts.args, HARNESS_CODEX_FLAGS, "codexArgs");
+    args.push("-");
+    return { args, stdin: opts.prompt };
+}