create-agent-rig 0.6.1 → 0.7.0

package/templates/agent-os/universal/.claude/hooks/gate-stop-dod.mjs

@@ -66,6 +66,7 @@ import { readFileSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
 import { withoutGitLocation } from '../scripts/git-env.mjs';
+import { readHookInput } from './lib/hook-input.mjs';
 
 // 🔴 The tree this gate measures is the project the hook BELONGS to — the
 // directory above `.claude/hooks/` — never the directory the session happens
@@ -166,12 +167,8 @@ function budgetMs(env) {
 }
 
 function main() {
-  let input;
-  try {
-    input = JSON.parse(readFileSync(0, 'utf8'));
-  } catch (error) {
-    return failOpen(`the Stop payload could not be read: ${error.message}`);
-  }
+  const input = readHookInput();
+  if (input === null) return failOpen('the Stop payload could not be read');
   if (input.hook_event_name !== 'Stop' && input.hook_event_name !== 'SubagentStop') return 0;
   if (input.stop_hook_active) return 0;
 

package/templates/agent-os/universal/.claude/hooks/guard-bash.mjs

@@ -74,12 +74,48 @@
 // written without thinking — not an adversary, and circumventing it is itself a
 // Never-tier violation. The layers behind it are review and CI.
 //
+// ── Which SURFACES it sees, and what that does not promise (RP-65) ───────────
+//
+// This runs for every tool named in `.claude/scripts/lib/shell-tools.mjs`, not
+// for `Bash` alone. It used to be wired under `Bash` only, and the measurement
+// that changed it is in that file: the same `--no-verify` command was blocked
+// through one tool and ran through the other, in one session.
+//
+// ⚠ Widening the matcher makes the same RULES run on both surfaces. It does not
+// make the PARSING identical: the tokeniser above is POSIX, and PowerShell's
+// quoting, escaping and separators are its own, so a command whose danger is
+// visible only after PowerShell-specific parsing can read differently here.
+//
+// ⚠ And the coarse checks are narrower than "coarse" suggests. The rules
+// match a command NAME — `git`, `gh`, `rm` — so they refuse the operation
+// only when the operation is spelled that way.
+// Measured with the brake armed: `gh pr merge …` is refused on both surfaces,
+// while `gh.exe pr merge …`, `Start-Process gh -ArgumentList …` and
+// `Remove-Item -Recurse -Force C:\` are all allowed. The first of those is
+// allowed under `Bash` too, so this is a rule-set bound rather than anything
+// the widened matcher introduced — but it is a bound, and an earlier draft of
+// this block claimed the opposite. This gap is why the file keeps a name that
+// says `bash`: a rename would promise a parity the parser does not have.
+//
 // Contract (Claude Code): JSON on stdin; exit 0 = allow, exit 2 = block, and
-// stderr is shown to the agent as the reason. Fails open on anything it cannot
-// parse — a crashed guard must never make the session unusable.
-import { readFileSync, realpathSync } from 'node:fs';
+// stderr is shown to the agent as the reason.
+//
+// Two different things happen to input this guard cannot act on, and collapsing
+// them into one sentence is the mistake `.claude/rules/invariants.md`
+// ("Refusing to inspect is a third outcome") says costs a credential either way:
+//   - NOTHING TO JUDGE -> allow. An unparseable payload, no `tool_input`, no
+//     `command`, an empty one, a tool this guard does not answer for, or a crash
+//     inside `inspect` — a guard that has nothing to look at, or that broke, must
+//     never make the session unusable.
+//   - HANDED SOMETHING IT CANNOT READ -> block. A `command` that is present in a
+//     shape this guard does not accept is refused, naming the shape expected,
+//     because allowing it would report a check that never ran.
+// The split is decided in one place for both shell guards, `lib/hook-input.mjs`.
+import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { brakeIsOn } from '../scripts/stop-flag.mjs';
+import { SHELL_TOOLS } from '../scripts/lib/shell-tools.mjs';
+import { readHookInput, refusalText, shellCommandOf } from './lib/hook-input.mjs';
 
 /** Branches that are shared by definition. */
 const PROTECTED_BRANCH = /^(main|master|develop|development|trunk)$/;
@@ -804,16 +840,35 @@ export const inspect = (raw, brake, depth = 0) => {
 };
 
 function main() {
-  let input;
-  try {
-    input = JSON.parse(readFileSync(0, 'utf8'));
-  } catch {
-    return 0;
+  const input = readHookInput();
+  if (input === null) return 0;
+  // The ONE list decides which surfaces this guard answers for. Comparing a
+  // literal here is what made the widened matcher in `settings.json` cosmetic:
+  // the hook was launched for every shell tool and then excused itself from all
+  // but one, so the Never tier and the kill switch stayed bypassable on the
+  // other. Two spellings of one fact, and the one that ran was the wrong one.
+  if (!SHELL_TOOLS.includes(input.tool_name)) return 0;
+  // Three outcomes, decided in one shared place (RP-80): absent → allow, a
+  // string → inspect, present-in-a-shape-this-cannot-read → REFUSE. The last
+  // one used to be an allow, and what that cost is measured rather than
+  // asserted: on `master` at `254b25c8`, with the kill switch armed, a
+  // `command` spelled as an array of argv words returned 0 here before
+  // `brakeIsOn()` was ever consulted. Pinned in hook-command-shape.test.ts
+  // (absent in a generated rig) › "refuses an unreadable command through %s
+  // while the kill switch is armed". A rule that can be stepped over by
+  // restating the same command in another container is not a rule.
+  const command = shellCommandOf(input);
+  if (command.kind === 'unreadable') {
+    process.stderr.write(`${refusalText(command)}\n`);
+    return 2;
   }
-  if (input.tool_name !== 'Bash') return 0;
-  const commandValue = input.tool_input?.command;
-  if (typeof commandValue !== 'string') return 0;
-  const raw = commandValue;
+  // Every member except `string` leaves nothing to inspect. Stated as one
+  // POSITIVE test rather than a list of the others, so a member added later
+  // cannot fall through to `raw.trim()` — which sits outside the try below,
+  // where a throw exits 1 and the harness reads that as allow. That is the
+  // fail-open this change removes, re-entering by another door.
+  if (command.kind !== 'string') return 0;
+  const raw = command.command;
   if (!raw.trim()) return 0;
 
   try {

package/templates/agent-os/universal/.claude/hooks/guard-core-purity.mjs

@@ -6,10 +6,10 @@
 // Contract (Claude Code and Codex): JSON on stdin; exit 0 = allow, exit 2 = block, and
 // stderr is shown to the agent as the reason.
 // Generator-owned coverage for the neutral bounded-inspection refusal lives upstream in
-// codex.test.ts › "$guard blocks with a neutral, actionable size-limit refusal"; generated
-// projects do not carry that suite, and a downstream edit requires a local replacement test.
-import { readFileSync } from 'node:fs';
+// codex.test.ts (absent in a generated rig) › "$guard blocks with a neutral,
+// actionable size-limit refusal" — a downstream edit requires a local replacement test.
 import { editFragments } from './lib/edit-input.mjs';
+import { readHookInput } from './lib/hook-input.mjs';
 
 /** The only non-relative import the core may use: its schema/validation library. */
 const ALLOWED_PACKAGES = ['zod'];
@@ -29,12 +29,8 @@ const BANNED = [
 ];
 
 function main() {
-  let input;
-  try {
-    input = JSON.parse(readFileSync(0, 'utf8'));
-  } catch {
-    return 0; // unparseable payload: not ours to judge
-  }
+  const input = readHookInput();
+  if (input === null) return 0; // unparseable payload: not ours to judge
   const fragments = editFragments(input);
   const blocked = fragments.find(
     ({ inspectionRefusal, appliesToAll }) => appliesToAll && inspectionRefusal,

package/templates/agent-os/universal/.claude/hooks/guard-rulebook.mjs

@@ -4,8 +4,9 @@
 //
 // The rulebook is the set of files that decide what this session may do — hooks
 // and settings wiring, the queue config and selector, all scripts, rules, skills
-// and agents, the `.codex/` configuration, the integrity manifest, `AGENTS.md`
-// and `CLAUDE.md`. Every one of them was editable by the run it governs: a
+// and agents, the `.codex/` configuration, the integrity manifest,
+// `.claude/doctor-exemptions.json`, `AGENTS.md` and `CLAUDE.md`. Every one of
+// them was editable by the run it governs: a
 // Write to `.claude/hooks/dod-checks.json` with `[]` switched the stop gate
 // off, and nothing refused it until the merge sweep, long after.
 //
@@ -60,10 +61,11 @@
 //     adversary.
 //
 // The rule it enforces is stated in `.claude/rules/autonomy.md`, "Never".
-import { readFileSync, realpathSync } from 'node:fs';
+import { realpathSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { editFragments } from './lib/edit-input.mjs';
 import { RULEBOOK_PREFIXES, isRulebookPath, readUnattended } from '../scripts/unattended-flag.mjs';
+import { readHookInput } from './lib/hook-input.mjs';
 
 export { RULEBOOK_PREFIXES, isRulebookPath };
 
@@ -71,9 +73,20 @@ const EDIT_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'apply
 
 const toPosix = (value) => String(value ?? '').replaceAll('\\', '/');
 
+// RP-54: `.native`, never plain `realpathSync`. Both resolve symlinks and
+// normalise separators; only the native one expands a Windows 8.3 short name,
+// so `C:\Users\RUNNER~1\…` and `C:\Users\runneradmin\…` otherwise survive as
+// two spellings of one directory. The root arrives from
+// `git rev-parse --show-toplevel` (long) while a payload path arrives however
+// the tool spelled it (short under an 8.3 temp or home), and a root that
+// matches no spelling of the payload makes this fail-open guard allow the
+// rulebook edit it exists to refuse. Both sites take the same canonicaliser or
+// the comparison is between two different normalisations. Measured on Windows
+// by codex.test.ts (absent in a generated rig) › "anchors a nested-cwd Windows
+// Codex rulebook edit to the canonical repository root".
 const canonicalRoot = (root) => {
   try {
-    return realpathSync(root);
+    return realpathSync.native(root);
   } catch {
     return root;
   }
@@ -85,7 +98,7 @@ const canonicalPath = (filePath) => {
   const tail = [];
   for (;;) {
     try {
-      return join(realpathSync(cursor), ...tail);
+      return join(realpathSync.native(cursor), ...tail);
     } catch {
       const parent = dirname(cursor);
       if (parent === cursor) return filePath;
@@ -112,12 +125,8 @@ const protectedRelative = (roots, filePath) =>
     .find(isRulebookPath);
 
 function main() {
-  let input;
-  try {
-    input = JSON.parse(readFileSync(0, 'utf8'));
-  } catch {
-    return 0; // unparseable payload: not ours to judge
-  }
+  const input = readHookInput();
+  if (input === null) return 0; // unparseable payload: not ours to judge
   if (!EDIT_TOOLS.has(input?.tool_name)) return 0;
 
   const selectedRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();

package/templates/agent-os/universal/.claude/hooks/guard-secret-file.mjs

@@ -82,10 +82,10 @@
 // by an explicit per-line candidate cap rather than running to exhaustion. Any
 // unbounded work in a fail-open guard is a total bypass of every rule at once,
 // not just of this one.
-import { readFileSync } from 'node:fs';
 
 import { findSecretValues, isCredentialPath } from '../scripts/lib/secrets.mjs';
 import { editFragments } from './lib/edit-input.mjs';
+import { readHookInput } from './lib/hook-input.mjs';
 
 /** Where a refusal points the agent, so the block is actionable rather than a wall. */
 const WHERE_CREDENTIALS_BELONG =
@@ -93,12 +93,8 @@ const WHERE_CREDENTIALS_BELONG =
   'and reach the process through the environment — see .claude/rules/autonomy.md, "Never".';
 
 function main() {
-  let input;
-  try {
-    input = JSON.parse(readFileSync(0, 'utf8'));
-  } catch {
-    return 0; // unparseable payload: not ours to judge
-  }
+  const input = readHookInput();
+  if (input === null) return 0; // unparseable payload: not ours to judge
 
   const editTools = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'apply_patch']);
   if (!editTools.has(input?.tool_name)) return 0;

package/templates/agent-os/universal/.claude/hooks/guard-web-boundary.mjs

@@ -6,10 +6,10 @@
 // Contract (Claude Code and Codex): JSON on stdin; exit 0 = allow, exit 2 = block, and
 // stderr is shown to the agent as the reason.
 // Generator-owned coverage for the neutral bounded-inspection refusal lives upstream in
-// codex.test.ts › "$guard blocks with a neutral, actionable size-limit refusal"; generated
-// projects do not carry that suite, and a downstream edit requires a local replacement test.
-import { readFileSync } from 'node:fs';
+// codex.test.ts (absent in a generated rig) › "$guard blocks with a neutral,
+// actionable size-limit refusal" — a downstream edit requires a local replacement test.
 import { editFragments } from './lib/edit-input.mjs';
+import { readHookInput } from './lib/hook-input.mjs';
 
 const WEB_PATH = /(^|\/)apps\/web\//;
 const CODE_FILE = /\.(ts|tsx|js|jsx|mjs|cjs)$/;
@@ -20,12 +20,8 @@ const FORBIDDEN_WORKSPACE = /^@[^/]+\/(db|api|worker)$/;
 const FORBIDDEN_RELATIVE = /(^|\/)(packages\/db|services)(\/|$)/;
 
 function main() {
-  let input;
-  try {
-    input = JSON.parse(readFileSync(0, 'utf8'));
-  } catch {
-    return 0; // unparseable payload: not ours to judge
-  }
+  const input = readHookInput();
+  if (input === null) return 0; // unparseable payload: not ours to judge
   const violations = [];
   const importRe =
     /(?:\bfrom\s*|\bimport\s*\(\s*|\brequire\s*\(\s*|^\s*import\s+)['"]([^'"]+)['"]/gm;

package/templates/agent-os/universal/.claude/hooks/inject-rules.mjs

@@ -30,6 +30,7 @@
 // is why every ambiguity resolves toward injecting more.
 import { readFileSync, realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import { readHookInput } from './lib/hook-input.mjs';
 
 // Regions the rule file marks as not worth injecting. The marker is explicit
 // and lives in the rule file itself, where the person editing it can see it —
@@ -150,12 +151,8 @@ function invokedDirectly() {
 }
 
 function main() {
-  let input;
-  try {
-    input = JSON.parse(readFileSync(0, 'utf8'));
-  } catch {
-    return 0;
-  }
+  const input = readHookInput();
+  if (input === null) return 0;
   if (input.hook_event_name !== 'SessionStart') return 0;
 
   let rules;

package/templates/agent-os/universal/.claude/hooks/lib/hook-input.mjs

@@ -0,0 +1,164 @@
+// The one place a hook reads its payload — `invariants.md`, "One mechanism,
+// one implementation". Eight hooks each parsing stdin is eight chances for one
+// of them to keep a defect the others fixed, and the one nobody looks at is the
+// one that will.
+//
+// 🔴 Why this module exists at all (RP-54). A hook that cannot parse its
+// payload allows the tool call — that is the documented fail-open, and it is
+// correct: a crashed guard must not make the session unusable. But it means an
+// unreadable payload silently disarms EVERY rule the hook carries, so what
+// counts as unreadable has to be as narrow as the format honestly allows.
+//
+// Measured on the hosted `windows-unit` runner, through the generated Codex
+// `commandWindows` wrapper (CI run 33281160544): the wrapper delivers stdin and
+// propagates the child's exit code, but the guard received **290 bytes for a
+// 287-byte payload**. PowerShell prepends a UTF-8 BOM on that host. `JSON.parse`
+// throws on a leading U+FEFF, so every guard resolved a well-formed payload to
+// "not ours to judge" and allowed the edit — including `guard-bash`, which
+// carries the Never tier and the kill switch. A Windows host whose PowerShell
+// does not add the BOM parses the same payload fine, which is why this looked
+// like a runner-only mystery for two days.
+//
+// A BOM is a byte-order mark, not content: stripping one leading U+FEFF is what
+// the format means, not a tolerance added to get a test green.
+//
+// Bounded work, because a fail-open reader is a total bypass if it can throw or
+// spin: one read, one character comparison, one slice, one parse. No loop, no
+// recursion, no rescanning.
+//
+// Limits, stated rather than implied:
+// - Only a BOM at position 0 is stripped. A payload with other leading bytes is
+//   still unreadable, and still resolves to `null`.
+// - `null` means "no payload this hook can judge" and every caller keeps its own
+//   fail-open on it. This module does not decide policy; it only removes the
+//   spelling difference between two hosts.
+// Pinned in hook-stdin.test.ts (absent in a generated rig) ›
+// "blocks the same command when PowerShell prepends a UTF-8 BOM" and ›
+// "reads stdin through the one shared reader, in every hook that reads it".
+
+import { readFileSync } from 'node:fs';
+
+/** The hook payload as an object, or `null` when there is none this hook can read. */
+export const readHookInput = () => {
+  let raw;
+  try {
+    raw = readFileSync(0, 'utf8');
+  } catch {
+    return null;
+  }
+  if (raw.charCodeAt(0) === 0xfeff) raw = raw.slice(1);
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * ── The shape of a shell command, for the Never-tier SHELL guards (RP-80) ───
+ *
+ * One place, for the two guards that read `tool_input.command` on a shell tool —
+ * `guard-bash` and `block-no-verify`. It is deliberately NOT a repository-wide
+ * ruling on the word `command`: `guard-secret-file` reads an `apply_patch`
+ * `command` that is a **list of strings**, which is exactly the shape this
+ * module classifies as unreadable, and it is right to — the reasoning is in
+ * `docs/decisions/codex-adapter.md`. Routing a third guard through here without
+ * checking which shape its tool actually sends would start refusing input
+ * another guard exists to read.
+ *
+ * `.claude/rules/invariants.md` ("Refusing to inspect is a third outcome, not a
+ * match and not an error") draws the line these guards need:
+ *
+ * - **absent** — nothing to judge, so the guard fails OPEN. A `Write` with no
+ *   content and a shell tool with no `command` are the same case.
+ * - **`string`** — the guard inspects it as it always did.
+ * - **present and unreadable** — the guard was handed something and can tell
+ *   that it cannot read it. That is a REFUSAL: block, name the shape expected,
+ *   and say to resend in that shape.
+ *
+ * 🔴 Getting that last line backwards costs the whole rule set. Measured on
+ * `master` at `254b25c8`: a payload whose `command` was `["gh","pr","merge","1"]`
+ * exited 0 from `guard-bash` **with the kill switch armed** — the brake was
+ * never consulted, because the guard had already excused itself. `block-no-verify`
+ * had the same hole by another road: `String(argv)` comma-joins, and its
+ * tokeniser never splits on a comma, so `--no-verify` became invisible rather
+ * than unreadable.
+ *
+ * 🔴 The remedy is carried as a FIELD beside the reason, not inferred from the
+ * reason's wording by whoever prints it — `invariants.md` again. A remedy
+ * chosen by pattern-matching a sentence is wrong the day somebody rewords the
+ * sentence, in every copy at once. And it is deliberately NOT "split the change
+ * and retry": that advice belongs to a crossed BOUND, where a smaller input
+ * really does fit. Nothing about splitting changes a container's shape, so
+ * offering it here would turn a refusal into a loop.
+ *
+ * Bounded work, because a fail-open guard is a total bypass if any input can
+ * make it spin or throw: a fixed number of `typeof` tests and one lookup. The
+ * offending value is NEVER serialised into the message — only its shape word —
+ * so an enormous or cyclic `command` costs nothing and leaks nothing.
+ *
+ * Limits, stated rather than implied:
+ * - It reads `tool_input.command`. A surface that names its command field
+ *   differently is not seen at all, and that is the same blind spot the whole
+ *   list in `.claude/scripts/lib/shell-tools.mjs` has: harness → guard is
+ *   guarded by nobody.
+ * - `absent` covers `null` as well as `undefined`, on both `tool_input` and
+ *   `command`. A key explicitly set to null carries no command to read, and
+ *   refusing it would fire on payloads that mean "no command".
+ * - An empty or whitespace-only string is READABLE and allowed. It is a
+ *   command that does nothing, not a shape the guard failed to parse.
+ * Pinned in hook-command-shape.test.ts (absent in a generated rig) ›
+ * "refuses an unreadable command through %s while the kill switch is armed"
+ * and › "allows an ABSENT command through %s".
+ */
+
+/** The shape word for a value, bounded: never the value itself. */
+const shapeOf = (value) => {
+  if (Array.isArray(value)) return 'an array';
+  const type = typeof value;
+  return type === 'object' ? 'an object' : `a ${type}`;
+};
+
+/**
+ * What a shell guard was handed, as one of three outcomes.
+ *
+ * @returns {{kind:'absent'}
+ *          |{kind:'string', command:string}
+ *          |{kind:'unreadable', reason:string, remedy:string}}
+ */
+export const shellCommandOf = (input) => {
+  const toolInput = input?.tool_input;
+  if (toolInput === undefined || toolInput === null) return { kind: 'absent' };
+  if (typeof toolInput !== 'object' || Array.isArray(toolInput)) {
+    return unreadable('tool_input', shapeOf(toolInput), 'an object');
+  }
+  const command = toolInput.command;
+  if (command === undefined || command === null) return { kind: 'absent' };
+  if (typeof command !== 'string') {
+    return unreadable('tool_input.command', shapeOf(command), 'a string');
+  }
+  return { kind: 'string', command };
+};
+
+const unreadable = (field, got, expected) => ({
+  kind: 'unreadable',
+  reason:
+    `BLOCKED — ${field} is present as ${got}, and this guard reads ${expected}. ` +
+    'An input it cannot read is refused, never allowed: the Never-tier rules and ' +
+    'the kill switch are decided by reading the command, so allowing what was ' +
+    'not read would report a check that did not happen ' +
+    '(.claude/rules/invariants.md, "Refusing to inspect is a third outcome").',
+  remedy: `Resend the call with ${field} as ${expected}.`,
+});
+
+/**
+ * One refusal, one wording — so two guards cannot drift apart in what they say.
+ *
+ * It answers for the `unreadable` member only. Handed anything else it returns
+ * the empty string rather than `"undefined undefined"`: a guard that printed
+ * that would be reporting a refusal it cannot explain, and the caller could not
+ * act on it. The call sites below never do this today; the guard is here so a
+ * later one cannot introduce it silently.
+ */
+export const refusalText = (refusal) =>
+  refusal?.kind === 'unreadable' ? `${refusal.reason} ${refusal.remedy}` : '';

package/templates/agent-os/universal/.claude/rules/invariants.md

@@ -223,6 +223,25 @@ an artifact may cite the generator's upstream tests, which are absent locally,
 only when the pointer says they are absent and `.claude/.rig-manifest.json`
 proves the current artifact's hash matches the installed manifest.
 
+**In the generator, part of that is mechanical.** A citation there is a
+test-file name followed by `›` and a quoted test name, and the generator's
+`test/template/evidence-pointers.test.ts` (absent in a generated rig) resolves
+the citations it reads: › "names a test file this repository still has" and ›
+"quotes a test name that file still declares" go red when a target is renamed
+or a test retitled, and › "says so when the test it names is one a generated
+project never receives" goes red when a pointer into the generator's suite
+carries no word that the reader does not have it. The wording that satisfies
+the last one is `(absent in a generated rig)` beside the pointer, or the
+one-line disclosure nine scripts here open with — a phrase naming the generator
+is not enough, because it tells the reader where the test lives and nothing
+about whether they have it.
+
+⚠ **"the citations it reads" is not all of them**, and the test's own header
+states where the edges are: it looks only at the tree that ships into a rig,
+and it reads a citation's names from the line the file is named on and the two
+after it. A green run means no citation it read has gone dead — not that every
+pointer in the generator was verified.
+
 A manifest-backed upgrade remains an inherited, generator-owned artifact even
 though the upgrade diff changes its bytes. The exception applies **only while the
 manifest hash matches**. A hash mismatch, missing manifest, or no evidence ends