model-orchestrator 0.1.15 → 0.1.17

package/templates/agents/claude-code/README.md

@@ -6,11 +6,11 @@ One per tier, plus two checks and two agents with no file-editing tools: `findin
 |---|---|---|---|---|
 | deep-planner | deep | opus | xhigh | judges every build twice; never retrieves |
 | builder | standard | sonnet | high | executes; the default for everything that changes files |
-| code-reviewer | standard | sonnet | high | read-only findings |
+| code-reviewer | standard | sonnet | high | findings only; no file-editing tools, Bash for checks only |
 | finding-verifier | standard | sonnet | high | tries to disprove a finding before it causes a repair |
 | live-researcher | standard | sonnet | medium | fresh data through tools |
 | bulk-worker | fast | haiku | low | mechanical volume, writes output |
 | done-verifier | fast | haiku | low | probes a tracker item's stated done-signal; no file-editing tools, Bash for probes only |
 | reader | fast | haiku | low | reads and digests many files or notes; read-only |
 
-Aliases resolve to the newest model in each family, so a version bump needs no edit here. Each agent carries its own token-discipline rule; the `effort` field is the third cost lever. Neither `done-verifier` nor `reader` carries `Write` or `Edit` in its `tools:` line. `reader` is read-only by tool grant as well: it carries no `Bash`. `done-verifier` does carry `Bash`, for its probes (`git log`, `grep`, `wc -l`, `test -f`); nothing in that grant stops it from running a command that changes state, so staying read-only there is a rule in its prompt, not a restriction on the tool, and its own file says so.
+Aliases resolve to the newest model in each family, so a version bump needs no edit here. Each agent carries its own token-discipline rule; the `effort` field is the third cost lever. None of `done-verifier`, `finding-verifier`, `code-reviewer` or `reader` carries `Write` or `Edit` in its `tools:` line. `reader` is read-only by tool grant as well: it carries no `Bash`. `done-verifier`, `finding-verifier` and `code-reviewer` do carry `Bash`, for their probes and checks (`git log`, `grep`, `wc -l`, `test -f`); nothing in that grant stops any of them from running a command that changes state, so staying read-only there is a rule in each one's prompt, not a restriction on the tool, and each file says so.

package/templates/agents/claude-code/code-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: code-reviewer
-description: Code review. Use when asked to review code, a diff, or a repo for bugs, security issues, or quality. Read-only, returns findings. Do not use for writing or fixing code.
+description: Code review. Use when asked to review code, a diff, or a repo for bugs, security issues, or quality. No file-editing tools; Bash is for read-only checks, bound by the prompt below, not by the tool grant. Returns findings. Do not use for writing or fixing code.
 tools: Read, Glob, Grep, Bash
 model: sonnet
 effort: high
@@ -10,10 +10,17 @@ You are the review tier of the model router.
 
 You review code for real bugs, security problems, and correctness issues.
 
+You carry no Write or Edit tool, so you cannot touch a file. You do carry
+Bash, and nothing in that grant stops you from running a command that changes
+state; staying to read-only checks is a rule you follow below, not a
+restriction you were given. Treat that boundary as load-bearing.
+
 Rules:
 - Report only findings you can defend with a concrete failure scenario. No style nitpicks unless asked.
 - Rank by severity. For each: file, line, what breaks, and the fix in one or two sentences.
 - Security findings (auth, secrets, injection, exposed endpoints) always rank first. Treat every endpoint as internet-facing.
-- You are read-only. Suggest fixes; do not apply them.
+- Bash is for read-only checks only (`git log`, `grep`, `wc -l`, `test -f`, a
+  HEAD or GET request): never a command that changes state. Suggest fixes; do
+  not apply them.
 - If the code is clean, say so plainly. Do not invent findings.
 - Token discipline: read only the files under review, targeted sections where possible; report findings without restating the code; quote at most the few lines a finding needs.

package/templates/agents/claude-code/finding-verifier.md

@@ -1,6 +1,6 @@
 ---
 name: finding-verifier
-description: Adversarial verification of review findings. Use after a review or audit returns findings and before any of them trigger a repair. Read-only. Tries to DISPROVE each finding and returns CONFIRMED, NOT_REPRODUCED or INCONCLUSIVE per finding. Do not use to find new problems, and do not use to fix anything.
+description: Second-opinion verification of review findings. Use after a review or audit returns findings and before any of them trigger a repair. No file-editing tools; Bash is for read-only checks, bound by the prompt below, not by the tool grant. Tries to DISPROVE each finding and returns CONFIRMED, NOT_REPRODUCED or INCONCLUSIVE per finding. Do not use to find new problems, and do not use to fix anything.
 tools: Read, Glob, Grep, Bash
 model: sonnet
 effort: high
@@ -12,6 +12,11 @@ A finding is a claim, not a fact. Your job is to try to disprove each one before
 it is allowed to cause a change. A false finding is expensive twice: it buys a
 repair nobody needed, and it teaches everyone to skim the next report.
 
+You carry no Write or Edit tool, so you cannot touch a file. You do carry
+Bash, and nothing in that grant stops you from running a command that changes
+state; staying to read-only checks is a rule you follow below, not a
+restriction you were given. Treat that boundary as load-bearing.
+
 You are given findings from a review or an audit. For each one, independently:
 
 1. Read the cited file and line yourself. A citation that does not point at what
@@ -36,7 +41,9 @@ Return one verdict per finding, in the order you were given them:
 Rules:
 - Verify only the findings you were given. New problems you happen to notice go
   in a separate list at the end, clearly marked as unverified observations.
-- You are read-only. You never repair, and you never soften a finding's wording.
+- Bash is for read-only checks only (`git log`, `grep`, `wc -l`, `test -f`, a
+  HEAD or GET request): never a command that changes state. You never repair,
+  and you never soften a finding's wording.
 - Verifying nothing is a real answer. If every finding is NOT_REPRODUCED, say
   that plainly; a verifier that always confirms something is a rubber stamp
   facing the other way.

package/templates/agents/snippets/chat.md

@@ -4,8 +4,8 @@
 
 ```
 You follow a model-orchestrator workflow inside this chat. Tiers describe effort, not automatic model switching or cost savings.
-Route first: bulk/formatting -> fast; live data -> standard with tools; review -> standard, read-only; ambiguous/high-risk -> deep; otherwise standard. State the tier. Escalate on failure instead of silently retrying.
-For builds: map affected parts; identify the biggest risk and any flaw in the request (none is valid with reasons); build and verify; use a fresh turn to challenge the result. Before irreversible actions, explain rollback and ask for approval.
+Route first: bulk/formatting -> fast; live data -> standard with tools; review -> standard, read-only; ambiguous/high-stakes -> deep; otherwise standard. State the tier. Escalate on failure instead of silently retrying.
+For builds: map affected parts; identify what is most likely to go wrong and any gap in the request (none is valid with reasons); build and verify; use a fresh turn to challenge the result. Before irreversible actions, explain rollback and ask for approval.
 For hand-offs: include purpose, scope, allowed and denied actions, required output, and stopping conditions. A fresh context has none of these instructions.
 After comprehensive work, check for omissions. Compute consequential numbers and comparisons with a tool; report what was checked and what remains unverified.
 Before durable writes, search existing records, update their index, use one writer, and label inferences.

package/templates/agents/snippets/claude-code.md

@@ -9,7 +9,7 @@ Routing rules live in `{{RULES_PATH}}/{{ROUTING_FILE}}`. Read them before any bu
 
 1. Bulk, mechanical, many similar items -> bulk-worker (fast tier).
 2. Needs live data -> live-researcher (standard tier + tools).
-3. Review without changing -> code-reviewer (standard, read-only).
+3. Review without changing -> code-reviewer (standard; no file-editing tools, Bash for checks only).
 3a. Holding findings from a review or scanner -> finding-verifier before any repair. Only CONFIRMED findings earn a change.
 3b. Checking a tracker item against its stated done-signal -> done-verifier. It never closes anything itself.
 4. Ambiguous, architectural, or expensive to get wrong -> deep-planner (deep tier), then hand the plan down.
@@ -17,7 +17,7 @@ Routing rules live in `{{RULES_PATH}}/{{ROUTING_FILE}}`. Read them before any bu
 
 A subagent starts with your CLAUDE.md and tool definitions already loaded, so it has a fixed start-up cost before it does anything. Measure yours once: spawn a subagent with a one-line task and read its token count. Work smaller than that stays inline.
 
-Every build runs `{{RULES_PATH}}/protocols/build-protocol.md`: two deep-tier checkpoints, a mechanical scan, one adversarial pass, an explicit human yes before anything irreversible, then the loud negative.
+Every build runs `{{RULES_PATH}}/protocols/build-protocol.md`: two deep-tier checkpoints, a mechanical scan, one challenge pass, an explicit human yes before anything irreversible, then the loud negative.
 
 Every delegation carries an `{{RULES_PATH}}/TASK_BUNDLE.md` brief. A Claude Code subagent loads this CLAUDE.md hierarchy, so it holds the standing rules already, just not this task's scope; a second CLI or a fresh chat window may hold none of them. Absence is denial either way.
 

package/templates/agents/snippets/generic.md

@@ -9,7 +9,7 @@ Routing rules live in `{{RULES_PATH}}/{{ROUTING_FILE}}`. Read them before any bu
 
 Route by capability tier, first match wins: bulk and mechanical -> fast tier · needs live data -> standard tier with tools · review without changing -> standard, read-only · ambiguous or expensive to get wrong -> deep tier, then hand the plan down · everything else -> build it directly at standard tier.
 
-Every build runs `{{RULES_PATH}}/protocols/build-protocol.md`: map the blast radius yourself, ask the deep tier for a named risk and a named flaw, build green, scan the added lines, one adversarial pass with every finding reproduced, an explicit human yes before anything irreversible, then re-grep the old identifier and expect zero.
+Every build runs `{{RULES_PATH}}/protocols/build-protocol.md`: map everything it touches yourself, ask the deep tier for one named weak spot and one gap in the request, build green, scan the added lines, one challenge pass with every finding reproduced, an explicit human yes before anything irreversible, then re-grep the old identifier and expect zero.
 
 Every delegation carries an `{{RULES_PATH}}/TASK_BUNDLE.md` brief. A fresh context holds none of these rules; absence is denial.
 

package/templates/agents/snippets/route-gate.mjs

@@ -10,7 +10,7 @@
 // This script always exits 0, never blocks on stdin past a short bound,
 // reads at most 64 KB of the rules file through a fixed-size buffer (never
 // a full read of an arbitrarily large or non-regular file), and never
-// executes anything it reads. See docs/audit-brief.md for the threat model.
+// executes anything it reads. See docs/audit-brief.md for the security notes.
 import { statSync, openSync, readSync, closeSync, realpathSync } from 'node:fs';
 import { join, isAbsolute } from 'node:path';
 

package/templates/agents/snippets/route-metrics.mjs

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+// route-metrics.mjs: routing telemetry hook for {{PRIMARY_NAME}}.
+//
+// Answers "is my agent actually routing and delegating?" by turning five
+// hook events into one JSON line each, appended to
+// ~/.ai-orchestrator/route-metrics.jsonl (the same directory bin/cli-run.mjs
+// already logs to, and the same os.homedir() resolution it uses):
+//
+//   UserPromptSubmit                 -> {event:"turn"}
+//   PreToolUse (matcher Agent|Task)  -> {event:"dispatch", subagent_type, background}
+//   SubagentStart                    -> {event:"start", agent_type}
+//   SubagentStop                     -> {event:"end", agent_type?, duration_s?}
+//   Stop                             -> {event:"route", lane}, parsed from the LAST
+//                                        <!-- route: <lane> | <why> --> marker in
+//                                        last_assistant_message (documented source;
+//                                        the transcript can lag, so that is never read)
+//
+// Pure telemetry, fail-open by design: this script prints NOTHING to stdout
+// (stdout on UserPromptSubmit/SubagentStart becomes model context) and always
+// exits 0, whether or not a line was written. A miss here is a missing log
+// line, never a blocked turn.
+//
+// The durable log holds no provider-supplied string: prompt text, tool
+// descriptions, and the "why" half of the route marker are never read into a
+// field, only the named, charset-bounded values below. See docs/audit-brief.md.
+//
+// Second entry point: `node route-metrics.mjs --summary [--since <ISO date>]`
+// prints a plain-text report from the log and exits 0 without touching stdin.
+import { createHash } from 'node:crypto';
+import {
+  existsSync, mkdirSync, appendFileSync, readFileSync, writeFileSync, unlinkSync, renameSync,
+  statSync, readdirSync
+} from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const HOME_DIR = join(homedir(), '.ai-orchestrator');
+const LOG_FILE = join(HOME_DIR, 'route-metrics.jsonl');
+const STATE_DIR = join(HOME_DIR, 'route-metrics.state');
+
+const STDIN_MAX_BYTES = 8 * 1024 * 1024; // size cap: a giant or runaway payload is truncated, not parsed
+const STDIN_DRAIN_MS = 1000; // hard cap: never let an open, never-closed stdin pipe hold this hook open
+const LOG_ROTATE_BYTES = 5 * 1024 * 1024; // rotate to .1 above this size
+const STATE_MAX_AGE_MS = 24 * 60 * 60 * 1000; // prune state files older than 24h
+const TOKEN_CHARSET = /[^A-Za-z0-9_.+-]/g; // session_id, subagent_type, agent_type, lane tokens
+const TOKEN_MAX_LEN = 64;
+const SESSION_ID_MAX_LEN = 128;
+
+// Strip anything outside the allowed charset and cap length, so no field in
+// the durable log can carry an arbitrary provider- or model-supplied string
+// (a newline, a control character, shell metacharacters, or just length).
+function sanitize(raw, maxLen) {
+  if (typeof raw !== 'string' || raw.length === 0) return '';
+  return raw.replace(TOKEN_CHARSET, '').slice(0, maxLen);
+}
+
+function stateKeyFor(agentId) {
+  if (typeof agentId !== 'string' || agentId.length === 0) return null;
+  return createHash('sha256').update(agentId).digest('hex');
+}
+
+// Best-effort housekeeping: a leaked state file (a SubagentStop that never
+// arrived) should not accumulate forever. Run on SubagentStart only, since
+// that is the one event guaranteed to fire at least as often as starts happen.
+function pruneOldState() {
+  let names;
+  try {
+    names = readdirSync(STATE_DIR);
+  } catch {
+    return; // no state dir yet: nothing to prune
+  }
+  const cutoff = Date.now() - STATE_MAX_AGE_MS;
+  for (const name of names) {
+    const p = join(STATE_DIR, name);
+    try {
+      if (statSync(p).mtimeMs < cutoff) unlinkSync(p);
+    } catch {
+      /* a race with another process touching the same file is not an error here */
+    }
+  }
+}
+
+function recordStart(agentId, agentType) {
+  const key = stateKeyFor(agentId);
+  if (!key) return;
+  try {
+    mkdirSync(STATE_DIR, { recursive: true });
+    writeFileSync(join(STATE_DIR, key + '.json'), JSON.stringify({ ts: Date.now(), agent_type: agentType }));
+  } catch {
+    /* telemetry never blocks the run */
+  }
+}
+
+// Reads and deletes the state file for this agent_id. Returns {agentType,
+// durationS}, either possibly null: no agent_id and no state file both mean
+// "none", which the caller reflects by omitting the field entirely.
+function consumeStart(agentId) {
+  const key = stateKeyFor(agentId);
+  if (!key) return { agentType: null, durationS: null };
+  const p = join(STATE_DIR, key + '.json');
+  let agentType = null;
+  let durationS = null;
+  try {
+    const parsed = JSON.parse(readFileSync(p, 'utf8'));
+    if (parsed && typeof parsed.ts === 'number') durationS = Math.max(0, (Date.now() - parsed.ts) / 1000);
+    if (parsed && typeof parsed.agent_type === 'string' && parsed.agent_type) agentType = parsed.agent_type;
+  } catch {
+    /* no state file, or it was unreadable: none, not an error */
+  }
+  try {
+    unlinkSync(p);
+  } catch {
+    /* already gone */
+  }
+  return { agentType, durationS };
+}
+
+function appendLog(record) {
+  try {
+    mkdirSync(HOME_DIR, { recursive: true });
+    let size = 0;
+    try {
+      size = statSync(LOG_FILE).size;
+    } catch {
+      /* file does not exist yet: size stays 0 */
+    }
+    if (size > LOG_ROTATE_BYTES) {
+      try {
+        renameSync(LOG_FILE, LOG_FILE + '.1');
+      } catch {
+        /* a concurrent rotation losing this race is not worth failing over */
+      }
+    }
+    appendFileSync(LOG_FILE, JSON.stringify(record) + '\n');
+  } catch {
+    /* telemetry never blocks the run */
+  }
+}
+
+// Parses the LAST <!-- route: <lane> | <why> --> marker out of text. The
+// "why" half is captured only to be discarded: it is never read into a
+// variable that reaches the log. Returns an array of lane tokens (split on
+// "+", the documented way to log more than one lane from a single marker),
+// or ["missing"] when there is no marker at all.
+export function extractLane(text) {
+  if (typeof text !== 'string' || text.length === 0) return ['missing'];
+  const re = /<!--\s*route:\s*([^|>]*)\|[^>]*-->/g;
+  let match;
+  let last = null;
+  while ((match = re.exec(text)) !== null) last = match;
+  if (!last) return ['missing'];
+  // A token carrying any character outside the charset is logged as
+  // "invalid", never stripped into a plausible-looking lane: stripping
+  // `main","evil":"1` would log a lane named "mainevil1" that nobody chose.
+  const parts = last[1]
+    .split('+')
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((t) => (t.length > TOKEN_MAX_LEN || /[^A-Za-z0-9_.-]/.test(t) ? 'invalid' : t));
+  return parts.length ? parts : ['missing'];
+}
+
+// Turns one parsed hook-input object into a log record, or null when the
+// event is not one this hook measures (or PreToolUse fired for a tool other
+// than Agent/Task, which the settings matcher should already have excluded;
+// this is a defensive second check, not the primary gate).
+export function buildRecord(input, now = () => new Date().toISOString()) {
+  if (!input || typeof input !== 'object') return null;
+  const sessionId = sanitize(input.session_id, SESSION_ID_MAX_LEN) || 'unknown';
+  const ts = now();
+  const base = { ts, v: 1 };
+
+  switch (input.hook_event_name) {
+    case 'UserPromptSubmit':
+      return { ...base, event: 'turn', session_id: sessionId };
+
+    case 'PreToolUse': {
+      if (input.tool_name !== 'Agent' && input.tool_name !== 'Task') return null;
+      const toolInput = (input.tool_input && typeof input.tool_input === 'object') ? input.tool_input : {};
+      const subagentType = sanitize(toolInput.subagent_type, TOKEN_MAX_LEN) || 'general-purpose';
+      const background = toolInput.run_in_background === true;
+      return { ...base, event: 'dispatch', session_id: sessionId, subagent_type: subagentType, background };
+    }
+
+    case 'SubagentStart': {
+      pruneOldState();
+      const agentType = sanitize(input.agent_type, TOKEN_MAX_LEN) || 'unknown';
+      recordStart(input.agent_id, agentType);
+      return { ...base, event: 'start', session_id: sessionId, agent_type: agentType };
+    }
+
+    case 'SubagentStop': {
+      const { agentType, durationS } = consumeStart(input.agent_id);
+      const record = { ...base, event: 'end', session_id: sessionId };
+      if (agentType) record.agent_type = agentType;
+      if (durationS !== null) record.duration_s = durationS;
+      return record;
+    }
+
+    case 'Stop':
+      return { ...base, event: 'route', session_id: sessionId, lane: extractLane(input.last_assistant_message) };
+
+    default:
+      return null;
+  }
+}
+
+// Drain stdin without ever blocking on it, bounded by BOTH time and size. A
+// bare `readFileSync(0)` waits for EOF, so a caller that pipes in and never
+// closes its end left the process running indefinitely (the same class of
+// bug route-gate.mjs and subagent-context.mjs already fix). The size cap is
+// this hook's own addition: hook input is normally small, so a payload past
+// the cap is treated as truncated and parsed as nothing, never partially.
+function drainStdinBounded(timeoutMs, maxBytes) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let bytes = 0;
+    let truncated = false;
+    const chunks = [];
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        process.stdin.removeAllListeners('data');
+        process.stdin.removeAllListeners('end');
+        process.stdin.removeAllListeners('error');
+        process.stdin.pause();
+      } catch {
+        /* stdin may already be gone */
+      }
+      resolve({ data: truncated ? null : Buffer.concat(chunks).toString('utf8'), truncated });
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    if (timer.unref) timer.unref();
+    try {
+      process.stdin.on('data', (chunk) => {
+        if (truncated) return;
+        bytes += chunk.length;
+        if (bytes > maxBytes) {
+          truncated = true;
+          return finish();
+        }
+        chunks.push(chunk);
+      });
+      process.stdin.on('end', finish);
+      process.stdin.on('error', finish);
+      process.stdin.resume();
+    } catch {
+      finish();
+    }
+  });
+}
+
+async function runHook() {
+  const { data } = await drainStdinBounded(STDIN_DRAIN_MS, STDIN_MAX_BYTES);
+  if (data) {
+    let input;
+    try {
+      input = JSON.parse(data);
+    } catch {
+      input = null; // invalid JSON: log nothing
+    }
+    if (input) {
+      try {
+        const record = buildRecord(input);
+        if (record) appendLog(record);
+      } catch {
+        /* telemetry never blocks or fails the run */
+      }
+    }
+  }
+  process.exit(0); // fail-open, always: a miss here is a missing log line, never a blocked turn
+}
+
+// ---- --summary: a plain-text report, no stdin involved ----
+
+function parseLines(text) {
+  const records = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      records.push(JSON.parse(trimmed));
+    } catch {
+      /* one bad line (a torn write, a rotation race) does not sink the report */
+    }
+  }
+  return records;
+}
+
+function formatNumber(n) {
+  return Number.isInteger(n) ? String(n) : n.toFixed(2);
+}
+
+function runSummary(args) {
+  if (!existsSync(LOG_FILE)) {
+    console.log('route-metrics: no data yet (' + LOG_FILE + ' does not exist).');
+    return process.exit(0);
+  }
+  const sinceIdx = args.indexOf('--since');
+  const since = sinceIdx !== -1 ? Date.parse(args[sinceIdx + 1]) : NaN;
+  let records = parseLines(readFileSync(LOG_FILE, 'utf8'));
+  if (!Number.isNaN(since)) records = records.filter((r) => Date.parse(r.ts) >= since);
+
+  const turns = records.filter((r) => r.event === 'turn').length;
+  const routes = records.filter((r) => r.event === 'route');
+  const covered = routes.filter((r) => !(Array.isArray(r.lane) && r.lane.length === 1 && r.lane[0] === 'missing')).length;
+  const coveragePct = turns > 0 ? (covered / turns) * 100 : null;
+
+  const laneCounts = new Map();
+  for (const r of routes) {
+    for (const lane of Array.isArray(r.lane) ? r.lane : []) laneCounts.set(lane, (laneCounts.get(lane) || 0) + 1);
+  }
+
+  const dispatches = records.filter((r) => r.event === 'dispatch');
+  const dispatchCounts = new Map();
+  for (const r of dispatches) dispatchCounts.set(r.subagent_type, (dispatchCounts.get(r.subagent_type) || 0) + 1);
+
+  const starts = records.filter((r) => r.event === 'start').length;
+  const noMatchingStart = Math.max(0, dispatches.length - starts);
+
+  const ends = records.filter((r) => r.event === 'end' && r.agent_type && typeof r.duration_s === 'number');
+  const durationsByType = new Map();
+  for (const r of ends) {
+    if (!durationsByType.has(r.agent_type)) durationsByType.set(r.agent_type, []);
+    durationsByType.get(r.agent_type).push(r.duration_s);
+  }
+
+  const lines = [];
+  lines.push('route-metrics summary' + (Number.isNaN(since) ? '' : ' since ' + args[sinceIdx + 1]));
+  lines.push('turns: ' + turns);
+  lines.push('route-marker coverage: ' + (coveragePct === null ? 'no turns yet' : formatNumber(coveragePct) + '%') + ' (' + covered + '/' + turns + ')');
+  lines.push('lanes by count:');
+  if (laneCounts.size === 0) lines.push('  (none)');
+  for (const [lane, count] of [...laneCounts.entries()].sort((a, b) => b[1] - a[1])) lines.push('  ' + lane + ': ' + count);
+  lines.push('dispatches by subagent_type:');
+  if (dispatchCounts.size === 0) lines.push('  (none)');
+  for (const [type, count] of [...dispatchCounts.entries()].sort((a, b) => b[1] - a[1])) lines.push('  ' + type + ': ' + count);
+  lines.push('dispatches with no matching start: ' + noMatchingStart + ' (a hook or guard blocked them before launch)');
+  lines.push('duration by agent_type (mean / max, seconds):');
+  if (durationsByType.size === 0) lines.push('  (none)');
+  for (const [type, durs] of durationsByType) {
+    const mean = durs.reduce((a, b) => a + b, 0) / durs.length;
+    lines.push('  ' + type + ': ' + formatNumber(mean) + ' / ' + formatNumber(Math.max(...durs)));
+  }
+  console.log(lines.join('\n'));
+  process.exit(0);
+}
+
+const args = process.argv.slice(2);
+if (args.includes('--summary')) {
+  runSummary(args);
+} else {
+  runHook();
+}

package/templates/agents/snippets/settings.hooks.snippet.json

@@ -7,6 +7,23 @@
             "type": "command",
             "command": "node",
             "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/route-gate.mjs"]
+          },
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/route-metrics.mjs"]
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Agent|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/route-metrics.mjs"]
           }
         ]
       }
@@ -18,6 +35,33 @@
             "type": "command",
             "command": "node",
             "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/subagent-context.mjs"]
+          },
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/route-metrics.mjs"]
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/route-metrics.mjs"]
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/route-metrics.mjs"]
           }
         ]
       }

package/templates/beginner/ORCHESTRATOR.md

@@ -29,8 +29,8 @@ Modifiers:
 
 ## The two checkpoints (every build)
 
-- **Checkpoint 1, before writing anything.** You map the blast radius yourself (files, systems, docs, tickets). Then ask the deep tier, on the finished map: *is this the simplest way, what is the single biggest risk, where is the request as filed wrong?* It must return a named risk and a named flaw. Approval alone is not an answer.
-- **Checkpoint 2, after the build is green.** Security-shaped diffs get an adversarial read (in a fresh context, told to attack, allowed to answer CLEAN). Architecture-shaped diffs get the deep tier reviewing build against plan. Never both on one diff. Every finding reproduced before it reaches a human.
+- **Checkpoint 1, before writing anything.** You map everything it touches yourself (files, systems, docs, tickets). Then ask the deep tier, on the finished map: *is this the simplest way, what is most likely to go wrong, what did the request miss?* It must return one named weak spot and one gap in the request. Approval alone is not an answer.
+- **Checkpoint 2, after the build is green.** Security-shaped diffs get a second-opinion read (in a fresh context, told to challenge, allowed to answer CLEAN). Architecture-shaped diffs get the deep tier reviewing build against plan. Never both on one diff. Every finding reproduced before it reaches a human.
 
 Cap: two deep-tier consults per build. The full procedure is `protocols/build-protocol.md`.
 

package/templates/common/README.md

@@ -47,7 +47,7 @@ Level 2 adds `ROUTING.md`, `TIERS.md`, `DELEGATION_MATRIX.md`, `RESEARCH_TRIAGE.
 ## The three rules that carry everything
 
 1. **Route by capability tier, not by model name.** deep = ambiguous or expensive to get wrong · standard = well-specified execution and review · fast = bulk and mechanical. Default down, escalate on evidence.
-2. **A gate you cannot fail is not a gate.** "Does it look good?" passes every time. "Name the single biggest risk and the flaw in the request" can come back empty, which is how you know it worked.
+2. **A gate you cannot fail is not a gate.** "Does it look good?" passes every time. "Name what is most likely to go wrong, and what the request missed" can come back empty, which is how you know it worked.
 3. **Exit 0 is not a deliverable.** Any tool, CLI or subagent can report success and hand back nothing. Check for the artifact, not the status line.
 
 ## Where things went

package/templates/common/protocols/build-protocol.md

@@ -2,7 +2,7 @@
 
 **Three phases, eight stages, and every gate is a question that can be answered wrong.**
 
-Fires on any task that builds, codes, implements, migrates or deploys. Rough test: if it would earn an adversarial audit or a tracker issue, it runs this.
+Fires on any task that builds, codes, implements, migrates or deploys. Rough test: if it would earn a second-opinion audit or a tracker issue, it runs this.
 
 > **The one rule underneath:** a gate you cannot fail is not a gate. If a stage's exit reads like "confirm it looks good", it is written wrong and it will pass every time, including the times it should not.
 
@@ -14,7 +14,7 @@ Three corollaries:
 | Phase | Master question | Stages |
 |---|---|---|
 | 1 Pre-build | What exactly are we building, what do we need first, and what does this touch or break? | 0 Route · 1 Map · 2 Judge |
-| 2 Build | Is it secure, built on current code, and correct without hidden flaws? | 3 Build · 4 Scan · 5 Attack · 5b Ship gate |
+| 2 Build | Is it secure, built on current code, and correct without hidden flaws? | 3 Build · 4 Scan · 5 Challenge · 5b Ship gate |
 | 3 Post-build | Did it land everywhere, is it proven against the real thing, and is it recorded? | 6 Verify · 7 Record |
 
 The two seams are the point. Pre-build to Build: nothing is written yet, changing your mind costs a conversation. Build to Post-build: the ship, the only irreversible step, the only one that needs an explicit human yes.
@@ -38,9 +38,9 @@ Four bounded questions, not four exhaustive scans. **The builder maps; the judgm
 ### Stage 2 · Judge (Checkpoint 1)
 Ask the judgment tier, on the finished map:
 1. Is this the simplest way to build it, or are we overcomplicating?
-2. What is the single biggest risk, and where is the request as filed wrong?
+2. What is most likely to go wrong, and what did the request miss?
 
-**Gate:** a **named risk** and a **named flaw in the request**. Approval alone is not an exit; an advisor asked only to approve will approve. If a consult comes back mostly restating the map, the brief asked it to retrieve when it should have asked it to decide.
+**Gate:** **one named weak spot** and **one gap in the request**. Approval alone is not an exit; an advisor asked only to approve will approve. If a consult comes back mostly restating the map, the brief asked it to retrieve when it should have asked it to decide.
 
 ## Phase 2 · Build
 
@@ -56,15 +56,15 @@ Ask the judgment tier, on the finished map:
 1. Any secret, key or token in the new code?
 2. Any vulnerability or vulnerable dependency in the lines we added?
 
-Secret detection, static analysis and dependency scanning, filtered to lines this diff added. Fail closed: a missing or erroring scanner exits non-zero, never a silent green.
+Secret detection, static analysis and dependency scanning, filtered to lines this diff added. Refuses by default: a missing or erroring scanner exits non-zero, never a silent green.
 
 **Gate:** zero flags on added lines. Pre-existing flags are reported, never inherited as blockers, and never waved through unread. A scanner finding is a claim; read the code before calling it anything.
 
-### Stage 5 · Attack (Checkpoint 2, one pass, never two)
+### Stage 5 · Challenge (Checkpoint 2, one pass, never two)
 1. Can bad input or a bad actor break it, and what happens when a dependency fails?
 2. Did the build stick to the approved plan, or did unintended changes sneak in?
 
-Route by shape: security-shaped diffs (auth, tokens, routes, deletion, bulk mutation, untrusted input) go to an adversarial auditor, ideally a **different model family**. Architecture-shaped diffs go to the judgment tier reviewing build against plan. Never both on one diff.
+Route by shape: security-shaped diffs (auth, tokens, routes, deletion, bulk mutation, untrusted input) go to a second-opinion reviewer, ideally a **different model family**. Architecture-shaped diffs go to the judgment tier reviewing build against plan. Never both on one diff.
 
 Findings do not go straight to a repair. Hand them to the **finding-verifier**, whose job is to DISPROVE each one: read the cited line, state what would trigger it, then hunt for the guard, caller or test that makes it impossible. It returns one of three verdicts per finding, and rounding between them is the failure mode to watch for.
 
@@ -106,7 +106,7 @@ Use a different model family from the one that produced the finding where you ha
 |---|---|---|
 {{ROLES_BUILDER_ROW}}
 | Judgment tier | Stage 2 and the architectural arm of Stage 5. Argues with a finished map | Perform the retrieval |
-| Adversarial auditor | The security arm of Stage 5. Attacks the diff | Fix anything |
+| Second-opinion reviewer | The security arm of Stage 5. Reviews the diff | Fix anything |
 | Mechanical gates | Stage 4 and any always-on guard | Be overridden without reading |
 | Cheap workers | Bounded sub-parts: bulk passes, wide searches, long loops | Own a stage |
 | Human | Stage 5b, and any irreversible or architectural call | Be the first line of review |
@@ -119,9 +119,9 @@ Use a different model family from the one that produced the finding where you ha
 PRE-BUILD
 [ ] 0  Inputs and access verified by live probe, not assumed
 [ ] 0  Confirmed this is a build and not a quick fix
-[ ] 1  Blast radius written: files, systems, issues
+[ ] 1  Everything it touches written: files, systems, issues
 [ ] 1  Asked what could break, and whether this already exists
-[ ] 2  Judgment tier named a risk AND a flaw in the request
+[ ] 2  Judgment tier named a weak spot AND a gap in the request
 
 BUILD
 [ ] 3  Repo clean, on a branch, base ref recorded