create-agent-rig 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -11,6 +11,84 @@ Numbering is ordinary semver — **additive is a minor, a fix is a patch** — s
 that "I only take minors" remains a usable policy; 0.3.2 shipped additive
 content as a patch by the owner's call and stays recorded as one.
 
+## 0.6.2
+
+**Patch hardening for the Agent OS shipped by 0.6.1.** This release closes six
+downstream-found governance and transport defects without changing the public
+CLI or adding a dependency.
+
+### Fixed
+
+- **A UTF-8 BOM on a hook's stdin no longer disarms it.** PowerShell prepends
+  one on some Windows hosts, `JSON.parse` throws on a leading U+FEFF, and every
+  hook resolved that to its documented fail-open — so a well-formed refusal
+  became an allow. On such a host all eight hooks failed open together,
+  `guard-bash` among them, which carries the Never tier and the kill switch.
+  They now read through one shared `.claude/hooks/lib/hook-input.mjs`. Pinned in
+  `test/template/hook-stdin.test.ts` › "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".
+- **Windows 8.3 short paths no longer hide a rulebook edit from the guard.**
+  `realpathSync` normalises separators but leaves a short name (`RUNNER~1`,
+  `SERHII~1`) unexpanded, so a checkout reached by two spellings hashed to two
+  unattended-flag names and compared as two directories. Both
+  `guard-rulebook` and `unattended-flag` now canonicalise with
+  `realpathSync.native`. Pinned in `test/template/unattended-flag.test.ts` ›
+  "scopes the flag by the checkout, so two spellings of one directory arm one
+  file".
+- **Codex hooks carry the canonical repository root in `CLAUDE_PROJECT_DIR` on
+  POSIX and Windows.** A session started in a nested directory therefore judges
+  a rulebook edit against the checkout the hook came from. Pinned in
+  `test/template/codex.test.ts` › "anchors a nested-cwd Codex rulebook edit to
+  the canonical repository root"; the same test file decodes and checks the
+  Windows command.
+- **Jira retry is limited to safe reads and the semantically read-only search
+  POST.** Comment, transition, issue-create and issue-update mutations return
+  the first ambiguous transient failure instead of replaying the write. Pinned
+  in `test/template/queue-jira.test.ts` › "does not retry %s" and › "retries a
+  semantically read-only search POST after a 429".
+- **`.claude/doctor-exemptions.json` is protected as rulebook input.** An
+  unattended edit is refused unless the current item's allow-list names that
+  exact file. Pinned in `test/template/guard-rulebook.test.ts` › "allows doctor
+  exemptions only when the item names that exact rulebook file" and the guarded
+  path table in the same suite.
+- **`lastCompletedTier` is explicitly repository-global across board switches.**
+  A selector change cannot reset the spacing brake and admit a second elevated
+  mechanism change in the same checkout. The ruling is in
+  `docs/decisions/spacing-rations-mechanisms.md`, pinned by
+  `test/template/queue-board.test.ts` › "keeps completed-tier spacing
+  repository-global when the active board switches".
+
+## 0.6.1
+
+**Security and upgrade hardening for the Agent OS shipped by 0.6.0.** This patch
+closes the rulebook, unattended-run and queue-board gaps found while upgrading a
+live generated repository; it adds no dependency and changes no public CLI
+command.
+
+### Security
+
+- **`guard-rulebook` now covers the whole shared rulebook and symlink aliases on
+  either side of the comparison.** `AGENTS.md` and `.codex/hooks.json` are
+  protected alongside the Claude files. Checkout roots and payload paths are
+  judged in both their selected and canonical spellings, including a
+  payload-only alias.
+- **Queue board names containing terminal control characters are rejected before
+  selection, diagnostics or selector writes.** Ordinary names, including names
+  with spaces, remain valid; ANSI, OSC, C1 and DEL bytes from repository-owned
+  `queue.json` keys can no longer repaint terminal output.
+- **Unattended authorization is checkout-scoped.** Concurrent worktrees derive
+  distinct flag paths from canonical checkout identity, legacy machine-wide
+  state fails closed, and migration or cleanup refuses when any armed flag cannot
+  be removed instead of reporting a partial disarm as success.
+
+### Fixed
+
+- The generated prose-reviewer exception for upstream-only tests now applies
+  only to manifest-proven generator snapshots and expires on local drift. This
+  keeps intentional generator test references available without turning a dead
+  reference in an edited downstream rulebook into a pass.
+
 ## 0.6.0
 
 **The loop now checks its premises against the tracker at three points, and

package/README.md

@@ -108,7 +108,7 @@ wired by both `.claude/settings.json` and `.codex/hooks.json`:
   the web talks to the backend over HTTP only;
 - **`guard-rulebook`** — in an unattended run (a flag file the `loop` skill
   writes at claim time), refuses an edit to the rulebook — hooks, wiring,
-  `queue.json`, the queue adapters, the router, the gate sweep, the rules,
+  `queue.json` and its board selector, the queue adapters, the router, the gate sweep, the rules,
   `CLAUDE.md` — outside the current item's allow-list; does nothing in an
   attended session.
 - **`guard-secret-file`** — refuses an edit that writes a credential: either the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agent-rig",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Scaffold a new project with an agent operating system (rules, gates, hooks) and a runnable code skeleton",
   "keywords": [
     "create",
@@ -51,6 +51,8 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/node": "^26.1.1",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "eslint": "^10.7.0",
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.7.0",

package/templates/agent-os/init/AGENTS.md

@@ -116,13 +116,15 @@ All four are one-liners, and all four are inert until you do them.
    no-op, and the Definition of Done is back to being a wish.
 2. **The elevated-path list below is a seed, not a survey.** It names only what
    every repo has. Everything else is yours to add.
-3. **Four runtime paths need a `.gitignore` line each**, and `init` cannot add
+3. **Five runtime paths need a `.gitignore` line each**, and `init` cannot add
    them — it installs into your repository and does not edit files it did not
-   bring. Add all four:
+   bring. If any are missing, add only the missing entries:
 
    ```
    # the tier the last close recorded
    .claude/queue.state.json
+   # the board this checkout runs on, when the config declares several
+   .claude/queue.board
    # gate rounds, one count per branch
    .claude/gate-rounds.json
    # task worktrees

package/templates/agent-os/init/CLAUDE.md

@@ -116,13 +116,15 @@ All four are one-liners, and all four are inert until you do them.
    no-op, and the Definition of Done is back to being a wish.
 2. **The elevated-path list below is a seed, not a survey.** It names only what
    every repo has. Everything else is yours to add.
-3. **Four runtime paths need a `.gitignore` line each**, and `init` cannot add
+3. **Five runtime paths need a `.gitignore` line each**, and `init` cannot add
    them — it installs into your repository and does not edit files it did not
-   bring. Add all four:
+   bring. If any are missing, add only the missing entries:
 
    ```
    # the tier the last close recorded
    .claude/queue.state.json
+   # the board this checkout runs on, when the config declares several
+   .claude/queue.board
    # gate rounds, one count per branch
    .claude/gate-rounds.json
    # task worktrees

package/templates/agent-os/universal/.agents/skills/loop/SKILL.md

@@ -39,6 +39,32 @@ node .claude/scripts/queue/index.mjs hygiene   # stale labels, link anomalies, o
   (`JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN`) and never from a file in the
   repo; the project or the JQL goes in `.claude/queue.json`.
 
+A config may declare several boards (`boards: { <name>: options }` plus a
+default `board`); the active one is chosen per checkout, not by editing the
+composed file:
+
+```bash
+node .claude/scripts/queue/index.mjs board        # the active board and the declared ones
+node .claude/scripts/queue/index.mjs board RP     # switch this checkout: writes .claude/queue.board
+```
+
+The selector is per-checkout runtime state, the same class as
+`.claude/queue.state.json`: it needs its own `.gitignore` line, which a generated
+project ships and an `init`-installed rig adds by hand. An undeclared name is
+refused, never read as "no board" (see `test/template/queue-board.test.ts` ›
+"refuses a board nobody declared instead of falling back" — in the generator,
+absent in a generated rig). It is a rulebook path for `guard-rulebook`:
+`.claude/queue.board` is refused even when an item allow-list names it,
+and the `board` command itself refuses a switch while the checkout is unattended. This
+does not prevent an arbitrary direct shell write to the selector — edit-tool
+hooks cannot see one. `.claude/queue.state.json` stays per config, not per board:
+the tier the last close recorded rations the next selection whichever board it
+lands on. This is repository-risk state, not tracker metadata: switching from
+one independent queue to another must not turn a previous mechanism close into
+permission for a second one in the same checkout. Pinned in the generator's
+`test/template/queue-board.test.ts` (absent in a generated rig) › "keeps
+completed-tier spacing repository-global when the active board switches".
+
 Adding a fourth is an adapter, not a rewrite: `core.mjs` holds every selection
 decision and each adapter only maps its tracker's records onto the neutral shape.
 
@@ -99,14 +125,15 @@ invocation. What a hook CAN see is a file, so the unattended signal is one:
 ```bash
 # at claim time, from the paths the item names (repo-relative prefixes, with
 # their trailing slash); the guard refuses every other rulebook edit while it is on
-node .claude/scripts/unattended-flag.mjs on --item <item-id> --run-dir "$RIG_RUN_DIR" --allow <prefix> [<prefix>…]
+node .claude/scripts/unattended-flag.mjs on --root "$PWD" --item <item-id> --run-dir "$RIG_RUN_DIR" --allow <prefix> [<prefix>…]
 ```
 
 `guard-rulebook` reads it (`.claude/rules/autonomy.md`, "Never"): with the flag
-on, a Write/Edit/MultiEdit/NotebookEdit/`apply_patch` under `.claude/hooks/`,
-`.claude/settings.json`, `.claude/queue.json`, `.claude/scripts/queue/`, the
-router, the gate sweep, `.claude/rules/` or `CLAUDE.md` is refused unless its
-path starts with an allowed prefix; with no flag the guard does nothing. An
+on, a Write/Edit/MultiEdit/NotebookEdit/`apply_patch` under the generated
+rulebook — both harnesses' rules, skills, agents and hook wiring, plus their
+scripts, queue config and integrity manifest — is refused unless its
+path starts with an allowed prefix; the board selector is the one always-refused
+exception and cannot be admitted by an allow-list. With no flag the guard does nothing. An
 item that needs a rulebook path names it here — a decision made at claim
 time, never a default — and the stop step below turns the flag off. Pinned in
 the generator's `test/template/guard-rulebook.test.ts` — absent in a generated
@@ -718,9 +745,18 @@ next attended session would find its rulebook edits refused in the name of an
 item nobody is working:
 
 ```bash
-node .claude/scripts/unattended-flag.mjs off
+node .claude/scripts/unattended-flag.mjs off --root "$PWD"
 ```
 
+If that command reports a legacy machine-wide flag, it deliberately leaves a
+foreign pre-upgrade authorization in place and the checkout stays fail-closed.
+Inspect the exact reported record and confirm that no pre-upgrade run still uses
+it, then remove only that record with
+`node .claude/scripts/unattended-flag.mjs off --legacy --path <reported-path>`.
+Run scoped `off --root "$PWD"` again to surface the next record, and repeat the
+inspection one at a time; do not record the flag as off until the scoped command
+succeeds.
+
 At every **stop** — not at a checkpoint — turn the run's findings into **at most
 three** improvement proposals. **The cap is the mechanism, not a budget:** an
 unbounded improvement list is another diary, and three forces a choice. Each names
@@ -750,7 +786,7 @@ node --input-type=module -e '
     // mechanism accepts a proposal without them; this procedure does not.
     measured: "<the paths the probe actually exercised>",
     inferred: "<the conclusion, citing only surfaces named in measured>",
-  }, { project: "<KEY>" }));   // jira only — the project key from .claude/queue.json;
+  }, { project: "<KEY>" }));   // jira only — the ACTIVE board's key: `queue/index.mjs board --json` → options.project;
                                // plan-md and github-issues take no second argument
 '
 ```
@@ -853,7 +889,7 @@ three poisons the only channel by which this project learns.
   validation and its take-up — an adapter re-records the take-up after each
   write of its own (§2, AR-140), so a comment posted after BEFORE_PR does not
   hold the close; pinned in the generator's
-  `test/template/self-inflicted-marker.test.ts` › "continues when the run’s own
+  `test/template/self-inflicted-marker.test.ts` (absent in a generated rig) › "continues when the run’s own
   write moved the marker after the last validation" — and its
   state against the `in-progress` a close expects, journals one `revalidation`
   event at `point: BEFORE_CLOSE`, and lists the item's dependants with each
@@ -864,7 +900,7 @@ three poisons the only channel by which this project learns.
   and reads a hold as a stop" and › "re-reads each dependant's state, and names
   one the tracker no longer offers". On a `github-issues` queue that list is
   empty: a single `gh issue view` carries no cross-index, so `find` answers no
-  `blocks` there (`test/template/close-transitioned.test.ts` › "github asks `gh
+  `blocks` there (`test/template/close-transitioned.test.ts` (absent in a generated rig) › "github asks `gh
   issue view` with the full field list and maps CLOSED to closed"). A
   hold (exit 2) stops the close: re-read the item, record the outcome with
   `node .claude/scripts/revalidate.mjs outcome --point BEFORE_CLOSE --ticket
@@ -876,7 +912,7 @@ three poisons the only channel by which this project learns.
   `true` says the close landed, because every adapter reads the item back after
   the transition — `jira` the status category after the POST, `github-issues`
   `gh issue view --json state`, `plan-md` the line being there and then gone
-  (the generator's `test/template/close-transitioned.test.ts` › "GETs the issue
+  (the generator's `test/template/close-transitioned.test.ts` (absent in a generated rig) › "GETs the issue
   status after the transition POST and reports transitioned: true when the
   category is done", › "runs `issue view <id> --json state` after `issue close`
   and reports transitioned: true on CLOSED", › "reports transitioned: true once

package/templates/agent-os/universal/.claude/agents/prose-reviewer.md

@@ -61,11 +61,16 @@ about it here, so the two gates never file competing opinions on one paragraph.
 
    ⚠ A pointer into a test suite the reader's project does not carry is normally
    item 2, not backing. There is one narrow inherited-snapshot exception from
-   `invariants.md`: a generator-authored hook may point to upstream generator
-   tests that are absent locally **only while the hook is unchanged downstream**
-   and its hook header identifies those tests as absent locally. If that hook is
-   edited downstream or appears as changed in the current diff, the exception
-   expires and the local test is yours; then an absent pointer is item 2 again.
+   `invariants.md`: a generator-authored artifact — rules, hooks, skills,
+   scripts, or agent specs —
+   may point to upstream generator tests that are absent locally only when the
+   pointer explicitly says the suite is absent locally and
+   `.claude/.rig-manifest.json` proves the current artifact's hash matches the
+   installed manifest. A manifest-backed upgrade remains an inherited,
+   generator-owned artifact; a changed file in the upgrade diff does not alone
+   make it downstream-authored. The exception applies **only while the manifest
+   hash matches**. A hash mismatch, missing manifest, or no evidence ends the
+   exception and the local test is yours; then an absent pointer is item 2 again.
 
    🔴 Three things this is not. It is not item 1: that one is about enforcement the
    mechanism does not provide, this one is about any claim with nothing behind it,

package/templates/agent-os/universal/.claude/hooks/block-no-verify.mjs

@@ -12,15 +12,11 @@
 // to tokenise: it owns exactly one invariant and stays readable because of it
 // (see .claude/rules/invariants.md, "One invariant per hook"). Use a file rather
 // than a heredoc, or quote the example.
-import { readFileSync } from 'node:fs';
+import { readHookInput } from './lib/hook-input.mjs';
 
 function main() {
-  let input;
-  try {
-    input = JSON.parse(readFileSync(0, 'utf8'));
-  } catch {
-    return 0;
-  }
+  const input = readHookInput();
+  if (input === null) return 0;
   if (input.tool_name !== 'Bash') return 0;
   const raw = String(input.tool_input?.command ?? '');
 

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

@@ -34,9 +34,9 @@
 // a per-step budget is how three checks quietly cost three times the wall
 // clock the wiring allows (`.claude/rules/invariants.md` — "an explicit total
 // budget rather than a per-step one").
-//   see hooks.test.ts › "gates the stop when a check outruns the budget — unmeasured is not a pass"
-//   see hooks.test.ts › "spends one budget across the whole suite, not a fresh one per check"
-//   see hooks.test.ts › "gives the stop gate a harness timeout its own budget finishes inside"
+//   see hooks.test.ts (absent in a generated rig) › "gates the stop when a check outruns the budget — unmeasured is not a pass"
+//   see hooks.test.ts (absent in a generated rig) › "spends one budget across the whole suite, not a fresh one per check"
+//   see hooks.test.ts (absent in a generated rig) › "gives the stop gate a harness timeout its own budget finishes inside"
 //
 // ⚠ This rests on ONE assumption about the harness that nothing in this
 // repository can prove or falsify: that a hook outrunning its timeout is
@@ -48,24 +48,25 @@
 // Limits, each with the test that pins it:
 //   - a check whose output outgrows the buffer is UNMEASURED, and blocks like
 //     any other unmeasured check —
-//     see hooks.test.ts › "gates the stop when a check drowns its own buffer — a pass nobody watched is not a pass"
+//     see hooks.test.ts (absent in a generated rig) › "gates the stop when a check drowns its own buffer — a pass nobody watched is not a pass"
 //   - below that buffer, output volume is not a verdict: a chatty check that
 //     passes, passes —
-//     see hooks.test.ts › "does not read a chatty passing check as a failure (the ENOBUFS false gate)"
+//     see hooks.test.ts (absent in a generated rig) › "does not read a chatty passing check as a failure (the ENOBUFS false gate)"
 //   - the RIG_DOD_BUDGET_MS override may only LOWER the budget, and an
 //     override this hook did not honour is announced rather than ignored —
-//     see hooks.test.ts › "clamps a budget override that would outlive the harness, and names the budget it used"
+//     see hooks.test.ts (absent in a generated rig) › "clamps a budget override that would outlive the harness, and names the budget it used"
 //   - a fail-open is announced on stderr, because a silent exit 0 and a clean
 //     pass are the same observation from outside —
-//     see hooks.test.ts › "announces a fail-open instead of returning a silent clean pass"
+//     see hooks.test.ts (absent in a generated rig) › "announces a fail-open instead of returning a silent clean pass"
 //   - an ABSENT config is not a failure and says nothing; only a config that
 //     exists and cannot be used announces —
-//     see hooks.test.ts › "stays silent when there is no config at all — nothing to gate is the design, not a swallowed error"
+//     see hooks.test.ts (absent in a generated rig) › "stays silent when there is no config at all — nothing to gate is the design, not a swallowed error"
 import { execSync, spawnSync } from 'node:child_process';
 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
@@ -81,9 +82,9 @@ import { withoutGitLocation } from '../scripts/git-env.mjs';
 // `worktree-task` worktree is measured at the main checkout, and the refusal
 // says so. Resolved inside `main()`, so a throw here reaches the backstop
 // and announces itself like every other fault of the gate's own.
-//   see hooks.test.ts › "runs the checks in the project root, so a check reading the tree sees the session project"
-//   see hooks.test.ts › "asks "is the tree clean?" about the project, not about the cwd"
-//   see hooks.test.ts › "names the tree it measured in the refusal, so a foreign failure is visible at a glance"
+//   see hooks.test.ts (absent in a generated rig) › "runs the checks in the project root, so a check reading the tree sees the session project"
+//   see hooks.test.ts (absent in a generated rig) › "asks "is the tree clean?" about the project, not about the cwd"
+//   see hooks.test.ts (absent in a generated rig) › "names the tree it measured in the refusal, so a foreign failure is visible at a glance"
 const projectRootOf = () => realpathSync(fileURLToPath(new URL('../..', import.meta.url)));
 
 // The default total budget, and the allowance for everything that happens
@@ -100,8 +101,8 @@ const projectRootOf = () => realpathSync(fileURLToPath(new URL('../..', import.m
 // So the preamble gets a number and a leash: `git status` below is given this
 // as its own timeout, which turns the allowance from a guess into a bound.
 // Both numbers are read from this file and compared against the wiring —
-//   see hooks.test.ts › "gives the stop gate a harness timeout its own budget finishes inside"
-//   see hooks.test.ts › "bounds its own preamble: the git status call carries a timeout derived from the declared margin"
+//   see hooks.test.ts (absent in a generated rig) › "gives the stop gate a harness timeout its own budget finishes inside"
+//   see hooks.test.ts (absent in a generated rig) › "bounds its own preamble: the git status call carries a timeout derived from the declared margin"
 const DEFAULT_BUDGET_MS = 600_000;
 const PREAMBLE_MARGIN_MS = 60_000;
 
@@ -137,7 +138,7 @@ const SPAWN_NEVER_STARTED = new Set(['ENOENT', 'EACCES', 'EPERM', 'EMFILE', 'ENF
  * it. `Number.isSafeInteger` is the test rather than `isFinite`, because
  * `spawnSync` throws on a fractional `timeout` — and a throw here would land in
  * the backstop and open the gate completely.
- *   see hooks.test.ts › "runs the gate on the default budget when the override is unusable, instead of not running it"
+ *   see hooks.test.ts (absent in a generated rig) › "runs the gate on the default budget when the override is unusable, instead of not running it"
  */
 function budgetMs(env) {
   const raw = env.RIG_DOD_BUDGET_MS;
@@ -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;
 
@@ -235,13 +232,13 @@ function main() {
   // still ended green. Both were shipped here, one after the other, and both
   // are closed the same way — every usable entry runs, and a skipped entry is
   // a check with no verdict, which blocks.
-  //   see hooks.test.ts › "never lets an unusable config entry hide a failing check behind it (an empty string)"
-  //   see hooks.test.ts › "refuses the stop for an empty config entry it skipped, even though every check it could run passed"
+  //   see hooks.test.ts (absent in a generated rig) › "never lets an unusable config entry hide a failing check behind it (an empty string)"
+  //   see hooks.test.ts (absent in a generated rig) › "refuses the stop for an empty config entry it skipped, even though every check it could run passed"
   //
   // The predicate is exactly the three shapes `spawnSync` throws on, and no
   // wider: the shell answers every other unrunnable string with 127, which is
   // a verdict. Filtering past these three converts a real block into a skip.
-  //   see hooks.test.ts › "refuses the stop for a config it could read but cannot use, and names the file to fix"
+  //   see hooks.test.ts (absent in a generated rig) › "refuses the stop for a config it could read but cannot use, and names the file to fix"
   const runnable = (command) =>
     typeof command === 'string' && command !== '' && !command.includes('\0');
   const usable = checks.filter(runnable);

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

@@ -24,7 +24,8 @@
 //
 // ── The limits, stated exactly — and TESTED ──────────────────────────────────
 //
-// This block is a credibility claim, so `test/template/guard-hardening.test.ts`
+// This block is a credibility claim, so the generator's
+// `test/template/guard-hardening.test.ts` (absent in a generated rig)
 // asserts each line twice: that the limit is documented here, and that the
 // command really does pass. A limits comment nothing checks drifts into fiction,
 // which is what happened the first time — an earlier version of this list was
@@ -76,9 +77,10 @@
 // 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';
+import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { brakeIsOn } from '../scripts/stop-flag.mjs';
+import { readHookInput } from './lib/hook-input.mjs';
 
 /** Branches that are shared by definition. */
 const PROTECTED_BRANCH = /^(main|master|develop|development|trunk)$/;
@@ -803,12 +805,8 @@ 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;
   if (input.tool_name !== 'Bash') return 0;
   const commandValue = input.tool_input?.command;
   if (typeof commandValue !== 'string') return 0;

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

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