model-orchestrator 0.1.13 → 0.1.15

package/docs/part-2-intermediate.md

@@ -26,16 +26,22 @@ One driver, no second AI in the mix: the orchestrator invokes the CLIs; it never
 
 Every agent CLI can report success and deliver nothing. `bin/cli-run.mjs` builds the right invocation per lane, reads that lane's **native** terminal event, and exits `10` when a run produced no deliverable, `12` on timeout, `13` when the lane is missing. Byte count is not a check either; a run can emit hundreds of kilobytes and no conclusion. One lane's own success flags lie outright (an upstream 400 reported as success), so its judge reads the two honest signals instead.
 
-Every call goes through it. "This lane is flaky" becomes a query over its log instead of an argument. `node bin/cli-run.mjs --doctor` is the first thing to run after install: enabled lanes, binaries on PATH, and with `--run` a one-word canary per lane.
+Every call goes through it. "This lane is flaky" becomes a query over its log instead of an argument. `node bin/cli-run.mjs --doctor` is the first thing to run after install: enabled lanes, binaries on PATH, the route each lane is pinned to, and with `--run` a one-word canary per lane.
+
+There is a second thing a lane can be quietly wrong about. Left unpinned, it runs on **its own config file**, which the runner cannot see: a CLI set up months ago at a low reasoning effort keeps auditing at that effort while your routing docs describe an adversarial pass, and no error is ever raised. `--model` and `--effort` pin it per call, `defaults` in `bin/lanes.json` pins it per lane, and every run records the value requested and where it came from (`flag`, `lanes.json`, `lane_default`). The log claims no actual: grok reports a model id in its output, the other four lanes report none, so the field would be populated for one lane and empty for four, and it would be a provider-supplied string the durable log never holds.
 
 ## 4. Every delegation carries a task bundle, on both surfaces
 
-Subagents and CLI lanes are the same problem: something with none of your rules and broad tool access. 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`. If you can, gate it mechanically: a pre-dispatch hook that refuses a brief missing purpose, denied actions or a report contract.
+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.
 
 ## 5. Research: three engines, one triager
 
 Fan the same plan to three model families (web sweep, adversarial read, live data), each as one `cli-run` call. The orchestrator opens the primary sources itself, marks every claim, and writes the only durable record. Expect one engine to return confident unsourced numerics; downgrade it. Weight the engines that report their own gaps. Count dispositions, not briefs.
 
+## 5a. A finding is a claim, not a fact
+
+An audit that returns six findings has returned six claims. Hand them to `finding-verifier` before any of them causes a repair: it reads the cited line, states what would trigger the problem, then hunts for the guard, caller or test that makes it impossible, and answers CONFIRMED, NOT_REPRODUCED or INCONCLUSIVE. Only CONFIRMED earns a change. Use a different family from the one that produced the finding, and let INCONCLUSIVE stand: rounding it up to be safe buys unnecessary repairs, rounding it down to be tidy hides real ones.
+
 ## 6. Gap analysis gets a second family
 
 The second pass is now a different model reading the same artifact, in read-only audit mode. Disagreement between families is the cheapest signal that something is soft.

package/llms.txt

@@ -0,0 +1,27 @@
+# model-orchestrator
+
+> Model orchestrator for AI coding agents and LLMs (Claude Code, Codex, Gemini, Grok, Qwen, Ollama). One installer writes routing rules, subagent definitions and a CLI lane runner for the AI tools you already have. The 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. It is not a proxy or gateway: it does not automatically compare prices or select models; your agent follows the rules and chooses.
+
+Install and run: `npx model-orchestrator` (interactive), or headless: `npx model-orchestrator --yes --level 2 --ais claude-code,codex --project . --dir ./ai-orchestrator`. Preview without writing: add `--dry-run`. List every supported AI: `npx model-orchestrator --list`. Node 18 or newer, zero runtime dependencies, MIT licence.
+
+Levels: 1 beginner (one agent or chat app), 2 intermediate (several agent CLIs, each called through `cli-run`), 3 advanced (adds a virtual machine with a gateway and a scheduled audit job). On Claude Code the install also delegates execution to subagents by default and ships two hooks (UserPromptSubmit, SubagentStart) that inject the routing table every turn.
+
+## Docs
+
+- [README](https://github.com/aunysillyme/model-orchestrator/blob/main/README.md): what it writes, flags, principles, what is enforced versus instructed
+- [Part 1: beginner](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/part-1-beginner.md): one agent, tiers, the task bundle every delegation carries
+- [Part 2: intermediate](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/part-2-intermediate.md): several agent CLIs, the lane runner, pinning model and effort per lane
+- [Part 3: advanced](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/part-3-advanced.md): the VM, the gateway, scheduled jobs, privacy gates
+- [AI catalog](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/catalog.md): every supported AI, how to sign in, how each is detected
+
+## Reference
+
+- [CLI runner](https://github.com/aunysillyme/model-orchestrator/blob/main/bin/README.md): `cli-run` lanes, exit codes, the route logged per run
+- [Templates](https://github.com/aunysillyme/model-orchestrator/blob/main/templates/README.md): the routing, tiers, task bundle and protocol files the installer renders
+- [Changelog](https://github.com/aunysillyme/model-orchestrator/blob/main/CHANGELOG.md): every release and the issue behind each fix
+- [Agent instructions](https://github.com/aunysillyme/model-orchestrator/blob/main/AGENTS.md): running the installer from an agent, and contributing
+
+## Optional
+
+- [Security policy](https://github.com/aunysillyme/model-orchestrator/blob/main/SECURITY.md)
+- [Audit brief](https://github.com/aunysillyme/model-orchestrator/blob/main/docs/audit-brief.md): the threat model and what has already been attacked

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "model-orchestrator",
-  "version": "0.1.13",
-  "description": "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.",
+  "version": "0.1.15",
+  "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": {
     "model-orchestrator": "bin/cli.js"
@@ -15,7 +15,9 @@
     "LICENSE",
     "CHANGELOG.md",
     "SECURITY.md",
-    "scripts"
+    "scripts",
+    "llms.txt",
+    "AGENTS.md"
   ],
   "scripts": {
     "start": "node bin/cli.js",
@@ -51,7 +53,33 @@
     "agents",
     "subagents",
     "qwen",
-    "mcp"
+    "mcp",
+    "reasoning-effort",
+    "model-routing",
+    "code-review",
+    "ai-agents",
+    "hooks",
+    "claude-code-hooks",
+    "delegation",
+    "llm-router",
+    "ai-router",
+    "model-switching",
+    "multi-model",
+    "token-optimization",
+    "token-efficiency",
+    "cost-optimization",
+    "llm-orchestration",
+    "agent-orchestration",
+    "ai-orchestration",
+    "claude",
+    "anthropic",
+    "openai",
+    "gemini",
+    "claude-code-router",
+    "agent-routing",
+    "prompt-routing",
+    "coding-agent",
+    "ai-coding"
   ],
   "author": "aunysillyme (https://github.com/aunysillyme)",
   "license": "MIT"

package/src/README.md

@@ -4,6 +4,6 @@
 |---|---|
 | `catalog.js` | the single list of levels and AIs. Add an AI here and the prompts, docs tables, delegation matrix, gateway config and installer all pick it up. Nothing else lists AIs. |
 | `detect.js` | PATH lookup for a binary, plus the few places vendor installers drop binaries without touching PATH. No shell-outs. |
-| `install.js` | pure planner: turns (level, selection, primary) into a list of files to write, rendering templates and computing every generated table. `writeFiles` is the only thing that touches disk. `activationSteps()` and `snippetFor()` live here so the terminal summary and the generated README render the same list. |
+| `install.js` | pure planner: turns (level, selection, primary) into a list of files to write, rendering templates and computing every generated table. `writeFiles` is the only thing that touches disk. `activationSteps()` and `snippetFor()` live here so the terminal summary and the generated README render the same list. `subagentsLoadRules(primary)` gates every delegate-by-default render var (builder-by-default wording, the route-gate table, the inline-threshold note) on the one verified premise: a claude-code subagent loads CLAUDE.md. |
 | `prompt.js` | line-buffered questions for the interactive path; piped answers are queued, EOF mid-prompt aborts instead of confirming a write. |
 | `render.js` | `{{KEY}}` substitution. Throws on an unknown key, so a template typo fails the test suite instead of shipping a literal placeholder. |

package/src/catalog.js

@@ -69,7 +69,15 @@ export const AIS = [
     rulesFile: 'CLAUDE.md',
     agentsDir: '.claude/agents',
     cliRun: false,
-    models: { deep: 'opus', standard: 'sonnet', fast: 'haiku' }
+    models: { deep: 'opus', standard: 'sonnet', fast: 'haiku' },
+    // Verified at code.claude.com/docs/en/sub-agents (fetched 2026-09-10): "A
+    // non-fork subagent's initial context contains: CLAUDE.md files: every
+    // level of the CLAUDE.md hierarchy the main conversation loads ... The
+    // built-in Explore and Plan agents skip this." No other lane in this
+    // catalog has that documented, so the builder-by-default routing, the
+    // route-gate hook and the inline-threshold note are gated on this field
+    // and stay claude-code only.
+    subagentsLoadRules: true
   },
   {
     id: 'codex',

package/src/install.js

@@ -193,6 +193,146 @@ export function laneVars(selected) {
   };
 }
 
+// Only claude-code has a verified sub-agents doc quote saying its subagents
+// load the project's CLAUDE.md hierarchy (code.claude.com/docs/en/sub-agents,
+// see the comment on the catalog entry). Every delegate-by-default surface below
+// (builder-by-default wording, the route-gate hook, the inline-threshold
+// note) is gated on this so a primary with no verified premise keeps the
+// original, more conservative wording.
+export function subagentsLoadRules(primary) {
+  return !!(primary && primary.subagentsLoadRules);
+}
+
+// Canonical agent order, tier-first. Used to render a stable, non-hardcoded
+// "available as" list for the claude-code snippet from the files actually
+// shipped, so a future agent addition or removal cannot leave the sentence
+// stale the way the finding-verifier omission did.
+const AGENT_ORDER = ['deep-planner', 'builder', 'code-reviewer', 'finding-verifier', 'live-researcher', 'bulk-worker', 'done-verifier', 'reader'];
+export function claudeAgentIds() {
+  const dir = join(TEMPLATES, 'agents', 'claude-code');
+  if (!existsSync(dir)) return [];
+  const files = readdirSync(dir).filter((f) => f.endsWith('.md') && f !== 'README.md').map((f) => f.replace(/\.md$/, ''));
+  const set = new Set(files);
+  const ordered = AGENT_ORDER.filter((id) => set.has(id));
+  const extra = files.filter((id) => !AGENT_ORDER.includes(id)).sort();
+  return [...ordered, ...extra];
+}
+
+// The compact "pick the lane before acting" table, rendered from the AIs the
+// user actually selected and the agents actually installed, never a second
+// hand-typed copy of ROUTING.md's decision tree.
+export function routeGateTable(selected) {
+  const rows = [
+    ['Bulk or mechanical, many similar items', 'bulk-worker'],
+    ['Needs live data', 'live-researcher'],
+    ['Review without changing', 'code-reviewer'],
+    ['Findings from a review or a scanner', 'finding-verifier, before any repair'],
+    ['Reading or digesting many files or notes', 'reader'],
+    ['Checking a tracker item against its stated done-signal', 'done-verifier'],
+    ['Ambiguous, architectural, expensive to get wrong', 'deep-planner'],
+    ['Everything else that changes files', 'builder, by default']
+  ];
+  for (const a of selected.filter((x) => x.cliRun)) rows.push([a.role, '`cli-run ' + a.id + '`']);
+  return table(rows, ['Task', 'Lane']);
+}
+
+// The marked block route-gate.mjs extracts at runtime. Installed only for
+// claude-code so the hook always finds a block to read; other primaries get
+// no hook and so get no block.
+export function routeGateSection(selected) {
+  return [
+    '<!-- route-gate:start -->',
+    '## Route gate: pick the lane before acting',
+    '',
+    'Injected on every turn by the `route-gate` hook, so this table is read at runtime rather than recalled from memory.',
+    '',
+    routeGateTable(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.',
+    '<!-- route-gate:end -->'
+  ].join('\n');
+}
+
+// ROUTING.md / ORCHESTRATOR.md decision-tree rule 5 and the "Who builds"
+// section read differently for claude-code, because only claude-code has the
+// verified premise that its subagents load CLAUDE.md. Every other primary
+// keeps the original wording: the orchestrator builds the main line directly
+// and a subagent or second CLI is assumed to hold none of these rules.
+export function decisionRule5(primary) {
+  return subagentsLoadRules(primary)
+    ? `5. **Everything else that changes files** → builder executes by default. 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 (a delegate never verifies itself). Never route rule-bound work to the built-in Explore or Plan agents: both skip CLAUDE.md. general-purpose should not take work a named agent already owns.`
+    : `5. **Everything else that changes files** → the orchestrator builds it directly. Bounded sub-parts go to cheaper tiers; the main build is never handed off whole.`;
+}
+export function decisionRule5Beginner(primary) {
+  return subagentsLoadRules(primary)
+    ? `5. **Everything else that changes files or executes a known plan** → builder executes by default, at standard tier. The orchestrator plans, briefs, verifies and talks to you; 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 your decision, or the final verification of delegated work. Never route rule-bound work to the built-in Explore or Plan agents: both skip CLAUDE.md.`
+    : `5. **Everything else that changes files or executes a known plan** → you build it directly, at standard tier. The main build is never handed off whole; bounded sub-parts (a bulk pass, a wide search, a long audit loop) can go to cheaper tiers.`;
+}
+export function whoBuildsSection(primary) {
+  if (subagentsLoadRules(primary)) {
+    return [
+      '## Who builds',
+      '',
+      `**Builder executes by default.** A Claude Code subagent loads this project's CLAUDE.md hierarchy at start (verified: code.claude.com/docs/en/sub-agents), so it already carries the standing rules; the orchestrator's job is to plan, brief, verify and talk to the human, not to hold work a delegate can do. Stay inline only when: (a) the brief would cost as much as the work itself, (b) the task needs this conversation's own context, or (c) it is the human's decision to make, or the final verification of delegated work (a delegate never verifies its own output as final). Never route rule-bound work to the built-in Explore or Plan agents: both skip CLAUDE.md and the git status the router depends on. general-purpose should not take work a named agent already owns.`,
+      '',
+      `Delegate: the main build, background and long-running tasks, small tasks, scoping, verification, research, bounded sub-parts. Never delegate: the human's own decision, or the final sign-off on a delegate's work.`,
+      '',
+      `Every delegation carries \`TASK_BUNDLE.md\`. Its brief must restate this task's scope: a Claude Code subagent already has the standing rules, just not that.`
+    ].join('\n');
+  }
+  return [
+    '## Who builds',
+    '',
+    '**The orchestrator owns the main build.** It is the only surface that holds these rules: a subagent or a second CLI starts with none of them and cannot route. Handing the main build to one hands it to something the router cannot reach.',
+    '',
+    'Delegate: background and long-running tasks, small tasks, scoping, verification, research, bounded sub-parts. Never delegate: the main build, or any step that must carry a house rule (secrets handling, the loud-negative verification, the durable record).',
+    '',
+    'Every delegation carries `TASK_BUNDLE.md`. Its brief must restate every convention the delegate needs.'
+  ].join('\n');
+}
+export function addEndpointRow(primary) {
+  return subagentsLoadRules(primary)
+    ? '| "Add an endpoint" | builder, briefed and verified by the orchestrator |'
+    : '| "Add an endpoint" | the orchestrator builds it |';
+}
+export function inlineThresholdNote(primary) {
+  return subagentsLoadRules(primary)
+    ? '\n- **Measure your inline threshold once.** A subagent starts with your CLAUDE.md and tool definitions already loaded, so it has a fixed start-up cost before it does anything. Spawn one with a one-line task and read its token count. Work smaller than that stays inline.'
+    : '';
+}
+export function delegateRulesNote(primary) {
+  return subagentsLoadRules(primary)
+    ? `Subagents, a fresh chat, a second window: a Claude Code subagent loads this project's CLAUDE.md hierarchy, so it holds the standing rules already, just not this task's scope; a second CLI or a fresh chat window may hold none of them.`
+    : 'Subagents, a fresh chat, a second window: each one holds none of these rules.';
+}
+
+// Pre-release audit finding 3: the delegate-by-default gate reached the
+// decision tree and "Who builds" but missed three other generated surfaces
+// stating the same old premise (the orchestrator writes the main build
+// itself; a delegate inherits none of the session's rules). These three
+// close that gap the same way: gated on subagentsLoadRules(primary), every
+// other primary keeps the original wording unchanged.
+export function planBigExecuteSmallLine(primary) {
+  return subagentsLoadRules(primary)
+    ? `- **Plan big, execute small**, within a build: deep tier plans at Checkpoint 1, builder executes from the orchestrator's brief, bulk and wide searches go down.`
+    : '- **Plan big, execute small**, within a build: deep tier plans at Checkpoint 1, the orchestrator executes, bulk and wide searches go down.';
+}
+export function rolesBuilderRow(primary) {
+  return subagentsLoadRules(primary)
+    ? [
+        '| Orchestrator | Routes, maps, briefs, verifies, records. Stages 0, 1, 2, 4, 5b, 6, 7 | Write the build |',
+        "| Builder | Executes Stage 3 from the orchestrator's brief | Route further, or verify its own work as final |"
+      ].join('\n')
+    : '| Builder / orchestrator | Routes, maps, writes, verifies, records. Stages 0, 1, 3, 6, 7 | Hand off the main build |';
+}
+export function builderHandoffNote(primary) {
+  return subagentsLoadRules(primary)
+    ? `**Why Stage 3 goes to builder by default:** a Claude Code subagent loads this project's CLAUDE.md hierarchy at start, so it already carries the standing rules; the orchestrator's brief only has to restate this task's scope (see \`TASK_BUNDLE.md\`). The orchestrator keeps Stage 3 for itself only when the brief would cost as much as the work, the task needs this conversation's own context, or it is the human's decision or the final verification of delegated work.`
+    : `**Why the builder does not hand off the main build:** a delegated agent does not inherit the session's standing rules and usually cannot delegate further. Any brief must restate every convention it needs (see \`TASK_BUNDLE.md\`), and that cost is itself a reason to build directly when the work fits.`;
+}
+
 // Which activation file this primary gets. ONE decision, read by three
 // surfaces: planFiles writes the file, vars() names it in the generated README,
 // and bin/cli.js prints it in the terminal. Before 0.1.12 the README hardcoded
@@ -218,6 +358,9 @@ export function activationSteps(opts) {
   // replaces (#22).
   else if (snippet) steps.push(`open ${primary.chatName || primary.name} and paste the block in ${join(dirAbs, snippet)} into its ${primary.chatSurface || 'custom instructions'}`);
   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`);
   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).
@@ -232,15 +375,22 @@ export function activationSteps(opts) {
 // activationSteps is: level 1 writes no bin/, so a step naming cli-run.mjs or
 // lanes.json there described an install that did not happen (#27).
 export function proofSteps(opts) {
-  const { level } = opts;
+  const { level, primary } = opts;
   const steps = [
     'Start a fresh agent session and ask: "Read the orchestrator instructions. Quote the routing rule you will use, then sort pear, apple, banana alphabetically. Name the tier and whether you delegated."',
     'Expect the fast tier and `apple, banana, pear`. If the agent cannot quote the routing rule, check the snippet location or chat instructions before continuing. This is a manual activation check, not proof that every future task follows the rules.'
   ];
   if (level >= 2) {
-    steps.push('Run `node bin/cli-run.mjs --doctor` from this folder. It checks binary presence, not authentication or loaded instructions. `--doctor --run` additionally uses a little quota to test live responses. No enabled lanes means delegation is inactive.');
+    steps.push('Run `node bin/cli-run.mjs --doctor` from this folder. It checks binary presence, not authentication or loaded instructions, and prints the model and effort each lane is pinned to. `--doctor --run` additionally uses a little quota to test live responses. No enabled lanes means delegation is inactive.');
+    steps.push('Decide whether the route matters to you. Every lane starts unpinned, which means it runs on whatever its own config file says: a CLI configured months ago at a low reasoning effort will keep auditing at that effort while your docs describe something stronger. Pin it in `bin/lanes.json` under `defaults`, or per call with `--model` and `--effort`. Either way the run is recorded in the log with the value requested and where it came from.');
     steps.push('To test a real output contract, choose an enabled lane from `bin/lanes.json` and run `node bin/cli-run.mjs <lane> \'Return only {"sorted":["apple","banana","pear"]}\' --expect-json`. This uses quota. Expect JSON and exit 0; inspect the array yourself. A non-JSON response exits 10, a missing binary exits 13, and an authentication failure reports the vendor error. The explicit lane tests execution; your primary agent still makes delegation decisions.');
   }
+  // Only claude-code ships the route-gate hook, so only claude-code gets a
+  // proof step that checks it fired: the table must come from the hook's
+  // injected context, not from the agent reciting ROUTING.md from memory.
+  if (subagentsLoadRules(primary)) {
+    steps.push('Ask the agent: "Quote the route-gate table you were given this turn." It should quote the injected table verbatim, not recite it from memory. If it cannot, the hooks snippet was not merged into `.claude/settings.json`, or the hook found no rules file: check both before trusting the routing docs are actually reaching the agent.');
+  }
   return steps;
 }
 
@@ -259,7 +409,14 @@ function vars(opts) {
   const pinOf = (id) => (toolById[id] && toolById[id].pin) || 'latest';
   const snippet = snippetFor(primary);
   const steps = activationSteps({ level, selected, primary, tools, dir: opts.dir, project: opts.project });
-  const proofs = proofSteps({ level });
+  const proofs = proofSteps({ level, primary });
+  const routingFile = level >= 2 ? 'ROUTING.md' : 'ORCHESTRATOR.md';
+  // The path route-gate.mjs and subagent-context.mjs resolve at runtime,
+  // relative to CLAUDE_PROJECT_DIR. Mirrors the RULES_PATH fallback below:
+  // outside the project, the honest path is absolute, never a hardcoded one.
+  const relJoin = (name) => (rulesPath === dirAbs ? join(dirAbs, name) : rulesPath === '.' ? name : rulesPath + '/' + name);
+  const rulesFileRel = relJoin(routingFile);
+  const taskBundleRel = relJoin('TASK_BUNDLE.md');
   // Only claude-code and agy put files under the project root. A chat primary
   // puts nothing there, so naming a project root would name a folder this run
   // never created (#21).
@@ -335,7 +492,24 @@ function vars(opts) {
     NPM_PACKAGES: selected.map(npmSpec).filter(Boolean).join(' ') || '""',
     SCRIPT_INSTALLERS: scriptInstallers(selected),
     COMPOSE_ENV: composeEnv(selected, apis),
-    COMPOSE_OLLAMA: composeOllama(selected)
+    COMPOSE_OLLAMA: composeOllama(selected),
+    // Delegate by default (0.1.15): gated on subagentsLoadRules(primary), currently
+    // claude-code only. Every other primary keeps the original, more
+    // conservative wording these replace.
+    DECISION_RULE5: decisionRule5(primary),
+    DECISION_RULE5_L1: decisionRule5Beginner(primary),
+    WHO_BUILDS: whoBuildsSection(primary),
+    ADD_ENDPOINT_ROW: addEndpointRow(primary),
+    INLINE_THRESHOLD_NOTE: inlineThresholdNote(primary),
+    DELEGATE_RULES_NOTE: delegateRulesNote(primary),
+    PLAN_BIG_LINE: planBigExecuteSmallLine(primary),
+    ROLES_BUILDER_ROW: rolesBuilderRow(primary),
+    BUILDER_HANDOFF_NOTE: builderHandoffNote(primary),
+    ROUTE_GATE_SECTION: subagentsLoadRules(primary) ? '\n' + routeGateSection(selected) + '\n' : '',
+    AGENTS_LIST_LINE: claudeAgentIds().map((id) => '`' + id + '`').join(', '),
+    RULES_FILE_REL: rulesFileRel,
+    RULES_FILE_REL_JSON: JSON.stringify(rulesFileRel),
+    TASK_BUNDLE_REL_JSON: JSON.stringify(taskBundleRel)
   };
 }
 
@@ -365,6 +539,13 @@ export function planFiles(opts) {
       add(join('.claude', 'agents', f.rel), render(readFileSync(f.abs, 'utf8'), v), 0o644, 'project');
     }
     add('CLAUDE.snippet.md', render(readFileSync(join(TEMPLATES, 'agents', 'snippets', 'claude-code.md'), 'utf8'), v));
+    // Delegate-by-default hooks (0.1.15), claude-code only: route-gate.mjs (UserPromptSubmit)
+    // and subagent-context.mjs (SubagentStart) live where Claude Code looks for
+    // project hooks; the wiring snippet is a document the user merges in, never
+    // 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');
+    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'))) {
       if (!installable('agents', f.rel)) continue;
@@ -389,7 +570,9 @@ export function planFiles(opts) {
       JSON.stringify(
         {
           enabled: selected.filter((a) => a.cliRun).map((a) => a.id),
-          note: 'Lanes cli-run may call. Edit to enable or disable a lane. A lane not listed here exits 13 (unavailable).'
+          defaults: {},
+          note: 'Lanes cli-run may call. Edit to enable or disable a lane. A lane not listed here exits 13 (unavailable).',
+          defaultsNote: 'Pin what a lane runs with, so the route in your docs is the route that runs: "defaults": {"codex": {"model": "gpt-6-astra", "effort": "high"}}. Left empty, a lane inherits its own config file, which cli-run cannot see and does not guess. `--model` and `--effort` override this per call, and `--doctor` prints what each lane is pinned to. Every lane takes a model; every lane except qwen takes an effort.'
         },
         null,
         2

package/templates/README.md

@@ -6,7 +6,7 @@ Everything the installer can write, organized by the level that adds it. Files a
 |---|---|---|
 | `common/` | every level | the start-here README, `TASK_BUNDLE.md`, `protocols/` (build, propagate, gap analysis, deep research, numbers and logic, memory and record) |
 | `beginner/` | every level | `ORCHESTRATOR.md`, the single-agent routing rules |
-| `agents/` | every level, one variant | the primary agent's loading surface: Claude Code subagents, Antigravity custom agents, or a paste snippet |
+| `agents/` | every level, one variant | the primary agent's loading surface: Claude Code subagents (plus `.claude/hooks/route-gate.mjs` and `subagent-context.mjs`, and `settings.hooks.snippet.json` to wire them in), Antigravity custom agents, or a paste snippet |
 | `intermediate/` | level 2+ | `ROUTING.md`, `TIERS.md`, `DELEGATION_MATRIX.md`, `RESEARCH_TRIAGE.md`, `CLI-RUN.md` |
 | `advanced/` | level 3 | `vm/`: gateway config, compose file, box rules, privacy gates, scheduled jobs |
 | `tools/` | when selected | companion tools the AIs call: `codecalc/` and `obsidian-tc/` (install doc + MCP snippets each). See `tools/README.md` |

package/templates/agents/README.md

@@ -10,4 +10,6 @@ Loading surfaces for the primary agent. The installer writes exactly one of thes
 | `grok`, `hermes` | nothing agent-specific | rules travel with the prompt or the task bundle |
 | a chat app | `PASTE-INTO-YOUR-AGENT.md` | no files to load; paste into custom instructions |
 
-`snippets/` are rendered with the chosen agent's name and rules file. Nothing here is appended to a file the user already has.
+`snippets/` are rendered with the chosen agent's name and rules file. Nothing here is appended to a file the user already has. `snippets/route-gate.mjs`, `snippets/subagent-context.mjs`, and `snippets/settings.hooks.snippet.json` are claude-code only: two hooks and the settings block that wires them, installed to `.claude/hooks/` and next to `CLAUDE.snippet.md`.
+
+`claude-code/` and `agy/` both ship the same agent set: one per tier, plus `finding-verifier`, `done-verifier` and `reader`. Add an agent to one folder and its README, and the other.

package/templates/agents/agy/README.md

@@ -1,5 +1,5 @@
 # .agents/agents/
 
-Antigravity CLI custom agents, one per tier, in the `.agents/agents/<name>.md` format (YAML frontmatter + system prompt). `model` is a tier (`flash`, `pro`) or `inherit`. `subagent: true` lets a coordinator call them through `invoke_subagent`, which takes an array and launches concurrently; `mainAgent: true` lets you launch them directly with `agy --agent <name>`.
+Antigravity CLI custom agents, one per tier plus three checks (`finding-verifier`, `done-verifier`, `reader`), in the `.agents/agents/<name>.md` format (YAML frontmatter + system prompt). `model` is a tier (`flash`, `pro`) or `inherit`. `subagent: true` lets a coordinator call them through `invoke_subagent`, which takes an array and launches concurrently; `mainAgent: true` lets you launch them directly with `agy --agent <name>`.
 
-`commandExecutionPolicy` is `auto` for `builder` (it has to run builds and tests; `auto` keeps deletes and other high-risk commands gated) and `off` for the read-only agents. `model` is a tier: `pro` for deep-planner, `flash` for the rest.
+`commandExecutionPolicy` is `auto` for `builder` (it has to run builds and tests; `auto` keeps deletes and other high-risk commands gated) and `off` for the read-only agents: `code-reviewer`, `finding-verifier`, `live-researcher`, `done-verifier`, `reader`. `model` is a tier: `pro` for deep-planner, `flash` for the rest. `done-verifier` and `reader` never write and, with `commandExecutionPolicy: off`, cannot execute any command at all here, mutating or not: unlike its claude-code counterpart, which does carry an unrestricted `Bash` and stays read-only by its prompt rather than by the tool grant, agy's `done-verifier` is mechanically blocked from shelling out and probes artifacts through whatever read or fetch capability it has instead. Neither is `bulk-worker`, which classifies, tags and transforms items and does write.

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

@@ -0,0 +1,35 @@
+---
+name: done-verifier
+description: Checks tracker items or tasks against their stated done-signal by probing the named artifact (a file, a commit, a URL, a log line, a count); no file-editing tools, no command execution (commandExecutionPolicy off); returns MET, NOT_MET or UNVERIFIABLE per item; never closes or edits anything.
+model: flash
+subagent: true
+mainAgent: true
+commandExecutionPolicy: off
+---
+
+# done-verifier
+
+Checks tracker items or tasks against their stated done-signal by probing the
+named artifact. No file-editing tools, and no command execution: this agent's
+`commandExecutionPolicy` is `off`, so unlike its claude-code counterpart it
+cannot shell out at all, not even to a read-only command; probe with whatever
+read or fetch capability you have instead.
+
+For each item: read the stated done-signal, probe the exact artifact it
+names, compare what you found against the claim.
+
+Return one verdict per item:
+- MET: the artifact matches the claim. Name what you checked.
+- NOT_MET: the artifact is missing or contradicts the claim. Name what you
+  found instead.
+- UNVERIFIABLE: you cannot probe it from here, no done-signal was stated, or
+  the check would need a command you are not able to run. Say what is
+  missing.
+
+Rules:
+- Stay inside the task bundle you were given. Anything not granted is denied.
+- Never close, edit or comment on a tracker item; return verdicts only.
+- If the only way to check something would mutate it, or would need command
+  execution you do not have, the item is UNVERIFIABLE, not MET.
+- Token discipline: read only the cited artifact, hand back verdicts not
+  narration.

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

@@ -0,0 +1,29 @@
+---
+name: finding-verifier
+description: Adversarial verification of review findings; tries to disprove each one and returns CONFIRMED, NOT_REPRODUCED or INCONCLUSIVE. Read-only, never repairs.
+model: flash
+subagent: true
+mainAgent: true
+commandExecutionPolicy: off
+---
+
+# finding-verifier
+
+A finding is a claim, not a fact. You try to disprove each one before it is
+allowed to cause a repair.
+
+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).
+
+Return one verdict per finding, in the order given:
+- CONFIRMED: reproduced, or a concrete unblocked path. Give the path.
+- NOT_REPRODUCED: you found what stops it. Name it and where it is.
+- INCONCLUSIVE: not settleable read-only. Say what you would need.
+
+Rules:
+- Stay inside the task bundle you were given. Anything not granted is denied.
+- Verify only the findings handed to you; anything else you notice goes at the end, marked unverified.
+- Never round INCONCLUSIVE up to CONFIRMED to be safe, or down to NOT_REPRODUCED to be tidy.
+- Read-only: you never repair and never reword a finding.
+- Token discipline: read the cited code and its callers, not the repository.

package/templates/agents/agy/reader.md

@@ -0,0 +1,22 @@
+---
+name: reader
+description: Reads and digests many files or notes and returns facts, quotes with source, an index or a digest. Read-only. Different from bulk-worker, which classifies, tags and transforms items: reader only reads and reports.
+model: flash
+subagent: true
+mainAgent: true
+commandExecutionPolicy: off
+---
+
+# reader
+
+Reads and digests many files or notes and hands back exactly what the brief
+asks for: facts, quotes, an index, a digest. Does not classify, tag,
+transform or rewrite; that is bulk-worker's job, and reader never writes a
+file.
+
+Rules:
+- Stay inside the task bundle you were given. Anything not granted is denied.
+- Cite every fact or quote with its source (path or URL).
+- Report what you did, what you did not do, and what you could not verify.
+- Token discipline: read only what the brief needs, never re-read, hand back
+  a structured result, not prose that blends sources together.

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

@@ -1,13 +1,16 @@
 # .claude/agents/
 
-Five subagents, one per tier. Claude Code loads project-level agents from this folder automatically.
+One per tier, plus two checks and two agents with no file-editing tools: `finding-verifier` sits between a review and a repair, `done-verifier` sits between a claim of "done" and a tracker close, and `reader` digests many files or notes without writing anything. Claude Code loads project-level agents from this folder automatically; the count is whatever this folder holds; `test/install.test.js` ties the claude-code snippet's agent list to the files actually shipped here, so this table cannot drift silently.
 
 | Agent | Tier | Model alias | Effort | Job |
 |---|---|---|---|---|
 | deep-planner | deep | opus | xhigh | judges every build twice; never retrieves |
-| builder | standard | sonnet | high | bounded sub-parts of a build |
+| builder | standard | sonnet | high | executes; the default for everything that changes files |
 | code-reviewer | standard | sonnet | high | read-only findings |
+| 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 |
+| 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.
+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.

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

@@ -1,12 +1,17 @@
 ---
 name: builder
-description: Well-specified execution of a bounded sub-part. Use for writing code, editing files, wiring configs, and implementing a plan that already exists. Do not use for open-ended architecture questions, bulk classification, or the main build itself.
+description: Executes builds by default on this router, including the main build, from a brief the orchestrator wrote. Use for writing code, editing files, wiring configs, running commands, and implementing a plan the orchestrator briefed. Do not use for open-ended architecture questions or bulk classification; those still go to deep-planner or bulk-worker.
 model: sonnet
 effort: high
 ---
 
 You are the execution tier of the model router.
 
+The orchestrator stays inline only when the brief would cost as much as the
+work, the task needs this conversation's own context, or it is the human's
+decision or the final verification of delegated work. Everything else that
+changes files, the main build included, comes to you.
+
 You implement specs and plans: write code, edit files, run commands.
 
 Rules:

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

@@ -0,0 +1,44 @@
+---
+name: done-verifier
+description: Checks tracker items or tasks against their stated done-signal. Use after work is claimed finished, to probe the named artifact (a file, a commit, a URL, a log line, a count) before a tracker item is closed. No file-editing tools; Bash is for read-only probes, bound by the prompt below, not by the tool grant. Returns MET, NOT_MET or UNVERIFIABLE per item, and never closes or edits anything itself.
+tools: Read, Glob, Grep, Bash
+model: haiku
+effort: low
+---
+
+You are the done-signal verification tier of the model router.
+
+A tracker item is not done because someone said it is done; it is done because
+its stated done-signal is true. Your job is to probe the artifact the
+done-signal names, not to judge the work more broadly.
+
+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.
+
+For each item you are given:
+1. Read the stated done-signal. If there is none, or it only restates the
+   title, say so; that is a finding, not a thing to guess past.
+2. Probe the exact artifact it names: read the file, check the commit exists,
+   describe the URL, grep the log line, count what it says to count.
+3. Compare what you found against what the signal claims.
+
+Return one verdict per item, in the order given:
+- **MET**: the artifact exists and matches the claim. Name what you checked.
+- **NOT_MET**: the artifact is missing, contradicts the claim, or the check
+  failed. Name what you found instead.
+- **UNVERIFIABLE**: you cannot probe the artifact from here (behind a login,
+  on a machine you cannot reach, no done-signal stated). Say exactly what is
+  missing.
+
+Rules:
+- You never close, edit, or comment on a tracker item. You return verdicts;
+  something else acts on them.
+- Verify only the items you were given. Anything else you notice goes in a
+  separate list at the end, marked unverified.
+- 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. If the only way
+  to check something would mutate it, that item is UNVERIFIABLE, not MET.
+- Token discipline: read the cited artifact and nothing else; do not
+  summarize the whole tracker.