model-orchestrator 0.1.15 → 0.1.16

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ## [Unreleased]
 
+## [0.1.16] - 2026-09-11
+
+### Added
+
+- **A third claude-code-only hook, `route-metrics.mjs`, answers "is my agent actually routing and delegating?"** A routing rule nobody measures is a rule nobody knows is followed. Wired to five events (`UserPromptSubmit`, `PreToolUse` on `Agent`/`Task`, `SubagentStart`, `SubagentStop`, `Stop`), it appends one JSON line per event to `~/.ai-orchestrator/route-metrics.jsonl` (the same directory and home resolution `bin/cli-run.mjs` already logs to): a turn, a subagent dispatch (`subagent_type`, background flag), a subagent start and stop (so a duration can be computed from a small state file keyed by `sha256(agent_id)`), and the lane parsed from a new hidden marker, `<!-- route: <lane> | <why> -->`, that the route-gate block now asks every reply to end with. Only named, charset-bounded fields ever reach the log; prompt text, tool descriptions, the raw assistant message, and the marker's "why" half never do. `node .claude/hooks/route-metrics.mjs --summary [--since <ISO date>]` reports turns, route-marker coverage, lanes by count, dispatches by `subagent_type`, dispatches with no matching start, and mean/max duration per agent type. Plain Node, zero deps, prints nothing to stdout on any event, fail-open (a miss is a missing log line, never a blocked turn). Installed and wired only when claude-code is the primary, same no-overwrite rules as the other two hooks. See `docs/audit-brief.md` for the full threat-model writeup.
+- **CI now runs on `windows-latest` too, node 18/20/22, alongside Ubuntu and macOS.** `defaults.run.shell: bash` makes every workflow step Git Bash on the Windows runner instead of the default `pwsh`, so the same script runs on all three OSes with no parallel Windows rewrite.
+
+### Fixed
+
+- **`finding-verifier` and `code-reviewer` (claude-code) called themselves unqualified "Read-only" in their descriptions while carrying an unrestricted `Bash` grant**, the same overclaim `done-verifier` shipped with in 0.1.15 and was fixed there; nothing in that grant stops either from running a mutating command. Both descriptions and bodies now say plainly that they carry no file-editing tools and that Bash is bound by the prompt, not the tool grant. `templates/agents/claude-code/README.md` and `templates/agents/snippets/claude-code.md` are corrected the same way. The done-verifier-only test is replaced with one that walks every claude-code agent file: any agent whose `tools:` line includes `Bash` must qualify any "Read-only" claim, checked against its own file and against every generated doc surface.
+- **`CLAUDE.md` and `CONTRIBUTING.md` each pinned a fixed test count that drifted the moment a test was added or removed**, the same class of drift `AGENTS.md` already avoided by saying the suite prints the current number instead. Both now say the same thing `AGENTS.md` does. A new test in `test/prose.test.js` fails if any top-level `.md` states a fixed count of test cases.
+- **`which()` (`src/detect.js`, and its standalone copy in `bin/cli-run.mjs`) never found a Windows lane binary, because a PATH entry there never holds a bare `grok`: npm and vendor installers drop `grok.cmd` (or `.exe`/`.bat`), the same way any Windows shell resolves a bare command through `%PATHEXT%`.** `which()` now tries the bare name first (a no-op on POSIX, and still matching an already-extensioned name on Windows), then each `%PATHEXT%` suffix. `platform` is a parameter (default `process.platform`), the same pattern `killTree(pid, platform, deps)` already used, so the win32 branch has a real test (`test/detect.test.js`, new) on every OS this suite runs on. `home` is a parameter too, for the same testability reason: a dev machine with a real vendor CLI already on `~/.local/bin` made the new win32 tests false-negative until it was injectable.
+- **Committed text files were checked out as CRLF on `windows-latest`, breaking every test that compares a file's exact bytes against a string built in memory with `\n`** (`docs/catalog.md` vs. `catalogMarkdown()`, the README's generated vendor-table section, `llms.txt`'s first line, and a backslash-continued shell example's line-rejoin regex in a test). New `.gitattributes` (`* text=auto eol=lf`) forces LF on checkout regardless of a contributor's or a runner's `core.autocrlf`; `test/fixtures/` (real captured vendor output, byte-exact on purpose) is marked `-text` so line-ending normalization never touches it.
+- **A large block of `test/install.test.js` and `test/cli.test.js` compared a planned file's `f.rel` (built with `path.join`, so backslash-separated on win32) against a hardcoded forward-slash literal** (`'protocols/build-protocol.md'`, `'vm/README.md'`, `'.claude/agents/deep-planner.md'`, and about a dozen more), which is never equal on Windows; several other assertions hardcoded a POSIX `:` `PATH` delimiter and `/usr/bin`, `/bin` absolute paths, or replaced a spawned child's `env` outright and dropped `PATH`/`USERPROFILE`/the rest of the parent environment Windows itself needs. Path literals now go through `join(...)`; PATH construction goes through `node:path`'s `delimiter`; every replaced `env` object spreads `process.env` first and sets `USERPROFILE` alongside `HOME` (`os.homedir()` does not consult `HOME` on win32).
+- **On a real Windows install, a reconfigure's "applied:" line always said "nothing" and the existing-runtime upgrade/conflict checks never fired**, because `bin/cli.js` checked a written file's `f.rel` (backslash-separated on win32, built by `path.join`) directly against `MACHINE_OWNED`/`RUNTIME` (`src/install.js`, hand-written with forward slashes), which never match on that OS. `fileClass()` already normalized before checking; it now exports that normalizer (`toPosixRel`) for `bin/cli.js`'s two direct checks to use too. Both take an optional `separator` parameter (default the real `path.sep`) so the win32 case has a test (`test/install.test.js`) provable from any host. Found via `test/cli.test.js`'s "#6: rerunning with an added lane..." on windows-latest CI.
+- **A replaced child `env` object could carry both `PATH` and the host's own differently-cased `Path` key at once** (`{ ...process.env, PATH: x }` adds a new key next to whichever case the real environment block used; Windows env vars are case-insensitive, plain JS object keys are not), so which one a spawned child actually saw was implementation-defined, not last-key-wins. `test/cli.test.js`'s `mergeEnv()` replaces any existing case-variant of an overridden key instead of adding a second one.
+- **`test/cli.test.js`'s fake lane binaries are `#!/bin/sh` scripts, which Windows cannot execute as `argv[0]`** (no shebang interpretation in `CreateProcess`). `writeShellStub()`/`writeNodeStub()` write a `.cmd` launcher beside the POSIX file on win32 that hands off to Git Bash's `sh.exe` or `node`; `which()`'s detection of the resulting binary works, but running one all the way through `cli-run.mjs`'s own spawn path is not yet reliable on Windows CI for a reason this pass did not fully root-cause. Those specific tests (and the `#12` upgrade-path pair, which diverges in its own, separately unclear way) are skipped on win32 with a stated reason rather than shipped flaky or silently broken; `killTree`'s win32 branch and `which()`'s `%PATHEXT%` resolution each keep their own direct, passing test. A handful of other tests assert an exact POSIX `--dir`/`--project` path string verbatim in output, which `path.resolve()` reinterprets as drive-relative on win32 (a real design question - should a level-3 `--dir` describing a remote Linux box's path ever go through the local host's path semantics at all? - out of scope to decide here) and are skipped the same way. `statSync().mode`'s executable bit is a POSIX-only assertion, dropped on win32 rather than asserted against a filesystem that has no equivalent concept.
+
 ## [0.1.15] - 2026-09-10
 
 The portable parts of a live routing revision, delegate by default, gated on one verified fact rather than a guess: [code.claude.com/docs/en/sub-agents](https://code.claude.com/docs/en/sub-agents) states that a non-fork Claude Code subagent's initial context includes "every level of the CLAUDE.md hierarchy the main conversation loads", and that the built-in Explore and Plan agents skip it. No other lane in this catalog has that documented, so everything below is gated on `subagentsLoadRules(primary)`, currently true for claude-code alone; every other primary keeps its original wording unchanged.
@@ -238,7 +256,8 @@ First release.
 - Tests: a case per fix, judges proven to go red, mutation checks; `npm test` prints the current count.
 - Adversarial audit: two Codex rounds plus a two-engine review (Codex, Antigravity); findings and fixes in `docs/audit-brief.md`. After the review: subagents go to the project root (`--project`), snippet paths computed from `--dir`, lane sections rendered from the selection, a primary agent required, level 3 asks for API keys separately from CLIs, images and CLI installs pinned, an activation summary at the end of every install.
 
-[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.15...HEAD
+[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.16...HEAD
+[0.1.16]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.15...v0.1.16
 [0.1.15]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.14...v0.1.15
 [0.1.14]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.13...v0.1.14
 [0.1.13]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.12...v0.1.13

package/README.md

@@ -72,7 +72,7 @@ An install has two targets, and a scripted run should set both.
 | Flag | Default | What lands there |
 |---|---|---|
 | `--dir` | `./ai-orchestrator` | the docs, protocols and (level 2+) `bin/cli-run.mjs`. Named after what it contains, not after this package, so a project can hold one without looking like a checkout of it. Pass `--dir ./model-orchestrator` if you prefer the package name. |
-| `--project` | the current directory | the subagent definitions, and the rules file your agent reads. Only Claude Code (`.claude/agents/`) and Antigravity (`.agents/agents/`) get files here, because that is the only place those CLIs look. Claude Code also gets two hook scripts in `.claude/hooks/`, wired by a settings snippet you merge yourself. |
+| `--project` | the current directory | the subagent definitions, and the rules file your agent reads. Only Claude Code (`.claude/agents/`) and Antigravity (`.agents/agents/`) get files here, because that is the only place those CLIs look. Claude Code also gets three hook scripts in `.claude/hooks/`, wired by a settings snippet you merge yourself. |
 
 `--project` defaulting to the current directory is the one that surprises people: run the command from your home folder with Claude Code as the primary and five agent files land in your home folder. The installer prints the resolved project path in the plan and says when you left it at the default. Set it.
 
@@ -100,7 +100,7 @@ ai-orchestrator/
   protocols/                build-protocol · propagate · gap-analysis · deep-research · numbers-and-logic · memory-and-record
   CODECALC.md  OBSIDIAN-TC.md  mcp/   companion-tool install docs + per-agent registration snippets (if selected)
   <project>/.claude/agents/ one per tier plus finding-verifier, done-verifier, reader, at the PROJECT root (if Claude Code is primary)
-  <project>/.claude/hooks/  route-gate.mjs (UserPromptSubmit) + subagent-context.mjs (SubagentStart), Claude Code only
+  <project>/.claude/hooks/  route-gate.mjs (UserPromptSubmit) + subagent-context.mjs (SubagentStart) + route-metrics.mjs (all five: see "Measuring routing" below), Claude Code only
   CLAUDE.snippet.md         the block to paste into your CLAUDE.md
   settings.hooks.snippet.json  the hooks block to merge into .claude/settings.json (Claude Code only)
   ROUTING.md                multi-lane decision tree (level 2+)
@@ -117,7 +117,7 @@ ai-orchestrator/
 | [`src/`](src/README.md) | the catalog, the pure planner, detection, rendering |
 | [`templates/`](templates/README.md) | everything the installer can write, by level, plus `tools/` for companions |
 | [`docs/`](docs/README.md) | the three parts and the catalog |
-| [`test/`](test/README.md) | `npm test`: judges proven to go red, catalog integrity, planner, end-to-end install in a temp dir; `.github/workflows/test.yml` runs it on Ubuntu and macOS, Node 18/20/22 |
+| [`test/`](test/README.md) | `npm test`: judges proven to go red, catalog integrity, planner, end-to-end install in a temp dir; `.github/workflows/test.yml` runs it on Ubuntu, macOS and Windows, Node 18/20/22 |
 
 ## What is enforced, what is delegated, what is an instruction
 
@@ -161,7 +161,7 @@ One number per lane, and it is the same number the installer pins: where a lane
 
 **The live canary runs on your machine, with your credentials.** That is what `node bin/cli-run.mjs --doctor --run` is: it sends every enabled lane one tiny prompt through your own sign-ins and reports `canary ok` or `canary FAILED rc=` per lane. Run it after install, and again after any vendor upgrade.
 
-It deliberately does not run in this repository's CI. A canary is only meaningful against real credentials, and there are no credentials a maintainer could supply that would tell **you** anything about **your** lanes: your sign-ins, your quota, your vendor versions. A maintainer-credential canary in CI would prove one machine works and bill someone per run to do it. So CI runs the full suite against stub lanes on Ubuntu and macOS, Node 18/20/22, plus a packaged install into a clean consumer, and the live check ships to you instead.
+It deliberately does not run in this repository's CI. A canary is only meaningful against real credentials, and there are no credentials a maintainer could supply that would tell **you** anything about **your** lanes: your sign-ins, your quota, your vendor versions. A maintainer-credential canary in CI would prove one machine works and bill someone per run to do it. So CI runs the full suite against stub lanes on Ubuntu, macOS and Windows, Node 18/20/22, plus a packaged install into a clean consumer, and the live check ships to you instead.
 
 ## Principles the whole thing rests on
 
@@ -205,6 +205,17 @@ itself.
 
 `done-verifier` probes the artifact a tracker item's done-signal names (a file, a commit, a URL, a log line, a count) and returns MET, NOT_MET or UNVERIFIABLE; it never closes or edits anything itself. It carries no file-editing tools, but on claude-code it does carry `Bash` for those probes (`git log`, `grep`, `wc -l`, `test -f`); staying to read-only commands there is a rule in its prompt, not a restriction on the tool grant, and its own description says so. On agy, `commandExecutionPolicy: off` blocks command execution mechanically instead. `reader` is the one that is read-only by tool grant on both: no `Write`, `Edit`, or `Bash`. It reads and digests many files or notes and hands back exactly what the brief asked for, cited by `path:line`; it never classifies, tags or writes, which is what separates it from `bulk-worker`. Both ship in the claude-code and agy agent sets, at the fast tier.
 
+## Measuring routing
+
+A routing rule nobody measures is a rule nobody knows is followed. On a claude-code install, `route-metrics.mjs` (the third hook, wired to `UserPromptSubmit`, `PreToolUse` on `Agent`/`Task`, `SubagentStart`, `SubagentStop` and `Stop`) turns each of those into one JSON line under `~/.ai-orchestrator/route-metrics.jsonl`: a turn started, a subagent was dispatched (and with what, and in the background or not), a subagent started and stopped (so a duration can be computed), and the lane your agent named in its own hidden `<!-- route: <lane> | <why> -->` marker, which the route-gate block now asks for on every reply. It never logs prompt text, tool descriptions, or the "why" half of the marker: only the named fields above, charset-bounded, same principle as `cli-run.mjs`'s log.
+
+```bash
+node .claude/hooks/route-metrics.mjs --summary                        # since the log began
+node .claude/hooks/route-metrics.mjs --summary --since 2026-09-01     # since a date
+```
+
+The report prints turns, **route-marker coverage** (the percentage of turns whose `Stop` event carried a real lane, not `missing`, which is the number that answers "is the agent actually tagging its routing decisions?"), lanes by count, dispatches by `subagent_type`, dispatches with no matching start (a hook or guard blocked the subagent before it launched), and mean/max duration per agent type. Fail-open by design, like the other two hooks: a miss here is a missing log line, never a blocked turn, and it prints nothing to stdout on any event since stdout on `UserPromptSubmit`/`SubagentStart` becomes model context.
+
 ## Pin the route, or know that you did not
 
 A lane with no `--model`, no `--effort` and no `defaults` entry in
@@ -245,7 +256,7 @@ Yes. `--yes` with `--level`, `--ais` and `--project` runs headless, `--dry-run`
 
 ## Requirements
 
-Node 18 or newer. No dependencies. Works on macOS and Linux; the level 3 box templates assume Ubuntu. Windows is untested: `cli-run` ends a lane's process tree there with `taskkill`, but nothing in CI runs on Windows, so treat it as unsupported until someone reports otherwise.
+Node 18 or newer. No dependencies. Works on macOS and Linux; the level 3 box templates assume Ubuntu. Windows: CI runs the suite on `windows-latest` (Node 18, 20, 22). Install, detection, the hooks and `cli-run`'s `taskkill` tree kill are tested there; a named set of tests is skipped on Windows, each with its reason in the test file, mainly running a lane end to end through `cli-run`, so treat lane execution on Windows as unproven until someone reports otherwise.
 
 **Privacy.** The installer sends no telemetry and makes no network call of its own once it is running. Two things around that are worth being exact about:
 

package/bin/cli-run.mjs

@@ -75,18 +75,33 @@ export const REASONS = new Set([
 
 const LOG = join(homedir(), '.ai-orchestrator', 'cli-run.log.jsonl');
 
+// On win32, a PATH entry never holds a bare "grok": npm and vendor installers
+// drop "grok.cmd" (or .exe/.bat/.ps1), the same way any Windows shell resolves
+// a bare command through %PATHEXT%. Trying the bare name first keeps this a
+// no-op on POSIX and matches an already-extensioned name (a .exe someone put
+// on PATH directly) on Windows too. Kept in sync with src/detect.js's which(),
+// which this file cannot import: it ships standalone into a user's install.
+function candidateExtensions() {
+  if (process.platform !== 'win32') return [''];
+  const pathext = process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD';
+  return ['', ...pathext.split(';').filter(Boolean)];
+}
+
 function which(bin) {
   const dirs = (process.env['PATH'] || '').split(delimiter).filter(Boolean);
   const home = homedir();
   dirs.push(join(home, '.local', 'bin'), join(home, '.grok', 'bin'), join(home, '.npm-global', 'bin'));
+  const exts = candidateExtensions();
   for (const d of dirs) {
-    const p = join(d, bin);
-    try {
-      if (!statSync(p).isFile()) continue; // a directory named like the binary is not the binary
-      accessSync(p, constants.X_OK);
-      return p;
-    } catch {
-      /* next */
+    for (const ext of exts) {
+      const p = join(d, bin + ext);
+      try {
+        if (!statSync(p).isFile()) continue; // a directory named like the binary is not the binary
+        accessSync(p, constants.X_OK);
+        return p;
+      } catch {
+        /* next */
+      }
     }
   }
   return null;

package/bin/cli.js

@@ -10,7 +10,7 @@ import { spawnSync } from 'node:child_process';
 import { resolve, join } from 'node:path';
 import { which } from '../src/detect.js';
 import { AIS, LEVELS, TOOLS, PROVIDERS, aisForLevel, agentCandidates, byId, npmSpec } from '../src/catalog.js';
-import { planFiles, writeFiles, resolveSelection, resolveTools, resolveApis, dirProblems, readManifest, activationSteps, MACHINE_OWNED, RUNTIME, GENERATOR_VERSION } from '../src/install.js';
+import { planFiles, writeFiles, resolveSelection, resolveTools, resolveApis, dirProblems, readManifest, activationSteps, MACHINE_OWNED, RUNTIME, toPosixRel, GENERATOR_VERSION } from '../src/install.js';
 
 // One strict parse. Unknown flags, missing values and duplicates are usage
 // errors (exit 2) before anything is planned, so a typo like --dryy can never
@@ -310,10 +310,10 @@ async function main() {
     if (e && e.code === 'PREFLIGHT') bad(e.message);
     throw e;
   }
-  const ownedWritten = written.filter((w) => MACHINE_OWNED.has(w));
+  const ownedWritten = written.filter((w) => MACHINE_OWNED.has(toPosixRel(w)));
   console.log(`\nWrote ${written.length} file(s)` + (skipped.length ? `, kept ${skipped.length} existing:` : '.'));
   for (const s of skipped) console.log('  kept ' + s);
-  const existingRuntime = files.filter((f) => f.root !== 'project' && RUNTIME.has(f.rel)).length;
+  const existingRuntime = files.filter((f) => f.root !== 'project' && RUNTIME.has(toPosixRel(f.rel))).length;
   if (prev || existingRuntime && (upgraded.length || conflicts.length || unverifiable.length) || docsUnverifiable.length) {
     console.log(`\nExisting installation found${prev ? ` (MANIFEST.json from generator ${prev.generatorVersion || 'pre-0.1.1'}, ${prev.generatedAt || 'undated'}; this run is ${GENERATOR_VERSION})` : ' (no MANIFEST.json: it predates 0.1.1)'}.`);
     if (prev) {

package/docs/audit-brief.md

@@ -102,3 +102,14 @@ Three findings reproduced against the 0.1.15 branch before it shipped, none of t
 | 1 | HIGH. `readFileSync(0)` in both hooks blocked until stdin reached EOF (`sleep 3 \| ... node route-gate.mjs` still running past 1.5s); `route-gate.mjs` also read the whole rules file into memory before bounding it, so a FIFO planted at the rules path blocked forever on open. | Stdin is drained asynchronously against a 250ms hard cap in both hooks. `route-gate.mjs` refuses anything that is not `isFile()` via `statSync` before ever calling open, then reads through one fixed 64 KB buffer via `openSync`/`readSync`. Tests: an open, never-closed stdin pipe exits within 1s for both hooks; a FIFO at the rules path returns the fallback instead of hanging; a 200 MB sparse rules file completes in well under a second with output still capped. |
 | 2 | MEDIUM. `done-verifier`'s description, both agent-folder READMEs, and the root README called it "read-only" without qualification, while its claude-code file carries an unrestricted `Bash` grant; nothing in that grant stops it from running a mutating command. | Every one of those surfaces now says plainly that `done-verifier` carries no file-editing tools and that its Bash use is bound by its own prompt, not by the tool grant; `reader` is named as the one that is read-only by tool grant (no Bash) on both formats. |
 | 3 | MEDIUM. Three generated surfaces still stated the pre-0.1.15 premise on a claude-code install: `builder.md`'s description ("... or the main build itself"), `build-protocol.md`'s roles table and its "why the builder does not hand off" note, and `ROUTING.md`'s "Plan big, execute small" line ("the orchestrator executes"). | All three now render through `subagentsLoadRules(primary)`, the same gate the decision tree and "Who builds" already used; every other primary is unchanged. A semantic-regression test asserts a claude-code install contains none of the old phrasing and a codex install still does. |
+
+## New in 0.1.16: a third hook, route-metrics.mjs
+
+`route-metrics.mjs` ships to `.claude/hooks/` alongside `route-gate.mjs` and `subagent-context.mjs`, only when claude-code is the primary. Same shape as the other two: plain Node, zero deps, mode `0o755`. Unlike them, it is wired to five events at once (`UserPromptSubmit`, `PreToolUse` matched to `Agent|Task`, `SubagentStart`, `SubagentStop`, `Stop`), and it does write, deliberately: one JSON line per event, appended to `~/.ai-orchestrator/route-metrics.jsonl`.
+
+- **Reads.** Only its own stdin (the JSON Claude Code sends per event) and, for `--summary`, its own log file. It never reads `transcript_path` even though that field is present on every event: the documented source for the route marker is `last_assistant_message`, and the docs say the transcript can lag, so a hook that read it instead could log a stale or absent marker as if it were current. It never reads the rules file, the task bundle, or any other project file.
+- **Writes.** `~/.ai-orchestrator/route-metrics.jsonl` (append-only, rotated to `.jsonl.1` above 5 MB) and `~/.ai-orchestrator/route-metrics.state/<sha256(agent_id)>.json`, a small file recording a subagent's start time and type so `SubagentStop` can compute a duration; it is deleted on stop, and anything older than 24h is pruned on the next `SubagentStart`. Nothing outside `~/.ai-orchestrator/`. It never writes to stdout: on `UserPromptSubmit` and `SubagentStart`, stdout becomes model context, and this hook has nothing to say there, so it stays silent on every event, not just those two.
+- **What it never logs.** Prompt text, tool descriptions, the full `tool_input`, `last_assistant_message` itself, or the "why" half of a route marker. Only six named fields ever reach a record: `session_id`, `subagent_type`, `agent_type`, and the parsed `lane`, each stripped to `[A-Za-z0-9_.+-]` and capped at 64 characters (128 for `session_id`) before being written, plus the event name and a `duration_s` number it computed itself. This mirrors `bin/cli-run.mjs`'s own log, which stores a fixed reason code and never a provider-supplied string.
+- **Fail-open, on purpose.** Every code path that can fail (a malformed state file, a full disk, a rotation race, invalid JSON on stdin, an unrecognized event) is caught and produces no record rather than a thrown error or a non-zero exit; the process always exits 0. A miss here is a missing line in a telemetry log, never a blocked turn, so there is nothing to gate.
+- **Bounded.** Stdin is drained asynchronously against a combined 1s time cap and 8 MB size cap; a payload that exceeds either is treated as truncated and parsed as nothing, never partially. `--summary` reads the log directly (never spawns anything, never executes a line in it).
+- **Not yet attacked.** Untested here: two processes racing the same rotation at once (a rename plus an append landing on the same file); a state directory with thousands of leaked files from a long-lived session with a crashed hook (pruning runs, but only on `SubagentStart`, so an install that never starts a subagent again would never prune); behavior if `agent_id` collides across two concurrent subagents (sha256 makes this astronomically unlikely, not impossible).

package/docs/part-2-intermediate.md

@@ -32,7 +32,7 @@ There is a second thing a lane can be quietly wrong about. Left unpinned, it run
 
 ## 4. Every delegation carries a task bundle, on both surfaces
 
-Subagents and CLI lanes are close to the same problem: something that may hold none of your rules, and broad tool access. A Claude Code subagent is the one documented exception, loading the project's CLAUDE.md hierarchy at start, so it keeps the standing rules but not this task's scope; a CLI lane and a fresh chat window get no such credit. The brief (purpose, task class, scope, capabilities, denied actions, conventions, report contract, exit parameters) goes in the prompt or in the file passed to `--brief` either way. If you can, gate it mechanically: a pre-dispatch hook that refuses a brief missing purpose, denied actions or a report contract. On claude-code, a `SubagentStart` hook can inject the essentials (where the rules and the brief format live) automatically; `.claude/hooks/subagent-context.mjs` is the generated example.
+Subagents and CLI lanes are close to the same problem: something that may hold none of your rules, and broad tool access. A Claude Code subagent is the one documented exception, loading the project's CLAUDE.md hierarchy at start, so it keeps the standing rules but not this task's scope; a CLI lane and a fresh chat window get no such credit. The brief (purpose, task class, scope, capabilities, denied actions, conventions, report contract, exit parameters) goes in the prompt or in the file passed to `--brief` either way. If you can, gate it mechanically: a pre-dispatch hook that refuses a brief missing purpose, denied actions or a report contract. On claude-code, a `SubagentStart` hook can inject the essentials (where the rules and the brief format live) automatically; `.claude/hooks/subagent-context.mjs` is the generated example. A third hook, `.claude/hooks/route-metrics.mjs`, turns that same delegation into a measurement instead of an assumption: it logs every turn, dispatch, subagent start/stop and the lane named in the reply's hidden route marker, and `--summary` reports route-marker coverage, dispatches with no matching start, and duration per agent type.
 
 ## 5. Research: three engines, one triager
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "model-orchestrator",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "Model orchestrator for AI coding agents and LLMs: Claude Code, Codex, Gemini, Grok, Qwen, Ollama. Routing rules tell your agent which model, subagent or CLI to use for each task, so small work goes to cheap tiers and fewer tokens go to frontier models. One installer, plus a CLI runner that logs every route.",
   "type": "module",
   "bin": {

package/src/detect.js

@@ -2,24 +2,43 @@ import { accessSync, statSync, constants } from 'node:fs';
 import { delimiter, join } from 'node:path';
 import { homedir } from 'node:os';
 
+// On win32, a PATH entry never holds a bare "grok": npm and vendor installers
+// drop "grok.cmd" (or .exe/.bat/.ps1), the same way any Windows shell resolves
+// a bare command through %PATHEXT%. Trying the bare name first keeps this a
+// no-op on POSIX and matches an already-extensioned name (a .exe someone put
+// on PATH directly) on Windows too.
+// platform is a parameter (default process.platform), not a hardcoded read,
+// so the win32 branch has a test on every OS this suite runs on: the same
+// pattern bin/cli-run.mjs's killTree(pid, platform, deps) already uses.
+export function candidateExtensions(platform = process.platform, pathext = process.env.PATHEXT) {
+  if (platform !== 'win32') return [''];
+  return ['', ...(pathext || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)];
+}
+
 // PATH lookup plus the handful of places vendor installers drop binaries
 // without touching PATH. Never a shell function, never a shell out.
 // A directory with the binary's name is not a binary (X_OK passes on
 // searchable directories), so the candidate must be a regular file.
-export function which(bin) {
+// home is a parameter too (default homedir()), for the same reason platform
+// is: a dev machine with a real ~/.local/bin/grok on it made the win32 tests
+// here false-negative until this was injectable, since PATH alone was never
+// the whole search.
+export function which(bin, platform = process.platform, home = homedir()) {
   if (!bin) return null;
-  const home = homedir();
   const searchPath = process.env['PATH'] || '';
   const dirs = searchPath.split(delimiter).filter(Boolean);
   dirs.push(join(home, '.local', 'bin'), join(home, '.grok', 'bin'), join(home, '.npm-global', 'bin'));
+  const exts = candidateExtensions(platform);
   for (const d of dirs) {
-    const p = join(d, bin);
-    try {
-      if (!statSync(p).isFile()) continue;
-      accessSync(p, constants.X_OK);
-      return p;
-    } catch {
-      /* keep looking */
+    for (const ext of exts) {
+      const p = join(d, bin + ext);
+      try {
+        if (!statSync(p).isFile()) continue;
+        accessSync(p, constants.X_OK);
+        return p;
+      } catch {
+        /* keep looking */
+      }
     }
   }
   return null;

package/src/install.js

@@ -251,6 +251,8 @@ export function routeGateSection(selected) {
     "Stay inline only when: (a) the brief would cost as much as the work itself, (b) the task needs this conversation's own context, (c) it is the human's decision or the final verification of delegated work (a delegate never verifies itself).",
     '',
     'Never: the built-in Explore or Plan agents for rule-bound work (they skip CLAUDE.md). general-purpose taking work a named agent already owns.',
+    '',
+    'End every reply with a hidden marker: `<!-- route: <lane> | <why, a few words> -->`. The route-metrics hook reads only the lane out of it, so routing coverage can be measured instead of assumed.',
     '<!-- route-gate:end -->'
   ].join('\n');
 }
@@ -360,7 +362,7 @@ export function activationSteps(opts) {
   if (primary && primary.agentsDir) steps.push(`subagents are in ${join(projectAbs, primary.agentsDir)}; run ${primary.bin} from ${projectAbs} to pick them up`);
   // Only claude-code ships hooks (route-gate, subagent-context): the wiring
   // lives in a snippet, never written into a settings.json the user already has.
-  if (subagentsLoadRules(primary)) steps.push(`merge the hooks in ${join(dirAbs, 'settings.hooks.snippet.json')} into ${join(projectAbs, '.claude', 'settings.json')} (create it if missing) to wire the route-gate and subagent-context hooks`);
+  if (subagentsLoadRules(primary)) steps.push(`merge the hooks in ${join(dirAbs, 'settings.hooks.snippet.json')} into ${join(projectAbs, '.claude', 'settings.json')} (create it if missing) to wire the route-gate, subagent-context and route-metrics hooks`);
   for (const a of selected.filter((a) => a.bin && a.kind === 'agent-cli')) steps.push(`sign in to ${a.name}: ${a.auth}`);
   // A local runtime has a bin but no sign-in, so the agent-cli loop above skips it
   // and before this it appeared in no ordered list at any level (#26).
@@ -545,6 +547,11 @@ export function planFiles(opts) {
     // written into a settings.json they already have.
     add(join('.claude', 'hooks', 'route-gate.mjs'), render(readFileSync(join(TEMPLATES, 'agents', 'snippets', 'route-gate.mjs'), 'utf8'), v), 0o755, 'project');
     add(join('.claude', 'hooks', 'subagent-context.mjs'), render(readFileSync(join(TEMPLATES, 'agents', 'snippets', 'subagent-context.mjs'), 'utf8'), v), 0o755, 'project');
+    // route-metrics.mjs (0.1.16), claude-code only: five events (UserPromptSubmit,
+    // PreToolUse on Agent|Task, SubagentStart, SubagentStop, Stop) turned into one
+    // JSON line each under ~/.ai-orchestrator/, so a routing rule nobody measures
+    // is not a rule nobody knows is followed.
+    add(join('.claude', 'hooks', 'route-metrics.mjs'), render(readFileSync(join(TEMPLATES, 'agents', 'snippets', 'route-metrics.mjs'), 'utf8'), v), 0o755, 'project');
     add('settings.hooks.snippet.json', render(readFileSync(join(TEMPLATES, 'agents', 'snippets', 'settings.hooks.snippet.json'), 'utf8'), v));
   } else if (primary && primary.id === 'agy') {
     for (const f of walk(join(TEMPLATES, 'agents', 'agy'))) {
@@ -703,8 +710,22 @@ export const RUNTIME = new Set([
   'vm/jobs/weekly-audit.service',
   'vm/jobs/weekly-audit.timer'
 ]);
-export function fileClass(rel) {
-  const r = rel.split(sep).join('/');
+// MACHINE_OWNED and RUNTIME are keyed with forward slashes (they read as
+// prose in the comment above them, and every caller needs the same one
+// spelling regardless of host OS); an f.rel or a writeFiles() "written" path
+// is built with path.join, so it is backslash-separated on win32. Both sets
+// must be checked against the SAME normalized form, or a win32 install
+// silently drops bin/lanes.json and every RUNTIME file from set membership
+// (found: bin/cli.js's own "applied:"/existing-runtime checks did exactly
+// that before this was exported for them to use too).
+// separator is a parameter (default the real path.sep) so a test can prove
+// the win32 case from any host, the same pattern which()'s platform
+// parameter already uses.
+export function toPosixRel(rel, separator = sep) {
+  return rel.split(separator).join('/');
+}
+export function fileClass(rel, separator = sep) {
+  const r = toPosixRel(rel, separator);
   if (MACHINE_OWNED.has(r)) return 'owned';
   if (RUNTIME.has(r)) return 'runtime';
   return 'document';

package/templates/agents/agy/finding-verifier.md

@@ -12,6 +12,12 @@ commandExecutionPolicy: off
 A finding is a claim, not a fact. You try to disprove each one before it is
 allowed to cause a repair.
 
+No file-editing tools, and no command execution: this agent's
+`commandExecutionPolicy` is `off`, so unlike its claude-code counterpart,
+which carries an unrestricted `Bash` and stays read-only by its prompt rather
+than by the tool grant, this agent is mechanically blocked from shelling out;
+probe with whatever read or fetch capability you have instead.
+
 For each finding you are given: read the cited file and line yourself, state the
 input or sequence that would trigger it, then hunt for what makes it impossible
 (a guard upstream, a caller that never passes that value, an existing test).

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: Adversarial 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/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.

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"]
           }
         ]
       }