create-agent-rig 0.8.0 → 0.9.1

package/packages/cli/dist/policy/core/vocabulary.js

@@ -16,9 +16,13 @@
 const closed = (values) => Object.freeze(values);
 /**
  * Whether a declared policy can actually be enforced on a given harness
- * surface. `UNSUPPORTED` and `INTEGRATION-FAILED` never yield a silent pass:
- * a decision record carrying either must qualify its verdict `UNVERIFIABLE`
- * (`./decision-record.ts`). The four states are defined here.
+ * surface. `UNSUPPORTED` and `INTEGRATION-FAILED` must never yield a silent
+ * pass: a decision record carrying either has to qualify its verdict
+ * `UNVERIFIABLE` (`./decision-record.ts`). The four states are defined here.
+ *
+ * ⚠ That is the rule, and the enforcement behind it is narrower than the rule
+ * — see `UNENFORCEABLE_STATES` below, which states the gap once for every
+ * reader of this file.
  */
 export const CAPABILITY_STATES = closed([
     'SUPPORTED',
@@ -26,6 +30,69 @@ export const CAPABILITY_STATES = closed([
     'UNSUPPORTED',
     'INTEGRATION-FAILED',
 ]);
+/**
+ * The states under which no question was actually put to a working mechanism.
+ *
+ * One spelling of one fact (`rules/invariants.md`, "One mechanism, one
+ * implementation"): `./decision-record.ts` refuses an unqualified verdict
+ * carrying one of these, and `./coverage.ts` › `qualifierFor` returns
+ * `UNVERIFIABLE` for exactly the same set. Two copies would disagree, and the
+ * one nobody is looking at would be the one that let a silent pass through.
+ *
+ * ⚠ **"Refuses" now holds against a hand-built prototype too** — this note used
+ * to say the opposite, and this is the file a reader auditing that question
+ * lands on first, so it is corrected here rather than only where the fix landed.
+ * `./decision-record.ts` used to decide whether a verdict carries a qualifier
+ * with the `in` operator, so a verdict INHERITING one satisfied the check and
+ * then serialised without it. RP-153 closed that: every field of both
+ * `./decision-record.ts` and `./declaration.ts` is read through
+ * `carriesField`/`ownField`, the way `./probe.ts` and `./evidence-matrix.ts`
+ * already read theirs, and both uncarried shapes are pinned in
+ * `packages/cli/test/policy-declaration.test.ts` › "refuses an UNSUPPORTED
+ * record whose verdict qualifier is %s, because what it writes out is a silent
+ * pass" — `%s` as the `it.each` case declares it, so one grep lands on it.
+ *
+ * What remains is narrower and is NOT this sentence's subject: a value carrying
+ * a live accessor is validated on one read and serialised from another (RP-157),
+ * and an array HOLE serialises as `null` while the two `forEach` loops in
+ * `./decision-record.ts` skip it (RP-161) — those two only, since `members` in
+ * `./validation.ts` and `./probe.ts` iterate with `for…of`, which sees a hole as
+ * `undefined` and refuses it. `docs/decisions/capability-coverage.md`, "What
+ * this does NOT do", carries the current limits at length.
+ *
+ * It is deliberately NOT derived from a rank or an ordering. `coverage.ts`
+ * carries an enforcement ordering for deciding what counts as a downgrade;
+ * keying verdict qualification off that would mean a future re-rank silently
+ * changed which verdicts are unverifiable.
+ */
+export const UNENFORCEABLE_STATES = closed(['UNSUPPORTED', 'INTEGRATION-FAILED']);
+/**
+ * The two ways a capability status is established, and the only two.
+ *
+ * `probe` is one active read of the surface's own wiring, taken when the
+ * surface changes (`PROBE_TRIGGERS`). `traffic` is passive: an operation that
+ * was expected to produce an observable signal, and what it actually produced.
+ * There is deliberately no third source meaning "time passed" — silence is
+ * absence of evidence, not evidence of absence.
+ */
+export const VERIFICATION_SOURCES = closed(['probe', 'traffic']);
+/**
+ * The occasions on which a surface is probed. Every member is an event on the
+ * surface; none of them is an interval.
+ *
+ * What this vocabulary does, exactly: `./coverage.ts` › `coverageFromProbe`
+ * takes a trigger as a required argument and refuses a word outside this list,
+ * so a probe must NAME its occasion and cannot name a schedule — ›
+ * "refuses the trigger %j, because the coverage contract accepts only a
+ * declared surface-change trigger".
+ *
+ * ⚠ What it does NOT do, stated because an earlier draft of this comment
+ * claimed it: nothing here stops a caller passing `'upgrade'` on a timer. The
+ * check refuses a LABEL outside the vocabulary, not the practice of probing
+ * periodically. `docs/decisions/capability-coverage.md` §1 says the same, and
+ * this file used to contradict it.
+ */
+export const PROBE_TRIGGERS = closed(['install', 'upgrade', 'registration', 'reconnect']);
 /** The autonomy tiers of `rules/autonomy.md`; `never` is the tier the guards enforce. */
 export const AUTONOMY_TIERS = closed(['tier-0', 'tier-1', 'tier-2', 'never']);
 /** The operations a policy can apply to, named by what the agent does, not by a tool. */

package/packages/cli/dist/policy/harness/claude.js

@@ -19,7 +19,7 @@
  * shipped scripts, and `test/template/shell-tools.test.ts` holds that
  * correspondence.
  */
-import { SHARED_HOOKS_DIR } from './shared-hooks.js';
+import { SHARED_HOOK_ROOT_ENV, SHARED_HOOKS_DIR } from './shared-hooks.js';
 const EVENT_OF = {
     'before-operation': 'PreToolUse',
 };
@@ -31,6 +31,14 @@ export const nativeSurfaceOf = (policy) => ({
     event: EVENT_OF[policy.timing],
     matcher: policy.operations.map((operation) => MATCHER_OF[operation]).join('|'),
     hookPath: `${SHARED_HOOKS_DIR}/${policy.mechanism}.mjs`,
+    // The exact command this harness generates for a hook. The probe compares
+    // against this rather than parsing what it finds, so this string and the one
+    // in the shipped snapshot must agree — pinned in both directions by
+    // `test/template/policy-coverage.test.ts` (absent in a generated rig) ›
+    // "the %s snapshot wires %s with exactly the command that adapter generates".
+    commands: {
+        command: [`node "$${SHARED_HOOK_ROOT_ENV}/${SHARED_HOOKS_DIR}/${policy.mechanism}.mjs"`],
+    },
 });
 export const claudeAdapter = Object.freeze({
     harness: 'claude',

package/packages/cli/dist/policy/harness/codex.js

@@ -20,7 +20,7 @@
  * restated, for the same reason the snapshot is derived rather than
  * hand-written: one spelling of one fact.
  */
-import { SHARED_HOOKS_DIR } from './shared-hooks.js';
+import { SHARED_HOOK_ROOT_ENV, SHARED_HOOKS_DIR } from './shared-hooks.js';
 const EVENT_OF = {
     'before-operation': 'PreToolUse',
 };
@@ -28,10 +28,57 @@ const MATCHER_OF = {
     'file-edit': 'Write|Edit|MultiEdit|NotebookEdit|apply_patch',
     'shell-command': 'Bash|PowerShell',
 };
+/**
+ * The Windows spelling this harness generates for a hook.
+ *
+ * ⚠ A SECOND implementation of the wrapper that `scripts/sync-codex-adapter.mjs`
+ * writes into the shipped file, and deliberately so: that script is a build tool
+ * outside the published package, and this module may not import it. The two are
+ * held equal by a correspondence check that goes red in BOTH directions —
+ * `test/template/policy-coverage.test.ts` (absent in a generated rig) › "the %s
+ * snapshot wires %s with exactly the spelling that adapter generates, in every
+ * field it generates one for" — which is what `rules/invariants.md` ("One
+ * mechanism, one implementation") requires of a copy that has to stay.
+ *
+ * The wrapper exists because PowerShell owns its stdin, so the hook would
+ * receive an empty stream; it copies the original bytes into the child instead
+ * of re-encoding them.
+ */
+const windowsCommand = (hookPath) => {
+    const script = [
+        "$ErrorActionPreference = 'Stop'",
+        '$repoRoot = git rev-parse --show-toplevel',
+        'if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }',
+        `$env:${SHARED_HOOK_ROOT_ENV} = $repoRoot`,
+        `$hookPath = Join-Path $repoRoot '${hookPath}'`,
+        '$startInfo = New-Object System.Diagnostics.ProcessStartInfo',
+        "$startInfo.FileName = 'node'",
+        "$startInfo.Arguments = '\"' + $hookPath + '\"'",
+        '$startInfo.UseShellExecute = $false',
+        '$startInfo.RedirectStandardInput = $true',
+        '$child = [System.Diagnostics.Process]::Start($startInfo)',
+        '[Console]::OpenStandardInput().CopyTo($child.StandardInput.BaseStream)',
+        '$child.StandardInput.Close()',
+        '$child.WaitForExit()',
+        'exit $child.ExitCode',
+    ].join('; ');
+    const encoded = Buffer.from(script, 'utf16le').toString('base64');
+    return `powershell.exe -NoProfile -NonInteractive -EncodedCommand ${encoded}`;
+};
 export const nativeSurfaceOf = (policy) => ({
     event: EVENT_OF[policy.timing],
     matcher: policy.operations.map((operation) => MATCHER_OF[operation]).join('|'),
     hookPath: `${SHARED_HOOKS_DIR}/${policy.mechanism}.mjs`,
+    // Both commands this harness generates. It runs the first on POSIX and the
+    // second on Windows, so the probe has to know both: replacing only the
+    // Windows spelling in the shipped file used to leave every policy reading
+    // SUPPORTED while the guard no longer ran there.
+    commands: {
+        command: [
+            `repoRoot="$(git rev-parse --show-toplevel)" && ${SHARED_HOOK_ROOT_ENV}="$repoRoot" node "$repoRoot/${SHARED_HOOKS_DIR}/${policy.mechanism}.mjs"`,
+        ],
+        commandWindows: [windowsCommand(`${SHARED_HOOKS_DIR}/${policy.mechanism}.mjs`)],
+    },
 });
 export const codexAdapter = Object.freeze({
     harness: 'codex',

package/packages/cli/dist/policy/harness/shared-hooks.js

@@ -8,3 +8,21 @@
  * implementation").
  */
 export const SHARED_HOOKS_DIR = '.claude/hooks';
+/**
+ * The environment variable a shared hook reads when it needs the repository
+ * root, and therefore the one each harness sets when it runs one.
+ *
+ * Not every hook needs it: of the eight this rig ships, `guard-rulebook` and
+ * `guard-secret-file` read it, both falling back to the working directory.
+ * The variable is still part of the wiring contract, because the harness sets
+ * it for whichever hook it runs.
+ *
+ * It carries a harness's name for the same historical reason `.claude/hooks`
+ * does — the hooks are shared, so both harnesses speak this one variable — and
+ * this module is the one adapter-side file allowed to spell that name for both
+ * (`test/template/policy-declaration.test.ts` › "claude is named only by its
+ * own adapter, the shared hooks directory and the adapter index"). Stating it
+ * here is what lets the other harness's adapter build its generated command
+ * without naming a harness that is not its own.
+ */
+export const SHARED_HOOK_ROOT_ENV = 'CLAUDE_PROJECT_DIR';

package/packages/cli/dist/policy/index.js

@@ -1,10 +1,17 @@
 /**
  * The policy declaration, registry, decision-record schema and harness
- * adapters (RP-76). Library surface only — nothing here is reached by the CLI
- * commands yet; emitting decision records at runtime is a separate task.
+ * adapters (RP-76), plus the capability & degradation contract that says what
+ * each of them is worth on a given surface (RP-36).
+ *
+ * Library surface only — nothing here is reached by the CLI commands yet;
+ * emitting decision records at runtime, and rendering the coverage report in
+ * `doctor`, are separate tasks.
  */
 export * from './core/vocabulary.js';
 export * from './core/declaration.js';
 export * from './core/registry.js';
 export * from './core/decision-record.js';
+export * from './core/probe.js';
+export * from './core/coverage.js';
+export * from './core/evidence-matrix.js';
 export * from './harness/index.js';

package/templates/agent-os/stack/aws-cdk/.claude/agents/cdk-diff-reviewer.md

@@ -2,6 +2,8 @@
 name: cdk-diff-reviewer
 description: Reviews an infrastructure change via `cdk diff` BEFORE any deploy. MUST run on every change under infra/ — a deploy without this review is a Never-tier action. Read-only; findings gate the deploy.
 tools: Read, Grep, Glob, Bash
+model: claude-opus-5
+effort: high
 ---
 
 You review what a deploy would actually do to running infrastructure. Your

package/templates/agent-os/stack/aws-cdk/.codex/agents/cdk-diff-reviewer.toml

@@ -1,4 +1,6 @@
 name = "cdk-diff-reviewer"
 description = "Reviews an infrastructure change via `cdk diff` BEFORE any deploy. MUST run on every change under infra/ — a deploy without this review is a Never-tier action. Read-only; findings gate the deploy."
+model = "gpt-5.6-sol"
+model_reasoning_effort = "high"
 sandbox_mode = "read-only"
 developer_instructions = "You review what a deploy would actually do to running infrastructure. Your\ninput is the change under `infra/` **and** the synthesized diff (`cdk diff`,\nrun it yourself); your output is a verdict. You never fix and never deploy.\n\n## How you work\n\n1. Run `cdk diff` (and read the changed `infra/` sources for intent). The diff\n   is the truth: review what CloudFormation will do, not what the TypeScript\n   looks like it does.\n2. Walk every resource change and flag it **by named rule** (below). Findings\n   come as **BLOCKERS first, then nits** — one list each, with the resource\n   and the rule it violates.\n3. Your message IS the review, not a summary of it: every finding carries the\n   resource, the change, the rule, and the smallest fix. End with the verdict\n   block below — `SHIP` where `DEPLOY: OK` used to be, `HOLD` where\n   `DEPLOY: BLOCKED` did.\n\n## Named rules — blockers\n\n- **IAM broadening.** Any policy gaining actions, resources widening to `*`,\n  or a grant that outruns what a usecase does today. Least privilege is added\n  in the same PR as the need, never \"for later\".\n- **Data loss paths.** A stateful resource (table, bucket, queue) being\n  replaced, deleted, or flipping its RemovalPolicy toward DESTROY.\n  Logical-id renames on stateful resources are replacements in disguise.\n- **Safety-net removal.** A DLQ detached, an alarm deleted or loosened, a\n  retry budget widened to infinity, a dead-letter retention shortened.\n- **Blast-radius growth.** New public surface (endpoints, permissions to\n  external principals), broadened network access, cross-stack exports that\n  make future changes harder to reverse.\n- **Cost-relevant flips.** On-demand → provisioned capacity, log retention to\n  \"forever\", memory/timeout jumps with no stated reason.\n\n## Nits (report, do not block)\n\nNaming drift, missing descriptions, constructs that could use the narrower\ngrant helper, duplication between stacks.\n\n## Boundaries\n\n- Read-only: you run `cdk diff` and read code; you never run `cdk deploy`,\n  never edit files, never mutate AWS state.\n- An empty diff is a real finding too — say \"no infrastructure change\" and\n  return `SHIP`, so the gate leaves a trace either way.\n\n## The verdict block\n\nEnd your report with **exactly one** fenced `json` block of this shape, and\nnothing after it. It is what the calling gate reads.\n\n```json\n{\n  \"gate\": \"cdk-diff-reviewer\",\n  \"verdict\": \"HOLD\",\n  \"blockers\": [\n    {\n      \"file\": \"infra/lib/api-stack.ts\",\n      \"line\": 88,\n      \"rule\": \"data loss\",\n      \"note\": \"the table's RemovalPolicy went to DESTROY — replacement drops it\"\n    }\n  ],\n  \"advisories\": [],\n  \"evidence\": [\"cdk diff against the deployed stage\"],\n  \"headSha\": \"9c1f0a7d4b3e2c5a8f6d0b9e7c4a1f2d3e5b6c70\"\n}\n```\n\n- `verdict` is `SHIP` (nothing blocking, including an empty diff), `HOLD`, or\n  `NOT_APPLICABLE` when the change touches no infrastructure at all.\n- Every blocker names the `rule` it violates, with `file` and `line` when it has\n  a location and neither when it does not.\n- A `HOLD` naming no blocker is **refused**, and so is a `SHIP` carrying one:\n  `node .claude/scripts/verdict.mjs check <report> cdk-diff-reviewer` is what\n  refuses them.\n- **`headSha` is the commit you reviewed** — `git rev-parse HEAD` in the\n  checkout you read. It is what lets `node .claude/scripts/verdict.mjs coverage\n  <commit>` tell \"this gate answered for the commit being merged\" from \"it\n  answered two pushes ago\". A verdict naming no commit is counted as neither\n  covered nor missing, so `pr-ship` holds on it — and only `pr-ship`: no hook\n  runs that check, so a session that skips the gate skips this with it."

package/templates/agent-os/subagent-routing.json

@@ -0,0 +1,32 @@
+{
+  "claudeModels": {
+    "claude-opus-5": ["low", "medium", "high", "xhigh", "max"],
+    "claude-sonnet-5": ["low", "medium", "high", "xhigh", "max"]
+  },
+  "unnamed": {
+    "claude": { "model": "claude-sonnet-5" },
+    "codex": { "model": "gpt-5.6-terra", "effort": "medium" }
+  },
+  "roles": {
+    "test-writer": {
+      "claude": { "model": "claude-sonnet-5", "effort": "high" },
+      "codex": { "model": "gpt-5.6-terra", "effort": "high" }
+    },
+    "prose-reviewer": {
+      "claude": { "model": "claude-sonnet-5", "effort": "high" },
+      "codex": { "model": "gpt-5.6-terra", "effort": "high" }
+    },
+    "code-reviewer": {
+      "claude": { "model": "claude-opus-5", "effort": "high" },
+      "codex": { "model": "gpt-5.6-sol", "effort": "high" }
+    },
+    "security-scanner": {
+      "claude": { "model": "claude-opus-5", "effort": "high" },
+      "codex": { "model": "gpt-5.6-sol", "effort": "high" }
+    },
+    "cdk-diff-reviewer": {
+      "claude": { "model": "claude-opus-5", "effort": "high" },
+      "codex": { "model": "gpt-5.6-sol", "effort": "high" }
+    }
+  }
+}

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

@@ -79,16 +79,23 @@ state-vs-queue split exists to prevent.
 node .claude/scripts/preflight.mjs
 ```
 
-Five items are scripted (kill switch absent · `RIG_RUN_DIR` not already
-exported · the versioned revalidation detection contract is supported · local
-default branch matches the remote · the last deploy concluded successfully)
+Scripted checks cover the kill switch, inherited `RIG_RUN_DIR`, the versioned
+revalidation detection contract, queue readability through its configured adapter,
+default-branch freshness, and the last deploy result,
 and the script **prints the ones it did not check, every time**. Paste the block into the journal: a checklist that
 leaves no record cannot tell you it was skipped.
 
 Verdicts: **STOP** → do not start, deal with the cause. **CAUTION** → start,
-knowing which ground is soft. **GO** → the scripted five are clean; the rest are
+knowing which ground is soft. **GO** → the scripted checks are clean; the rest are
 still yours.
 
+The queue probe reads one adapter listing without selecting or claiming an item.
+A readable empty queue passes this probe; a configuration, adapter, or queue-read
+failure produces **STOP**. See the generator's `test/template/preflight-queue.test.ts`
+(absent in a generated rig) › "reads exactly one adapter listing without selecting, claiming, or writing queue and run files",
+› "passes a readable empty queue without changing the other preflight verdict or queue state",
+and › "stops when %s cannot be read".
+
 **An `unknown` never becomes a `pass`.** A probe that could not run tells you
 nothing.
 
@@ -149,8 +156,38 @@ What a hook CAN see is a file, so the unattended signal is one:
 # 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 --root "$PWD" --item <item-id> --run-dir "$RIG_RUN_DIR" --allow <prefix> [<prefix>…]
+
+# 🔴 THEN READ IT BACK, and stop the run if it is not armed. Not optional.
+node .claude/scripts/unattended-flag.mjs verify --root "$PWD" --item <item-id>
 ```
 
+🔴 **The second command is the one that makes the first one's failure
+visible, and skipping it inverts the whole mechanism.** `on` refuses an allow
+entry that *widens* the rulebook — and the refusal leaves **no flag on disk**
+(pinned in the generator's `test/template/unattended-flag.test.ts`, absent in a
+generated rig, › "does not change `on`: a widening --allow still exits 1 and
+still writes no flag"), while `guard-rulebook` reads an absent flag as an
+attended session and refuses nothing. So a run that armed with a widening entry and did not check is the
+**least** constrained run this project can produce: every rule, hook, skill and
+settings path editable, with nothing downstream saying so. The failure is loud
+for one line at claim time and silent for the rest of the session.
+
+`verify` exits non-zero when no usable flag is armed for this item — absent,
+unreadable, or naming a different item — and its message says the run is
+unguarded rather than merely that a file is missing. **A non-zero exit here ends
+the run**; it does not get retried with a wider allow-list. The natural way to
+hit this is not exotic: an item touching the queue adapter invites `--allow
+.claude/scripts/`, and that entry is refused outright. Pinned in the
+generator's `test/template/unattended-flag.test.ts` (absent in a generated rig)
+› "refuses when no flag is armed, naming the item and the unguarded rulebook"
+and › "refuses when the armed flag names a different item, naming both".
+
+⚠ **What this does not close.** `verify` is mechanical where it runs; that it
+runs is this sentence. It removes the silence, not the possibility that a run
+ignores an exit status — and the hook-enforced version is not available, because
+`guard-rulebook` cannot tell "attended" from "unattended but unarmed": absence of
+a flag is all it sees.
+
 `guard-rulebook` reads it (`.claude/rules/autonomy.md`, "Never"): with the flag
 on, a Write/Edit/MultiEdit/NotebookEdit/`apply_patch` under the generated
 rulebook is refused unless its

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

@@ -2,6 +2,8 @@
 name: code-reviewer
 description: Reviews a completed change against the checklist before a PR is opened or merged. Use after any non-trivial implementation work, and always before opening a PR the decision-router puts on its `model` lane, which is everything its two cheap lanes did not claim — code, a rulebook document, an unclassifiable path, a derived artifact git does not report as drift, or anything a risk flag escalated. Blocking findings must be resolved, not argued with.
 tools: Read, Grep, Glob, Bash
+model: claude-opus-5
+effort: high
 ---
 
 You review changes. You do not fix them — you report, with file:line

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

@@ -2,6 +2,8 @@
 name: prose-reviewer
 description: Reviews the documents that instruct agents — rule files, skills, agent specs, CLAUDE.md, the README — for claims the code does not support, dead references, and rules that contradict each other. Use when a change touches any of them, before the PR.
 tools: Read, Grep, Glob, Bash
+model: claude-sonnet-5
+effort: high
 ---
 
 In this project the prose **is** the implementation. A rule file is what an agent

package/templates/agent-os/universal/.claude/agents/security-scanner.md

@@ -2,6 +2,8 @@
 name: security-scanner
 description: Scans a change for security issues. MUST be used when a change touches authentication, authorization, secrets or configuration, input parsing, file handling, or any new outbound call. Findings gate the PR.
 tools: Read, Grep, Glob, Bash
+model: claude-opus-5
+effort: high
 ---
 
 You are the security gate. You run on changes in sensitive territory and your

package/templates/agent-os/universal/.claude/agents/test-writer.md

@@ -2,6 +2,8 @@
 name: test-writer
 description: Writes the failing test BEFORE any implementation exists. Use at the start of every feature, bug fix, or behavior change — the Red step of TDD. Also use to reproduce a reported bug as a test.
 tools: Read, Grep, Glob, Write, Edit, Bash
+model: claude-sonnet-5
+effort: high
 ---
 
 You write tests that define behavior which does not exist yet. You are the Red

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

@@ -0,0 +1,234 @@
+// PreToolUse hook (Claude Code's Agent tool): a subagent whose project
+// definition pins its model is never dispatched with a call-site `model`.
+//
+// Why it exists. Claude Code takes a subagent's model from the per-invocation
+// `model` parameter FIRST, and only then from the definition's `model:` line
+// (Claude Code's sub-agents documentation, "model resolution"). A pin is
+// therefore only as strong as every call site: the generator's
+// docs/capability-evidence.json (absent in a generated rig) records a pinned
+// agent that ran the call-site model instead — mechanism `subagent-model-pin`,
+// surface `Agent tool call-site model, without guard-subagent-model`. Which
+// model a role reads with is the routing policy's decision
+// (docs/decisions/subagent-routing.md), not one dispatch's.
+//
+// What "pinned" means here: `<project>/.claude/agents/<subagent_type>.md` is a
+// regular file whose leading frontmatter carries a `model:` line with a value
+// other than `inherit`. The project root is CLAUDE_PROJECT_DIR, else the working
+// directory. One leading byte-order mark is not content and is skipped.
+//
+// The three outcomes (.claude/rules/invariants.md):
+// - allow — nothing it can read, another event, no call-site model, or an
+//   ad-hoc subagent: no `subagent_type`, a built-in, a name that is not a plain
+//   file name (`plugin:agent`, `../x`), no such file, a path that is not a
+//   regular file (a directory, a FIFO — opened without waiting, never read), or
+//   no pin in it;
+// - block — a call-site model for a pinned agent;
+// - refuse to inspect — `model` or `subagent_type` PRESENT in a shape other
+//   than a string (resend it as one), or a frontmatter that does not close
+//   within MAX_HEAD_BYTES (a bound crossed).
+// An error opening or reading the agent file fails open, like every guard here.
+//
+// Bounded work: one non-blocking open, one fstat, one read of at most
+// MAX_HEAD_BYTES + 1 bytes, one frontmatter match, and one pass over its lines
+// with a prefix test per line. Nothing recurses or rescans.
+//
+// Limits, stated so nobody relies on cover that is not here:
+// - project agents only. A user-level or plugin agent that pins a model is not
+//   a role of this project, and its call-site model is allowed;
+// - the file is found by the dispatched name, so a project agent whose
+//   frontmatter `name` differs from its file name is not matched;
+// - `model:` is read as a frontmatter line, not through a YAML parser, so a pin
+//   spelled another YAML way (a quoted key) is not seen.
+// Pinned in the generator's test/template/subagent-routing-hooks.test.ts
+// (absent in a generated rig) › "blocks a call-site model on a project agent
+// that pins one, and says to re-dispatch without it", › "never resolves %s to a
+// project agent file, so the call is allowed", › "refuses an agent file whose
+// frontmatter does not close within the read bound, and names the bound", ›
+// "allows a call-site model without waiting when the agent path is not a regular
+// file", › "reads a pin in an agent file that starts with a byte-order mark", ›
+// "echoes a model pinned in the agent file bounded and escaped" (the bound) and
+// › "escapes a control byte inside the echoed part of both model names".
+import { closeSync, constants, fstatSync, openSync, readSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readHookInput } from './lib/hook-input.mjs';
+
+/** How much of an agent file is read to find its frontmatter. */
+export const MAX_HEAD_BYTES = 64 * 1024;
+
+/** How much of a model name a refusal repeats, from either side of the comparison. */
+const MAX_ECHOED_MODEL = 64;
+
+/** A name that can only ever be a file directly under `.claude/agents/`. */
+const AGENT_FILE_NAME = /^[A-Za-z0-9_-]{1,128}$/;
+
+/**
+ * Open without blocking: a FIFO at the agent path would otherwise hold the open
+ * until a writer appears. Windows has no such flag and no such file there.
+ */
+const OPEN_FLAGS = constants.O_RDONLY | (constants.O_NONBLOCK ?? 0);
+
+const ALLOW = Object.freeze({ outcome: 'allow' });
+
+/** 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}`;
+};
+
+/**
+ * A model name as a refusal may print it: at most MAX_ECHOED_MODEL characters,
+ * through JSON.stringify — which escapes C0 control bytes such as ESC, and
+ * leaves other non-ASCII characters (C1 controls, bidi overrides) as they are.
+ */
+const echoed = (model) => JSON.stringify(model.slice(0, MAX_ECHOED_MODEL));
+
+const unreadable = (field, value, expected) => ({
+  outcome: 'refuse',
+  message:
+    `BLOCKED — ${field} is present as ${shapeOf(value)}, and this guard reads ${expected}. ` +
+    'An input it cannot read is refused, never allowed: whether this dispatch overrides a ' +
+    'pinned model is decided by reading it (.claude/rules/invariants.md, "Refusing to ' +
+    `inspect is a third outcome"). Resend the Agent call with ${field} as ${expected}.`,
+});
+
+/**
+ * The first MAX_HEAD_BYTES of a regular file, and whether it went on past them;
+ * null when the path is absent, is not a regular file, or cannot be read.
+ */
+function readHead(file) {
+  let fd;
+  try {
+    fd = openSync(file, OPEN_FLAGS);
+    if (!fstatSync(fd).isFile()) return null;
+    const buffer = Buffer.alloc(MAX_HEAD_BYTES + 1);
+    let filled = 0;
+    while (filled < buffer.length) {
+      const read = readSync(fd, buffer, filled, buffer.length - filled, null);
+      if (read === 0) break;
+      filled += read;
+    }
+    return {
+      text: buffer.subarray(0, Math.min(filled, MAX_HEAD_BYTES)).toString('utf8'),
+      cut: filled > MAX_HEAD_BYTES,
+    };
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd);
+      } catch {
+        // nothing left to release
+      }
+    }
+  }
+}
+
+/**
+ * `{ kind: 'pinned', model }`, `{ kind: 'none' }`, or `{ kind: 'unbounded' }`
+ * when a frontmatter opens and does not close inside the bytes that were read.
+ */
+function pinOf({ text: raw, cut }) {
+  const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+  if (!/^---\r?\n/.test(text)) return { kind: 'none' };
+  // A head that was cut may end in the middle of a line, so only a closer
+  // followed by a newline counts there; an uncut head may end at the closer.
+  const closed = (
+    cut
+      ? /^---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n/
+      : /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/
+  ).exec(text);
+  if (!closed) return cut ? { kind: 'unbounded' } : { kind: 'none' };
+  for (const line of closed[1].split(/\r?\n/)) {
+    if (!line.startsWith('model:')) continue;
+    const value = line.slice('model:'.length).trim();
+    const quoted =
+      value.length >= 2 && (value[0] === '"' || value[0] === "'") && value.at(-1) === value[0];
+    const model = quoted ? value.slice(1, -1) : value;
+    return model !== '' && model !== 'inherit' ? { kind: 'pinned', model } : { kind: 'none' };
+  }
+  return { kind: 'none' };
+}
+
+/** The verdict for one hook payload, judged against the project at `root`. */
+export function judge(input, root) {
+  if (input === null || typeof input !== 'object' || input.hook_event_name !== 'PreToolUse') {
+    return ALLOW;
+  }
+  const toolInput = input.tool_input;
+  if (toolInput === undefined || toolInput === null) return ALLOW;
+  if (typeof toolInput !== 'object' || Array.isArray(toolInput)) {
+    return unreadable('tool_input', toolInput, 'an object');
+  }
+
+  const model = toolInput.model;
+  if (model === undefined || model === null) return ALLOW;
+  if (typeof model !== 'string') return unreadable('tool_input.model', model, 'a string');
+  if (model.trim() === '') return ALLOW;
+
+  const name = toolInput.subagent_type;
+  if (name === undefined || name === null) return ALLOW;
+  if (typeof name !== 'string') return unreadable('tool_input.subagent_type', name, 'a string');
+  if (!AGENT_FILE_NAME.test(name)) return ALLOW;
+
+  const relative = `.claude/agents/${name}.md`;
+  const head = readHead(path.join(root, '.claude', 'agents', `${name}.md`));
+  if (head === null) return ALLOW;
+  const pin = pinOf(head);
+  if (pin.kind === 'unbounded') {
+    return {
+      outcome: 'refuse',
+      message:
+        `BLOCKED — ${relative} opens a frontmatter that does not close within the first ` +
+        `${MAX_HEAD_BYTES} bytes, the limit this guard reads, so it cannot tell whether ` +
+        `\`${name}\` pins its model. Close the frontmatter near the top of the file, or ` +
+        're-dispatch without `model`.',
+    };
+  }
+  if (pin.kind !== 'pinned') return ALLOW;
+  return {
+    outcome: 'block',
+    message:
+      `BLOCKED — \`${name}\` pins its model in ${relative} (${echoed(pin.model)}), and this ` +
+      `dispatch passes model ${echoed(model)}, which Claude Code would run instead.\n` +
+      'Re-dispatch without `model`: the agent definition decides which model a role runs on. ' +
+      "Changing a role's model is a policy change — make it in the agent definition, in a " +
+      'reviewed change, never in one call (docs/decisions/subagent-routing.md).',
+  };
+}
+
+/**
+ * Whether this file is being run as a script rather than imported — the realpath
+ * on both sides, as `inject-rules.mjs` explains, so a symlinked checkout still runs.
+ */
+function invokedDirectly() {
+  if (!process.argv[1]) return false;
+  const real = (p) => {
+    try {
+      return realpathSync(p);
+    } catch {
+      return p;
+    }
+  };
+  return real(fileURLToPath(import.meta.url)) === real(process.argv[1]);
+}
+
+function main() {
+  let verdict;
+  try {
+    const input = readHookInput();
+    if (input === null) return 0;
+    verdict = judge(input, process.env.CLAUDE_PROJECT_DIR || process.cwd());
+  } catch {
+    return 0;
+  }
+  if (verdict.outcome === 'allow') return 0;
+  process.stderr.write(`${verdict.message}\n`);
+  return 2;
+}
+
+if (invokedDirectly()) {
+  process.exit(main());
+}