create-agent-rig 0.7.1 → 0.9.0

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,13 +156,47 @@ 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 — 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
+rulebook is refused unless its
+path starts with an allowed prefix. 🔴 **Which paths that covers is
+`RULEBOOK_PREFIXES` in `.claude/scripts/unattended-flag.mjs`** — read it before
+composing an allow-list, rather than working from a summary here. A summary is a
+second copy, and the one that used to sit in this sentence had gone stale against
+the set it described. One fact the set cannot carry, so it is stated: 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

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

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

@@ -49,9 +49,73 @@ const MAX_PATCH_SECTIONS = 128;
 const MAX_MULTI_EDITS = 256;
 const MAX_PATCH_PATH_COMPONENTS = 512;
 
+/**
+ * The surfaces this normaliser answers for. A tool outside the set is one the
+ * hook does not understand, and the refusal below must not reach it: a guard
+ * that blocks payloads it was never asked about is a guard that gets deleted.
+ */
+const EDIT_TOOL_NAMES = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'apply_patch']);
+
+/**
+ * The one refusal for a container this file cannot read, on every surface it
+ * owns. `apply_patch` keeps its own wording because the shape it expects is a
+ * different shape — a patch string — and a remedy naming an object would be
+ * advice its caller cannot act on.
+ */
+const unreadableToolInput = (toolName) =>
+  toolName === 'apply_patch'
+    ? {
+        filePath: '',
+        fragment: '',
+        inspectionRefusal:
+          'the apply_patch command arrived in a shape this guard cannot read — it is a ' +
+          'string, or a list of strings, and nothing else. Nothing was inspected, so ' +
+          'nothing about this patch is vouched for.',
+        remedy: 'Send the command as a patch string, or a list of strings.',
+        appliesToAll: true,
+      }
+    : {
+        filePath: '',
+        fragment: '',
+        inspectionRefusal:
+          'the tool_input arrived in a shape this guard cannot read — it is an object ' +
+          'carrying the edit fields, and nothing else. Nothing was inspected, so nothing ' +
+          'about this edit is vouched for.',
+        remedy: 'Send the tool_input as an object carrying the edit fields.',
+        appliesToAll: true,
+      };
+
 export function editFragments(input) {
   const toolName = input?.tool_name;
-  const toolInput = input?.tool_input ?? {};
+  const rawToolInput = input?.tool_input;
+  // 🔴 **"I could not look" is not "there was nothing to look at" — and this
+  // file used to answer both ways depending on which arm you reached.**
+  // `?? {}` substitutes only for null/undefined, so a `tool_input` PRESENT as a
+  // string, a number or an array flowed on as that value: every field read came
+  // back `undefined`, and the Write/Edit/NotebookEdit arms returned a fragment
+  // with an empty path and empty text — which every consuming guard reads as a
+  // clean edit. Measured on master `6589db36`: a `tool_input` that is a string
+  // carrying a credential exited 0 through Write, Edit, MultiEdit and
+  // NotebookEdit, while the SAME shape through `apply_patch` exited 2. The
+  // divergence was between arms of this one file, which is why the contract
+  // belongs here rather than in each guard (RP-85, applying RP-80's ruling).
+  //
+  // ⚠ **ABSENT stays fail-open, and the difference is the whole rule.**
+  // `.claude/rules/invariants.md`: a field that is simply absent is the case the
+  // guard has nothing to judge — it must allow, exactly as a `Write` carrying no
+  // content does. A field PRESENT in a shape the guard does not accept is the
+  // case where it was handed something and could tell it could not read it,
+  // which is the one thing reporting is for. Getting these backwards costs a
+  // credential in either direction.
+  if (
+    EDIT_TOOL_NAMES.has(toolName) &&
+    rawToolInput !== null &&
+    rawToolInput !== undefined &&
+    (typeof rawToolInput !== 'object' || Array.isArray(rawToolInput))
+  ) {
+    return [unreadableToolInput(toolName)];
+  }
+  const toolInput = rawToolInput ?? {};
   if (toolName === 'Write' || toolName === 'Edit') {
     return [
       {
@@ -107,21 +171,10 @@ export function editFragments(input) {
   // they exited 1 with a stack trace, which neither harness treats as blocking, so
   // a crash here was an ALLOW. A `tool_input` that is not an object is the same
   // case as a `command` whose container this guard cannot read: detected, not
-  // readable, refused.
-  if (typeof toolInput !== 'object' || toolInput === null || Array.isArray(toolInput)) {
-    return [
-      {
-        filePath: '',
-        fragment: '',
-        inspectionRefusal:
-          'the apply_patch command arrived in a shape this guard cannot read — it is a ' +
-          'string, or a list of strings, and nothing else. Nothing was inspected, so ' +
-          'nothing about this patch is vouched for.',
-        remedy: 'Send the command as a patch string, or a list of strings.',
-        appliesToAll: true,
-      },
-    ];
-  }
+  // readable, refused. That check used to sit HERE, guarding this one arm; it is
+  // now the first thing `editFragments` does, for every surface in
+  // `EDIT_TOOL_NAMES`, so `toolInput` is an object by the time this line runs and
+  // `in` cannot throw (RP-85). One mechanism, one implementation.
   if (!('command' in toolInput)) return [];
   if (
     typeof rawCommand !== 'string' &&
@@ -140,22 +193,12 @@ export function editFragments(input) {
     // "a crashed guard that blocks everything gets deleted within the hour" —
     // and this branch is neither. Two opposite answers to one question, ten
     // lines apart, was the real defect.
-    return [
-      {
-        filePath: '',
-        fragment: '',
-        inspectionRefusal:
-          'the apply_patch command arrived in a shape this guard cannot read — it is a ' +
-          'string, or a list of strings, and nothing else. Nothing was inspected, so ' +
-          'nothing about this patch is vouched for.',
-        // 🔴 The remedy travels WITH the refusal that earns it. It was chosen by
-        // `/shape/i.test(reason)` in six copies — correct only by coincidence of
-        // wording, so rewording the reason silently restored the retry loop this
-        // remedy exists to replace. One field, one place.
-        remedy: 'Send the command as a patch string, or a list of strings.',
-        appliesToAll: true,
-      },
-    ];
+    // 🔴 The remedy travels WITH the refusal that earns it. It was chosen by
+    // `/shape/i.test(reason)` in six copies — correct only by coincidence of
+    // wording, so rewording the reason silently restored the retry loop this
+    // remedy exists to replace. One field, one place — and since RP-85 that
+    // place is `unreadableToolInput`, shared with the four edit surfaces.
+    return [unreadableToolInput(toolName)];
   }
   const command = typeof rawCommand === 'string' ? rawCommand : rawCommand.join('\n');
   if (command.length > MAX_PATCH_CHARACTERS) {

package/templates/agent-os/universal/.claude/hooks/warn-subagent-routing.mjs

@@ -0,0 +1,120 @@
+// SessionStart hook (Claude Code): says out loud when this session's
+// environment may keep the pinned subagent routing from holding.
+//
+// The pins live in each agent definition (`model:`, `effort:`) and in the
+// shipped settings (`env.CLAUDE_CODE_SUBAGENT_MODEL`). Four conditions are
+// invisible from inside the rulebook, and each is reported:
+// - CLAUDE_CODE_SUBAGENT_MODEL_FORCE is set: Claude Code applies one model to
+//   every subagent and ignores each definition's `model:` (its 2.1.257
+//   changelog);
+// - CLAUDE_CODE_EFFORT_LEVEL is set: its level replaced a definition's
+//   `effort:` in a live run — the generator's docs/capability-evidence.json
+//   (absent in a generated rig), mechanism `subagent-effort-pin`, surface
+//   `environment: CLAUDE_CODE_EFFORT_LEVEL=low`;
+// - Claude Code is older than MINIMUM_CLAUDE_CODE_VERSION: until 2.1.251,
+//   CLAUDE_CODE_SUBAGENT_MODEL overrode an agent definition's `model:` (its
+//   2.1.251 changelog), so the shipped unnamed default replaced every model pin;
+// - the version cannot be read: then whether the pins hold cannot be confirmed.
+//
+// The version is read from AI_AGENT, which Claude Code sets for its subprocesses
+// (its 2.1.120 changelog) and which a SessionStart hook's environment was
+// observed to carry (the same evidence file, mechanism
+// `claude-code-version-signal`). Its shape,
+// `claude-code_<major>-<minor>-<patch>_<role>`, is observed and not documented —
+// so a value this hook cannot parse is reported as an unknown version, never
+// taken for a supported one.
+//
+// It warns and never blocks: exit 0 always, the warning on stdout, which Claude
+// Code adds to the session's context at SessionStart. An empty variable counts
+// as unset. The rationale is docs/decisions/subagent-routing.md.
+//
+// Pinned in the generator's test/template/subagent-routing-hooks.test.ts
+// (absent in a generated rig) › "warns when %s is set, and never blocks the
+// session", › "warns on a Claude Code older than 2.1.251 and names the minimum"
+// and › "warns that it could not determine the version when %s".
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { readHookInput } from './lib/hook-input.mjs';
+
+/** The first Claude Code release in which an agent definition's `model:` outranks the env default. */
+export const MINIMUM_CLAUDE_CODE_VERSION = '2.1.251';
+
+const PIN_REPLACING_VARIABLES = [
+  [
+    'CLAUDE_CODE_SUBAGENT_MODEL_FORCE',
+    "replaces the `model:` every agent definition pins with one model for all subagents",
+  ],
+  ['CLAUDE_CODE_EFFORT_LEVEL', "replaces the `effort:` every agent definition pins with its own level"],
+];
+
+const VERSION = /^claude-code_(\d{1,6})-(\d{1,6})-(\d{1,6})(?:_|$)/;
+
+const numbers = (version) => version.split('.').map(Number);
+
+const olderThan = (found, minimum) => {
+  for (let index = 0; index < minimum.length; index += 1) {
+    if (found[index] !== minimum[index]) return found[index] < minimum[index];
+  }
+  return false;
+};
+
+/** Every routing problem this environment has, as sentences; empty when there is none. */
+export function routingProblems(env) {
+  const problems = [];
+  for (const [variable, effect] of PIN_REPLACING_VARIABLES) {
+    const value = env[variable];
+    if (typeof value === 'string' && value !== '') {
+      problems.push(`${variable} is set: it ${effect}. Unset it for those pins to hold.`);
+    }
+  }
+  const agent = typeof env.AI_AGENT === 'string' ? VERSION.exec(env.AI_AGENT) : null;
+  if (agent === null) {
+    problems.push(
+      `could not determine the Claude Code version from AI_AGENT, so it cannot be confirmed ` +
+        `that the model pins hold: they need Claude Code ${MINIMUM_CLAUDE_CODE_VERSION} or later.`,
+    );
+  } else {
+    const found = [Number(agent[1]), Number(agent[2]), Number(agent[3])];
+    if (olderThan(found, numbers(MINIMUM_CLAUDE_CODE_VERSION))) {
+      problems.push(
+        `Claude Code ${found.join('.')} is older than ${MINIMUM_CLAUDE_CODE_VERSION}: before it, ` +
+          "CLAUDE_CODE_SUBAGENT_MODEL overrides every agent definition's `model:`. Upgrade Claude Code.",
+      );
+    }
+  }
+  return problems;
+}
+
+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() {
+  try {
+    const input = readHookInput();
+    if (input === null || input.hook_event_name !== 'SessionStart') return 0;
+    const problems = routingProblems(process.env);
+    if (problems.length === 0) return 0;
+    process.stdout.write(
+      '[agent-os] WARNING — the pinned subagent routing may not hold in this session:\n' +
+        problems.map((problem) => `- ${problem}`).join('\n') +
+        '\nA gate may run on a model or effort the routing policy did not choose ' +
+        '(docs/decisions/subagent-routing.md).\n',
+    );
+  } catch {
+    // a broken warning must never make the session unusable
+  }
+  return 0;
+}
+
+if (invokedDirectly()) {
+  process.exit(main());
+}

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

@@ -99,7 +99,7 @@ own cost figures are read next to the lane they do not cover.
   `MultiEdit`, `NotebookEdit`, or `apply_patch` that names a credential file or carries a credential value,
   reading its vocabulary from `.claude/scripts/lib/secrets.mjs`. ⚠ **Only that
   part.** The hook sees what an agent writes through those five tools and
-  nothing else — its own header states the four blind spots — so whether a
+  nothing else — its own header states its blind spots — so whether a
   credential typed by a human, or committed from disk, is also refused depends
   on whether this project has a commit-time check. Look at `.husky/` and the CI
   workflow; this file cannot tell you, and a
@@ -108,15 +108,25 @@ own cost figures are read next to the lane they do not cover.
   at runtime instead of writing it out, or the check reports its own test data as
   a leak.
 - touch production data outside a reviewed migration
-- edit the rulebook from an **unattended** run outside the item's allow-list — `guard-rulebook` refuses it.
-  The rulebook is both harnesses' instruction, agent, skill, script and hook
-  trees (`CLAUDE.md`, `AGENTS.md`, `.claude/{agents,hooks,rules,scripts,skills}`,
-  `.agents/`, `.codex/`), plus `.claude/settings.json`, the queue config and its
-  always-refused board selector, and the integrity manifest. Mechanical:
+- edit the rulebook from an **unattended** run outside the item's allow-list — `guard-rulebook` refuses it,
+  and the checkout board selector is refused **even when the item's allow-list
+  names it**; that one carve-out does not follow from the set below.
+  The rulebook is both harnesses' instruction, rule, agent, skill, script and
+  hook trees, plus the settings, queue, exemption and integrity files that decide
+  what a session may do. **Which paths exactly is not restated here**: the
+  mechanism reads them from `RULEBOOK_PREFIXES` in
+  `.claude/scripts/unattended-flag.mjs`, and so should you — the guard judges an
+  edit against it, and the flag writer refuses an allow entry that *widens* it.
+  Which entries those are is `isWidening`'s answer in that same module, not a
+  paraphrase here: pinned in the generator's `unattended-flag.test.ts` — absent
+  in a generated rig — › "explains exact protected-prefix refusal separately
+  from proper-prefix widening". An entry
+  outside the set — ordinary source — is not widening and is accepted. A second
+  copy in prose is a copy that goes stale, and this one did. Mechanical:
   the hook refuses the edit while the unattended flag the `loop` skill writes
   at claim time is on disk (`.claude/scripts/unattended-flag.mjs`), and does
   nothing in an attended session. ⚠ It sees edit tool calls only — a
-  shell redirect into `.claude/settings.json` is not one — and the flag, not
+  shell redirect into a protected file is not one — and the flag, not
   the run, is what arms it; its header states the rest of its limits.
 
 ## Stop rules — by work-state, not by feelings

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

@@ -38,6 +38,11 @@ subagent with a fresh context, and why the `pr-ship` gate fans reviewers out
 instead of self-checking. This isolation is load-bearing, not ceremony — do
 not "optimise" it away by reviewing in the authoring session.
 
+A reviewer whose definition pins its model is never dispatched with a call-site
+`model`: which model reads a change is the routing policy's decision, not the
+dispatching session's, and `guard-subagent-model` refuses the override
+(`docs/decisions/subagent-routing.md`).
+
 ## PR flow
 
 This applies **once the project has a remote and CI checks** — a freshly