model-orchestrator 0.1.14 → 0.1.16

package/src/install.js

@@ -193,6 +193,148 @@ 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.',
+    '',
+    'End every reply with a hidden marker: `<!-- route: <lane> | <why, a few words> -->`. The route-metrics hook reads only the lane out of it, so routing coverage can be measured instead of assumed.',
+    '<!-- route-gate:end -->'
+  ].join('\n');
+}
+
+// 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 +360,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, subagent-context and route-metrics hooks`);
   for (const a of selected.filter((a) => a.bin && a.kind === 'agent-cli')) steps.push(`sign in to ${a.name}: ${a.auth}`);
   // A local runtime has a bin but no sign-in, so the agent-cli loop above skips it
   // and before this it appeared in no ordered list at any level (#26).
@@ -232,7 +377,7 @@ 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.'
@@ -242,6 +387,12 @@ export function proofSteps(opts) {
     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;
 }
 
@@ -260,7 +411,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).
@@ -336,7 +494,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)
   };
 }
 
@@ -366,6 +541,18 @@ 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');
+    // route-metrics.mjs (0.1.16), claude-code only: five events (UserPromptSubmit,
+    // PreToolUse on Agent|Task, SubagentStart, SubagentStop, Stop) turned into one
+    // JSON line each under ~/.ai-orchestrator/, so a routing rule nobody measures
+    // is not a rule nobody knows is followed.
+    add(join('.claude', 'hooks', 'route-metrics.mjs'), render(readFileSync(join(TEMPLATES, 'agents', 'snippets', 'route-metrics.mjs'), 'utf8'), v), 0o755, 'project');
+    add('settings.hooks.snippet.json', render(readFileSync(join(TEMPLATES, 'agents', 'snippets', 'settings.hooks.snippet.json'), 'utf8'), v));
   } else if (primary && primary.id === 'agy') {
     for (const f of walk(join(TEMPLATES, 'agents', 'agy'))) {
       if (!installable('agents', f.rel)) continue;
@@ -523,8 +710,22 @@ export const RUNTIME = new Set([
   'vm/jobs/weekly-audit.service',
   'vm/jobs/weekly-audit.timer'
 ]);
-export function fileClass(rel) {
-  const r = rel.split(sep).join('/');
+// MACHINE_OWNED and RUNTIME are keyed with forward slashes (they read as
+// prose in the comment above them, and every caller needs the same one
+// spelling regardless of host OS); an f.rel or a writeFiles() "written" path
+// is built with path.join, so it is backslash-separated on win32. Both sets
+// must be checked against the SAME normalized form, or a win32 install
+// silently drops bin/lanes.json and every RUNTIME file from set membership
+// (found: bin/cli.js's own "applied:"/existing-runtime checks did exactly
+// that before this was exported for them to use too).
+// separator is a parameter (default the real path.sep) so a test can prove
+// the win32 case from any host, the same pattern which()'s platform
+// parameter already uses.
+export function toPosixRel(rel, separator = sep) {
+  return rel.split(separator).join('/');
+}
+export function fileClass(rel, separator = sep) {
+  const r = toPosixRel(rel, separator);
   if (MACHINE_OWNED.has(r)) return 'owned';
   if (RUNTIME.has(r)) return 'runtime';
   return 'document';

package/templates/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 plus a finding-verifier, 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

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

package/templates/agents/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,14 +1,16 @@
 # .claude/agents/
 
-Six subagents. Five are one per tier; `finding-verifier` is the check that sits between a review and a repair. 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 |
-| code-reviewer | standard | sonnet | high | read-only findings |
+| builder | standard | sonnet | high | executes; the default for everything that changes files |
+| code-reviewer | standard | sonnet | high | findings only; no file-editing tools, Bash for checks only |
 | finding-verifier | standard | sonnet | high | tries to disprove a finding before it causes a repair |
 | live-researcher | standard | sonnet | medium | fresh data through tools |
-| bulk-worker | fast | haiku | low | mechanical volume |
+| 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. None of `done-verifier`, `finding-verifier`, `code-reviewer` or `reader` carries `Write` or `Edit` in its `tools:` line. `reader` is read-only by tool grant as well: it carries no `Bash`. `done-verifier`, `finding-verifier` and `code-reviewer` do carry `Bash`, for their probes and checks (`git log`, `grep`, `wc -l`, `test -f`); nothing in that grant stops any of them from running a command that changes state, so staying read-only there is a rule in each one's prompt, not a restriction on the tool, and each file says so.

package/templates/agents/claude-code/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/code-reviewer.md

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

package/templates/agents/claude-code/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.

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

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

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

@@ -0,0 +1,26 @@
+---
+name: reader
+description: Reads and digests many files or notes and returns exactly what the brief asks for (facts, quotes with path:line, an index, a digest). Read-only. Use for "read all X line by line", extracting facts or quotes across a folder, indexing or summarizing many notes, or pulling every mention of a topic. Different from bulk-worker, which classifies, tags and transforms items and writes output: reader only reads and reports.
+tools: Read, Glob, Grep
+model: haiku
+effort: low
+---
+
+You are the reading tier of the model router.
+
+You read and digest many files or notes and hand back exactly what the brief
+asked for: facts, quotes, an index, a digest. You do not classify, tag,
+transform or rewrite; that is bulk-worker's job, not yours, and you never
+write a file.
+
+Rules:
+- Read the brief first and answer only what it asks. "Every mention of X"
+  means grep for X and read the hits, not the whole corpus.
+- Cite every fact or quote with its source: `path:line` for code and notes, a
+  URL and a retrieval note for anything fetched.
+- An index or digest is a structured list, one row or bullet per source, not
+  prose that blends sources together.
+- If a source is missing, unreadable, or empty, say so by name; do not
+  silently skip it.
+- Token discipline: read only what the brief needs, never re-read a file,
+  summarize as you go rather than holding full text for later.

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

@@ -9,14 +9,17 @@ Routing rules live in `{{RULES_PATH}}/{{ROUTING_FILE}}`. Read them before any bu
 
 1. Bulk, mechanical, many similar items -> bulk-worker (fast tier).
 2. Needs live data -> live-researcher (standard tier + tools).
-3. Review without changing -> code-reviewer (standard, read-only).
+3. Review without changing -> code-reviewer (standard; no file-editing tools, Bash for checks only).
 3a. Holding findings from a review or scanner -> finding-verifier before any repair. Only CONFIRMED findings earn a change.
+3b. Checking a tracker item against its stated done-signal -> done-verifier. It never closes anything itself.
 4. Ambiguous, architectural, or expensive to get wrong -> deep-planner (deep tier), then hand the plan down.
-5. Everything else that changes files -> build it directly. The main build is never handed off whole; bounded sub-parts go to builder.
+5. Everything else that changes files -> builder executes by default. 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 send rule-bound work to the built-in Explore or Plan agents: they skip CLAUDE.md. general-purpose should not take work a named agent already owns.
+
+A subagent starts with your CLAUDE.md and tool definitions already loaded, so it has a fixed start-up cost before it does anything. Measure yours once: spawn a subagent with a one-line task and read its token count. Work smaller than that stays inline.
 
 Every build runs `{{RULES_PATH}}/protocols/build-protocol.md`: two deep-tier checkpoints, a mechanical scan, one adversarial pass, an explicit human yes before anything irreversible, then the loud negative.
 
-Every delegation carries an `{{RULES_PATH}}/TASK_BUNDLE.md` brief. A subagent holds none of these rules; absence is denial.
+Every delegation carries an `{{RULES_PATH}}/TASK_BUNDLE.md` brief. A Claude Code subagent loads this CLAUDE.md hierarchy, so it holds the standing rules already, just not this task's scope; a second CLI or a fresh chat window may hold none of them. Absence is denial either way.
 
 Never silently retry a failed attempt at the same tier. Escalate once and say so.
 
@@ -25,4 +28,6 @@ Numbers, comparisons, complexity and equivalence claims go through codecalc (or
 Anything durable is searched for before it is written and its folder index is corrected in the same pass; one writer per run: `{{RULES_PATH}}/protocols/memory-and-record.md`.
 ```
 
-Subagents were written to `{{AGENTS_DIR}}` (the project root, which is where Claude Code reads project-level agents; `--project` changes it). Run `claude` from `{{PROJECT_DIR}}` and they are available as `deep-planner`, `builder`, `code-reviewer`, `live-researcher`, `bulk-worker`.
+Subagents were written to `{{AGENTS_DIR}}` (the project root, which is where Claude Code reads project-level agents; `--project` changes it). Run `claude` from `{{PROJECT_DIR}}` and they are available as {{AGENTS_LIST_LINE}}.
+
+Two hooks were written to `{{AGENTS_DIR}}/../hooks/` (`.claude/hooks/`): `route-gate.mjs` injects the routing table on every prompt, and `subagent-context.mjs` reminds a spawned subagent where the rules and the task-bundle format live. Merge `settings.hooks.snippet.json`, written next to this file, into `.claude/settings.json` to wire them in.