ruvnet-brain 3.9.134-dev → 4.0.2

package/plugin/scripts/md-stamp.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// plugin/scripts/md-stamp.mjs — PostToolUse (Write|Edit|MultiEdit). Refreshes an EXISTING doc
+// stamp's date to today, in-place, whenever a touched .md file's stamp has gone stale.
+//
+// WHY. The owner: "I told you to update all .md docs with time/date stamps when touched. I don't
+// want to have to remind you again in any repo." Today that convention lives only in the model's
+// memory — it forgets, in this repo and in every other one. This makes it a mechanism instead:
+// the date on a doc's own `Updated:` line (or an ADR/DDD frontmatter `updated:` key) is corrected
+// by the harness itself, the instant the file is touched, with zero model involvement.
+//
+// SCOPE, DELIBERATELY NARROW. This does not invent a stamp format (a file with none is left alone —
+// "only maintain existing stamps, never impose a format") and it does not implement ADR-034's larger
+// doc-currency system (governs:, verified:, digests, a currency log) — that is a separate, heavier,
+// push-time gate over docs/adr/ + docs/ddd/ (scripts/doc-currency.mjs). This hook is the small,
+// always-on half: keep the date people actually read from going stale, on every .md file in the repo.
+//
+// CONTRACT (matches every other advisory hook body in this dir): dispatched via hook-shim.mjs
+// (mode: advisory), fed the Claude Code tool-event JSON on stdin exactly like learn-capture.sh /
+// continuation-gate.mjs. ALWAYS exits 0 — a hook that can block a turn over a markdown date is a
+// hook that gets disabled within a day. On any parse/IO error: do nothing, exit 0, silently.
+//
+// IDEMPOTENCY IS THE WHOLE SAFETY ARGUMENT. A write here re-fires this same PostToolUse hook. If a
+// file already carries today's date, this script MUST NOT touch it — no write, byte-for-byte
+// identical — or every `Write`/`Edit` of an up-to-date doc would loop forever. Every code path below
+// is built around that: compute the new content, and only call fs.writeFileSync if it actually
+// differs from what's on disk.
+//
+// PURITY: node builtins only (fs, path, url) plus this dir's own hook-input.mjs (ADR-0021's shared,
+// tested payload parser) — no npm dependency, no shelling out.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseHookEvent, toolName, field, readStdinBounded } from './hook-input.mjs';
+
+// ── date, from the system clock, formatted in the repo's standard timezone ─────────────────────────
+// Same idiom as scripts/self-update.mjs's README badge stamp: Intl.DateTimeFormat is a Node builtin
+// (ICU is bundled), never a guessed/hardcoded string.
+// The date is computed in the MACHINE'S OWN timezone by default — this plugin ships to other
+// machines, and a user in Tokyo editing their own doc should get Tokyo's date, not New York's.
+// Overridable with RUVNET_MD_STAMP_TZ for anyone who wants their docs pinned to a fixed zone (e.g.
+// a team standardising on ET). Name kept `todayNY` for import stability; the "NY" is now only the
+// legacy default's ghost, not a hardcode. An invalid TZ value falls back to system-local, never throws.
+export function todayNY(now = new Date(), tz = process.env.RUVNET_MD_STAMP_TZ) {
+  const opts = { year: 'numeric', month: '2-digit', day: '2-digit' };
+  if (tz) opts.timeZone = tz;
+  let parts;
+  try { parts = new Intl.DateTimeFormat('en-CA', opts).formatToParts(now); }
+  catch { parts = new Intl.DateTimeFormat('en-CA', { year: 'numeric', month: '2-digit', day: '2-digit' }).formatToParts(now); }
+  const g = (t) => parts.find((p) => p.type === t)?.value || '';
+  return `${g('year')}-${g('month')}-${g('day')}`;
+}
+
+// ── the two known stamp conventions (grepped from this repo's real docs, not guessed) ──────────────
+//   1. Plain docs (README/SPEC/docs/*.md): a line near the top reading
+//        Updated: 2026-07-22 01:40:00 EDT | Version 1.0.0
+//      (sometimes backtick-wrapped, sometimes date-only, sometimes a trailing comment instead of a
+//      version — the DATE is the only part every observed variant shares, so it's the only part
+//      touched: time/TZ/version/comment text survive byte-for-byte).
+//   2. ADR/DDD YAML frontmatter: a bare `updated: 2026-07-22` key inside the leading `---` block.
+
+const PLAIN_UPDATED_RE = /^([ \t]*`?Updated:[ \t]*)(\d{4}-\d{2}-\d{2})/m;
+const FRONTMATTER_BLOCK_RE = /^---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n/;
+const FRONTMATTER_UPDATED_RE = /^(updated:[ \t]*)(\d{4}-\d{2}-\d{2})([ \t]*)$/m;
+
+// Real stamps in this repo sit on line 1-4 (README/SPEC/docs/*.md); 10 lines is generous headroom
+// without wandering into prose that merely discusses the convention (which never contains a real
+// date next to the literal capitalized word "Updated:", so the risk is already low — this is a
+// second, structural guard on top of that).
+const PLAIN_STAMP_MAX_LINES = 10;
+
+function headSlice(content, maxLines) {
+  let idx = 0;
+  for (let line = 0; line < maxLines; line++) {
+    const nl = content.indexOf('\n', idx);
+    if (nl === -1) return content; // whole file is shorter than the window
+    idx = nl + 1;
+  }
+  return content.slice(0, idx);
+}
+
+/** Refresh a plain `Updated: <date>...` line near the top of the file. No-op if absent/current. */
+function refreshPlainStamp(content, today) {
+  const head = headSlice(content, PLAIN_STAMP_MAX_LINES);
+  const m = head.match(PLAIN_UPDATED_RE);
+  if (!m || m[2] === today) return content;
+  const patchedHead = head.slice(0, m.index) + m[1] + today + head.slice(m.index + m[0].length);
+  return patchedHead + content.slice(head.length);
+}
+
+/** Refresh a bare `updated: <date>` key inside the leading YAML frontmatter block. No-op if absent/current. */
+function refreshFrontmatterStamp(content, today) {
+  const block = content.match(FRONTMATTER_BLOCK_RE);
+  if (!block || block.index !== 0) return content;
+  const um = block[0].match(FRONTMATTER_UPDATED_RE);
+  if (!um || um[2] === today) return content;
+  const patchedBlock =
+    block[0].slice(0, um.index) + um[1] + today + um[3] + block[0].slice(um.index + um[0].length);
+  return patchedBlock + content.slice(block[0].length);
+}
+
+// ── ENSURE (ADR-056 §2/§3, 2026-07-27) ───────────────────────────────────────────────────────────
+// Everything above only ever REFRESHES a stamp someone already wrote. That is deliberately half the
+// job, and the duel proved it is the WRONG half: a hook that fires on edit "never reaches a stale
+// file, by definition of stale" — the 166 unstamped files are unstamped precisely because nobody is
+// editing them. So there is a second entry point, used by the one-time sweep
+// (scripts/stamp-sweep.mjs) and available to the hook behind an explicit opt-in.
+//
+// PLACEMENT IS BY SHAPE, NEVER A LITERAL LINE 1. Five plugin/skills/*/SKILL.md files require YAML
+// frontmatter at line 1 for Claude Code's skill loader; a blind line-1 insert stops them loading. And
+// this ships to strangers, whose line 1 is load-bearing in ways this repo cannot enumerate.
+//
+// THE REFUSAL IS THE FEATURE. On any prologue we do not positively recognise, this returns the
+// content UNCHANGED. Silence is the correct output for a shape we do not understand — an insertion
+// that corrupts someone's document is far worse than a document without a date.
+
+const H1_RE = /^(#[^\n]*\r?\n)/;
+// A leading HTML comment, an MDX import/export, a Jekyll/Astro directive, a license banner: all
+// prologue shapes whose first line is load-bearing. We recognise them only well enough to REFUSE.
+const UNKNOWN_PROLOGUE_RE = /^\s*(<!--|<|import\s|export\s|\{\/\*|%%|\/\*|#!)/;
+
+/** Is this document safe to insert into, and where? Returns null when the answer is "do not touch". */
+export function stampInsertionPoint(content) {
+  if (FRONTMATTER_BLOCK_RE.test(content)) return { kind: 'frontmatter' };
+  if (UNKNOWN_PROLOGUE_RE.test(content)) return null;      // refuse — shape not understood
+  const h1 = content.match(H1_RE);
+  // After a leading `# Title` is where every stamped document in this repo actually puts it
+  // (DDD-0008, SPEC.md, the primer). Matching the house shape beats a pedantic line 1.
+  if (h1) return { kind: 'after-h1', index: h1[0].length };
+  return { kind: 'top', index: 0 };
+}
+
+// A THIRD stamp shape, found 2026-07-27: README carries its date inside a shields.io badge
+// ("version 3.9.85-dev — updated 2026-07-27 06:02 EDT"), maintained by self-update.mjs. Without
+// this, README reported "prologue shape not recognised" — a refusal that was RIGHT IN OUTCOME and
+// WRONG IN ITS REASON, which is precisely the class of accidental correctness this ADR exists to
+// end. Recognising it makes the report say the true thing: already stamped, leave it alone.
+// Deliberately narrow: the word `updated` adjacent to a date, inside a link/image, in the head.
+const BADGE_UPDATED_RE = /!?\[[^\]]*updated[_\s-]+\d{4}-{1,2}\d{2}-{1,2}\d{2}/i;
+
+/** Does this document already carry a stamp anywhere we would look? */
+export function hasStamp(content) {
+  const fm = content.match(FRONTMATTER_BLOCK_RE);
+  if (fm && fm.index === 0 && FRONTMATTER_UPDATED_RE.test(fm[0])) return true;
+  const head = headSlice(content, PLAIN_STAMP_MAX_LINES);
+  return PLAIN_UPDATED_RE.test(head) || BADGE_UPDATED_RE.test(head);
+}
+
+/**
+ * Pure. Insert a stamp when — and only when — the document has none and its shape is understood.
+ * `updated` is REQUIRED and must be derived by the caller (git), never defaulted to today: stamping
+ * an untouched file with today's date is the "false freshness" failure DDD-0008 invariant 4 names.
+ */
+export function ensureStamp(content, { updated, created } = {}) {
+  if (!updated || !/^\d{4}-\d{2}-\d{2}$/.test(updated)) return content;  // no derived date ⇒ no stamp
+  if (hasStamp(content)) return content;                                  // already stamped ⇒ never touch
+  const at = stampInsertionPoint(content);
+  if (!at) return content;                                                // shape refused
+
+  if (at.kind === 'frontmatter') {
+    // Frontmatter with no `updated:` key — add it INSIDE the block, never above it.
+    const block = content.match(FRONTMATTER_BLOCK_RE)[0];
+    const closing = block.lastIndexOf('---');
+    const line = `updated: ${updated}\n`;
+    return block.slice(0, closing) + line + block.slice(closing) + content.slice(block.length);
+  }
+
+  const stamp = created && /^\d{4}-\d{2}-\d{2}$/.test(created) && created !== updated
+    ? `\nUpdated: ${updated}\nCreated: ${created}\n`
+    : `\nUpdated: ${updated}\n`;
+  return content.slice(0, at.index) + stamp + content.slice(at.index);
+}
+
+/** Pure: given a .md file's current bytes, return the bytes it should have. Identical in ⇒ identical out. */
+export function computeStampedContent(content, today = todayNY()) {
+  return refreshPlainStamp(refreshFrontmatterStamp(content, today), today);
+}
+
+// ── the hook body ────────────────────────────────────────────────────────────────────────────────
+async function readHookInput() {
+  // Never block waiting on stdin: a TTY (someone running this file by hand) has none to give.
+  if (process.stdin.isTTY) return null;
+  try { return parseHookEvent((await readStdinBounded()).toString('utf8')); } catch { return null; }
+}
+
+async function main() {
+  // THE OFF SWITCH. This hook writes to the user's own files, so it must be silenceable in one move
+  // — the same "nothing without you" bar anticipate.sh's RUVNET_ANTICIPATE=0 meets. Set
+  // RUVNET_MD_STAMP=0 (or =off) and it becomes a no-op. Absence = on (it only ever refreshes a stamp
+  // the user already put there, never invents one), but the escape hatch exists and is honoured first.
+  const sw = String(process.env.RUVNET_MD_STAMP ?? '').trim().toLowerCase();
+  if (sw === '0' || sw === 'off' || sw === 'false' || sw === 'no') return;
+
+  const ev = await readHookInput();
+  if (!['Write', 'Edit', 'MultiEdit'].includes(toolName(ev))) return; // wrong tool: do nothing
+
+  const filePath = field(ev, 'tool_input.file_path');
+  if (!filePath || path.extname(filePath).toLowerCase() !== '.md') return; // wrong file: do nothing
+
+  let original;
+  try { original = fs.readFileSync(filePath, 'utf8'); } catch { return; } // unreadable/gone: exit 0
+
+  let stamped;
+  try { stamped = computeStampedContent(original); } catch { return; } // malformed content: exit 0
+
+  if (stamped === original) return; // already current (or no stamp at all) — NEVER write; loop guard
+
+  try { fs.writeFileSync(filePath, stamped); } catch { /* advisory — a failed write is not our problem */ }
+}
+
+function isMain() {
+  try { return process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url); }
+  catch { return false; }
+}
+
+if (isMain()) {
+  try { await main(); } catch { /* fail open, always — see CONTRACT above */ }
+  process.exit(0);
+}

package/plugin/scripts/protect-brain-state.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# protect-brain-state.sh — PreToolUse gate on Write|Edit|MultiEdit.
+# AN AGENT MAY NOT EDIT THE USER'S OWN CONSENT RECORD.
+#
+# ─────────────────────────────────────────────────────────────────────────────────────────────────
+# WHY (ADR-054 §3, Fable 5's single most pointed duel finding). The moment the brain can be switched
+# off, the switch becomes a thing an agent can switch back on. Every plane of the off contract is
+# built to keep the model from noticing the lever — search_ruvnet's soft answer deliberately omits
+# the re-enable mechanism, the session-start line is one dim sentence with no instruction attached —
+# but a prompt is advisory and this repo has learned twice over what advisory means. rUv states the
+# rule himself (@claude-flow/guidance, ADR-G007): "The model can forget a rule; the gate does not."
+#
+# So the paths that record the user's choice are walled off from the tools an agent writes with:
+#   • the sentinel        ~/.config/ruvnet-brain/brain-off   — the switch itself
+#   • the settings mirror ~/.config/ruvnet-brain/settings.json, and its .bak-*/.lock/.tmp-* siblings
+#     (a restore-from-backup or a lock-file trick is the same edit by another route)
+#
+# WHAT THIS DOES NOT CLAIM. It guards Write/Edit/MultiEdit, which is where an agent writes files. It
+# does NOT guard `rm` or `>` through Bash — that is a different matcher with a different parse and a
+# much larger false-positive surface, and pretending otherwise would be a bigger lie than the gap.
+# Stated plainly here rather than discovered later: this raises the cost of an accidental flip and
+# of a careless one; it is not a sandbox.
+#
+# The refusal deliberately names no MODEL-EXECUTABLE remedy. Every other blocking gate in this repo
+# teaches the way through, because there the way through is something the model should do. Here it
+# is something only the user may do, so a helpful "run this to undo it" line would be the
+# vulnerability rather than the fix. It says who owns the change, not how to perform it.
+#
+# CONTRACT: exit 0 = allow · exit 2 + stderr = BLOCK (stderr returns to the model as the reason).
+# FAILS OPEN on anything unparseable — a blocking hook must never brick a session. Pure bash
+# builtins, no node/jq/python, for the same reason as ground-before-write.sh: a wall that can
+# fail-open because a tool went missing is not a wall.
+# ─────────────────────────────────────────────────────────────────────────────────────────────────
+
+set -uo pipefail
+
+INPUT=""
+# BOUNDED READ (2026-07-27, ADR-055 F20): an unqualified `read` never returns on a stdin that is
+# opened and never closed — measured across the mesh, 18 of 37 registered commands sat until the
+# harness killed them. Real Claude Code writes and closes, so this costs no normal turn; that is
+# exactly why a hook that CAN hang forever survives unnoticed. -t bounds the wait, and the string
+# is truncated AFTER the loop because a hook payload is one line with no newline, so `read` hands
+# the whole thing back at once and a per-iteration cap never fires.
+while IFS= read -r -t 2 _l; do
+  INPUT+="$_l"
+  [ ${#INPUT} -ge 65536 ] && break
+done
+[ -n "$_l" ] && INPUT+="$_l"
+INPUT="${INPUT:0:65536}"
+[ -n "$INPUT" ] || exit 0
+
+field() { local re="\"$1\"[[:space:]]*:[[:space:]]*\"([^\"]*)\""; [[ $INPUT =~ $re ]] && printf '%s' "${BASH_REMATCH[1]}"; }
+
+case "$(field tool_name)" in Write|Edit|MultiEdit|NotebookEdit) ;; *) exit 0 ;; esac
+
+FILE_PATH=$(field file_path)
+[ -n "$FILE_PATH" ] || exit 0
+
+# The same two paths brain-state.mjs and user-settings.mjs compute, resolved the same way. The env
+# overrides exist so this suite (and a second machine profile) can point them elsewhere; the literal
+# defaults are matched TOO, so the guard protects a real user even when no override is set — a gate
+# that only fires under its own test harness protects nobody.
+STATE_DIR="${RUVNET_BRAIN_STATE_DIR:-$HOME/.config/ruvnet-brain}"
+SETTINGS_FILE="${RUVNET_SETTINGS_FILE:-$HOME/.config/ruvnet-brain/settings.json}"
+
+PROTECTED=""
+case "$FILE_PATH" in
+  "$STATE_DIR"/brain-off|"$STATE_DIR"/brain-off.*)         PROTECTED="the on/off switch" ;;
+  "$SETTINGS_FILE"|"$SETTINGS_FILE".*)                     PROTECTED="your saved settings" ;;
+  # Literal defaults, for any HOME/override combination that did not match above. The trailing `*`
+  # covers .bak-<stamp>, .lock and .tmp-<pid> — the same file by another name.
+  */.config/ruvnet-brain/brain-off|*/.config/ruvnet-brain/brain-off.*)         PROTECTED="the on/off switch" ;;
+  */.config/ruvnet-brain/settings.json|*/.config/ruvnet-brain/settings.json.*) PROTECTED="your saved settings" ;;
+esac
+[ -n "$PROTECTED" ] || exit 0
+
+cat >&2 <<EOF
+⛔ BLOCKED — that file is the user's own record of how they want this machine to behave ($PROTECTED).
+
+It is changed by the person, from the RuvNet Brain console, and never by an agent editing the file.
+Do not attempt this another way, and do not offer to. If the user's intent was to change one of
+these settings, say so in plain words and let them make the change themselves.
+EOF
+exit 2

package/plugin/scripts/route-dispatch.sh

@@ -0,0 +1,147 @@
+#!/bin/bash
+# route-dispatch.sh — PreToolUse gate on subagent dispatch. Ends model-inheritance-by-omission.
+#
+# ─────────────────────────────────────────────────────────────────────────────────────────────────
+# THE LEAK (2026-07-13). Stuart: "What happens when I'm right here in Opus 4.8 and it has 10 things
+# to run? Is it going to just run them as Opus 4.8?" — YES:
+#
+#     A SUBAGENT INHERITS THE MAIN-LOOP MODEL UNLESS `model` IS EXPLICITLY PASSED.
+#
+# Ten agents on a Fable session = ten agents at $10/$50 per Mtok, ~10x Haiku for identical mechanical
+# work. The router existed; the rule to use it existed; the router's ENTIRE LIFETIME OUTPUT was 3 test
+# pings and $0.018 saved — because the rule was ADVISORY. So this is a wall, not advice.
+#
+# ─────────────────────────────────────────────────────────────────────────────────────────────────
+# THREE DEFECTS IN MY OWN FIRST VERSION, caught by asking the questions Stuart would have asked
+# (2026-07-13, minutes after shipping it — the whole point of the adversarial pass):
+#
+#   1. IT BLOCKED EVERY USER. This hook ships to everyone who installs RuvNet Brain. Hard-blocking
+#      the Task tool for people who never asked for cost routing is hostile — I would have broken
+#      strangers' workflows to save Stuart money. Now it ENFORCES ONLY FOR USERS WHO OPTED IN
+#      (a model-router profile.json exists = they answered the two subscription questions). Everyone
+#      else gets NOTHING — not even a warning. Consent is the default.
+#   2. IT REQUIRED python3. The other three plugin hooks are pure bash. A hard dependency inside a
+#      BLOCKING hook is how you brick someone's session. Now pure bash — no interpreters.
+#   3. IT COULD FAIL CLOSED. A blocking hook that errors must never take the session with it. Every
+#      unparseable/ambiguous case now FAILS OPEN (exit 0). A gate that breaks your tools is worse
+#      than the leak it prevents.
+#
+# CONTRACT (verified against this machine's live hook config):
+#   exit 0          → allow
+#   exit 2 + stderr → BLOCK, and stderr comes back to the model as the reason (so it retries correctly)
+# ─────────────────────────────────────────────────────────────────────────────────────────────────
+
+set -uo pipefail
+
+# Read stdin with a BASH BUILTIN, not `cat`. Break-testing on a bare PATH caught this: `INPUT=$(cat)`
+# made the hook depend on an external binary, and when it was missing the gate silently allowed
+# everything. Second hole found the same way as the first (the grep|sed parse). The rule this file
+# now obeys absolutely: A HOOK THAT CAN BLOCK MUST DEPEND ON NOTHING IT CANNOT GUARANTEE.
+INPUT=""
+# BOUNDED READ (2026-07-27, ADR-055 F20): an unqualified `read` never returns on a stdin that is
+# opened and never closed — measured across the mesh, 18 of 37 registered commands sat until the
+# harness killed them. Real Claude Code writes and closes, so this costs no normal turn; that is
+# exactly why a hook that CAN hang forever survives unnoticed. -t bounds the wait, and the string
+# is truncated AFTER the loop because a hook payload is one line with no newline, so `read` hands
+# the whole thing back at once and a per-iteration cap never fires.
+while IFS= read -r -t 2 _line; do
+  INPUT+="$_line"
+  [ ${#INPUT} -ge 65536 ] && break
+done
+[ -n "$_line" ] && INPUT+="$_line"
+INPUT="${INPUT:0:65536}"
+[ -n "$INPUT" ] || exit 0                      # nothing to inspect → never block
+
+# ── OPT-IN GATE. No profile = this user never asked for cost routing = we do not touch their tools. ──
+PROFILE="${MODEL_ROUTER_PROFILE:-$HOME/.claude/model-router/profile.json}"
+[ -f "$PROFILE" ] || exit 0
+# A non-interactive install records useful detection data with an explicit `assumed:` basis, but it
+# never asked the consent questions. Treat that provenance as inert. Existing confirmed profiles
+# that predate the basis field remain compatible; malformed/unreadable profiles fail open.
+PROFILE_INPUT=""
+while IFS= read -r _profile_line; do
+  PROFILE_INPUT+="$_profile_line"
+  [ ${#PROFILE_INPUT} -ge 65536 ] && break
+done < "$PROFILE" 2>/dev/null || exit 0
+[ -n "$_profile_line" ] && PROFILE_INPUT+="$_profile_line"
+case "$PROFILE_INPUT" in *'"basis"'*'"assumed:'*) exit 0 ;; esac
+
+# ── Deliberate escape hatch (must be used ON PURPOSE, never reached by omission). ──
+[ "${RUVNET_ALLOW_INHERITED_MODEL:-0}" = "1" ] && exit 0
+
+# ── JSON field reads via BASH'S OWN REGEX — no subprocess, no PATH, no locale, no interpreter.
+#    v1 used a `grep | head | sed` pipeline. Break-testing it on a bare environment (env -i, only
+#    coreutils on PATH) exposed the hole: the pipeline produced an EMPTY string, so the gate silently
+#    FAILED OPEN and blocked nothing. A wall with a hole is not a wall — and I would only have learned
+#    that from a user whose routing quietly never enforced. `[[ =~ ]]` is a bash builtin: it cannot be
+#    missing, cannot be shadowed by PATH, and cannot fail on a locale.
+field() {
+  local re="\"$1\"[[:space:]]*:[[:space:]]*\"([^\"]*)\""
+  [[ $INPUT =~ $re ]] && printf '%s' "${BASH_REMATCH[1]}"
+}
+
+TOOL=$(field tool_name)
+case "$TOOL" in Task|Agent) ;; *) exit 0 ;; esac   # only subagent dispatches
+
+SUBTYPE=$(field subagent_type)
+[ "$SUBTYPE" = "fork" ] && exit 0                  # a fork inherits the parent model BY DESIGN
+
+MODEL=$(field model)
+DESC=$(field description)
+TOOL_USE_ID=$(field tool_use_id)
+SESSION_ID=$(field session_id)
+DESC="${DESC// /_}"; DESC="${DESC:0:40}"   # builtin substitution — no `tr`, no `cut`
+
+if [ -n "$MODEL" ]; then
+  # Declared. Log it so routing is AUDITABLE, not merely claimed — a growing ledger is evidence;
+  # a promise is not. (This log is how the $0.018-lifetime failure became visible in the first place.)
+  # `date` is the ONE external command left, and only on the ALLOW path — so its absence must be
+  # silent, not a stderr spew from a hook that just said "yes". (bash's printf %()T would avoid it
+  # entirely, but macOS still ships bash 3.2, which does not support it.)
+  # The ENTIRE logging block is stderr-silenced as one unit: if the mkdir fails, the append redirect
+  # fails too, and BASH ITSELF writes that error — a `2>/dev/null` on the printf does not catch it.
+  # A hook that just said "yes" must say nothing at all.
+  {
+    TS=$(date -u +%FT%TZ) || TS="unknown"   # the one external command, and only on the allow path
+    mkdir -p "$HOME/.claude/metaharness"
+    printf '{"ts":"%s","event":"dispatch","model":"%s","agent":"%s","task":"%s","toolUseId":"%s","sessionId":"%s"}\n' \
+      "$TS" "$MODEL" "${SUBTYPE:-unknown}" "${DESC:-unlabeled}" "${TOOL_USE_ID:-}" "${SESSION_ID:-}" \
+      >> "$HOME/.claude/metaharness/dispatch-log.jsonl"
+  } 2>/dev/null || true
+  exit 0
+fi
+
+# ── BLOCKED: no model declared → it would silently inherit the session model. ──
+# `read` + `printf` are BUILTINS. The original used `cat >&2 <<EOF`, which made the BLOCK path itself
+# depend on an external binary — the third dependency hole found in my own hook in ten minutes.
+read -r -d '' BLOCK_MSG <<'EOF' || true
+⛔ SUBAGENT DISPATCH BLOCKED — you did not declare a `model`.
+
+An agent with no `model` INHERITS this session's model. On an Opus session that is an Opus agent;
+on a Fable session it is $10/$50 per Mtok — up to 10x what the same work costs on Haiku.
+Inheritance-by-omission is the biggest cost leak in this harness, and an advisory rule did not fix
+it (the router's entire first life saved $0.018). Hence a wall.
+
+Re-issue the SAME Agent call with an explicit `model`, chosen by what the task actually IS:
+
+  model: "haiku"   mechanical — greps, file sweeps, log triage, mechanical edits, fixture rewrites
+  model: "sonnet"  analytical — trace a bug across files, summarize a subsystem, draft tests
+  model: "opus"    judgment   — architecture, root cause, security, anything user-facing
+                   (if it truly needs the main model's judgment, ask whether it should be a
+                    subagent at all, or work you should do inline)
+
+Not sure? Ask rUv's real router — it predicts each model's quality on THIS task and returns the
+cheapest one that clears the bar, with your subscriptions priced at $0:
+
+  node ~/.claude/model-router/bin/model-router-engine.mjs --harness claude-code --prompt "<task>" --json
+
+Then log the receipt when it returns, so the saving is visible instead of asserted:
+
+  node scripts/dispatch-receipt.mjs --model <m> --inherited <this session's model> \
+       --task "<what it did>" --total-tokens <the agent's reported total>
+
+Deliberate exception (rare — and say WHY out loud): RUVNET_ALLOW_INHERITED_MODEL=1
+EOF
+bash "$(dirname "${BASH_SOURCE[0]}")/gate-receipt.sh" route-dispatch "subagent" "would inherit the session model instead of routing to a cheaper one" 2>/dev/null || true
+printf '%s\n' "$BLOCK_MSG" >&2
+exit 2

package/plugin/scripts/routing-outcome-capture.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+// PostToolUse Task/Agent observer. It records the host's terminal status after an explicitly routed
+// dispatch. Host completion is an observation, not a quality grade, so these rows are always marked
+// verified:false and intentionally contain neither embeddings nor scores.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import {
+  parseHookEvent,
+  rawToolResponse,
+  readStdinBounded,
+  toolName,
+} from './hook-input.mjs';
+
+const SUCCESS = new Set(['completed', 'success', 'succeeded']);
+const FAILURE = new Set(['failed', 'error', 'cancelled', 'canceled', 'timed_out', 'timeout']);
+
+export function outcomesPath() {
+  return process.env.MODEL_ROUTER_OUTCOMES
+    || path.join(os.homedir(), '.claude', 'metaharness', 'routing-outcomes.jsonl');
+}
+
+export function dispatchLogPath() {
+  return process.env.MODEL_ROUTER_DISPATCH_LOG
+    || path.join(os.homedir(), '.claude', 'metaharness', 'dispatch-log.jsonl');
+}
+
+export function findDispatchDecision(toolUseId, file = dispatchLogPath()) {
+  if (!toolUseId) return null;
+  let lines;
+  try { lines = fs.readFileSync(file, 'utf8').trim().split('\n').filter(Boolean); }
+  catch { return null; }
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let row;
+    try { row = JSON.parse(lines[i]); } catch { continue; }
+    if (row?.event === 'dispatch' && row.toolUseId === toolUseId) return row;
+  }
+  return null;
+}
+
+export function observationFrom(event, now = new Date().toISOString(), decision = null) {
+  if (!['Task', 'Agent'].includes(toolName(event))) return null;
+  const model = event?.tool_input?.model;
+  if (typeof model !== 'string' || !model.trim()) return null;
+  const response = rawToolResponse(event);
+  const status = typeof response?.status === 'string' ? response.status.toLowerCase() : '';
+  if (!SUCCESS.has(status) && !FAILURE.has(status)) return null;
+  const task = String(event?.tool_input?.prompt || event?.tool_input?.description || '');
+  return {
+    schema: 'dispatch-observation-v1',
+    ts: now,
+    source: 'PostToolUse',
+    model,
+    success: SUCCESS.has(status),
+    hostStatus: status,
+    verified: false,
+    taskHash: createHash('sha256').update(task).digest('hex').slice(0, 24),
+    toolUseId: event.tool_use_id || null,
+    sessionId: event.session_id || null,
+    decisionLinked: !!decision,
+    decisionModel: typeof decision?.model === 'string' ? decision.model : null,
+    decisionModelMatch: decision ? decision.model === model : null,
+  };
+}
+
+export function appendObservation(row, file = outcomesPath()) {
+  if (!row) return false;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, JSON.stringify(row) + '\n');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function main() {
+  if (process.stdin.isTTY) return;
+  let event = null;
+  try { event = parseHookEvent((await readStdinBounded()).toString('utf8')); } catch { return; }
+  const decision = findDispatchDecision(event?.tool_use_id);
+  appendObservation(observationFrom(event, new Date().toISOString(), decision));
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try { await main(); } catch { /* advisory observer: fail open */ }
+}