model-orchestrator 0.1.14 → 0.1.15

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/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 |
+| 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.

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

@@ -11,12 +11,15 @@ Routing rules live in `{{RULES_PATH}}/{{ROUTING_FILE}}`. Read them before any bu
 2. Needs live data -> live-researcher (standard tier + tools).
 3. Review without changing -> code-reviewer (standard, read-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.

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

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// route-gate.mjs: UserPromptSubmit hook for {{PRIMARY_NAME}}.
+//
+// Reads the route-gate table out of {{RULES_FILE_REL}} and injects it as
+// additionalContext on every turn, so the routing table is read at runtime
+// from the one place it is generated (the rules file), never a second
+// hand-typed copy that can drift from it.
+//
+// Fail-open by design: a miss here is a stray context string, not a gate.
+// This script always exits 0, never blocks on stdin past a short bound,
+// reads at most 64 KB of the rules file through a fixed-size buffer (never
+// a full read of an arbitrarily large or non-regular file), and never
+// executes anything it reads. See docs/audit-brief.md for the threat model.
+import { statSync, openSync, readSync, closeSync, realpathSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
+
+// Rendered at install time from the level and directory the user chose.
+// Never hardcoded: a level 1 install points this at ORCHESTRATOR.md, level
+// 2+ at ROUTING.md, and a --dir outside the project resolves to an absolute
+// path instead of a relative one.
+const RULES_FILE_REL = {{RULES_FILE_REL_JSON}};
+
+const MAX_READ = 64 * 1024; // bounded read: this is a rules file, not a log
+const MAX_CONTEXT = 4000; // bounded injection: a table, not the whole file
+const STDIN_DRAIN_MS = 250; // hard cap: never let an open, never-closed stdin pipe hold this hook open
+const START = '<!-- route-gate:start -->';
+const END = '<!-- route-gate:end -->';
+
+function fallback(reason) {
+  return 'route-gate: ' + reason + '. Pick the lane before acting: read ' + RULES_FILE_REL + ' yourself.';
+}
+
+function resolveRulesPath() {
+  if (isAbsolute(RULES_FILE_REL)) return RULES_FILE_REL;
+  const projectDir = process.env.CLAUDE_PROJECT_DIR;
+  if (!projectDir) return null;
+  // Resolve through whatever part of the project dir already exists, so a
+  // symlinked project folder still resolves to the real path the rules file
+  // was written under.
+  let root = projectDir;
+  try {
+    root = realpathSync(projectDir);
+  } catch {
+    /* keep the unresolved value; the read below reports the real failure */
+  }
+  return join(root, RULES_FILE_REL);
+}
+
+// Bounded, regular-file-only read. statSync (not lstatSync) follows a
+// symlink to its target and reports what the target actually is, so a
+// symlinked rules file still reads; a FIFO, socket, device or directory at
+// the resolved path is refused before any open/read call touches it. That
+// check matters: opening a FIFO for reading blocks until a writer opens the
+// other end, and a plain readFileSync on any of these can hang or, for a
+// huge or sparse regular file, allocate far more than this hook needs. The
+// fixed-size buffer plus a single bounded readSync call means the on-disk
+// size of the file never determines how much this hook reads or how long it
+// takes.
+function readBounded(path) {
+  let st;
+  try {
+    st = statSync(path);
+  } catch (e) {
+    throw Object.assign(new Error('could not stat ' + path + ' (' + ((e && e.code) || e) + ')'), { code: e && e.code });
+  }
+  if (!st.isFile()) throw new Error(path + ' is not a regular file');
+  const buf = Buffer.alloc(MAX_READ);
+  let fd;
+  try {
+    fd = openSync(path, 'r');
+    const bytesRead = readSync(fd, buf, 0, MAX_READ, 0);
+    return buf.toString('utf8', 0, bytesRead);
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+function computeContext() {
+  const path = resolveRulesPath();
+  if (!path) return fallback('CLAUDE_PROJECT_DIR is not set, so ' + RULES_FILE_REL + ' could not be located');
+
+  let text;
+  try {
+    text = readBounded(path);
+  } catch (e) {
+    return fallback((e && e.message) || String(e));
+  }
+
+  const s = text.indexOf(START);
+  const e = s === -1 ? -1 : text.indexOf(END, s);
+  if (s === -1 || e === -1) return fallback(path + ' has no route-gate block');
+
+  return text.slice(s, e + END.length).slice(0, MAX_CONTEXT);
+}
+
+// Drain stdin without ever blocking on it. A bare `readFileSync(0)` waits
+// for stdin to reach EOF, so a caller that pipes into this hook and never
+// closes its end of the pipe (or a bare TTY with no redirection at all)
+// left the process running indefinitely. This races the real 'end' event
+// against a hard timeout instead: whichever settles first wins, and the
+// timer is unref'd so it can never itself be the reason the process stays
+// alive past a normal exit.
+function drainStdin(timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        process.stdin.removeAllListeners('data');
+        process.stdin.removeAllListeners('end');
+        process.stdin.removeAllListeners('error');
+        process.stdin.pause();
+      } catch {
+        /* stdin may already be gone; nothing left to clean up */
+      }
+      resolve();
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    if (timer.unref) timer.unref();
+    try {
+      process.stdin.on('data', () => {});
+      process.stdin.on('end', finish);
+      process.stdin.on('error', finish);
+      process.stdin.resume();
+    } catch {
+      finish();
+    }
+  });
+}
+
+let additionalContext;
+try {
+  additionalContext = computeContext();
+} catch (err) {
+  additionalContext = fallback('route-gate.mjs failed unexpectedly (' + ((err && err.message) || err) + ')');
+}
+
+drainStdin(STDIN_DRAIN_MS).then(() => {
+  const payload = JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext
+    }
+  });
+  // Exit only after the write's callback fires, so a buffered write to a
+  // pipe (the common case on Windows, and possible anywhere output exceeds
+  // one write's worth) is not truncated by an exit that races ahead of it.
+  process.stdout.write(payload, () => process.exit(0));
+});

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

@@ -0,0 +1,26 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/route-gate.mjs"]
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/subagent-context.mjs"]
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/agents/snippets/subagent-context.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// subagent-context.mjs: SubagentStart hook for {{PRIMARY_NAME}}.
+//
+// A Claude Code subagent loads this project's CLAUDE.md hierarchy at start
+// (code.claude.com/docs/en/sub-agents), so it already has the standing
+// rules. What it does not have is this task's scope, and it can be tempted
+// to route further work itself or to mark its own output verified. This
+// hook injects a short, static reminder of where the rest lives and what
+// "delegate" means.
+//
+// Fail-open by design: a miss here is a stray context string, not a gate.
+// This script always exits 0, never executes anything it reads, and never
+// blocks on stdin past a short bound (see drainStdin below).
+import { isAbsolute } from 'node:path';
+
+// Rendered at install time so a --dir outside the project still names an
+// honest path rather than a hardcoded one.
+const RULES_FILE_REL = {{RULES_FILE_REL_JSON}};
+const TASK_BUNDLE_REL = {{TASK_BUNDLE_REL_JSON}};
+const STDIN_DRAIN_MS = 250; // hard cap: never let an open, never-closed stdin pipe hold this hook open
+
+const additionalContext = [
+  'SUBAGENT CONTEXT (model-orchestrator).',
+  'Routing rules: ' + RULES_FILE_REL + (isAbsolute(RULES_FILE_REL) ? '.' : ' (relative to the project root).'),
+  'Task bundle format: ' + TASK_BUNDLE_REL + '.',
+  'Report contract: say what you did, what you did NOT do, and what you could not verify. "Unverified" is acceptable; a confident guess is not. Stop at the bound your brief set, and never claim work you cannot show.',
+  'You are a delegate: do not route further work to another subagent yourself, and do not mark your own output as the final verification of it.'
+].join(' ');
+
+// Drain stdin without ever blocking on it. A bare `readFileSync(0)` waits
+// for stdin to reach EOF, so a caller that pipes into this hook and never
+// closes its end of the pipe left the process running indefinitely. This
+// races the real 'end' event against a hard timeout instead: whichever
+// settles first wins, and the timer is unref'd so it can never itself be
+// the reason the process stays alive past a normal exit.
+function drainStdin(timeoutMs) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        process.stdin.removeAllListeners('data');
+        process.stdin.removeAllListeners('end');
+        process.stdin.removeAllListeners('error');
+        process.stdin.pause();
+      } catch {
+        /* stdin may already be gone; nothing left to clean up */
+      }
+      resolve();
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    if (timer.unref) timer.unref();
+    try {
+      process.stdin.on('data', () => {});
+      process.stdin.on('end', finish);
+      process.stdin.on('error', finish);
+      process.stdin.resume();
+    } catch {
+      finish();
+    }
+  });
+}
+
+drainStdin(STDIN_DRAIN_MS).then(() => {
+  const payload = JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SubagentStart',
+      additionalContext
+    }
+  });
+  // Exit only after the write's callback fires, so a buffered write to a
+  // pipe is not truncated by an exit that races ahead of it.
+  process.stdout.write(payload, () => process.exit(0));
+});

package/templates/beginner/ORCHESTRATOR.md

@@ -20,10 +20,10 @@ Robustness first, cost second. Split tiers because the split produces better wor
 2. **Needs live data?** trends, current docs, pricing, recent events → standard tier with tools; freshness comes from tools, not from a bigger model.
 3. **Reviewing without changing?** → standard tier, read-only, findings ranked by severity. Escalate to deep only for security-critical review.
 4. **Ambiguous, strategic, or expensive to get wrong?** "design my…", "figure out…", unknown cause → deep tier. Then hand the plan down.
-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.
+{{DECISION_RULE5_L1}}
 
 Modifiers:
-- **Plan big, execute small.** The expensive tier steers, the cheaper tier does the volume. Never make the fast tier design anything; never make the deep tier grind out bulk output.
+- **Plan big, execute small.** The expensive tier steers, the cheaper tier does the volume. Never make the fast tier design anything; never make the deep tier grind out bulk output.{{INLINE_THRESHOLD_NOTE}}
 - **Never silently retry at the same tier after a failure.** Escalate one tier, or consult the deep tier once, and say which you did. If two consults do not unstick it, stop and tell the human.
 - **De-escalate.** If a request sounds deep but is a lookup or a small edit, route down. Default down, escalate on evidence.
 
@@ -36,7 +36,7 @@ Cap: two deep-tier consults per build. The full procedure is `protocols/build-pr
 
 ## Delegating inside one agent
 
-Subagents, a fresh chat, a second window: each one holds none of these rules. Every hand-off carries a `TASK_BUNDLE.md` brief: purpose, task class, granted scope, capabilities, denied actions, conventions it does not have, report contract, exit parameters. Absence is denial.
+{{DELEGATE_RULES_NOTE}} Every hand-off carries a `TASK_BUNDLE.md` brief: purpose, task class, granted scope, capabilities, denied actions, conventions it does not have, report contract, exit parameters. Absence is denial.
 
 ## Numbers and logic go through a tool, never your head
 
@@ -53,3 +53,4 @@ Anything durable is searched for before it is written, its folder index is corre
 ## When you outgrow this
 
 You will know: you keep wanting a second model family to read your diff, a $0 lane for bulk, or a live-data lane your primary does not have. That is level 2. Re-run the installer with `--level 2`.
+{{ROUTE_GATE_SECTION}}

package/templates/common/TASK_BUNDLE.md

@@ -1,6 +1,6 @@
 # Task Bundle: the brief every delegation carries
 
-A subagent, a second CLI, or a fresh chat window holds none of the rules your main session is holding. It cannot see your conventions, it cannot route, and it will read an unspecified edge as an open one.
+A subagent, a second CLI, or a fresh chat window may hold none of the rules your main session is holding, and that is the default to assume. One exception: a Claude Code subagent loads the project's CLAUDE.md hierarchy at start, so it already carries the standing rules, just not this task's scope. Either way, it cannot see this task's conventions and will read an unspecified edge as an open one.
 
 > A delegate gets an approved, bounded brief. Absence is not permission.
 
@@ -25,7 +25,7 @@ Copy this into the delegate's prompt. Delete nothing; write `none` where a field
 **Denied actions.** <explicit list: do not commit, push, deploy, delete, send, publish, close a ticket...>
 - Anything absent from Capabilities is denied. Absence is not permission.
 
-**Conventions you do not have.** <restate every house rule this task needs; the delegate holds none>
+**Conventions you do not have.** <restate every house rule this task needs; even a delegate that loaded the standing rules still needs this task's scope, and a second CLI or a fresh chat window may hold none of it>
 
 **Report contract.** Return: <exactly what to hand back>. State plainly what you did NOT do
 and anything you could not verify. "Unverified" is an acceptable answer; a confident guess is not.

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

@@ -104,14 +104,14 @@ Use a different model family from the one that produced the finding where you ha
 
 | Role | Does | Does not |
 |---|---|---|
-| Builder / orchestrator | Routes, maps, writes, verifies, records. Stages 0, 1, 3, 6, 7 | Hand off the main build |
+{{ROLES_BUILDER_ROW}}
 | Judgment tier | Stage 2 and the architectural arm of Stage 5. Argues with a finished map | Perform the retrieval |
 | Adversarial auditor | The security arm of Stage 5. Attacks the diff | Fix anything |
 | Mechanical gates | Stage 4 and any always-on guard | Be overridden without reading |
 | Cheap workers | Bounded sub-parts: bulk passes, wide searches, long loops | Own a stage |
 | Human | Stage 5b, and any irreversible or architectural call | Be the first line of review |
 
-**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.
+{{BUILDER_HANDOFF_NOTE}}
 
 ## Checklist
 

package/templates/intermediate/ROUTING.md

@@ -15,19 +15,15 @@ Rule of thumb: never spend a frontier token on a task a cheap tier finishes corr
 0. **Is there a cheaper or better external lane for this?** Check `DELEGATION_MATRIX.md`. Your enabled lanes, every one called through `bin/cli-run.mjs`:
 {{LANE_STEP0}}
 1. **Bulk and mechanical?** → fast tier{{BULK_LANE}}. Many independent items each needing its own agent turn → a concurrent fan-out lane if you have one.
+1a. **Reading or digesting many files or notes, not writing?** → reader. Different from a bulk pass: reader reports, it does not classify, tag or transform.
 2. **Needs live data?** → {{LIVE_LANE}} standard tier with web tools.
 3. **Reviewing without changing?** → standard tier read-only. Security-critical → {{ATTACK_LANE}}.
 3a. **Holding findings from a review or a scanner?** → finding-verifier before any of them cause a repair. A finding is a claim, not a fact.
+3b. **Checking a tracker item or task against its stated done-signal?** → done-verifier. It probes the named artifact and returns MET, NOT_MET or UNVERIFIABLE; it never closes anything itself.
 4. **Ambiguous, strategic, expensive to get wrong?** → deep tier (deep-planner). Then hand the plan down.
-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.
+{{DECISION_RULE5}}
 
-## 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.
+{{WHO_BUILDS}}
 
 ## The Build Protocol, with lanes bound
 
@@ -56,7 +52,7 @@ One writer per run; every other lane proposes. Search before writing, index in t
 
 ## Modifier rules
 
-- **Plan big, execute small**, within a build: deep tier plans at Checkpoint 1, the orchestrator executes, bulk and wide searches go down.
+{{PLAN_BIG_LINE}}{{INLINE_THRESHOLD_NOTE}}
 - **Escalation:** never silently retry at the same tier. Escalate one tier or consult deep once, and say which. Two consults that do not unstick it → stop and tell the human.
 - **De-escalation:** a request that sounds deep but is a lookup routes down.
 - **Long context:** mechanical digestion → fast tier in chunks; judgment over a long input → standard tier.
@@ -71,8 +67,11 @@ One writer per run; every other lane proposes. Search before writing, index in t
 |---|---|
 | "Design the architecture for X" | deep-planner |
 | "Review this service for bugs" | code-reviewer |
-| "Add an endpoint" | the orchestrator builds it |
+{{ADD_ENDPOINT_ROW}}
 | "Why does this silently drop rows sometimes" | deep-planner (unknown cause), then build the fix directly |
 | "Summarize these 30 notes into one index" | bulk-worker |
+| "Read every note in this folder and pull out every mention of X" | reader |
 | "The audit returned 6 findings" | finding-verifier first; repair only what comes back CONFIRMED |
+| "Is issue #123 actually done" | done-verifier |
 {{LANE_EXAMPLES}}
+{{ROUTE_GATE_SECTION}}

package/templates/intermediate/TIERS.md

@@ -23,6 +23,8 @@ Tier sets the price per token. Token discipline sets how many tokens. **Effort s
 | builder | standard | high | a botched deploy is the costly failure |
 | live-researcher | standard | medium | tools do the retrieval |
 | bulk-worker | fast | low | the biggest cost win |
+| done-verifier | fast | low | a done-signal check is a lookup, not a judgment call |
+| reader | fast | low | digestion, not judgment |
 
 ## Three inputs, not one