model-orchestrator 0.1.13 → 0.1.15

package/AGENTS.md

@@ -0,0 +1,26 @@
+# AGENTS.md
+
+Two audiences: an agent that wants to USE this package for a project, and an agent that is working ON this repository.
+
+## Using this package from an agent
+
+model-orchestrator writes routing rules, subagents and a CLI lane runner so an agent sends each task to the right model, subagent or CLI and spends fewer frontier tokens. It is not a proxy or gateway. Headless use:
+
+- `npx model-orchestrator --list` prints every supported AI id.
+- `npx model-orchestrator --yes --level 2 --ais claude-code,codex --project <repo> --dir <repo>/ai-orchestrator --dry-run` prints the plan and writes nothing.
+- Drop `--dry-run` to write it. Existing files are never overwritten without `--force`; activation snippets (for example `CLAUDE.snippet.md`, `settings.hooks.snippet.json`) are written for a person or agent to merge.
+- The generated `README.md` in `--dir` lists what to copy where and one smoke command to prove the rules took.
+- A summary for LLMs, with links to every doc: [`llms.txt`](llms.txt).
+
+## Working on this repository
+
+The files the installer writes for end users live under `templates/`.
+
+- Read `CONTRIBUTING.md` first, then `src/README.md` (the catalog drives everything) and `docs/audit-brief.md` (the threat model and what has already been attacked).
+- Run `npm test` before proposing a change and quote the count and the exit code; the suite prints the current number.
+- Everything renders from `src/catalog.js`. Add an AI or a tool there, not in a template. Templates carry no logic.
+- Never put a value that looks like a credential anywhere in this repo, including tests and examples. Environment variable names only.
+- `bin/cli.js` writes only inside `--dir` and `--project`, never over a document without `--force`, and never runs a vendor script. A change that weakens any of those will be refused in review; the tests that hold them are in `test/install.test.js` and `test/cli.test.js`.
+- `bin/cli-run.mjs` must exit non-zero when a lane produced nothing. Every judge has a red case in `test/judges.test.js`; add one before you change a judge.
+- Prose in this repo uses no em dashes (`test/prose.test.js` enforces it).
+- Why these rules exist: each one is the fix for a failure that reached an audit or CI. `CHANGELOG.md` names the issue behind each.

package/CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ## [Unreleased]
 
+## [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.
+
+### Added
+
+- **`subagentsLoadRules: true` on the claude-code catalog entry**, with the doc quote as its comment. Drives every new render var below through `src/install.js`; nothing here is a template branch, per the house rule that templates carry no logic.
+- **Builder executes by default, on claude-code.** `ROUTING.md` rule 5, its "Who builds" section, the "Add an endpoint" example, and the claude-code `CLAUDE.snippet.md` now say: the orchestrator plans, briefs, verifies and talks to the human; it stays inline only when (a) the brief would cost as much as the work, (b) the task needs this conversation's own context, or (c) it is the human's decision or the final verification of delegated work. Every other primary keeps "the orchestrator builds it directly."
+- **Two hooks, claude-code only: `route-gate.mjs` (`UserPromptSubmit`) and `subagent-context.mjs` (`SubagentStart`)**, written to `.claude/hooks/`, wired by a `settings.hooks.snippet.json` the user merges into `.claude/settings.json` themselves, never written over one they have. `route-gate.mjs` reads the `<!-- route-gate:start -->...<!-- route-gate:end -->` block out of the rendered routing rules file and injects it every turn, so the table is read from the one place it is generated, not recited from memory; a missing file or block still exits 0 with a one-line fallback naming the path it looked for. `subagent-context.mjs` injects a static reminder of where the rules and `TASK_BUNDLE.md` live and that a delegate does not route further or verify its own work as final. Both are plain Node, zero deps, bounded reads, fail-open by design (a miss is a stray context string, not a gate): see `docs/audit-brief.md`.
+- **`done-verifier` and `reader`, two new fast-tier agents with no file-editing tools, in both the claude-code and agy formats.** `done-verifier` probes a tracker item's stated done-signal (a file, a commit, a URL, a log line, a count) and returns MET, NOT_MET or UNVERIFIABLE; it never closes or edits anything. `reader` reads and digests many files or notes and returns exactly what the brief asks (facts, quotes cited `path:line`, an index, a digest); unlike `bulk-worker`, it never classifies, tags, transforms or writes. `reader` is read-only by tool grant on both formats (no `Bash`); `done-verifier` on claude-code carries `Bash` for its probes, bound only by its prompt, not by the grant, and its description says so; on agy, `commandExecutionPolicy: off` blocks command execution mechanically instead. `ROUTING.md`'s decision tree, `TIERS.md`'s effort table, and both agent-folder READMEs now name them.
+- **The inline threshold gets a measurement instead of a guessed figure.** "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." (claude-code `ROUTING.md` and `CLAUDE.snippet.md` only; no private number shipped.)
+
+### Changed
+
+- **The package now says what it is for in the first line people and agents read.** npm search, GitHub search and the installer banner showed "Routing instructions and a CLI runner", which named the parts and not the purpose. The description, the README opening and the banner now lead with the goal (each task to the right model, agent or LLM, fewer frontier tokens) while keeping the 0.1.11 correction intact: routing is an instruction your agent follows, and the README still states it does not automatically compare prices or select models. A test holds all three surfaces to that. New: an "At a glance" block and question-shaped "Common questions" in the README, request-level alternatives named for readers who want a proxy, `llms.txt` at the root and a headless-use section in `AGENTS.md` (both now ship in the package), and search keywords matching what comparable routers use.
+- **Corrected the unqualified premise "a subagent holds none of these rules" everywhere it appeared** (`TASK_BUNDLE.md`, `ORCHESTRATOR.md`, the claude-code snippet, `docs/part-1-beginner.md`, `docs/part-2-intermediate.md`, README principle 6, and `ROUTING.md`'s "Who builds"). The corrected fact: a Claude Code subagent loads CLAUDE.md and so keeps the standing rules, just not this task's scope; a second CLI or a fresh chat window may still hold none of it. "Absence is denial" is unchanged; only the premise about who is absent what was wrong.
+- **The claude-code snippet's closing "available as ..." agent list is generated from the files actually shipped in `templates/agents/claude-code/`, never hand-typed.** It had drifted once already: `finding-verifier` shipped in 0.1.14 and was missing from this sentence until now. `claudeAgentIds()` in `src/install.js` reads the folder; a test ties the rendered list to it.
+- **The delegate-by-default gate now reaches every generated surface it should, not just three of them.** `build-protocol.md`'s "Roles, as capabilities" table and its "Why the builder does not hand off the main build" line, `builder.md`'s description, and `ROUTING.md`'s "Plan big, execute small" modifier still said, on a claude-code install, that the orchestrator writes the main build itself, never hands it off whole, and that a delegate inherits none of the session's rules: the exact premise the rest of this release corrects. All four now render through `subagentsLoadRules(primary)` the same way the decision tree and "Who builds" already did; 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.
+
+### Fixed
+
+- **Both new hooks could hang, and `route-gate.mjs` could read an unbounded or blocking file (pre-release audit finding, never shipped).** `readFileSync(0)` in both `route-gate.mjs` and `subagent-context.mjs` blocked until stdin reached EOF, so a caller that piped input in without closing its end (or ran the hook from a bare TTY) left the process running indefinitely; reproduced with `sleep 3 | CLAUDE_PROJECT_DIR=... node route-gate.mjs` still running past 1.5s. Separately, `route-gate.mjs` read the whole rules file into memory before bounding it (`readFileSync(path).slice(0, MAX_READ)`), so a FIFO planted at the rules path blocked forever on open, and a very large file was read in full before being truncated. Fixed in both hooks: stdin is now drained asynchronously against a 250ms hard cap, never blocking past it. `route-gate.mjs` additionally `statSync`s the resolved path and refuses anything that is not `isFile()` (a FIFO, socket, device or directory, symlink target included) before ever calling open, then reads through a single fixed 64 KB buffer via `openSync`/`readSync`, closed in a `finally`, so neither the read time nor the memory used depends on the file's on-disk size. Tests: an open, never-closed stdin pipe now 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.
+
+Three refinements to the routing model, from a review by [@shawnwows](https://x.com/shawnwows). The theme is the same in all three: a routing decision that was implied, inherited or asserted is now stated, pinned or checked.
+
+### Added
+
+- **`--model` and `--effort` on every lane, and a route recorded per run.** A lane with no flag and no `defaults` entry in `bin/lanes.json` runs on its own config file, which `cli-run` cannot see: a CLI configured months ago at a low reasoning effort keeps auditing at that effort while the routing docs describe an adversarial pass, and nothing raises an error. Each vendor spells the flags differently and `cli-run` translates (`grok -m/--reasoning-effort`, `codex -m/-c model_reasoning_effort="X"`, `agy --model/--effort`, `hermes -m/--reasoning`, `qwen -m` and no reasoning flag), each one read from that CLI's own `--help`. Flags beat `defaults`, `defaults` beats nothing, `--doctor` prints what each lane is pinned to, and the log carries `model_requested`, `effort_requested`, `model_source` and `effort_source` on every record, including runs refused before the lane started. It records no "actual": one lane of five (grok) reports a model id in its own output and the other four report none, so the field would be populated for one lane and empty for four, and it would be a provider-supplied string, which the durable log never holds. `--effort` on qwen is a usage error rather than a silent drop, and route values are charset-bounded because a model id becomes an argv element and, on codex, part of a TOML value.
+- **`finding-verifier`, a sixth subagent, in both agent formats.** Review and scanner findings no longer go straight to a repair. It reads the cited line, states what would trigger the problem, hunts for the guard, caller or test that makes it impossible, and returns CONFIRMED, NOT_REPRODUCED or INCONCLUSIVE per finding. Only CONFIRMED earns a change; INCONCLUSIVE is never rounded up to be safe or down to be tidy. Bound into the build protocol as Stage 5a, into `ROUTING.md`, and into the Claude Code activation snippet. The reproduction rule already existed in Stage 5; it had no owner, no separate model family and no way to say "I could not settle this".
+- **Complexity and risk as inputs, alongside role** (`TIERS.md`). Complexity moves the effort: a worker executing a finished plan needs less reasoning than the reviewer judging its output. Risk (security, privacy, data loss, irreversible) moves the tier and who reads the result, because none of those failures is fixable by editing the code afterwards. A one-line change to an auth check is simple and high-risk at once, and the risk decides. Deliberately two rules and two small tables rather than a role by complexity by risk matrix: an 80-cell table is not maintained, and an unmaintained routing table is worse than none because it is believed.
+
+### Changed
+
+- `--model` is no longer qwen-only. `--safe-mode` still is.
+- The route is resolved before the "lane disabled" and "binary missing" refusals, so those records carry it too. Found by the pre-release audit: a run refused for a missing binary is still a run that requested a route, and a failure record without one is the gap this release exists to close.
+- `bin/lanes.json` gains an optional `defaults` block. It fails closed with the rest of the file: an unknown lane, an unknown key, a value outside the charset, or an effort pinned on a lane with no reasoning flag refuses every lane until it is fixed, rather than being skipped quietly.
+- The generated activation list gains a step about pinning the route, and `--doctor` output gains a route column with a plain sentence about what "not pinned" means.
+
 ## [0.1.13] - 2026-09-08
 
 Three issues from a fresh first-run walkthrough of 0.1.12 (#26, #27, #28). Same class as 0.1.12's five: a surface describing an install that did not happen. A fourth, #25, was filed and closed as a mistake on the reporter's side, not a defect: the warning it said was missing has been printed since 0.1.12 and the repro had been read through a truncated pipe.
@@ -200,7 +238,9 @@ 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.13...HEAD
+[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.15...HEAD
+[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
 [0.1.12]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.11...v0.1.12
 [0.1.11]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.10...v0.1.11

package/README.md

@@ -2,7 +2,16 @@
 
 [![npm](https://img.shields.io/npm/v/model-orchestrator.svg)](https://www.npmjs.com/package/model-orchestrator) [![test](https://github.com/aunysillyme/model-orchestrator/actions/workflows/test.yml/badge.svg)](https://github.com/aunysillyme/model-orchestrator/actions/workflows/test.yml) [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![node >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
 
-**Routing instructions and a CLI runner for your AI tools.** One installer asks what you have access to and generates a matching setup, from one chat app to several agent CLIs or a virtual machine. Your primary agent follows the instructions to choose a tier or lane; the runner executes the lane it is given. It does not automatically compare prices or select models.
+**Route every task to the right model, agent or LLM, and spend fewer tokens.** A model orchestrator for AI coding agents and LLMs: Claude Code, Codex, Gemini, Grok, Qwen, Ollama. One installer asks what you have access to and writes routing rules, subagents and a CLI runner for exactly that setup, from one chat app to several agent CLIs or a virtual machine. 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; the runner executes the lane it is given. On Claude Code it also delegates execution to subagents by default, with two hooks that inject the routing table every turn.
+
+## At a glance
+
+- **What it is:** routing rules, subagent definitions and a CLI lane runner (`cli-run`) for the AI tools you already pay for.
+- **What it is not:** a proxy, a gateway or an API router. It does not automatically compare prices or select models; your agent follows the rules and chooses.
+- **Install:** `npx model-orchestrator` (interactive), or headless from a script or an agent: `npx model-orchestrator --yes --level 2 --ais claude-code,codex --project . --dir ./ai-orchestrator`.
+- **Use it when:** you run more than one model or agent and want each task sent to the smallest one that can do it well.
+- **What it saves:** frontier-model tokens. Bulk work, reading and checks go to fast tiers; the expensive tier is kept for planning and judgment.
+- **For agents:** [`llms.txt`](llms.txt) summarizes the package and links every doc; [`AGENTS.md`](AGENTS.md) has the headless commands.
 
 Built from a working system, not a diagram: the routing rules, the protocols and the lane runner here run in production, generalized so they transfer to any stack.
 
@@ -18,14 +27,14 @@ The installer asks a few things, then writes a folder:
 2. **Which AIs do you have access to?** (it marks the ones already on your PATH)
 3. **Which one is your primary agent?** (the one that runs the system)
 
-It never writes a secret, never runs a vendor shell script for you, and never overwrites a document you already have unless you pass `--force`. Two exceptions, both stated when they happen: `MANIFEST.json` and `bin/lanes.json` are machine-owned and rewritten on every run so a changed selection applies; runtime files (`cli-run`, the audit job, compose, gateway config, setup script) are upgraded when the installed copy matches the hash a previous run recorded, kept and reported as a conflict when you edited them, and kept as unverifiable when no manifest exists (`--upgrade-runtime` replaces runtime files only). The same hash rule is available for documents on request: `--update-docs` regenerates the documents a previous run wrote and nobody edited, so a changed selection reaches `ROUTING.md` and the delegation matrix without `--force`; edited documents are kept and named. Docs and protocols go to `--dir` (default `./ai-orchestrator`); subagent definitions go to the project root your agent runs from (`--project`, default the current directory), because that is the only place Claude Code and Antigravity read them. It ends with an activation summary: what to copy where, which sign-ins, and one smoke command. Uninstall: follow the generated README. Inspect the manifest and remove only the individual managed subagent files you no longer need, preserve edited or pre-existing files, and remove your manually pasted activation block. Never delete a shared subagent folder.
+It never writes a secret, never runs a vendor shell script for you, and never overwrites a document you already have unless you pass `--force`. Two exceptions, both stated when they happen: `MANIFEST.json` and `bin/lanes.json` are machine-owned and rewritten on every run so a changed selection applies; runtime files (`cli-run`, the audit job, compose, gateway config, setup script) are upgraded when the installed copy matches the hash a previous run recorded, kept and reported as a conflict when you edited them, and kept as unverifiable when no manifest exists (`--upgrade-runtime` replaces runtime files only). The same hash rule is available for documents on request: `--update-docs` regenerates the documents a previous run wrote and nobody edited, so a changed selection reaches `ROUTING.md` and the delegation matrix without `--force`; edited documents are kept and named. Docs and protocols go to `--dir` (default `./ai-orchestrator`); subagent definitions (and, on Claude Code, two hook scripts) go to the project root your agent runs from (`--project`, default the current directory), because that is the only place Claude Code and Antigravity read them. It ends with an activation summary: what to copy where, which sign-ins, and one smoke command. Uninstall: follow the generated README. Inspect the manifest and remove only the individual managed subagent files you no longer need, preserve edited or pre-existing files, and remove your manually pasted activation block. Never delete a shared subagent folder.
 
 ## The three levels
 
 | Level | You have | You get |
 |---|---|---|
 | **1 · Beginner** | one LLM or one agent | tiers, task classification, the two build checkpoints, the protocols (build, propagate, gap analysis, deep research, numbers and logic, memory and record), a task-bundle template, and your agent set up to follow them |
-| **2 · Intermediate** | several AIs with CLIs | everything above, plus `cli-run` (exit 0 means a structurally accepted non-empty response; opt-in `--expect-file` / `--expect-json` for real contracts), a delegation matrix generated from your selection, research triage across the lanes you have |
+| **2 · Intermediate** | several AIs with CLIs | everything above, plus `cli-run` (exit 0 means a structurally accepted non-empty response; opt-in `--expect-file` / `--expect-json` for real contracts; `--model` / `--effort` to pin the route and log it), a delegation matrix generated from your selection, research triage across the lanes you have |
 | **3 · Advanced** | a virtual machine | everything above, plus a gateway config rendered from the API keys you hold (asked separately from your CLIs), pinned images, box rules, privacy gates, and a weekly gap-analysis job with "what watches it" written down |
 
 Read the thinking behind each level in [docs/](docs/README.md): [Part 1](docs/part-1-beginner.md) · [Part 2](docs/part-2-intermediate.md) · [Part 3](docs/part-3-advanced.md).
@@ -63,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. |
+| `--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` 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.
 
@@ -90,8 +99,10 @@ ai-orchestrator/
   TASK_BUNDLE.md            the brief every delegation carries
   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/ five subagents, one per tier, at the PROJECT root (if Claude Code is primary)
+  <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
   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+)
   TIERS.md  DELEGATION_MATRIX.md  RESEARCH_TRIAGE.md  CLI-RUN.md
   bin/cli-run.mjs  bin/lanes.json          (node bin/cli-run.mjs --doctor is the smoke test)
@@ -159,9 +170,79 @@ It deliberately does not run in this repository's CI. A canary is only meaningfu
 3. **Exit 0 is not a deliverable.** Check for the artifact, not the status line. `cli-run` checks the response is structurally there; `--expect-file` checks the artifact.
 4. **Numbers are computed, never guessed.** A tool that calculates beats a model that feels finished.
 5. **A write nobody can find again did not happen.** Search first, keep the index true, one writer.
-6. **The orchestrator owns the main build.** Delegates hold none of your rules; they get bounded sub-parts and a brief.
+6. **A delegate's brief carries this task's scope, whatever it already holds.** A Claude Code subagent loads the project's CLAUDE.md hierarchy at start, so it already has the standing rules; a second CLI or a fresh chat window may hold none of them. Either way, only the brief carries what this task needs. On claude-code, that changes who executes: see "Who builds" in `ROUTING.md`.
 7. **Only one process holds keys.** Names in the environment, values in a secrets manager, never in a file here.
 
+## Routing by role, complexity and risk
+
+Role picks the agent. Two more inputs move the choice, and they move it in
+different directions, so `TIERS.md` states them separately rather than folding
+them into the role:
+
+- **Complexity moves the effort.** A worker executing a finished plan needs less
+  reasoning than the reviewer judging its output. When the plan is airtight the
+  spec is carrying the thinking.
+- **Risk moves the tier and the reader.** Security, privacy, data loss and
+  irreversible changes buy the attack lane, a named check, a rollback path or a
+  human yes. A one-line change to an auth check is simple and high-risk at the
+  same time, and it is the risk that decides.
+
+The top of the ladder is bought with evidence: a reproduced failure, an
+unresolved checkpoint, an irreversible change. A task that merely feels hard is
+a deep-tier task, not an escalation.
+
+## A finding is a claim, not a fact
+
+Review findings do not go straight to a repair. `finding-verifier` reads the
+cited line, states what would trigger the problem, then hunts for the guard,
+caller or test that makes it impossible, and returns **CONFIRMED**,
+**NOT_REPRODUCED** or **INCONCLUSIVE** per finding. Only CONFIRMED earns a
+change. Use a different model family from the one that produced the finding
+where you have one: a family asked to check its own claim tends to agree with
+itself.
+
+## Two more fast-tier checks
+
+`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.
+
+## Pin the route, or know that you did not
+
+A lane with no `--model`, no `--effort` and no `defaults` entry in
+`bin/lanes.json` runs on **its own config file**, which `cli-run` cannot see. A
+CLI configured months ago at a low reasoning effort keeps auditing at that
+effort while your routing docs describe an adversarial pass.
+
+```bash
+node bin/cli-run.mjs codex "<prompt>" --model gpt-6-astra --effort high
+node bin/cli-run.mjs --doctor     # prints what each lane is pinned to, and what is not pinned
+```
+
+Every run logs the model and effort **requested** and where the request came
+from: `flag`, `lanes.json`, or `lane_default`, on every record including the
+runs that never reached a lane. It does not log an actual. One lane of five
+(grok) reports a model id in its own output and the other four report none, so
+an actual field would be present for one lane and missing for four, and it
+would be a provider-supplied string, which the durable log deliberately never
+holds.
+
+## Common questions
+
+### How do I cut token usage across Claude Code, Codex and Gemini?
+
+Install for the tools you have, then let the generated `ROUTING.md` decide the tier per task: bulk, reading and verification go to the fast tier or a cheaper CLI lane, and the deep tier only plans and judges. On Claude Code, execution goes to the `builder` subagent by default and the main session plans and verifies. Every lane call through `cli-run` logs the model and effort it ran with, so you can check where the tokens went.
+
+### How do I route tasks to cheaper models?
+
+The rules route by role, complexity and risk (see [Routing by role, complexity and risk](#routing-by-role-complexity-and-risk)). Role picks the agent, complexity moves the effort, risk moves the tier. A task a cheap tier finishes correctly never gets a frontier token.
+
+### Is this an LLM router or an AI gateway?
+
+No. It routes at the task level, through instructions your agent follows and a runner for agent CLIs. If you want a service or proxy that picks or forwards the model on every API request, look at request-level routers and gateways such as RouteLLM, LiteLLM, OpenRouter or claude-code-router. They solve a different problem and can sit underneath this.
+
+### Can an agent install and run it without a person?
+
+Yes. `--yes` with `--level`, `--ais` and `--project` runs headless, `--dry-run` previews the plan, and `--list` prints every supported AI. Nothing is appended to a file you already have; activation snippets are written next to your files for you to merge.
+
 ## 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.
@@ -177,6 +258,14 @@ Node 18 or newer. No dependencies. Works on macOS and Linux; the level 3 box tem
 
 Add an AI to `src/catalog.js` and every prompt, table, config and doc picks it up. Run `npm test`. Keep templates free of logic and free of anything that looks like a credential. The rest is in [CONTRIBUTING.md](CONTRIBUTING.md); releases in [RELEASING.md](RELEASING.md); security reports in [SECURITY.md](SECURITY.md).
 
+## Credits
+
+- [@shawnwows](https://x.com/shawnwows) reviewed the router and made the case for
+  separating role, complexity and risk instead of compressing them into one
+  scale, for recording the model and effort a lane was actually asked for, and
+  for verifying findings before they trigger repairs. All three shipped in
+  0.1.14.
+
 ## License
 
 [MIT](LICENSE)

package/bin/cli-run.mjs

@@ -39,6 +39,17 @@
 //
 // The durable log stores a FIXED reason code per run (see REASONS), never a
 // provider-supplied string. Bounded vendor stderr goes to your terminal only.
+//
+// ROUTE: which model and reasoning effort a lane ran with.
+// A lane with no --model and no lanes.json default inherits whatever its own
+// config file says, which is invisible from here and is how a documented route
+// silently stops being the route that runs. --model / --effort pin it per call,
+// `defaults` in lanes.json pins it per lane, and every run logs the value that
+// was REQUESTED plus where the request came from (flag, lanes.json, or nothing
+// at all). It does not log an "actual". One lane of five (grok) does report a
+// model id in its own output; the other four report none, and a field present
+// for one lane and absent for four is worse than no field. It would also be a
+// provider-supplied string, which this log deliberately never holds.
 
 import { spawn } from 'node:child_process';
 import { StringDecoder } from 'node:string_decoder';
@@ -190,28 +201,71 @@ export function judgeQwen(rc, out) {
   return pass(text, `subtype=success, totalErrors=0 across ${Object.keys(models).length} model(s)`);
 }
 
+// --- route: model and effort per lane --------------------------------------
+// Each vendor spells these differently, and the spelling was read from each
+// CLI's own --help, not remembered. A lane with `effort: null` has no reasoning
+// flag at all; asking for one there is a usage error, never a silent drop.
+//   grok    -m MODEL   --reasoning-effort EFFORT
+//   codex   -m MODEL   -c model_reasoning_effort="EFFORT"   (a TOML override, hence the quotes)
+//   agy     --model M  --effort EFFORT                      (low|medium|high)
+//   hermes  -m MODEL   --reasoning LEVEL                    (none|minimal|...)
+//   qwen    -m MODEL   no reasoning flag
+export const LANE_FLAGS = {
+  grok: { model: (v) => ['-m', v], effort: (v) => ['--reasoning-effort', v] },
+  codex: { model: (v) => ['-m', v], effort: (v) => ['-c', `model_reasoning_effort="${v}"`] },
+  agy: { model: (v) => ['--model', v], effort: (v) => ['--effort', v] },
+  hermes: { model: (v) => ['-m', v], effort: (v) => ['--reasoning', v] },
+  qwen: { model: (v) => ['-m', v], effort: null }
+};
+
+// A model id or effort level becomes an argv element and, for codex, part of a
+// TOML value. Bounding the charset is what makes both safe: no leading dash (a
+// value cannot become a flag), no quote, space or control character (a value
+// cannot break out of the TOML string), and a length cap so a config file
+// cannot push an unbounded string into the durable log.
+export const ROUTE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:@/+-]{0,63}$/;
+export function badRouteValue(kind, v) {
+  if (typeof v !== 'string' || !ROUTE_VALUE.test(v)) {
+    return `--${kind} must be 1 to 64 characters of letters, digits, dot, underscore, colon, at, slash, plus or dash, and may not start with a dash: ${JSON.stringify(v)}`;
+  }
+  return null;
+}
+
 // --- adapters: build argv for a lane -------------------------------------
+// Route flags go in front of the prompt for every lane, because two lanes
+// (hermes, codex) take the prompt as a positional argument and a flag after it
+// is either ignored or read as part of it.
+function routeFlags(lane, opts) {
+  const spec = LANE_FLAGS[lane];
+  const out = [];
+  if (!spec) return out;
+  if (opts.model) out.push(...spec.model(opts.model));
+  if (opts.effort && spec.effort) out.push(...spec.effort(opts.effort));
+  return out;
+}
+
 export function buildArgv(lane, binary, prompt, opts, tmp) {
   const timeout = opts.timeout;
+  const route = routeFlags(lane, opts);
   switch (lane) {
     case 'grok':
-      return { argv: [binary, '--output-format', 'json', '-p', prompt] };
+      return { argv: [binary, '--output-format', 'json', ...route, '-p', prompt] };
     case 'codex': {
       const last = join(tmp, 'last.txt');
       const argv = [binary, 'exec', '--json', '--color', 'never', '--skip-git-repo-check', '-o', last];
       if (opts.audit) argv.push('--sandbox', 'read-only'); // an audit lane that can write is a bug
+      argv.push(...route);
       argv.push(prompt);
       return { argv, outFile: last };
     }
     case 'agy': {
       const mins = Math.max(1, Math.round(timeout / 60));
-      return { argv: [binary, '--print-timeout', `${mins}m`, '--output-format', 'stream-json', '-p', prompt] };
+      return { argv: [binary, '--print-timeout', `${mins}m`, '--output-format', 'stream-json', ...route, '-p', prompt] };
     }
     case 'hermes':
-      return { argv: [binary, '-z', prompt, '--usage-file', join(tmp, 'usage.json')] };
+      return { argv: [binary, '-z', ...route, prompt, '--usage-file', join(tmp, 'usage.json')] };
     case 'qwen': {
-      const argv = [binary, '-o', 'json'];
-      if (opts.model) argv.push('-m', opts.model);
+      const argv = [binary, '-o', 'json', ...route];
       if (opts.safeMode) argv.push('--safe-mode');
       argv.push('-p', prompt);
       return { argv };
@@ -370,26 +424,67 @@ function log(rec) {
 // documented default). PRESENT BUT UNREADABLE OR MALFORMED = no lane enabled:
 // a half-written config must fail closed, never re-enable what the installer
 // disabled. Returns null when the file is bad so the caller can say so.
-export function enabledLanes(here = dirname(fileURLToPath(import.meta.url))) {
+export function laneConfig(here = dirname(fileURLToPath(import.meta.url))) {
   const p = join(here, 'lanes.json');
-  if (!existsSync(p)) return LANES;
+  if (!existsSync(p)) return { enabled: LANES, defaults: {} };
   try {
     const j = JSON.parse(readFileSync(p, 'utf8'));
     if (!j || typeof j !== 'object' || !Array.isArray(j.enabled)) return null;
     if (!j.enabled.every((l) => typeof l === 'string' && LANES.includes(l))) return null;
-    return j.enabled;
+    // `defaults` pins a model and effort per lane. It is optional; present and
+    // malformed fails closed with the rest of the file, because a half-written
+    // route is exactly the silent-inheritance problem this field exists to fix.
+    const defaults = {};
+    if (j.defaults !== undefined) {
+      if (!j.defaults || typeof j.defaults !== 'object' || Array.isArray(j.defaults)) return null;
+      for (const [lane, d] of Object.entries(j.defaults)) {
+        if (!LANES.includes(lane)) return null;
+        if (!d || typeof d !== 'object' || Array.isArray(d)) return null;
+        const { model, effort, ...rest } = d;
+        if (Object.keys(rest).length) return null;
+        if (model !== undefined && badRouteValue('model', model)) return null;
+        if (effort !== undefined) {
+          if (badRouteValue('effort', effort)) return null;
+          if (!LANE_FLAGS[lane] || !LANE_FLAGS[lane].effort) return null; // a lane with no reasoning flag cannot have one pinned
+        }
+        defaults[lane] = { model: model ?? null, effort: effort ?? null };
+      }
+    }
+    return { enabled: j.enabled, defaults };
   } catch {
     return null;
   }
 }
 
+// Kept as the narrow question most callers ask. null still means malformed.
+export function enabledLanes(here = dirname(fileURLToPath(import.meta.url))) {
+  const c = laneConfig(here);
+  return c === null ? null : c.enabled;
+}
+
+// Flag beats lanes.json beats nothing. `source` is what makes the log audit-worthy:
+// 'lane_default' means this run inherited the vendor CLI's own config, unseen from here.
+export function resolveRoute(lane, opts, defaults) {
+  const d = (defaults && defaults[lane]) || {};
+  const model = opts.model ?? d.model ?? null;
+  const effort = opts.effort ?? d.effort ?? null;
+  const src = (flag, def) => (flag != null ? 'flag' : def != null ? 'lanes.json' : 'lane_default');
+  return { model, effort, model_source: src(opts.model, d.model), effort_source: src(opts.effort, d.effort) };
+}
+
 function usage(msg) {
   if (msg) console.error('cli-run: ' + msg);
   console.error(`usage: cli-run <${LANES.join('|')}> "<prompt>" [--brief FILE] [--timeout SECS] [--quiet]
-                [--expect-file PATH] [--expect-json]
+                [--model ID] [--effort LEVEL] [--expect-file PATH] [--expect-json]
        cli-run codex --audit "<prompt>"          read-only sandbox (audit shape)
-       cli-run qwen [--model ID] [--safe-mode] "<prompt>"
-       cli-run --doctor [--run]                  enabled lanes, binaries on PATH; --run sends each a tiny prompt`);
+       cli-run qwen [--safe-mode] "<prompt>"     qwen-only flag
+       cli-run --doctor [--run]                  enabled lanes, binaries, and the route each one is pinned to
+
+  --model / --effort pin what a lane runs with, instead of letting it inherit its
+  own config. Every lane takes --model; every lane except qwen takes --effort.
+  Levels are the vendor's own (agy low|medium|high, hermes none|minimal|...): an
+  unknown level is rejected by the lane, and reported as that lane's exit code.
+  Pin them per lane instead of per call with "defaults" in bin/lanes.json.`);
   return USAGE;
 }
 
@@ -416,11 +511,12 @@ function installedPrimary(here = dirname(fileURLToPath(import.meta.url))) {
 
 // --doctor: the first thing to run after install.
 export async function doctor(run) {
-  const enabled = enabledLanes();
-  if (enabled === null) {
+  const cfg = laneConfig();
+  if (cfg === null) {
     console.error('doctor: lanes.json exists but is malformed; fix it first');
     return USAGE;
   }
+  const { enabled, defaults } = cfg;
   let bad = 0;
   console.log(`doctor: ${enabled.length} enabled lane(s): ${enabled.join(', ') || 'none'}`);
   const primary = installedPrimary();
@@ -432,7 +528,11 @@ export async function doctor(run) {
   for (const lane of LANES) {
     const on = enabled.includes(lane);
     const bin = which(lane);
-    let line = `  ${lane.padEnd(7)} ${on ? 'enabled ' : 'disabled'} ${bin ? 'binary ok' : 'binary MISSING'}`;
+    const d = defaults[lane] || {};
+    // A disabled lane has no route worth reporting; saying "not pinned" there
+    // reads as a finding about a lane that is not going to run.
+    const route = !on ? '' : d.model || d.effort ? `route ${d.model || 'lane default'}/${d.effort || 'lane default'}` : 'route not pinned (inherits the lane\'s own config)';
+    let line = `  ${lane.padEnd(7)} ${on ? 'enabled ' : 'disabled'} ${bin ? 'binary ok' : 'binary MISSING'}${route ? '  ' + route : ''}`;
     if (on && !bin) bad++;
     if (on && bin && run) {
       const rc = await main([lane, 'Reply with exactly the word OK and nothing else.', '--timeout', '120', '--quiet']);
@@ -443,6 +543,7 @@ export async function doctor(run) {
   }
   console.log(bad ? `doctor: ${bad} problem(s)` : 'doctor: all enabled lanes ' + (run ? 'answered' : 'present'));
   console.log('doctor checks presence and, with --run, a one-word canary. It does not check vendor versions.');
+  console.log('"route not pinned" means that lane runs on whatever its own config file says, which this tool cannot see. Pin it in lanes.json "defaults" if the route matters.');
   return bad ? NO_DELIVERABLE : OK;
 }
 
@@ -485,10 +586,10 @@ export function checkContracts(opts, text, before) {
 }
 
 export async function main(argv) {
-  const VALUE = new Set(['--brief', '--timeout', '--model', '--expect-file']);
+  const VALUE = new Set(['--brief', '--timeout', '--model', '--effort', '--expect-file']);
   const BOOL = new Set(['--quiet', '--audit', '--safe-mode', '--doctor', '--run', '--expect-json']);
   const args = [...argv];
-  const opts = { timeout: 900, quiet: false, audit: false, model: null, safeMode: false, brief: null, doctor: false, run: false, expectFile: null, expectJson: false };
+  const opts = { timeout: 900, quiet: false, audit: false, model: null, effort: null, safeMode: false, brief: null, doctor: false, run: false, expectFile: null, expectJson: false };
   const positional = [];
   while (args.length) {
     const a = args.shift();
@@ -498,6 +599,7 @@ export async function main(argv) {
       if (a === '--brief') opts.brief = v;
       else if (a === '--timeout') opts.timeout = Number(v);
       else if (a === '--expect-file') opts.expectFile = v;
+      else if (a === '--effort') opts.effort = v;
       else opts.model = v;
     } else if (BOOL.has(a)) {
       if (a === '--quiet') opts.quiet = true;
@@ -530,11 +632,33 @@ export async function main(argv) {
   if (!prompt) return usage('give a prompt or --brief FILE');
   if (!Number.isFinite(opts.timeout) || opts.timeout <= 0) return usage('--timeout must be a positive number of seconds');
   if (opts.audit && lane !== 'codex') return usage('--audit is codex-only');
-  if ((opts.model || opts.safeMode) && lane !== 'qwen') return usage('--model and --safe-mode are qwen-only');
+  if (opts.safeMode && lane !== 'qwen') return usage('--safe-mode is qwen-only');
+  for (const [kind, v] of [['model', opts.model], ['effort', opts.effort]]) {
+    if (v == null) continue;
+    const bad = badRouteValue(kind, v);
+    if (bad) return usage(bad);
+  }
+  // qwen has no reasoning flag. Dropping --effort silently would leave the caller
+  // believing a route that never happened, which is the defect this feature fixes.
+  if (opts.effort && !(LANE_FLAGS[lane] && LANE_FLAGS[lane].effort)) return usage(`${lane} has no reasoning-effort flag; --effort is not available on this lane`);
 
   const digest = createHash('sha256').update(prompt).digest('hex').slice(0, 12);
   const base = { lane, prompt_sha256_12: digest, prompt_chars: prompt.length };
-  const enabled = enabledLanes();
+  const cfg = laneConfig();
+  // Resolve the route BEFORE the refusals below. A run that never reached a lane
+  // was still a request for one, and a failure record with no route is the exact
+  // gap this feature exists to close. A malformed lanes.json has no usable
+  // defaults, so the flags stand alone and say so.
+  const route = resolveRoute(lane, opts, cfg === null ? {} : cfg.defaults);
+  opts.model = route.model;
+  opts.effort = route.effort;
+  Object.assign(base, {
+    model_requested: route.model,
+    effort_requested: route.effort,
+    model_source: route.model_source,
+    effort_source: route.effort_source
+  });
+  const enabled = cfg === null ? null : cfg.enabled;
   if (enabled === null) {
     console.error('cli-run: lanes.json exists but is not a valid {"enabled": [...]} file; refusing every lane until it is fixed');
     log({ ...base, verdict: 'unavailable', rc: UNAVAILABLE, reason: 'lanes_json_malformed' });
@@ -601,7 +725,8 @@ export async function main(argv) {
       }
     }
     if (text && code === OK) process.stdout.write(text + '\n');
-    if (!opts.quiet) console.error(`cli-run[${lane}] ${verdict} rc=${code} ${r.seconds.toFixed(1)}s raw=${r.outBytes || 0}B :: ${detail}`);
+    const routeNote = route.model || route.effort ? `${route.model || 'lane default'}/${route.effort || 'lane default'}` : 'lane default';
+    if (!opts.quiet) console.error(`cli-run[${lane}] ${verdict} rc=${code} ${r.seconds.toFixed(1)}s raw=${r.outBytes || 0}B route=${routeNote} :: ${detail}`);
     // Durable log: fixed reason code and structural numbers only.
     log({ ...base, verdict, rc: code, cli_rc: r.status, signal: r.signal || null, seconds: Math.round(r.seconds * 100) / 100, raw_bytes: r.outBytes || 0, deliverable_bytes: Buffer.byteLength(text), reason: REASONS.has(reason) ? reason : 'unknown' });
     return code;

package/bin/cli.js

@@ -144,7 +144,7 @@ async function main() {
   // Says what this generates, not what it guarantees. The old line promised
   // routing this package does not perform: lane choice is an instruction an
   // agent follows, never something enforced here (#11).
-  console.log('\nmodel-orchestrator\nRouting instructions and a CLI runner for the AIs you actually have.\n');
+  console.log('\nmodel-orchestrator\nA model orchestrator: routing rules and a CLI runner for the AIs you actually have.\n');
 
   // 1. Level
   let level = Number(opt('level'));

package/docs/audit-brief.md

@@ -81,3 +81,24 @@ Re-audit the same scope. Every round-1 finding was reproduced before it was touc
 Also new since round 1: the companion-tool path (`--tools codecalc`, `--no-tools`, `templates/tools/codecalc/`, `protocols/numbers-and-logic.md`, `resolveTools`). Attack it the same way: unknown tool ids, interaction with `--yes`, the extra interactive question, and whether any written snippet could be confused for a file the installer should not touch.
 
 Report only what reproduces on the current tree. `CLEAN` per area is expected where the fix holds.
+
+## New in 0.1.15: two claude-code-only hooks
+
+`route-gate.mjs` (`UserPromptSubmit`) and `subagent-context.mjs` (`SubagentStart`) ship to `.claude/hooks/` only when claude-code is the primary. Both are plain Node, zero deps, and installed with mode `0o755`.
+
+- **Reads.** `route-gate.mjs` reads at most 64 KB from one file: the routing rules file (`ROUTING.md` or `ORCHESTRATOR.md`) at a path rendered in at install time relative to `CLAUDE_PROJECT_DIR`, never a hardcoded absolute path. Before opening it, it `statSync`s the resolved path (following a symlink to its target) and refuses anything that is not `isFile()`, a FIFO, socket, device or directory included, so the read never touches a path that could block on open. The read itself is one `openSync` + one bounded `readSync` into a fixed 64 KB buffer, closed in a `finally`, so neither the time nor the memory this hook uses depends on how large the file on disk actually is. It then extracts the text between `<!-- route-gate:start -->` and `<!-- route-gate:end -->` and nothing else. `subagent-context.mjs` reads nothing from disk; its context is static text plus the same two rendered paths. Neither parses or executes anything it reads; the extracted block is passed through as a string.
+- **Stdin.** Neither hook uses a field from the JSON input Claude Code sends on stdin, but both must still consume the pipe rather than ignore it. Both drain stdin asynchronously against a 250ms hard cap: whichever comes first, the real `end` event or the timeout, the hook proceeds. Neither ever calls a blocking, synchronous read of stdin.
+- **Writes.** Neither writes a file. Both write one JSON object to stdout: `{"hookSpecificOutput":{"hookEventName":"...","additionalContext":"..."}}`, and both exit only after that write's callback fires, so a buffered write to a pipe is not truncated by an exit racing ahead of it.
+- **Fail-open, on purpose.** A missing `CLAUDE_PROJECT_DIR`, a missing rules file, a non-regular file at the rules path, or a missing block each produce a one-line fallback `additionalContext` naming what was found, and the script still exits 0. This is acceptable because a miss here is a stray context string reaching the model, not a security gate: nothing downstream trusts the hook's output for anything but a routing suggestion, and the settings snippet that wires it in is a document the user merges by hand, never written automatically over an existing `settings.json`.
+- **Bounded.** `route-gate.mjs` caps the read at 64 KB regardless of the file's reported size and the injected string at 4000 characters, so a rules file bloated by a bad edit, or truncated to an arbitrary length, cannot balloon the context or the read time on every turn. Both hooks cap stdin drain at 250ms.
+- **Not yet attacked.** Untested here: a rules file with a `route-gate:start` marker but no matching end marker very far into the file (bounded by `MAX_READ`, so the end marker past that point is treated as absent, which is the intended fail-open path, but worth a deliberate case); a `CLAUDE_PROJECT_DIR` pointing at a path with no read permission; behavior under the Windows exec-form `node` + `args` invocation named in the settings snippet; a `statSync` that itself hangs (a stalled network filesystem, for instance) rather than the FIFO-at-open case this round fixed.
+
+### Round 1 (pre-release), fixed before shipping
+
+Three findings reproduced against the 0.1.15 branch before it shipped, none of them ever released:
+
+| # | Finding | Fix |
+|---|---|---|
+| 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. |

package/docs/part-1-beginner.md

@@ -14,6 +14,8 @@ If your agent exposes model choice (Claude Code, Codex, Antigravity), map the ti
 
 Three cost levers, always together: tier (price per token), token discipline (how many tokens: read only what you will touch, never re-read, deliverables not narration), effort (how hard each call thinks).
 
+And three inputs into the choice, not one. **Role** picks the agent. **Complexity** moves the effort: a worker executing a finished plan needs less reasoning than the reviewer judging its output, so when the plan is airtight the spec is carrying the thinking. **Risk** moves the tier and who reads the result: security, privacy, data loss and irreversible changes are the four worth naming, because none of their failures can be fixed by editing the code afterwards. A one-line change to an auth check is simple and high-risk at once, and it is the risk that decides.
+
 Robustness first, cost second. You split tiers because the split produces better work.
 
 ## 2. Classify every task, first match wins
@@ -36,7 +38,7 @@ Every build gets two checkpoints. **Before writing:** you map what it touches an
 
 ## 4. Every hand-off carries a brief
 
-A subagent, a fresh chat, a second window holds none of your rules and reads an unspecified edge as an open one. The brief: purpose, task class, granted scope, capabilities, denied actions, conventions it does not have, report contract (what was not done, what is unverified), exit parameters (when to stop, and what to return if it hits the bound). Absence is denial.
+A subagent, a fresh chat, a second window may hold none of your rules, and that is the default to assume. The one documented exception is a Claude Code subagent: it loads the project's CLAUDE.md hierarchy at start, so it keeps the standing rules, just not this task's scope. Either way, it reads an unspecified edge as an open one. The brief: purpose, task class, granted scope, capabilities, denied actions, conventions it does not have, report contract (what was not done, what is unverified), exit parameters (when to stop, and what to return if it hits the bound). Absence is denial.
 
 ## 5. The second pass