create-agent-rig 0.6.2 → 0.7.0

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

@@ -74,13 +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.
+// 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 { readHookInput } from './lib/hook-input.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)$/;
@@ -807,10 +842,33 @@ export const inspect = (raw, brake, depth = 0) => {
 function main() {
   const input = readHookInput();
   if (input === null) return 0;
-  if (input.tool_name !== 'Bash') return 0;
-  const commandValue = input.tool_input?.command;
-  if (typeof commandValue !== 'string') return 0;
-  const raw = commandValue;
+  // 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;
+  }
+  // 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,8 +6,8 @@
 // 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.
+// 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';
 

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

@@ -6,8 +6,8 @@
 // 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.
+// 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';
 

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

@@ -53,3 +53,112 @@ export const readHookInput = () => {
     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