model-orchestrator 0.1.14 → 0.1.16

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/route-metrics.mjs

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+// route-metrics.mjs: routing telemetry hook for {{PRIMARY_NAME}}.
+//
+// Answers "is my agent actually routing and delegating?" by turning five
+// hook events into one JSON line each, appended to
+// ~/.ai-orchestrator/route-metrics.jsonl (the same directory bin/cli-run.mjs
+// already logs to, and the same os.homedir() resolution it uses):
+//
+//   UserPromptSubmit                 -> {event:"turn"}
+//   PreToolUse (matcher Agent|Task)  -> {event:"dispatch", subagent_type, background}
+//   SubagentStart                    -> {event:"start", agent_type}
+//   SubagentStop                     -> {event:"end", agent_type?, duration_s?}
+//   Stop                             -> {event:"route", lane}, parsed from the LAST
+//                                        <!-- route: <lane> | <why> --> marker in
+//                                        last_assistant_message (documented source;
+//                                        the transcript can lag, so that is never read)
+//
+// Pure telemetry, fail-open by design: this script prints NOTHING to stdout
+// (stdout on UserPromptSubmit/SubagentStart becomes model context) and always
+// exits 0, whether or not a line was written. A miss here is a missing log
+// line, never a blocked turn.
+//
+// The durable log holds no provider-supplied string: prompt text, tool
+// descriptions, and the "why" half of the route marker are never read into a
+// field, only the named, charset-bounded values below. See docs/audit-brief.md.
+//
+// Second entry point: `node route-metrics.mjs --summary [--since <ISO date>]`
+// prints a plain-text report from the log and exits 0 without touching stdin.
+import { createHash } from 'node:crypto';
+import {
+  existsSync, mkdirSync, appendFileSync, readFileSync, writeFileSync, unlinkSync, renameSync,
+  statSync, readdirSync
+} from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const HOME_DIR = join(homedir(), '.ai-orchestrator');
+const LOG_FILE = join(HOME_DIR, 'route-metrics.jsonl');
+const STATE_DIR = join(HOME_DIR, 'route-metrics.state');
+
+const STDIN_MAX_BYTES = 8 * 1024 * 1024; // size cap: a giant or runaway payload is truncated, not parsed
+const STDIN_DRAIN_MS = 1000; // hard cap: never let an open, never-closed stdin pipe hold this hook open
+const LOG_ROTATE_BYTES = 5 * 1024 * 1024; // rotate to .1 above this size
+const STATE_MAX_AGE_MS = 24 * 60 * 60 * 1000; // prune state files older than 24h
+const TOKEN_CHARSET = /[^A-Za-z0-9_.+-]/g; // session_id, subagent_type, agent_type, lane tokens
+const TOKEN_MAX_LEN = 64;
+const SESSION_ID_MAX_LEN = 128;
+
+// Strip anything outside the allowed charset and cap length, so no field in
+// the durable log can carry an arbitrary provider- or model-supplied string
+// (a newline, a control character, shell metacharacters, or just length).
+function sanitize(raw, maxLen) {
+  if (typeof raw !== 'string' || raw.length === 0) return '';
+  return raw.replace(TOKEN_CHARSET, '').slice(0, maxLen);
+}
+
+function stateKeyFor(agentId) {
+  if (typeof agentId !== 'string' || agentId.length === 0) return null;
+  return createHash('sha256').update(agentId).digest('hex');
+}
+
+// Best-effort housekeeping: a leaked state file (a SubagentStop that never
+// arrived) should not accumulate forever. Run on SubagentStart only, since
+// that is the one event guaranteed to fire at least as often as starts happen.
+function pruneOldState() {
+  let names;
+  try {
+    names = readdirSync(STATE_DIR);
+  } catch {
+    return; // no state dir yet: nothing to prune
+  }
+  const cutoff = Date.now() - STATE_MAX_AGE_MS;
+  for (const name of names) {
+    const p = join(STATE_DIR, name);
+    try {
+      if (statSync(p).mtimeMs < cutoff) unlinkSync(p);
+    } catch {
+      /* a race with another process touching the same file is not an error here */
+    }
+  }
+}
+
+function recordStart(agentId, agentType) {
+  const key = stateKeyFor(agentId);
+  if (!key) return;
+  try {
+    mkdirSync(STATE_DIR, { recursive: true });
+    writeFileSync(join(STATE_DIR, key + '.json'), JSON.stringify({ ts: Date.now(), agent_type: agentType }));
+  } catch {
+    /* telemetry never blocks the run */
+  }
+}
+
+// Reads and deletes the state file for this agent_id. Returns {agentType,
+// durationS}, either possibly null: no agent_id and no state file both mean
+// "none", which the caller reflects by omitting the field entirely.
+function consumeStart(agentId) {
+  const key = stateKeyFor(agentId);
+  if (!key) return { agentType: null, durationS: null };
+  const p = join(STATE_DIR, key + '.json');
+  let agentType = null;
+  let durationS = null;
+  try {
+    const parsed = JSON.parse(readFileSync(p, 'utf8'));
+    if (parsed && typeof parsed.ts === 'number') durationS = Math.max(0, (Date.now() - parsed.ts) / 1000);
+    if (parsed && typeof parsed.agent_type === 'string' && parsed.agent_type) agentType = parsed.agent_type;
+  } catch {
+    /* no state file, or it was unreadable: none, not an error */
+  }
+  try {
+    unlinkSync(p);
+  } catch {
+    /* already gone */
+  }
+  return { agentType, durationS };
+}
+
+function appendLog(record) {
+  try {
+    mkdirSync(HOME_DIR, { recursive: true });
+    let size = 0;
+    try {
+      size = statSync(LOG_FILE).size;
+    } catch {
+      /* file does not exist yet: size stays 0 */
+    }
+    if (size > LOG_ROTATE_BYTES) {
+      try {
+        renameSync(LOG_FILE, LOG_FILE + '.1');
+      } catch {
+        /* a concurrent rotation losing this race is not worth failing over */
+      }
+    }
+    appendFileSync(LOG_FILE, JSON.stringify(record) + '\n');
+  } catch {
+    /* telemetry never blocks the run */
+  }
+}
+
+// Parses the LAST <!-- route: <lane> | <why> --> marker out of text. The
+// "why" half is captured only to be discarded: it is never read into a
+// variable that reaches the log. Returns an array of lane tokens (split on
+// "+", the documented way to log more than one lane from a single marker),
+// or ["missing"] when there is no marker at all.
+export function extractLane(text) {
+  if (typeof text !== 'string' || text.length === 0) return ['missing'];
+  const re = /<!--\s*route:\s*([^|>]*)\|[^>]*-->/g;
+  let match;
+  let last = null;
+  while ((match = re.exec(text)) !== null) last = match;
+  if (!last) return ['missing'];
+  // A token carrying any character outside the charset is logged as
+  // "invalid", never stripped into a plausible-looking lane: stripping
+  // `main","evil":"1` would log a lane named "mainevil1" that nobody chose.
+  const parts = last[1]
+    .split('+')
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((t) => (t.length > TOKEN_MAX_LEN || /[^A-Za-z0-9_.-]/.test(t) ? 'invalid' : t));
+  return parts.length ? parts : ['missing'];
+}
+
+// Turns one parsed hook-input object into a log record, or null when the
+// event is not one this hook measures (or PreToolUse fired for a tool other
+// than Agent/Task, which the settings matcher should already have excluded;
+// this is a defensive second check, not the primary gate).
+export function buildRecord(input, now = () => new Date().toISOString()) {
+  if (!input || typeof input !== 'object') return null;
+  const sessionId = sanitize(input.session_id, SESSION_ID_MAX_LEN) || 'unknown';
+  const ts = now();
+  const base = { ts, v: 1 };
+
+  switch (input.hook_event_name) {
+    case 'UserPromptSubmit':
+      return { ...base, event: 'turn', session_id: sessionId };
+
+    case 'PreToolUse': {
+      if (input.tool_name !== 'Agent' && input.tool_name !== 'Task') return null;
+      const toolInput = (input.tool_input && typeof input.tool_input === 'object') ? input.tool_input : {};
+      const subagentType = sanitize(toolInput.subagent_type, TOKEN_MAX_LEN) || 'general-purpose';
+      const background = toolInput.run_in_background === true;
+      return { ...base, event: 'dispatch', session_id: sessionId, subagent_type: subagentType, background };
+    }
+
+    case 'SubagentStart': {
+      pruneOldState();
+      const agentType = sanitize(input.agent_type, TOKEN_MAX_LEN) || 'unknown';
+      recordStart(input.agent_id, agentType);
+      return { ...base, event: 'start', session_id: sessionId, agent_type: agentType };
+    }
+
+    case 'SubagentStop': {
+      const { agentType, durationS } = consumeStart(input.agent_id);
+      const record = { ...base, event: 'end', session_id: sessionId };
+      if (agentType) record.agent_type = agentType;
+      if (durationS !== null) record.duration_s = durationS;
+      return record;
+    }
+
+    case 'Stop':
+      return { ...base, event: 'route', session_id: sessionId, lane: extractLane(input.last_assistant_message) };
+
+    default:
+      return null;
+  }
+}
+
+// Drain stdin without ever blocking on it, bounded by BOTH time and size. A
+// bare `readFileSync(0)` waits for EOF, so a caller that pipes in and never
+// closes its end left the process running indefinitely (the same class of
+// bug route-gate.mjs and subagent-context.mjs already fix). The size cap is
+// this hook's own addition: hook input is normally small, so a payload past
+// the cap is treated as truncated and parsed as nothing, never partially.
+function drainStdinBounded(timeoutMs, maxBytes) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let bytes = 0;
+    let truncated = false;
+    const chunks = [];
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        process.stdin.removeAllListeners('data');
+        process.stdin.removeAllListeners('end');
+        process.stdin.removeAllListeners('error');
+        process.stdin.pause();
+      } catch {
+        /* stdin may already be gone */
+      }
+      resolve({ data: truncated ? null : Buffer.concat(chunks).toString('utf8'), truncated });
+    };
+    const timer = setTimeout(finish, timeoutMs);
+    if (timer.unref) timer.unref();
+    try {
+      process.stdin.on('data', (chunk) => {
+        if (truncated) return;
+        bytes += chunk.length;
+        if (bytes > maxBytes) {
+          truncated = true;
+          return finish();
+        }
+        chunks.push(chunk);
+      });
+      process.stdin.on('end', finish);
+      process.stdin.on('error', finish);
+      process.stdin.resume();
+    } catch {
+      finish();
+    }
+  });
+}
+
+async function runHook() {
+  const { data } = await drainStdinBounded(STDIN_DRAIN_MS, STDIN_MAX_BYTES);
+  if (data) {
+    let input;
+    try {
+      input = JSON.parse(data);
+    } catch {
+      input = null; // invalid JSON: log nothing
+    }
+    if (input) {
+      try {
+        const record = buildRecord(input);
+        if (record) appendLog(record);
+      } catch {
+        /* telemetry never blocks or fails the run */
+      }
+    }
+  }
+  process.exit(0); // fail-open, always: a miss here is a missing log line, never a blocked turn
+}
+
+// ---- --summary: a plain-text report, no stdin involved ----
+
+function parseLines(text) {
+  const records = [];
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      records.push(JSON.parse(trimmed));
+    } catch {
+      /* one bad line (a torn write, a rotation race) does not sink the report */
+    }
+  }
+  return records;
+}
+
+function formatNumber(n) {
+  return Number.isInteger(n) ? String(n) : n.toFixed(2);
+}
+
+function runSummary(args) {
+  if (!existsSync(LOG_FILE)) {
+    console.log('route-metrics: no data yet (' + LOG_FILE + ' does not exist).');
+    return process.exit(0);
+  }
+  const sinceIdx = args.indexOf('--since');
+  const since = sinceIdx !== -1 ? Date.parse(args[sinceIdx + 1]) : NaN;
+  let records = parseLines(readFileSync(LOG_FILE, 'utf8'));
+  if (!Number.isNaN(since)) records = records.filter((r) => Date.parse(r.ts) >= since);
+
+  const turns = records.filter((r) => r.event === 'turn').length;
+  const routes = records.filter((r) => r.event === 'route');
+  const covered = routes.filter((r) => !(Array.isArray(r.lane) && r.lane.length === 1 && r.lane[0] === 'missing')).length;
+  const coveragePct = turns > 0 ? (covered / turns) * 100 : null;
+
+  const laneCounts = new Map();
+  for (const r of routes) {
+    for (const lane of Array.isArray(r.lane) ? r.lane : []) laneCounts.set(lane, (laneCounts.get(lane) || 0) + 1);
+  }
+
+  const dispatches = records.filter((r) => r.event === 'dispatch');
+  const dispatchCounts = new Map();
+  for (const r of dispatches) dispatchCounts.set(r.subagent_type, (dispatchCounts.get(r.subagent_type) || 0) + 1);
+
+  const starts = records.filter((r) => r.event === 'start').length;
+  const noMatchingStart = Math.max(0, dispatches.length - starts);
+
+  const ends = records.filter((r) => r.event === 'end' && r.agent_type && typeof r.duration_s === 'number');
+  const durationsByType = new Map();
+  for (const r of ends) {
+    if (!durationsByType.has(r.agent_type)) durationsByType.set(r.agent_type, []);
+    durationsByType.get(r.agent_type).push(r.duration_s);
+  }
+
+  const lines = [];
+  lines.push('route-metrics summary' + (Number.isNaN(since) ? '' : ' since ' + args[sinceIdx + 1]));
+  lines.push('turns: ' + turns);
+  lines.push('route-marker coverage: ' + (coveragePct === null ? 'no turns yet' : formatNumber(coveragePct) + '%') + ' (' + covered + '/' + turns + ')');
+  lines.push('lanes by count:');
+  if (laneCounts.size === 0) lines.push('  (none)');
+  for (const [lane, count] of [...laneCounts.entries()].sort((a, b) => b[1] - a[1])) lines.push('  ' + lane + ': ' + count);
+  lines.push('dispatches by subagent_type:');
+  if (dispatchCounts.size === 0) lines.push('  (none)');
+  for (const [type, count] of [...dispatchCounts.entries()].sort((a, b) => b[1] - a[1])) lines.push('  ' + type + ': ' + count);
+  lines.push('dispatches with no matching start: ' + noMatchingStart + ' (a hook or guard blocked them before launch)');
+  lines.push('duration by agent_type (mean / max, seconds):');
+  if (durationsByType.size === 0) lines.push('  (none)');
+  for (const [type, durs] of durationsByType) {
+    const mean = durs.reduce((a, b) => a + b, 0) / durs.length;
+    lines.push('  ' + type + ': ' + formatNumber(mean) + ' / ' + formatNumber(Math.max(...durs)));
+  }
+  console.log(lines.join('\n'));
+  process.exit(0);
+}
+
+const args = process.argv.slice(2);
+if (args.includes('--summary')) {
+  runSummary(args);
+} else {
+  runHook();
+}

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

@@ -0,0 +1,70 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/route-gate.mjs"]
+          },
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/route-metrics.mjs"]
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Agent|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/route-metrics.mjs"]
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/subagent-context.mjs"]
+          },
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/route-metrics.mjs"]
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/route-metrics.mjs"]
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/route-metrics.mjs"]
+          }
+        ]
+      }
+    ]
+  }
+}

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