tumwater 0.1.3 → 0.3.0

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

@@ -1,8 +1,8 @@
-/** 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) and the notes MCP config path; this module turns those
- * inputs into the invocation's argv.
+ * `--session-id` or `--resume` to pass); this module turns those inputs into the invocation's
+ * argv.
  *
  * The environment is built separately (claude-env.ts) so each concern has one module.
  *
@@ -15,13 +15,15 @@
  * fallback the design holds in reserve is not needed. */
 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 `agents.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",
@@ -37,6 +39,7 @@ export const HARNESS_CLAUDE_FLAGS = new Set([
     "--permission-mode",
     "--tools",
     "--setting-sources",
+    "--settings",
     "--strict-mcp-config",
     "--mcp-config",
     "--disable-slash-commands",
@@ -68,14 +71,18 @@ function shouldAppendAgents(cwd) {
  * each would otherwise silently change what the harness asked for. */
 export function claudeArgs(opts) {
     if ((opts.sessionId === undefined) === (opts.resumeSessionId === undefined)) {
-        throw new Error("claudeArgs: pass exactly one of sessionId or resumeSessionId");
+        // Name which side fired so the invariant that would otherwise silently change the run's
+        // session is diagnosable at a glance: a conflicting pair (both set) differs from a missing
+        // choice (neither) and the two bugs have different fixes.
+        const state = opts.sessionId === undefined ? "neither is set" : "both are set";
+        throw new Error(`claudeArgs: pass exactly one of sessionId or resumeSessionId (${state})`);
     }
     const args = ["-p", "--output-format", "stream-json", "--verbose", "--model", opts.model];
     if (opts.thinking !== undefined) {
         // Own-property test, not a bare index: a level like `constructor` or `toString` would
         // otherwise inherit a function from Object.prototype and bypass the rejection below.
         if (!Object.hasOwn(EFFORT_BY_THINKING, opts.thinking)) {
-            throw new Error(`claudeArgs: unknown thinking level ${JSON.stringify(opts.thinking)}`);
+            throw new Error(`claudeArgs: unknown thinking level ${JSON.stringify(opts.thinking)} (known: ${Object.keys(EFFORT_BY_THINKING).join(", ")})`);
         }
         args.push("--effort", EFFORT_BY_THINKING[opts.thinking]);
     }
@@ -83,22 +90,15 @@ 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");
-    if (opts.mcpConfig !== undefined)
-        args.push("--mcp-config", opts.mcpConfig);
+    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");
     if (opts.maxBudgetUsd !== undefined && opts.maxBudgetUsd > 0) {
         args.push("--max-budget-usd", String(opts.maxBudgetUsd));
     }
-    for (const arg of opts.args ?? []) {
-        // Match the flag itself even when it carries its value as `--flag=value`.
-        const flag = arg.split("=", 1)[0];
-        if (HARNESS_CLAUDE_FLAGS.has(flag)) {
-            throw new Error(`claudeArgs: passthrough arg ${JSON.stringify(arg)} repeats a harness flag`);
-        }
-        args.push(arg);
-    }
+    appendPassthroughArgs(args, opts.args, HARNESS_CLAUDE_FLAGS, "claudeArgs");
     return { args, stdin: opts.prompt };
 }

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

@@ -16,34 +16,49 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 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 } from "../../process/run-marker.js";
-import { resolveBackendBin } from "../../pi/pi-bin.js";
+import { backendBaseEnv, withNotesPath } 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";
 import { claudeTranslator } from "./claude-stream.js";
 import { resumableSession } from "../session-ledger.js";
-/** claude's per-cwd project directory name under `~/.claude/projects/`: every character that
- * is not a letter or digit becomes `-`. Exported with `claudeTranscriptPath` so the PATH fake
- * and the tests create and look for exactly the file the resume check reads. */
+/** claude's per-cwd project directory name under the claude config dir's `projects/`:
+ * every character that is not a letter or digit becomes `-`. Exported with
+ * `claudeTranscriptPath` so the PATH fake and the tests create and look for exactly the file
+ * the resume check reads. */
 export function claudeProjectSlug(cwd) {
     return cwd.replace(/[^A-Za-z0-9]/g, "-");
 }
+/** claude's config directory: `$CLAUDE_CONFIG_DIR` when non-empty (a leading `~` expands
+ * against the home dir), else `~/.claude`. A configured team `configDir` (the expanded
+ * `backends.claude.configDir`) wins over any inherited env var — the team's own directory is
+ * never overridden by the operator's shell. This mirrors claude's own lookup and pi's
+ * `piAgentDir`; exported so doctor reads the same dir the adapter writes transcripts into. */
+export function claudeConfigDir(env = process.env, homeDir = os.homedir(), configured) {
+    if (configured)
+        return expandHomeTilde(configured, homeDir);
+    const dir = env.CLAUDE_CONFIG_DIR;
+    if (!dir)
+        return path.join(homeDir, ".claude");
+    return expandHomeTilde(dir, homeDir);
+}
 /** The transcript file claude writes for a session started in `cwd`: its resume check must find
  * a real file before passing `--resume`. claude's own layout is
- * `~/.claude/projects/<slug>/<sessionId>.jsonl`; exported so the fake and the resume logic
- * cannot drift. */
-export function claudeTranscriptPath(cwd, id) {
-    return path.join(os.homedir(), ".claude", "projects", claudeProjectSlug(cwd), `${id}.jsonl`);
+ * `<config>/projects/<slug>/<sessionId>.jsonl`; exported so the fake and the resume logic
+ * cannot drift. `configDir` is the configured team dir, threaded through so the resume check
+ * looks where the run's own env will write. */
+export function claudeTranscriptPath(cwd, id, env = process.env, homeDir = os.homedir(), configDir) {
+    return path.join(claudeConfigDir(env, homeDir, configDir), "projects", claudeProjectSlug(cwd), `${id}.jsonl`);
 }
 /** 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 fleet runs
+ * 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));
@@ -65,37 +80,27 @@ function classifyClaudeExit(info) {
     }
     return {};
 }
-/** The inline `--mcp-config` JSON that runs the bundled role-notes server (part 5/7): the
- * same dist module pi's extension resolves to, spawned by the same node running this harness
- * so it needs no PATH lookup. */
-function roleNotesMcpConfig() {
-    const server = fileURLToPath(new URL("../mcp/role-notes-server.js", import.meta.url));
-    return JSON.stringify({ mcpServers: { tumwater: { command: process.execPath, args: [server] } } });
-}
 /** The ledger record this run may resume, or null: the newest record of `opts.kind` for
  * claude, at `opts.cwd` when one is given, whose transcript file exists. Shared by
  * `resolveClaudeSession` and the backend's `resumable` hook, so the resume guard and the
  * invocation can never drift on what counts as resumable. */
-function claudeResumableRecord(dir, opts) {
+function claudeResumableRecord(dir, opts, configDir) {
     const record = resumableSession(dir, opts);
     if (record === null)
         return null;
     if (opts.cwd !== undefined && record.cwd !== opts.cwd)
         return null;
-    if (!fs.existsSync(claudeTranscriptPath(record.cwd, record.id)))
+    if (!fs.existsSync(claudeTranscriptPath(record.cwd, record.id, process.env, os.homedir(), configDir)))
         return null;
     return record;
 }
 /** The session id this run uses: for a continue, the ledger's newest record of this kind when
  * it is claude's, this cwd's, and its transcript file exists; otherwise a fresh UUID. Returns
- * the id and the `--resume` id when resuming. */
-function resolveClaudeSession(run) {
+ * the id and the `--resume` id when resuming. `configDir` is the configured team dir, so the
+ * resume check looks where the run's own env will write transcripts. */
+function resolveClaudeSession(run, configDir) {
     if (run.continueSession) {
-        const record = claudeResumableRecord(run.sessionDir, {
-            kind: run.kind,
-            agent: "claude",
-            cwd: run.cwd,
-        });
+        const record = claudeResumableRecord(run.sessionDir, { kind: run.kind, agent: "claude", cwd: run.cwd }, configDir);
         if (record !== null)
             return { sessionId: record.id, resumeSessionId: record.id };
     }
@@ -109,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
@@ -117,35 +122,35 @@ export const claudeBackend = {
         if (run.config.model === undefined) {
             throw new Error("claude backend: no model resolved for this run");
         }
-        const { sessionId, resumeSessionId } = resolveClaudeSession(run);
+        // 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 = 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);
         const { args, stdin } = claudeArgs({
             cwd: run.cwd,
             model: run.config.model,
             thinking: run.config.thinking,
             ...(resumeSessionId !== undefined ? { resumeSessionId } : { sessionId }),
-            // The operator's `agents.claude.args` passthrough, appended after the harness flags (the
-            // builder rejects any entry that repeats a harness-managed flag). resolvedAgentConfig
+            // The operator's `backends.claude.args` passthrough, appended after the harness flags (the
+            // 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: resolvedAgentConfig(run.config, "claude").args,
+            args: claudeCfg.args,
             prompt: run.prompt,
             // The caller computes the remaining daily budget for an API-billed claude run and the
             // adapter forwards it; a subscription run or the director passes none (part 7a/7).
             ...(run.maxBudgetUsd !== undefined ? { maxBudgetUsd: run.maxBudgetUsd } : {}),
-            // claude does not load the bundled pi extensions, so a run carrying a notebook gets the
-            // role_notes MCP server instead. Passed on EVERY claude invocation that carries a
-            // notebook — fresh or resumed, a transient retry, a SUMMARY follow-up — because claude
-            // keeps no flags across --resume, so a resume without this would lose the tool.
-            ...(run.notesPath !== undefined ? { mcpConfig: roleNotesMcpConfig() } : {}),
         });
-        // 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
-        // the marker the same way pi's adapter carries it (pi-backend.ts withNotesPath), so the
-        // spawned MCP server — which inherits this environment — reads the same notes file.
-        const base = run.notesPath === undefined
-            ? agentBaseEnv(run.runMarker)
-            : { ...agentBaseEnv(run.runMarker), TUMWATER_NOTES_PATH: run.notesPath };
+        // 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(backendBaseEnv(run.runMarker, undefined, run.binDir), run.notesPath);
         const env = claudeEnv(base, {
             quietTimeoutSeconds: run.config.quietTimeoutSeconds,
+            ...(expandedConfigDir !== undefined ? { configDir: expandedConfigDir } : {}),
         });
         return { args, stdin, env, sessionId };
     },
@@ -155,8 +160,13 @@ export const claudeBackend = {
         // seed the account file, so both must classify it the same way.
         return claudeTranslator({ thirdPartyProvider: claudeThirdPartyProvider(process.env) });
     },
-    resumable(dir, opts) {
-        return claudeResumableRecord(dir, opts) !== null;
+    resumable(dir, opts, configDir) {
+        return claudeResumableRecord(dir, opts, configDir) !== null;
+    },
+    // Every Claude model reads images (Claude Code's Read tool returns them as image blocks), so
+    // a claude seam is always capable — the doctor probes nothing and never works around it.
+    imageInput() {
+        return true;
     },
     classifyExit: classifyClaudeExit,
 };

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

@@ -1,8 +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/pi/pi-backend.ts's `withNotesPath` shows the pi adapter doing the
- * same), 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
@@ -13,7 +12,7 @@
  *
  * The set half disables auto-memory, backgrounded Bash tasks (finding 4: claude refuses a long
  * foreground command, backgrounds it, and abandons it when `-p` ends, which would report work
- * never verified), the auto-updater (a mid-fleet self-update must not swap the binary under a
+ * never verified), the auto-updater (a mid-team self-update must not swap the binary under a
  * run), telemetry, and error reporting; and raises the Bash timeouts so a slow suite runs in
  * the foreground. `BASH_MAX_TIMEOUT_MS` is derived from `quietTimeoutSeconds` so claude's own
  * Bash timeout fires before tumwater's quiet kill and the model sees a tool error rather than a
@@ -80,5 +79,10 @@ export function claudeEnv(base, opts) {
     env.DISABLE_AUTOUPDATER = "1";
     env.DISABLE_TELEMETRY = "1";
     env.DISABLE_ERROR_REPORTING = "1";
+    // A team config dir (plans/notes-command.md "Keeping funes out of team runs"): force claude's
+    // own config and transcripts under it, so a funes hook on ~/.claude/projects never indexes
+    // team runs. Unset leaves any inherited CLAUDE_CONFIG_DIR (or claude's default) untouched.
+    if (opts.configDir)
+        env.CLAUDE_CONFIG_DIR = opts.configDir;
     return env;
 }

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

@@ -14,7 +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 { isJsonObject, objectOrEmpty, nonNegativeNumber, parseJsonObject } from "../../files/json-object.js";
+import { joinParts } from "../../text/text.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
  * lower-cased so a future tool still reads as a name rather than as `undefined`. */
@@ -37,20 +38,10 @@ function str(value) {
 }
 /** claude's usage block → pi's canonical usage block, with `cost.total` 0 because the run's
  * authoritative cost rides the final `run_cost` event (a split-block message repeats its usage
- * on every event, so summing per event would double-count — the fold takes it once). */
+ * on every event, so summing per event would double-count — the fold takes it once). The
+ * wire-field reads stay here; the block's assembly is the shared canonicalUsageBlock. */
 function canonicalUsage(usage) {
-    const input = nonNegativeNumber(usage?.input_tokens, 0);
-    const cacheRead = nonNegativeNumber(usage?.cache_read_input_tokens, 0);
-    const cacheWrite = nonNegativeNumber(usage?.cache_creation_input_tokens, 0);
-    const output = nonNegativeNumber(usage?.output_tokens, 0);
-    return {
-        input,
-        cacheRead,
-        cacheWrite,
-        output,
-        totalTokens: input + cacheRead + cacheWrite + output,
-        cost: { total: 0 },
-    };
+    return canonicalUsageBlock(nonNegativeNumber(usage?.input_tokens, 0), nonNegativeNumber(usage?.cache_read_input_tokens, 0), nonNegativeNumber(usage?.cache_creation_input_tokens, 0), nonNegativeNumber(usage?.output_tokens, 0), 0);
 }
 /** One claude content block → one pi content block, or undefined for a block pi has no
  * vocabulary for (dropped, like any other unmapped native shape). `tool_use` becomes pi's
@@ -76,7 +67,7 @@ function canonicalBlock(block) {
             return {
                 type: "toolCall",
                 id: str(block.id) ?? "",
-                name: Object.hasOwn(TOOL_NAMES, name) ? TOOL_NAMES[name] : name.toLowerCase(),
+                name: Object.hasOwn(TOOL_NAMES, name) ? (TOOL_NAMES[name]) : name.toLowerCase(),
                 arguments: args,
             };
         }
@@ -96,7 +87,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);
@@ -203,7 +194,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",
@@ -304,7 +295,7 @@ 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.
+                    // resetsAt is a unix-seconds stamp; retryAfterSeconds is the wait the runner honors.
                     out.retryAfterSeconds = Math.max(0, Math.round(resetsAt - Date.now() / 1000));
                 }
                 return [JSON.stringify(out), ...windows];
@@ -347,7 +338,8 @@ export function claudeTranslator(opts = {}) {
                 return out;
             }
             case "tool_progress":
-                // A 30 s heartbeat of a running tool call: known, and the open call already tracks liveness.
+                // A 30 s heartbeat of a running tool call: known, and the open call already tracks
+                // liveness.
                 return [];
             default:
                 record(type ?? "unknown");

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;
+    }
+}