model-orchestrator 0.1.19 → 0.1.21

package/AGENTS.md

@@ -10,6 +10,7 @@ model-orchestrator writes routing rules, subagents and a CLI lane runner so an a
 - `npx model-orchestrator --yes --level 2 --ais claude-code,codex --project <repo> --dir <repo>/ai-orchestrator --dry-run` prints the plan and writes nothing.
 - Drop `--dry-run` to write it. Existing files are never overwritten without `--force`; activation snippets (for example `CLAUDE.snippet.md`, `settings.hooks.snippet.json`) are written for a person or agent to merge.
 - The generated `README.md` in `--dir` lists what to copy where and one smoke command to prove the rules took.
+- Claude Code users can install the hooks and subagents as a plugin instead of merging snippets: `claude plugin marketplace add aunysillyme/model-orchestrator`, then `claude plugin install model-orchestrator@model-orchestrator`. The rules still come from the installer above; see [`plugin/README.md`](plugin/README.md).
 - A summary for LLMs, with links to every doc: [`llms.txt`](llms.txt).
 
 ## Working on this repository
@@ -19,6 +20,7 @@ The files the installer writes for end users live under `templates/`.
 - Read `CONTRIBUTING.md` first, then `src/README.md` (the catalog drives everything) and `docs/audit-brief.md` (the threat model and what has already been attacked).
 - Run `npm test` before proposing a change and quote the count and the exit code; the suite prints the current number.
 - Everything renders from `src/catalog.js`. Add an AI or a tool there, not in a template. Templates carry no logic.
+- `plugin/` is generated. Edit the agent or hook in `templates/`, then `npm run gen:plugin`; `test/plugin.test.js` fails when the committed bundle drifts. A plugin hook may only read: no network, no file writes, no subprocess.
 - Never put a value that looks like a credential anywhere in this repo, including tests and examples. Environment variable names only.
 - `bin/cli.js` writes only inside `--dir` and `--project`, never over a document without `--force`, and never runs a vendor script. A change that weakens any of those will be refused in review; the tests that hold them are in `test/install.test.js` and `test/cli.test.js`.
 - `bin/cli-run.mjs` must exit non-zero when a lane produced nothing. Every judge has a red case in `test/judges.test.js`; add one before you change a judge.

package/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ## [Unreleased]
 
+## [0.1.21] - 2026-09-12
+
+### Added
+
+- **Subscription plans, stated by you and never guessed.** The installer asks which plan you hold for Claude Code, Codex, `agy` and `grok` (interactive, or `--plans codex=pro-20x,agy=ultra-5x`; `--plans none` clears). Each plan row in `src/catalog.js` carries only a name, a headroom level (`base`, `high`, `max`), its official source page and the date it was checked; no prices and no model ids, because both change faster than releases. `--list` prints them.
+- **Plan guidance in the generated docs.** The lanes table gains a `Plan` column, and `ROUTING.md` and `DELEGATION_MATRIX.md` gain a plan guidance block: high and max headroom lanes take volume (scoped builds, pre-ship second-family audits, first-pass research), base headroom lanes keep short second opinions. Headroom moves volume only; who reviews what does not change.
+- **`--effort auto` in `cli-run`.** Accepted as a flag or as a `lanes.json` default on every lane with an effort flag (qwen still refuses it). A call sizes from prompt length: under 4,000 characters is `medium`, otherwise `high`. A codex `--audit` always runs at `high` and logs the larger of prompt length and changed lines as evidence. Auto never resolves above `high`: `xhigh`, `max` and `ultra` are sent only when named. The durable log gains `effort_resolved`, `effort_basis` (`explicit`, `prompt_chars`, `audit_floor`, `none`), `effort_scope` and `effort_truncated`.
+- **Bounded change counting for audits.** Untracked files are listed NUL-delimited, only regular files are opened (FIFOs, devices and symlinks are skipped by `lstat`), and the pass stops at 200 files, 256 KiB per file, 2 MiB total or 2 seconds, marking the evidence truncated. An unborn `HEAD` or any git failure falls back to prompt length.
+
+### Changed
+
+- **Automatic effort is opt-in.** A high or max headroom plan does not change `bin/lanes.json` by itself; `--effort-auto` (or yes to the question) writes `"effort": "auto"` for exactly those cli-run lanes. Claude Code is never written there, since it is not a cli-run lane and an entry for it would fail the whole file closed. With no plan stated, `bin/lanes.json` is byte-identical to 0.1.20 and `MANIFEST.json` records no plan keys. A re-run that omits `--plans` keeps the previous plans.
+- **Five documented Windows skips, not four.** The FIFO half of the new untracked-file test needs `mkfifo`; its symlink half runs everywhere.
+
+## [0.1.20] - 2026-09-12
+
+### Added
+
+- **A Claude Code plugin.** `/plugin marketplace add aunysillyme/model-orchestrator`, then `/plugin install model-orchestrator@model-orchestrator`, installs `route-gate.mjs`, `subagent-context.mjs` and the eight subagents without merging a settings snippet by hand. The bundle lives in `plugin/`, listed by `.claude-plugin/marketplace.json` at the repo root. It passes `claude plugin validate --strict`, the check Anthropic's community marketplace review runs, and all eight checks of Sigistry's public plugin verification methodology (1.2), run standalone before release as a quality bar; the plugin is not listed there.
+- **The plugin is generated, never a second copy.** `npm run gen:plugin` renders `plugin/` from the same `templates/` the installer uses, and `test/plugin.test.js` fails when the committed bundle drifts from that, when `plugin.json`'s version is not `package.json`'s, when `hooks/hooks.json` references a hook that is not shipped, when a plugin hook gains a network call, a file write, credential access, dynamic evaluation or a subprocess, when an agent has no `tools:` line or a review-type agent carries Write or Edit, and when the plugin README loses its install commands. Each check was proved red against the real files before it was trusted.
+- **The plugin's route gate works without an install step.** A plugin cannot be rendered per project, so its `route-gate.mjs` reads the installer's default locations, `ai-orchestrator/ROUTING.md` then `ai-orchestrator/ORCHESTRATOR.md`, and takes the first that exists. Something at the first path that is not a readable file (a directory, a FIFO) is reported, never skipped for the second. With neither present it tells Claude on every prompt, and the user once at session start, to run `npx model-orchestrator`, so a project with no rules is never a silent no-op.
+
+### Changed
+
+- **`builder`, `deep-planner` and `live-researcher` now declare their tools, for npm installs too.** Until now they carried no `tools:` line and inherited every tool the session had, MCP tools included. `builder` gets `Read, Write, Edit, Glob, Grep, Bash`; `deep-planner` gets `Read, Glob, Grep` (its prompt already says it never edits); `live-researcher` gets `WebSearch, WebFetch`. This narrows what those three agents can do in an existing install once regenerated: if you relied on `builder` calling an MCP tool, or `deep-planner` running a command, add the tool to that agent's `tools:` line or delete the line.
+- **`route-gate.mjs` takes a list of rules paths instead of one.** An installer render is a one-element list with no setup hint, so an npm install behaves exactly as before; a test pins that render.
+
+### Fixed
+
+- **`route-gate.mjs` could emit more than Claude Code's 10,000-character hook output cap, on npm installs too.** The routing table was capped at 4,000 characters, but a fallback message embeds the resolved project path and the error text, so a 12,000-character `CLAUDE_PROJECT_DIR` produced 12,146 characters from an installer render. Every string the hook emits is now capped at 8,000 characters, with a test on both renders. Found by the pre-release audit round and reproduced before the fix.
+- **The plugin's hook-safety test could not see an async write or subprocess.** `writeFileSync?` matches `writeFileSyn` and `writeFileSync`, never `writeFile`, and every `process.env` read was exempt. The check now matches the Sync and async form of every file write and subprocess call, refuses dynamic `import(` and `require(`, allows static imports of `node:fs` and `node:path` only, requires `openSync` to open read-only, and allows no environment variable but `CLAUDE_PROJECT_DIR`, with a red case for each. Found by the same audit round.
+
+### Not changed
+
+- `route-metrics.mjs` still installs with `npx model-orchestrator`, unchanged. It is left out of the plugin only, because it writes a log to disk and the plugin ships only hooks that read.
+
 ## [0.1.19] - 2026-09-12
 
 ### Added
@@ -293,7 +329,9 @@ First release.
 - Tests: a case per fix, judges proven to go red, mutation checks; `npm test` prints the current count.
 - Adversarial audit: two Codex rounds plus a two-engine review (Codex, Antigravity); findings and fixes in `docs/audit-brief.md`. After the review: subagents go to the project root (`--project`), snippet paths computed from `--dir`, lane sections rendered from the selection, a primary agent required, level 3 asks for API keys separately from CLIs, images and CLI installs pinned, an activation summary at the end of every install.
 
-[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.19...HEAD
+[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.21...HEAD
+[0.1.21]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.20...v0.1.21
+[0.1.20]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.19...v0.1.20
 [0.1.19]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.18...v0.1.19
 [0.1.18]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.17...v0.1.18
 [0.1.17]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.16...v0.1.17

package/README.md

@@ -2,13 +2,14 @@
 
 [![npm](https://img.shields.io/npm/v/model-orchestrator.svg)](https://www.npmjs.com/package/model-orchestrator) [![test](https://github.com/aunysillyme/model-orchestrator/actions/workflows/test.yml/badge.svg)](https://github.com/aunysillyme/model-orchestrator/actions/workflows/test.yml) [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![node >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](package.json)
 
-**Route every task to the right model, agent or LLM, and spend fewer tokens.** A model orchestrator for AI coding agents and LLMs: Claude Code, Codex, Gemini, Grok, Qwen, Ollama. One installer asks what you have access to and writes routing rules, subagents and a CLI runner for exactly that setup, from one chat app to several agent CLIs or a virtual machine. Routing rules tell your agent which model, subagent or CLI to use for each task, so small work goes to cheap tiers and fewer tokens go to frontier models; the runner executes the lane it is given. On Claude Code it also delegates execution to subagents by default, with two hooks that inject the routing table every turn.
+**Route every task to the right model, agent or LLM, and spend fewer tokens.** A model orchestrator for AI coding agents and LLMs: Claude Code, Codex, Gemini, Grok, Qwen, Ollama. One installer asks what you have access to and writes routing rules, subagents and a CLI runner for exactly that setup, from one chat app to several agent CLIs or a virtual machine. Routing rules tell your agent which model, subagent or CLI to use for each task, so small work goes to cheap tiers and fewer tokens go to frontier models; the runner executes the lane it is given. On Claude Code it also delegates execution to subagents by default, with two hooks that inject the routing table every turn, and the hooks and subagents also install as a [Claude Code plugin](#claude-code-plugin).
 
 ## At a glance
 
 - **What it is:** routing rules, subagent definitions and a CLI lane runner (`cli-run`) for the AI tools you already pay for.
 - **What it is not:** a proxy, a gateway or an API router. It does not automatically compare prices or select models; your agent follows the rules and chooses.
 - **Install:** `npx model-orchestrator` (interactive), or headless from a script or an agent: `npx model-orchestrator --yes --level 2 --ais claude-code,codex --project . --dir ./ai-orchestrator`.
+- **Claude Code plugin:** `/plugin marketplace add aunysillyme/model-orchestrator`, then `/plugin install model-orchestrator@model-orchestrator`. The routing rules still come from the installer; see [Claude Code plugin](#claude-code-plugin).
 - **Use it when:** you run more than one model or agent and want each task sent to the smallest one that can do it well.
 - **What it saves:** frontier-model tokens. Bulk work, reading and checks go to fast tiers; the expensive tier is kept for planning and judgment.
 - **For agents:** [`llms.txt`](llms.txt) summarizes the package and links every doc; [`AGENTS.md`](AGENTS.md) has the headless commands.
@@ -29,6 +30,10 @@ The installer asks a few things, then writes a folder:
 
 It never writes a secret, never runs a vendor shell script for you, and never overwrites a document you already have unless you pass `--force`. Two exceptions, both stated when they happen: `MANIFEST.json` and `bin/lanes.json` are machine-owned and rewritten on every run so a changed selection applies; runtime files (`cli-run`, the audit job, compose, gateway config, setup script) are upgraded when the installed copy matches the hash a previous run recorded, kept and reported as a conflict when you edited them, and kept as unverifiable when no manifest exists (`--upgrade-runtime` replaces runtime files only). The same hash rule is available for documents on request: `--update-docs` regenerates the documents a previous run wrote and nobody edited, so a changed selection reaches `ROUTING.md` and the delegation matrix without `--force`; edited documents are kept and named. Docs and protocols go to `--dir` (default `./ai-orchestrator`); subagent definitions (and, on Claude Code, two hook scripts) go to the project root your agent runs from (`--project`, default the current directory), because that is the only place Claude Code and Antigravity read them. It ends with an activation summary: what to copy where, which sign-ins, and one smoke command. Uninstall: follow the generated README. Inspect the manifest and remove only the individual managed subagent files you no longer need, preserve edited or pre-existing files, and remove your manually pasted activation block. Never delete a shared subagent folder.
 
+## Plans and automatic effort
+
+State known subscription plans with `--plans codex=pro-20x,agy=ultra-5x`. The generated guidance uses plan headroom to allocate volume only. It never changes capability or independent-review rules. `--effort-auto` is explicit consent to set `auto` only for selected high or max headroom CLI lanes. Auto chooses medium below 4,000 prompt characters and high otherwise, never higher. A codex audit is always high. Name `xhigh` explicitly for security-critical or irreversible work.
+
 ## The three levels
 
 | Level | You have | You get |
@@ -90,6 +95,22 @@ npx model-orchestrator --yes --level 2 --ais claude-code,codex --project ~/my-ap
 npx model-orchestrator --yes --level 2 --ais claude-code,codex,grok --primary claude-code --dir ./ai-orchestrator --project . --update-docs   # added a lane: regenerate the docs you never edited
 ```
 
+## Claude Code plugin
+
+The Claude Code hooks and subagents also ship as a plugin, so they install and update through Claude Code itself instead of a settings snippet you merge by hand:
+
+```
+/plugin marketplace add aunysillyme/model-orchestrator
+/plugin install model-orchestrator@model-orchestrator
+```
+
+- **What it ships:** `route-gate.mjs` (UserPromptSubmit, plus a one-line notice at session start when the project has no rules), `subagent-context.mjs` (SubagentStart), and the eight subagents, each with an explicit tool list. Agents load namespaced, as `model-orchestrator:builder`.
+- **What it still needs from the installer:** the routing rules. A plugin runs no install step, so it reads the installer's default locations, `ai-orchestrator/ROUTING.md` then `ai-orchestrator/ORCHESTRATOR.md`, and names `npx model-orchestrator` when neither exists. A project installed with a different `--dir` should wire the installer's rendered hooks instead.
+- **What it leaves out:** `route-metrics.mjs`, the routing log. It writes to disk and the plugin ships only hooks that read, so `npx model-orchestrator` is how you get it.
+- **How it is kept honest:** `plugin/` is generated from `templates/` by `npm run gen:plugin`, and `test/plugin.test.js` fails when the committed bundle drifts, when a hook gains a network call, a write or a subprocess, or when an agent loses its tool list. The bundle passes `claude plugin validate --strict`, the check Anthropic's community marketplace review runs on every submission.
+
+Details, including running the plugin next to an npm install: [plugin/README.md](plugin/README.md).
+
 ## What gets written (level 3, everything)
 
 ```
@@ -117,6 +138,7 @@ ai-orchestrator/
 | [`src/`](src/README.md) | the catalog, the pure planner, detection, rendering |
 | [`templates/`](templates/README.md) | everything the installer can write, by level, plus `tools/` for companions |
 | [`docs/`](docs/README.md) | the three parts and the catalog |
+| [`plugin/`](plugin/README.md) | the Claude Code plugin, generated from `templates/` by `npm run gen:plugin`; `.claude-plugin/marketplace.json` at the root lists it |
 | [`test/`](test/README.md) | `npm test`: judges proven to go red, catalog integrity, planner, end-to-end install in a temp dir; `.github/workflows/test.yml` runs it on Ubuntu, macOS and Windows, Node 18/20/22 |
 
 ## What is enforced, what is delegated, what is an instruction
@@ -260,7 +282,7 @@ Yes. `--yes` with `--level`, `--ais` and `--project` runs headless, `--dry-run`
 
 ## Requirements
 
-Node 18 or newer. No dependencies. Works on macOS and Linux; the level 3 box templates assume Ubuntu. Windows: CI runs the suite on `windows-latest` (Node 18, 20, 22), including lane execution end to end through `cli-run` against a fake CLI installed the same way npm installs a real one (a `.cmd` shim). `cli-run` never runs a lane through `cmd.exe` when it can avoid it: it resolves the shim to the Node script underneath and spawns Node directly, so a prompt reaching a real lane never passes through a Windows shell. A `.cmd` or `.bat` lane that cannot be resolved that way (an old or hand-edited shim) is refused with exit 13 and a message saying how to fix it, rather than run through `cmd.exe`: a batch file re-reads its arguments after `cmd.exe` has parsed them once, and no escaping fully contains a prompt through both passes. Install, detection, the hooks and `cli-run`'s `taskkill` tree kill are tested on Windows too, including SIGTERM/SIGINT to the wrapper (Windows has no OS-level signals: both terminate it unconditionally, verified there rather than treated the same as POSIX). Four narrow skips remain on Windows, each for a POSIX behavior the OS or the CI shell genuinely does not have, and each named here because a test that is quietly skipped reads as a test that passed: `statSync().mode`'s executable bit (NTFS has none, so that one assertion is conditional inside a test that otherwise runs everywhere); a lane dying mid-run from a real POSIX signal (a real Windows lane cannot die "by signal"); running `weekly-audit.sh`'s watchdog functions for real under Git Bash's job control, both the end-to-end run and the `bounded()` timeout check (the script itself only ever runs on the Ubuntu box it targets); and a `mkfifo` FIFO at the rules path, the one case that proves `route-gate.mjs` cannot HANG on a non-regular file, since Windows has no `mkfifo` to build one (the guard behind it is covered on every OS by a directory at the same path). The list is not prose on trust: `test/prose.test.js` counts every `skip:` in the suite and fails if one of them is not documented here.
+Node 18 or newer. No dependencies. Works on macOS and Linux; the level 3 box templates assume Ubuntu. Windows: CI runs the suite on `windows-latest` (Node 18, 20, 22), including lane execution end to end through `cli-run` against a fake CLI installed the same way npm installs a real one (a `.cmd` shim). `cli-run` never runs a lane through `cmd.exe` when it can avoid it: it resolves the shim to the Node script underneath and spawns Node directly, so a prompt reaching a real lane never passes through a Windows shell. A `.cmd` or `.bat` lane that cannot be resolved that way (an old or hand-edited shim) is refused with exit 13 and a message saying how to fix it, rather than run through `cmd.exe`: a batch file re-reads its arguments after `cmd.exe` has parsed them once, and no escaping fully contains a prompt through both passes. Install, detection, the hooks and `cli-run`'s `taskkill` tree kill are tested on Windows too, including SIGTERM/SIGINT to the wrapper (Windows has no OS-level signals: both terminate it unconditionally, verified there rather than treated the same as POSIX). Five narrow skips remain on Windows, each for a POSIX behavior the OS or the CI shell genuinely does not have, and each named here because a test that is quietly skipped reads as a test that passed: `statSync().mode`'s executable bit (NTFS has none, so that one assertion is conditional inside a test that otherwise runs everywhere); a lane dying mid-run from a real POSIX signal (a real Windows lane cannot die "by signal"); running `weekly-audit.sh`'s watchdog functions for real under Git Bash's job control, both the end-to-end run and the `bounded()` timeout check (the script itself only ever runs on the Ubuntu box it targets); and a `mkfifo` FIFO at the rules path, the one case that proves `route-gate.mjs` cannot HANG on a non-regular file, since Windows has no `mkfifo` to build one (the guard behind it is covered on every OS by a directory at the same path); and an untracked `mkfifo` FIFO in the repository `cli-run --audit` sizes, the case that proves `--effort auto` never opens a non-regular file (the symlink half of that test runs on every OS). The list is not prose on trust: `test/prose.test.js` counts every `skip:` in the suite and fails if one of them is not documented here.
 
 **Privacy.** The installer sends no telemetry and makes no network call of its own once it is running. Two things around that are worth being exact about:
 

package/bin/cli-run.mjs

@@ -51,10 +51,10 @@
 // for one lane and absent for four is worse than no field. It would also be a
 // provider-supplied string, which this log deliberately never holds.
 
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { StringDecoder } from 'node:string_decoder';
 import { createHash } from 'node:crypto';
-import { readFileSync, existsSync, mkdirSync, appendFileSync, mkdtempSync, rmSync, accessSync, constants, realpathSync, statSync } from 'node:fs';
+import { readFileSync, existsSync, mkdirSync, appendFileSync, mkdtempSync, rmSync, accessSync, constants, realpathSync, statSync, lstatSync, openSync, readSync, closeSync } from 'node:fs';
 import { join, dirname, delimiter, resolve } from 'node:path';
 import { tmpdir, homedir } from 'node:os';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -233,6 +233,82 @@ export const LANE_FLAGS = {
   qwen: { model: (v) => ['-m', v], effort: null }
 };
 
+// Auto is deliberately a small, static ladder. It is not a vendor capability
+// probe and it never chooses the top of a vendor's effort range.
+export const AUTO_EFFORT = {
+  codex: { small: 'medium', large: 'high' },
+  grok: { small: 'medium', large: 'high' },
+  agy: { small: 'medium', large: 'high' },
+  hermes: { small: 'medium', large: 'high' }
+};
+
+export function gitChangedLines(cwd) {
+  try {
+    const r = spawnSync('git', ['diff', '--numstat', '-z', 'HEAD'], { cwd, timeout: 5000, maxBuffer: 1024 * 1024 });
+    if (r.error || r.status !== 0) return null;
+    let total = 0;
+    for (const row of String(r.stdout).split('\0')) {
+      if (!row) continue;
+      const [added, removed] = row.split('\t');
+      total += (Number.isFinite(Number(added)) ? Number(added) : 0) + (Number.isFinite(Number(removed)) ? Number(removed) : 0);
+    }
+    const listed = spawnSync('git', ['ls-files', '--others', '--exclude-standard', '-z'], { cwd, timeout: 5000, maxBuffer: 1024 * 1024 });
+    if (listed.error || listed.status !== 0) return null;
+    const root = realpathSync(cwd);
+    const deadline = Date.now() + 2000;
+    let files = 0, bytes = 0, truncated = false;
+    for (const rel of String(listed.stdout).split('\0')) {
+      if (!rel) continue;
+      if (files >= 200 || Date.now() > deadline) { truncated = true; break; }
+      const p = resolve(root, rel);
+      if (p !== root && !p.startsWith(root + '/') && !p.startsWith(root + '\\')) continue;
+      let st;
+      try { st = lstatSync(p); } catch { continue; }
+      if (!st.isFile()) continue;
+      const limit = Math.min(st.size, 256 * 1024, 2 * 1024 * 1024 - bytes);
+      if (limit <= 0) { truncated = true; break; }
+      let fd;
+      try {
+        fd = openSync(p, 'r');
+        const buf = Buffer.alloc(Math.min(limit, 64 * 1024));
+        let read = 0, last = -1;
+        while (read < limit && Date.now() <= deadline) {
+          const n = readSync(fd, buf, 0, Math.min(buf.length, limit - read), read);
+          if (!n) break;
+          for (let i = 0; i < n; i++) if (buf[i] === 10) total++;
+          last = buf[n - 1];
+          read += n;
+        }
+        if (read && last !== 10) total++;
+        bytes += read;
+        if (read < st.size || Date.now() > deadline) truncated = true;
+      } catch {
+        // A changed file disappearing is ordinary repository churn. The caller
+        // falls back to prompt sizing only when the git probes themselves fail.
+      } finally { if (fd !== undefined) try { closeSync(fd); } catch {} }
+      files++;
+      if (bytes >= 2 * 1024 * 1024) { truncated = true; break; }
+    }
+    return { lines: total, truncated };
+  } catch {
+    return null;
+  }
+}
+
+export function resolveAutoEffort(lane, requested, prompt, audit, cwd = process.cwd()) {
+  if (requested !== 'auto') return { resolved: requested || null, basis: requested ? 'explicit' : 'none', scope: null, truncated: false };
+  const promptScope = prompt.length;
+  if (!audit) {
+    const bucket = promptScope < 4000 ? 'small' : 'large';
+    return { resolved: AUTO_EFFORT[lane][bucket], basis: 'prompt_chars', scope: promptScope, truncated: false };
+  }
+  const git = gitChangedLines(cwd);
+  const scope = Math.max(promptScope, git ? git.lines : 0);
+  // Audit is a stakes floor. Scope records the larger independently observed
+  // input, but never moves an audit above or below high.
+  return { resolved: 'high', basis: 'audit_floor', scope, truncated: !!(git && git.truncated) };
+}
+
 // A model id or effort level becomes an argv element and, for codex, part of a
 // TOML value. Bounding the charset is what makes both safe: no leading dash (a
 // value cannot become a flag), no quote, space or control character (a value
@@ -579,6 +655,7 @@ export function laneConfig(here = dirname(fileURLToPath(import.meta.url))) {
         if (model !== undefined && badRouteValue('model', model)) return null;
         if (effort !== undefined) {
           if (badRouteValue('effort', effort)) return null;
+          if (effort.startsWith('auto') && effort !== 'auto') return null;
           if (!LANE_FLAGS[lane] || !LANE_FLAGS[lane].effort) return null; // a lane with no reasoning flag cannot have one pinned
         }
         defaults[lane] = { model: model ?? null, effort: effort ?? null };
@@ -618,6 +695,7 @@ function usage(msg) {
   own config. Every lane takes --model; every lane except qwen takes --effort.
   Levels are the vendor's own (agy low|medium|high, hermes none|minimal|...): an
   unknown level is rejected by the lane, and reported as that lane's exit code.
+  auto sizes per call: below 4,000 prompt characters is medium, otherwise high; a codex audit is always high. Auto never resolves above high.
   Pin them per lane instead of per call with "defaults" in bin/lanes.json.`);
   return USAGE;
 }
@@ -665,7 +743,7 @@ export async function doctor(run) {
     const d = defaults[lane] || {};
     // A disabled lane has no route worth reporting; saying "not pinned" there
     // reads as a finding about a lane that is not going to run.
-    const route = !on ? '' : d.model || d.effort ? `route ${d.model || 'lane default'}/${d.effort || 'lane default'}` : 'route not pinned (inherits the lane\'s own config)';
+    const route = !on ? '' : d.effort === 'auto' ? `route ${d.model || 'lane default'}/auto (sized per call)` : d.model || d.effort ? `route ${d.model || 'lane default'}/${d.effort || 'lane default'}` : 'route not pinned (inherits the lane\'s own config)';
     let line = `  ${lane.padEnd(7)} ${on ? 'enabled ' : 'disabled'} ${bin ? 'binary ok' : 'binary MISSING'}${route ? '  ' + route : ''}`;
     if (on && !bin) bad++;
     if (on && bin && run) {
@@ -771,6 +849,7 @@ export async function main(argv) {
     if (v == null) continue;
     const bad = badRouteValue(kind, v);
     if (bad) return usage(bad);
+    if (kind === 'effort' && v.startsWith('auto') && v !== 'auto') return usage('--effort auto must be spelled exactly');
   }
   // qwen has no reasoning flag. Dropping --effort silently would leave the caller
   // believing a route that never happened, which is the defect this feature fixes.
@@ -784,13 +863,18 @@ export async function main(argv) {
   // gap this feature exists to close. A malformed lanes.json has no usable
   // defaults, so the flags stand alone and say so.
   const route = resolveRoute(lane, opts, cfg === null ? {} : cfg.defaults);
+  const sizing = resolveAutoEffort(lane, route.effort, prompt, opts.audit);
   opts.model = route.model;
-  opts.effort = route.effort;
+  opts.effort = sizing.resolved;
   Object.assign(base, {
     model_requested: route.model,
     effort_requested: route.effort,
     model_source: route.model_source,
-    effort_source: route.effort_source
+    effort_source: route.effort_source,
+    effort_resolved: sizing.resolved,
+    effort_basis: sizing.basis,
+    effort_scope: sizing.scope,
+    effort_truncated: sizing.truncated
   });
   const enabled = cfg === null ? null : cfg.enabled;
   if (enabled === null) {
@@ -810,6 +894,8 @@ export async function main(argv) {
     return UNAVAILABLE;
   }
 
+  if (route.effort === 'auto' && !opts.quiet) console.error(`cli-run: effort auto -> ${sizing.resolved} (${sizing.basis})`);
+
   const tmp = mkdtempSync(join(tmpdir(), 'cli-run-'));
   const before = opts.expectFile ? snapshotFile(resolve(opts.expectFile)) : null;
   try {

package/bin/cli.js

@@ -22,8 +22,8 @@ import { windowsSpawnPlan } from './cli-run.mjs';
 // errors (exit 2) before anything is planned, so a typo like --dryy can never
 // turn a dry run into a real one.
 const SPEC = {
-  level: 'value', ais: 'value', primary: 'value', dir: 'value', project: 'value', tools: 'value', apis: 'value',
-  yes: 'bool', force: 'bool', dry: 'bool', 'dry-run': 'bool', 'no-install': 'bool', 'no-tools': 'bool', 'no-apis': 'bool', 'upgrade-runtime': 'bool', 'update-docs': 'bool', list: 'bool', help: 'bool', h: 'bool', version: 'bool', v: 'bool'
+  level: 'value', ais: 'value', primary: 'value', dir: 'value', project: 'value', tools: 'value', apis: 'value', plans: 'value',
+  yes: 'bool', force: 'bool', dry: 'bool', 'dry-run': 'bool', 'no-install': 'bool', 'no-tools': 'bool', 'no-apis': 'bool', 'effort-auto': 'bool', 'upgrade-runtime': 'bool', 'update-docs': 'bool', list: 'bool', help: 'bool', h: 'bool', version: 'bool', v: 'bool'
 };
 export function parseArgs(argv) {
   const out = {};
@@ -104,6 +104,8 @@ Flags
   --tools a,b        companion tools to set up, all optional (default with --yes: codecalc only); --no-tools for none
   --apis a,b         level 3 only: metered API keys you HOLD (anthropic,openai,google,xai,openrouter); --no-apis for none.
                      Asked separately from the CLIs because a subscription is not an API key.
+  --plans a=plan,b=plan  stated subscription plans for guidance; --plans none clears prior stated plans
+  --effort-auto      consent to write auto effort defaults for selected high or max plan cli-run lanes
   --dir path         where to write the docs and protocols (default ./ai-orchestrator)
   --project path     the project root your agent runs from; subagent definitions go here (default: current directory,
                      so set it: a run from your home folder otherwise drops the subagent files there)
@@ -129,6 +131,7 @@ if (flag('list')) {
   for (const a of AIS) {
     const here = a.bin ? (which(a.bin) ? 'installed' : 'not on PATH') : 'app';
     console.log(`${a.id.padEnd(13)} ${a.name}\n${''.padEnd(13)} level ${a.minLevel}+ · ${a.access} · ${here}\n${''.padEnd(13)} ${a.role}`);
+    if (a.plans) for (const p of a.plans) console.log(`${''.padEnd(13)} plan ${p.id}: ${p.name} (${p.headroom} headroom, checked ${p.checked}, ${p.source})`);
   }
   console.log('\nmetered API providers (--apis a,b, level 3 gateway only):');
   for (const prov of PROVIDERS) console.log(`${prov.id.padEnd(13)} ${prov.name}  (variable name: ${prov.envName})`);
@@ -146,6 +149,29 @@ function bad(msg) {
   process.exit(2);
 }
 
+function plansFromIds(raw, selected) {
+  if (raw === 'none') return {};
+  const out = {};
+  for (const part of raw.split(',')) {
+    const [id, plan, ...extra] = part.split('=');
+    if (!id || !plan || extra.length) bad(`--plans entry must be AI=plan: ${part}`);
+    if (Object.hasOwn(out, id)) bad(`--plans names ${id} more than once`);
+    const ai = byId[id];
+    if (!ai) bad(`--plans names unknown AI id: ${id}`);
+    if (!selected.includes(ai)) bad(`--plans names ${id}, which is not selected`);
+    const found = (ai.plans || []).find((p) => p.id === plan);
+    if (!found) bad(`--plans names unknown plan ${plan} for ${id}`);
+    out[id] = found;
+  }
+  return Object.fromEntries(Object.entries(out).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+function plansFromManifest(manifest, selected) {
+  const raw = manifest && manifest.plans;
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {};
+  return plansFromIds(Object.entries(raw).map(([id, plan]) => `${id}=${plan}`).join(','), selected);
+}
+
 async function main() {
   // Says what this generates, not what it guarantees. The old line promised
   // routing this package does not perform: lane choice is an instruction an
@@ -278,11 +304,51 @@ async function main() {
   const projectBad = dirProblems(project);
   if (projectBad.length) bad('--project: ' + projectBad.join('; '));
 
+  // A prior manifest is read before planning so an omitted reconfiguration
+  // preserves consent and stated plans instead of silently clearing either.
+  const prev = readManifest(dir);
+  let plans;
+  let plansKept = false;
+  if (opt('plans') !== null) {
+    plans = plansFromIds(opt('plans'), selected);
+  } else if (prev) {
+    plans = plansFromManifest(prev, selected);
+    plansKept = Object.keys(plans).length > 0;
+  } else if (!yes) {
+    plans = {};
+    for (const ai of selected.filter((a) => a.plans)) {
+      const first = ai.plans[0];
+      console.log(`\nWhich ${ai.vendor} plan? (checked ${first.checked}, source ${first.source})`);
+      ai.plans.forEach((p, i) => console.log(`  ${i + 1}  ${p.name} (${p.headroom} headroom)`));
+      console.log(`  ${ai.plans.length + 1}  not sure`);
+      const answer = Number(await ask(`Plan [${ai.plans.length + 1}]: `, String(ai.plans.length + 1)));
+      if (!Number.isInteger(answer) || answer < 1 || answer > ai.plans.length + 1) bad('pick a listed plan number');
+      if (answer <= ai.plans.length) plans[ai.id] = ai.plans[answer - 1];
+    }
+  } else {
+    plans = {};
+  }
+
+  const eligibleAuto = selected.filter((a) => a.cliRun && plans[a.id] && ['high', 'max'].includes(plans[a.id].headroom)).map((a) => a.id).sort();
+  let effortAuto;
+  if (flag('effort-auto')) {
+    effortAuto = eligibleAuto;
+  } else if (prev && Array.isArray(prev.effortAuto)) {
+    effortAuto = prev.effortAuto.filter((id) => selected.some((a) => a.id === id && a.cliRun));
+  } else if (!yes && eligibleAuto.length) {
+    const answer = await ask(`\nSize reasoning effort per task automatically on ${eligibleAuto.join(', ')}? [y/N] `, 'n');
+    effortAuto = /^y/i.test(answer) ? eligibleAuto : [];
+  } else {
+    effortAuto = [];
+  }
+
   // 5. Plan
-  const files = planFiles({ level, selected, primary, dir, project, tools, apis });
+  const files = planFiles({ level, selected, primary, dir, project, tools, apis, plans, effortAuto });
   const lvl = LEVELS.find((l) => l.id === level);
   const agentFiles = files.filter((f) => f.root === 'project');
-  console.log(`\nPlan\n  level    ${lvl.id} ${lvl.name}\n  access   ${selected.map((a) => a.id).join(', ')}\n  primary  ${primary ? primary.id : 'none'}${primaryAutoPicked ? ` (chosen for you from ${candidates.map((a) => a.id).join(', ')}; pass --primary to decide it yourself)` : ''}\n  tools    ${tools.map((t) => t.id).join(', ') || 'none'}` + (level >= 3 ? `\n  api keys ${apis.map((p) => p.id).join(', ') || 'none'}` : '') + `\n  folder   ${dir}\n  project  ${project}${agentFiles.length ? ' (' + agentFiles.length + ' subagent files go here)' : ''}\n  files    ${files.length}`);
+  const statedPlans = Object.entries(plans).map(([id, p]) => `${id}=${p.id}`).join(', ');
+  console.log(`\nPlan\n  level    ${lvl.id} ${lvl.name}\n  access   ${selected.map((a) => a.id).join(', ')}\n  primary  ${primary ? primary.id : 'none'}${primaryAutoPicked ? ` (chosen for you from ${candidates.map((a) => a.id).join(', ')}; pass --primary to decide it yourself)` : ''}\n  tools    ${tools.map((t) => t.id).join(', ') || 'none'}\n  plans    ${statedPlans || 'none stated'}` + (level >= 3 ? `\n  api keys ${apis.map((p) => p.id).join(', ') || 'none'}` : '') + `\n  folder   ${dir}\n  project  ${project}${agentFiles.length ? ' (' + agentFiles.length + ' subagent files go here)' : ''}\n  files    ${files.length}`);
+  if (plansKept) console.log('  plans kept from the previous run');
   if (agentFiles.length && !opt('project')) {
     console.log(`\nNote: --project was not given, so the ${agentFiles.length} subagent file(s) go to the current directory (${project}). Pass --project to put them somewhere else.`);
   }
@@ -303,10 +369,11 @@ async function main() {
   }
 
   // Reconfiguration: compare what a previous run recorded with what was asked now.
-  const prev = readManifest(dir);
   const changed = prev
     ? ['level', 'primary'].filter((k) => String(prev[k]) !== String(k === 'level' ? level : primary ? primary.id : null))
         .concat(['ais', 'tools', 'apis'].filter((k) => JSON.stringify(prev[k] || []) !== JSON.stringify({ ais: selected, tools, apis }[k].map((x) => x.id))))
+        .concat(JSON.stringify(prev.plans || {}) !== JSON.stringify(Object.fromEntries(Object.entries(plans).map(([id, p]) => [id, p.id]))) ? ['plans'] : [])
+        .concat(JSON.stringify((prev.effortAuto || []).slice().sort()) !== JSON.stringify(effortAuto.slice().sort()) ? ['effortAuto'] : [])
     : [];
 
   let written, skipped, upgraded, conflicts, unverifiable, docsUpdated, docsConflict, docsUnverifiable;

package/docs/catalog.md

@@ -19,6 +19,10 @@ Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrite
 - **Install:** `npm install -g @anthropic-ai/claude-code@2.1.226`
 - **Sign in:** run `claude` once and sign in with your Anthropic account
 - **Reads rules from:** `CLAUDE.md` · subagents in `.claude/agents/`
+- **Plans:**
+  - Claude Pro (base headroom, checked 2026-09-12): https://support.claude.com/en/articles/11049762-choose-a-claude-plan
+  - Claude Max 5x (high headroom, checked 2026-09-12): https://support.claude.com/en/articles/11049762-choose-a-claude-plan
+  - Claude Max 20x (max headroom, checked 2026-09-12): https://support.claude.com/en/articles/11049762-choose-a-claude-plan
 - **Built against:** 2.1.226 (the same number the npm pin uses)
 
 ### `codex` · Codex CLI (OpenAI, ChatGPT plan)
@@ -29,6 +33,10 @@ Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrite
 - **Sign in:** `codex login` (add `--device-auth` on a machine with no browser)
 - **Reads rules from:** `AGENTS.md`
 - **cli-run lane:** yes
+- **Plans:**
+  - ChatGPT Plus (base headroom, checked 2026-09-12): https://learn.chatgpt.com/codex/pricing.md
+  - ChatGPT Pro 5x (high headroom, checked 2026-09-12): https://learn.chatgpt.com/codex/pricing.md
+  - ChatGPT Pro 20x (max headroom, checked 2026-09-12): https://learn.chatgpt.com/codex/pricing.md
 - **Built against:** 0.153.4 (the same number the npm pin uses)
 
 ### `agy` · Antigravity CLI `agy` (Google AI plan)
@@ -39,6 +47,10 @@ Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrite
 - **Sign in:** first run opens a device-code sign-in with your Google account
 - **Reads rules from:** `GEMINI.md` · subagents in `.agents/agents/`
 - **cli-run lane:** yes
+- **Plans:**
+  - Google AI Pro (base headroom, checked 2026-09-12): https://gemini.google/subscriptions/
+  - Google AI Ultra 5x (high headroom, checked 2026-09-12): https://gemini.google/subscriptions/
+  - Google AI Ultra 20x (max headroom, checked 2026-09-12): https://gemini.google/subscriptions/
 - **Built against:** 1.1.27
 - **Note:** Gemini CLI was retired by Google in June 2026. agy is the successor. Do not install `gemini`.
 
@@ -49,6 +61,9 @@ Generated from `src/catalog.js`. Do not hand-edit; `npm run gen:catalog` rewrite
 - **Install:** vendor script (read it first): `https://x.ai/cli/install.sh`
 - **Sign in:** `grok login` (add `--device-auth` on a headless machine)
 - **cli-run lane:** yes
+- **Plans:**
+  - SuperGrok (base headroom, checked 2026-09-12): https://x.ai/news/grok-build-cli
+  - X Premium Plus (base headroom, checked 2026-09-12): https://x.ai/news/grok-build-cli
 - **Built against:** 1.0.5
 
 ### `hermes` · Hermes Agent (Nous Research)

package/docs/part-2-intermediate.md

@@ -2,6 +2,10 @@
 
 Everything in Part 1, plus lanes. One agent stays the orchestrator; every other AI becomes a lane it calls from the terminal.
 
+## Plans and automatic effort
+
+The installer can record plans with `--plans codex=pro-20x,agy=ultra-5x`. Plan headroom changes volume allocation only, never capability or the independent-review rule. `--effort-auto` is explicit consent to write `auto` for eligible high or max headroom CLI lanes. Auto resolves to medium or high from prompt size, and a codex audit is always high. It is a heuristic, not a measurement: name xhigh explicitly for security-critical or irreversible work.
+
 ## 1. Two kinds of lane
 
 **Lane A, subscription CLIs.** Claude Code, Codex, Antigravity, Grok, Hermes. Already paid for, $0 per call, used for interactive and agentic work. **Lane B, metered APIs.** Per token, used for programmatic bulk where a subscription CLI cannot serve. **Local.** A privacy lane, never a cost lane.

package/llms.txt

@@ -6,6 +6,8 @@ Install and run: `npx model-orchestrator` (interactive), or headless: `npx model
 
 Levels: 1 beginner (one agent or chat app), 2 intermediate (several agent CLIs, each called through `cli-run`), 3 advanced (adds a virtual machine with a gateway and a scheduled audit job). On Claude Code the install also delegates execution to subagents by default and ships two hooks (UserPromptSubmit, SubagentStart) that inject the routing table every turn.
 
+Claude Code plugin: `/plugin marketplace add aunysillyme/model-orchestrator`, then `/plugin install model-orchestrator@model-orchestrator`. It installs the two hooks and eight subagents; the routing rules still come from `npx model-orchestrator`, and the routing log (`route-metrics.mjs`) is npm-only.
+
 ## Docs
 
 - [README](https://github.com/aunysillyme/model-orchestrator/blob/main/README.md): what it writes, flags, principles, what is enforced versus instructed
@@ -16,7 +18,12 @@ Levels: 1 beginner (one agent or chat app), 2 intermediate (several agent CLIs,
 
 ## Reference
 
+- [Claude Code plugin](https://github.com/aunysillyme/model-orchestrator/blob/main/plugin/README.md): installing the hooks and subagents with `/plugin install`, what the plugin reads, and what it leaves to the installer
 - [CLI runner](https://github.com/aunysillyme/model-orchestrator/blob/main/bin/README.md): `cli-run` lanes, exit codes, the route logged per run
+
+## Plans and automatic effort
+
+Use `--plans AI=plan` to state a subscription plan and receive volume-allocation guidance. `--effort-auto` is opt-in and writes bounded `auto` effort only for selected high or max headroom CLI lanes. Auto is medium or high, never above high; name xhigh explicitly for security-critical or irreversible work.
 - [Templates](https://github.com/aunysillyme/model-orchestrator/blob/main/templates/README.md): the routing, tiers, task bundle and protocol files the installer renders
 - [Changelog](https://github.com/aunysillyme/model-orchestrator/blob/main/CHANGELOG.md): every release and the issue behind each fix
 - [Agent instructions](https://github.com/aunysillyme/model-orchestrator/blob/main/AGENTS.md): running the installer from an agent, and contributing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "model-orchestrator",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Model orchestrator for AI coding agents and LLMs: Claude Code, Codex, Gemini, Grok, Qwen, Ollama. Routing rules tell your agent which model, subagent or CLI to use for each task, so small work goes to cheap tiers and fewer tokens go to frontier models. One installer, plus a CLI runner that logs every route.",
   "type": "module",
   "bin": {
@@ -24,7 +24,8 @@
     "test": "node --test",
     "prepublishOnly": "npm test",
     "dry-run": "node bin/cli.js --yes --level 2 --ais claude-code,codex,grok --dir ./tmp-dry-run --dry",
-    "gen:catalog": "node scripts/gen-catalog.js"
+    "gen:catalog": "node scripts/gen-catalog.js",
+    "gen:plugin": "node scripts/gen-plugin.js"
   },
   "engines": {
     "node": ">=18"

package/scripts/README.md

@@ -3,3 +3,4 @@
 | File | Job |
 |---|---|
 | `gen-catalog.js` | regenerates `docs/catalog.md` AND the vendor compatibility table in `README.md` (between the `vendor-table` markers) from `src/catalog.js`; `npm run gen:catalog`. `test/catalog.test.js` fails if either generated surface disagrees with the catalog. |
+| `gen-plugin.js` | regenerates the Claude Code plugin bundle in `plugin/` (agents, the two read-only hooks, `plugin.json`, `LICENSE`) from `templates/`, using the plan in `src/plugin.js`; `npm run gen:plugin`. `test/plugin.test.js` fails if the committed bundle disagrees. `plugin/README.md` and `plugin/hooks/hooks.json` are hand-owned. |

package/scripts/gen-catalog.js

@@ -22,6 +22,10 @@ export function catalogMarkdown() {
     md += `### \`${a.id}\` · ${a.name}\n\n- **Kind:** ${a.kind} · **Access:** ${a.access} · **Lane:** ${a.lane} · **Level:** ${a.minLevel}+\n- **Wins at:** ${a.role}\n- **Install:** ${how}\n- **Sign in:** ${a.auth}\n`;
     if (a.rulesFile) md += `- **Reads rules from:** \`${a.rulesFile}\`` + (a.agentsDir ? ` · subagents in \`${a.agentsDir}/\`` : '') + '\n';
     if (a.cliRun) md += '- **cli-run lane:** yes\n';
+    if (a.plans) {
+      md += '- **Plans:**\n';
+      for (const p of a.plans) md += `  - ${p.name} (${p.headroom} headroom, checked ${p.checked}): ${p.source}\n`;
+    }
     if (a.builtAgainst) md += `- **Built against:** ${a.builtAgainst}` + (a.install.npm ? ' (the same number the npm pin uses)' : '') + '\n';
     if (a.note) md += `- **Note:** ${a.note}\n`;
     md += '\n';

package/scripts/gen-plugin.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+// Regenerates the Claude Code plugin bundle under plugin/ from the installer's
+// templates (src/plugin.js has the plan). The test suite checks the committed
+// bundle matches, so an agent or hook edited in templates/ cannot ship to npm
+// users and silently not to plugin users.
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { planPluginFiles, PLUGIN_DIR } from '../src/plugin.js';
+
+const files = planPluginFiles();
+for (const f of files) {
+  const abs = join(PLUGIN_DIR, ...f.rel.split('/'));
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, f.content);
+}
+console.log('plugin/ regenerated: ' + files.length + ' files');

package/src/README.md

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

package/src/catalog.js

@@ -27,6 +27,8 @@
 //              "(chat only, no CLI)" catalog note, so the activation line stays
 //              a sentence you can read once (#22)
 //   chatSurface chat apps only: where the pasted block goes in that app
+//   plans      optional known subscription plans: { id, name, headroom,
+//              source, checked }. Guidance uses headroom only, never prices.
 
 export const LEVELS = [
   {
@@ -70,6 +72,11 @@ export const AIS = [
     agentsDir: '.claude/agents',
     cliRun: false,
     models: { deep: 'opus', standard: 'sonnet', fast: 'haiku' },
+    plans: [
+      { id: 'pro', name: 'Claude Pro', headroom: 'base', source: 'https://support.claude.com/en/articles/11049762-choose-a-claude-plan', checked: '2026-09-12' },
+      { id: 'max-5x', name: 'Claude Max 5x', headroom: 'high', source: 'https://support.claude.com/en/articles/11049762-choose-a-claude-plan', checked: '2026-09-12' },
+      { id: 'max-20x', name: 'Claude Max 20x', headroom: 'max', source: 'https://support.claude.com/en/articles/11049762-choose-a-claude-plan', checked: '2026-09-12' }
+    ],
     // Verified at code.claude.com/docs/en/sub-agents (fetched 2026-09-10): "A
     // non-fork subagent's initial context contains: CLAUDE.md files: every
     // level of the CLAUDE.md hierarchy the main conversation loads ... The
@@ -95,6 +102,11 @@ export const AIS = [
     rulesFile: 'AGENTS.md',
     agentsDir: null,
     cliRun: true
+    , plans: [
+      { id: 'plus', name: 'ChatGPT Plus', headroom: 'base', source: 'https://learn.chatgpt.com/codex/pricing.md', checked: '2026-09-12' },
+      { id: 'pro-5x', name: 'ChatGPT Pro 5x', headroom: 'high', source: 'https://learn.chatgpt.com/codex/pricing.md', checked: '2026-09-12' },
+      { id: 'pro-20x', name: 'ChatGPT Pro 20x', headroom: 'max', source: 'https://learn.chatgpt.com/codex/pricing.md', checked: '2026-09-12' }
+    ]
   },
   {
     id: 'agy',
@@ -113,6 +125,11 @@ export const AIS = [
     agentsDir: '.agents/agents',
     cliRun: true,
     models: { deep: 'pro', standard: 'flash', fast: 'flash' },
+    plans: [
+      { id: 'ai-pro', name: 'Google AI Pro', headroom: 'base', source: 'https://gemini.google/subscriptions/', checked: '2026-09-12' },
+      { id: 'ultra-5x', name: 'Google AI Ultra 5x', headroom: 'high', source: 'https://gemini.google/subscriptions/', checked: '2026-09-12' },
+      { id: 'ultra-20x', name: 'Google AI Ultra 20x', headroom: 'max', source: 'https://gemini.google/subscriptions/', checked: '2026-09-12' }
+    ],
     note: 'Gemini CLI was retired by Google in June 2026. agy is the successor. Do not install `gemini`.'
   },
   {
@@ -131,6 +148,10 @@ export const AIS = [
     rulesFile: null,
     agentsDir: null,
     cliRun: true
+    , plans: [
+      { id: 'supergrok', name: 'SuperGrok', headroom: 'base', source: 'https://x.ai/news/grok-build-cli', checked: '2026-09-12' },
+      { id: 'x-premium-plus', name: 'X Premium Plus', headroom: 'base', source: 'https://x.ai/news/grok-build-cli', checked: '2026-09-12' }
+    ]
   },
   {
     id: 'hermes',

package/src/install.js

@@ -37,14 +37,26 @@ function table(rows, header) {
   return [line(header), line(header.map(() => '---')), ...rows.map(line)].join('\n');
 }
 
-export function lanesTable(selected) {
+export function lanesTable(selected, plans = {}) {
   const rows = selected.map((a) => [
     a.name,
     a.lane === 'A' ? 'A (subscription, $0 per call)' : a.lane === 'B' ? 'B (metered)' : a.lane === 'local' ? 'local' : 'chat',
     a.role,
-    a.cliRun ? '`cli-run ' + a.id + '`' : a.bin ? '`' + a.bin + '`' : 'the app'
+    a.cliRun ? '`cli-run ' + a.id + '`' : a.bin ? '`' + a.bin + '`' : 'the app',
+    plans[a.id] ? `${plans[a.id].name} (${plans[a.id].headroom} headroom)` : 'not stated'
   ]);
-  return table(rows, ['AI', 'Lane', 'Wins at', 'Call it with']);
+  return table(rows, ['AI', 'Lane', 'Wins at', 'Call it with', 'Plan']);
+}
+
+function planGuidance(selected, plans = {}) {
+  const lines = selected.filter((a) => plans[a.id]).map((a) => {
+    const p = plans[a.id];
+    const volume = p.headroom === 'base'
+      ? 'Keep this base-headroom lane for short second opinions. If it is primary, delegate volume to high or max headroom lanes.'
+      : 'Use this high or max headroom lane for volume: scoped well-specified builds, pre-ship second-family checks through cli-run, and first-pass research.';
+    return `- **${a.name}: ${p.name} (${p.headroom} headroom).** ${volume} Capability and independent-review rules are unchanged. Checked ${p.checked}.`;
+  });
+  return lines.length ? lines.join('\n') : 'State subscription plans with `--plans` to receive volume-allocation guidance. Capability and independent-review rules stay unchanged.';
 }
 
 export function installTable(selected) {
@@ -398,6 +410,7 @@ export function proofSteps(opts) {
 
 function vars(opts) {
   const { level, selected, primary } = opts;
+  const plans = opts.plans || {};
   const tools = opts.tools || [];
   const apis = opts.apis || [];
   const lvl = LEVELS.find((l) => l.id === level);
@@ -506,7 +519,8 @@ function vars(opts) {
     PRIMARY_FAST: primary && primary.models ? primary.models.fast : 'your cheapest model',
     AIS_LIST: selected.map((a) => '- ' + a.name + ': ' + a.role).join('\n'),
     AI_IDS: selected.map((a) => a.id).join(','),
-    LANES_TABLE: lanesTable(selected),
+    LANES_TABLE: lanesTable(selected, plans),
+    PLAN_GUIDANCE: planGuidance(selected, plans),
     INSTALL_TABLE: installTable(selected),
     CLI_RUN_LANES: selected.filter((a) => a.cliRun).map((a) => a.id).join(', ') || 'none selected',
     GATEWAY_MODELS: gatewayModels(selected, apis),
@@ -532,7 +546,14 @@ function vars(opts) {
     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)
+    TASK_BUNDLE_REL_JSON: JSON.stringify(taskBundleRel),
+    // route-gate.mjs takes a candidate list so the plugin bundle (src/plugin.js)
+    // can render the installer's default locations from the same template. An
+    // install knows its one rules file, and wrote it, so it needs no hint.
+    RULES_CANDIDATES_JSON: JSON.stringify([rulesFileRel]),
+    SETUP_HINT_JSON: JSON.stringify(''),
+    SETUP_NOTICE_JSON: JSON.stringify(''),
+    CONTEXT_SUFFIX_JSON: JSON.stringify('')
   };
 }
 
@@ -598,7 +619,7 @@ export function planFiles(opts) {
       JSON.stringify(
         {
           enabled: selected.filter((a) => a.cliRun).map((a) => a.id),
-          defaults: {},
+          defaults: Object.fromEntries((opts.effortAuto || []).map((lane) => [lane, { effort: 'auto' }])),
           note: 'Lanes cli-run may call. Edit to enable or disable a lane. A lane not listed here exits 13 (unavailable).',
           defaultsNote: 'Pin what a lane runs with, so the route in your docs is the route that runs: "defaults": {"codex": {"model": "gpt-6-astra", "effort": "high"}}. Left empty, a lane inherits its own config file, which cli-run cannot see and does not guess. `--model` and `--effort` override this per call, and `--doctor` prints what each lane is pinned to. Every lane takes a model; every lane except qwen takes an effort.'
         },
@@ -633,6 +654,8 @@ export function planFiles(opts) {
           primary: primary ? primary.id : null,
           tools: (opts.tools || []).map((t) => t.id),
           apis: (opts.apis || []).map((p) => p.id),
+          ...(Object.keys(opts.plans || {}).length ? { plans: Object.fromEntries(Object.entries(opts.plans).sort(([a], [b]) => a.localeCompare(b)).map(([id, p]) => [id, p.id])) } : {}),
+          ...((opts.effortAuto || []).length ? { effortAuto: [...opts.effortAuto].sort() } : {}),
           dir: resolve(opts.dir || 'ai-orchestrator'),
           project: resolve(opts.project || process.cwd()),
           files: fileHashes,

package/src/plugin.js

@@ -0,0 +1,83 @@
+// The Claude Code plugin bundle under plugin/. Every file this plans is
+// generated from the templates the installer renders, so the plugin carries
+// no second copy of an agent or a hook: `npm run gen:plugin` writes them and
+// test/plugin.test.js fails when the committed bundle drifts from this plan.
+// plugin/README.md and plugin/hooks/hooks.json are plugin-only and hand-owned.
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { render } from './render.js';
+import { TEMPLATES, GENERATOR_VERSION, claudeAgentIds } from './install.js';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+export const ROOT = join(HERE, '..');
+export const PLUGIN_DIR = join(ROOT, 'plugin');
+export const PLUGIN_NAME = 'model-orchestrator';
+export const REPO_URL = 'https://github.com/aunysillyme/model-orchestrator';
+
+// The installer's default --dir, and the rules file each level writes there:
+// ROUTING.md at level 2 and 3, ORCHESTRATOR.md at level 1. Level 2 first, so
+// a project that moved up a level reads the newer file.
+export const DEFAULT_RULES = ['ai-orchestrator/ROUTING.md', 'ai-orchestrator/ORCHESTRATOR.md'];
+export const DEFAULT_TASK_BUNDLE = 'ai-orchestrator/TASK_BUNDLE.md';
+
+// route-metrics.mjs is not here on purpose: it appends a routing log to disk,
+// and the plugin ships only hooks that read. `npx model-orchestrator` still
+// installs it.
+export const PLUGIN_HOOKS = ['route-gate.mjs', 'subagent-context.mjs'];
+
+// Files in plugin/ that are written by hand, not by planPluginFiles().
+export const HAND_OWNED = ['README.md', 'hooks/hooks.json'];
+
+export function pluginVars() {
+  return {
+    PRIMARY_NAME: 'Claude Code',
+    RULES_FILE_REL: DEFAULT_RULES.join(' or '),
+    RULES_FILE_REL_JSON: JSON.stringify(DEFAULT_RULES[0] + ' (' + DEFAULT_RULES[1] + ' on a level 1 install)'),
+    TASK_BUNDLE_REL_JSON: JSON.stringify(DEFAULT_TASK_BUNDLE),
+    RULES_CANDIDATES_JSON: JSON.stringify(DEFAULT_RULES),
+    SETUP_HINT_JSON: JSON.stringify(
+      'This project has no model-orchestrator routing rules yet. Running `npx model-orchestrator` in the project root writes them (' +
+        DEFAULT_RULES[0] +
+        '), and this hook reads them from the next prompt on. Until then, pick the lane yourself, and name that command if the user asks about routing.'
+    ),
+    SETUP_NOTICE_JSON: JSON.stringify(
+      'model-orchestrator: this project has no routing rules yet, so the plugin has no routing table to inject. Run `npx model-orchestrator` in the project root to write them; the plugin reads them from your next prompt.'
+    ),
+    CONTEXT_SUFFIX_JSON: JSON.stringify(
+      '\nThe model-orchestrator plugin installs the agents named above as model-orchestrator:<name>, for example model-orchestrator:builder.'
+    )
+  };
+}
+
+export function pluginManifest() {
+  const n = claudeAgentIds().length;
+  return {
+    name: PLUGIN_NAME,
+    version: GENERATOR_VERSION,
+    description:
+      'Routing for Claude Code: a hook injects your project\'s routing table on every prompt, so each task goes to the right subagent tier and fewer tokens go to the most expensive model. Ships ' +
+      n +
+      ' subagents across three model tiers.',
+    author: { name: 'model-orchestrator maintainers', url: REPO_URL },
+    homepage: REPO_URL + '#readme',
+    repository: REPO_URL,
+    license: 'MIT',
+    keywords: ['routing', 'subagents', 'hooks', 'model-router', 'token-optimization', 'delegation']
+  };
+}
+
+// Pure: reads templates, writes nothing. Paths are posix, relative to plugin/.
+export function planPluginFiles() {
+  const v = pluginVars();
+  const files = [];
+  files.push({ rel: '.claude-plugin/plugin.json', content: JSON.stringify(pluginManifest(), null, 2) + '\n' });
+  for (const id of claudeAgentIds()) {
+    files.push({ rel: 'agents/' + id + '.md', content: render(readFileSync(join(TEMPLATES, 'agents', 'claude-code', id + '.md'), 'utf8'), v) });
+  }
+  for (const hook of PLUGIN_HOOKS) {
+    files.push({ rel: 'hooks/' + hook, content: render(readFileSync(join(TEMPLATES, 'agents', 'snippets', hook), 'utf8'), v) });
+  }
+  files.push({ rel: 'LICENSE', content: readFileSync(join(ROOT, 'LICENSE'), 'utf8') });
+  return files;
+}

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

@@ -14,3 +14,5 @@ One per tier, plus two checks and two agents with no file-editing tools: `findin
 | 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. 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.
+
+Every agent names its tools explicitly, so none inherits every tool the session has: `builder` carries `Read, Write, Edit, Glob, Grep, Bash` (it changes files and runs checks), `deep-planner` carries `Read, Glob, Grep` (it plans and never edits), and `live-researcher` carries `WebSearch, WebFetch` (it answers from the web, not local files). The same files ship in the Claude Code plugin under `plugin/agents/`, generated from this folder.

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

@@ -1,6 +1,7 @@
 ---
 name: builder
 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.
+tools: Read, Write, Edit, Glob, Grep, Bash
 model: sonnet
 effort: high
 ---

package/templates/agents/claude-code/deep-planner.md

@@ -1,6 +1,7 @@
 ---
 name: deep-planner
 description: Ambiguous or high-stakes thinking. Use for architecture design, strategy, planning multi-step projects, hard debugging where the cause is unknown, and any "figure out what to even do" request. Do not use for well-specified execution or bulk work.
+tools: Read, Glob, Grep
 model: opus
 effort: xhigh
 ---

package/templates/agents/claude-code/live-researcher.md

@@ -1,6 +1,7 @@
 ---
 name: live-researcher
 description: Real-time information. Use for anything that needs current data such as latest news, current API docs or pricing, or recent events. Do not use for questions answerable from local files or general knowledge.
+tools: WebSearch, WebFetch
 model: sonnet
 effort: medium
 ---

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

@@ -14,36 +14,93 @@
 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}};
+// One template, two renders. The installer renders a one-element list from
+// the level and directory the user chose: a level 1 install points it at
+// ORCHESTRATOR.md, level 2+ at ROUTING.md, and a --dir outside the project
+// resolves to an absolute path instead of a relative one. The Claude Code
+// plugin (plugin/, generated by scripts/gen-plugin.js) has no install step to
+// render from, so it lists the installer's default locations and reads the
+// first one that exists.
+const RULES_CANDIDATES = {{RULES_CANDIDATES_JSON}};
+const RULES_FILE_REL = RULES_CANDIDATES.join(' or ');
+// Empty in an installer render, whose rules file was written by the same run.
+// The plugin renders a next step for a project that has no rules yet, so a
+// missing file is never a silent no-op: SETUP_HINT goes to the model on every
+// prompt, SETUP_NOTICE to the user once, at session start.
+const SETUP_HINT = {{SETUP_HINT_JSON}};
+const SETUP_NOTICE = {{SETUP_NOTICE_JSON}};
+// Appended after the table. Empty in an installer render.
+const CONTEXT_SUFFIX = {{CONTEXT_SUFFIX_JSON}};
+// Passed only by the plugin's SessionStart entry in hooks/hooks.json.
+const SESSION_START = process.argv.includes('--session-start');
 
 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
+// Bounded output, whatever produced it. The table is capped above, but a
+// fallback or missing-rules message embeds resolved paths and error text
+// whose length the project directory controls, and Claude Code caps hook
+// output strings at 10,000 characters. Every string this hook emits passes
+// through bound().
+const MAX_OUTPUT = 8000;
 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 bound(text) {
+  return text.length > MAX_OUTPUT ? text.slice(0, MAX_OUTPUT - 3) + '...' : text;
+}
+
 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;
+function projectRoot() {
   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);
+    return realpathSync(projectDir);
   } catch {
-    /* keep the unresolved value; the read below reports the real failure */
+    return projectDir; // keep the unresolved value; the read below reports the real failure
   }
-  return join(root, RULES_FILE_REL);
+}
+
+function resolveRulesPath(rel, root) {
+  if (isAbsolute(rel)) return rel;
+  return root ? join(root, rel) : null;
+}
+
+// ENOENT and ENOTDIR mean "nothing here, try the next candidate". Anything
+// else (a directory, a FIFO, a permission error) means something IS at that
+// path, so it is chosen and readBounded reports the real problem, rather than
+// this hook quietly reading a different file than the one the project has.
+function present(path) {
+  try {
+    statSync(path);
+    return true;
+  } catch (e) {
+    const code = e && e.code;
+    return !(code === 'ENOENT' || code === 'ENOTDIR');
+  }
+}
+
+// { path } to read, { error } when the rules cannot be located at all, or
+// { missing } (every path looked at) when a multi-candidate render finds
+// nothing. A one-candidate render never returns { missing }: it keeps the
+// installer's original behaviour exactly, and the read reports what is wrong.
+function locateRules() {
+  const root = projectRoot();
+  const paths = [];
+  for (const rel of RULES_CANDIDATES) {
+    const p = resolveRulesPath(rel, root);
+    if (!p) return { error: 'CLAUDE_PROJECT_DIR is not set, so ' + RULES_FILE_REL + ' could not be located' };
+    paths.push(p);
+  }
+  if (paths.length === 1) return { path: paths[0] };
+  const found = paths.find(present);
+  return found ? { path: found } : { missing: paths };
 }
 
 // Bounded, regular-file-only read. statSync (not lstatSync) follows a
@@ -76,21 +133,31 @@ function readBounded(path) {
 }
 
 function computeContext() {
-  const path = resolveRulesPath();
-  if (!path) return fallback('CLAUDE_PROJECT_DIR is not set, so ' + RULES_FILE_REL + ' could not be located');
+  const loc = locateRules();
+  if (loc.error) return fallback(loc.error);
+  if (loc.missing) return 'route-gate: no routing rules file at ' + loc.missing.join(' or ') + '. ' + SETUP_HINT;
 
   let text;
   try {
-    text = readBounded(path);
+    text = readBounded(loc.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');
+  if (s === -1 || e === -1) return fallback(loc.path + ' has no route-gate block');
+
+  return text.slice(s, e + END.length).slice(0, MAX_CONTEXT) + CONTEXT_SUFFIX;
+}
 
-  return text.slice(s, e + END.length).slice(0, MAX_CONTEXT);
+// The message a person sees at session start, or null when there is nothing
+// to say: an installer render (no notice), rules that exist, or a project
+// root that cannot be located.
+function sessionStartNotice() {
+  if (!SETUP_NOTICE) return null;
+  const loc = locateRules();
+  return loc.missing ? SETUP_NOTICE : null;
 }
 
 // Drain stdin without ever blocking on it. A bare `readFileSync(0)` waits
@@ -130,20 +197,35 @@ function drainStdin(timeoutMs) {
   });
 }
 
-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({
+let payload = null;
+if (SESSION_START) {
+  let notice = null;
+  try {
+    notice = sessionStartNotice();
+  } catch {
+    notice = null; // a session-start notice is a courtesy; never fail a session over it
+  }
+  if (notice) payload = JSON.stringify({ systemMessage: bound(notice) });
+} else {
+  let additionalContext;
+  try {
+    additionalContext = computeContext();
+  } catch (err) {
+    additionalContext = fallback('route-gate.mjs failed unexpectedly (' + ((err && err.message) || err) + ')');
+  }
+  payload = JSON.stringify({
     hookSpecificOutput: {
       hookEventName: 'UserPromptSubmit',
-      additionalContext
+      additionalContext: bound(additionalContext)
     }
   });
+}
+
+drainStdin(STDIN_DRAIN_MS).then(() => {
+  if (payload === null) {
+    process.exit(0);
+    return;
+  }
   // 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.

package/templates/intermediate/CLI-RUN.md

@@ -19,6 +19,7 @@ Enabled lanes (edit `bin/lanes.json`): {{CLI_RUN_LANES}}
 node bin/cli-run.mjs <grok|codex|agy|hermes|qwen> "<prompt>" [--brief FILE] [--timeout SECS] [--quiet]
 node bin/cli-run.mjs codex --audit "<prompt>"                  # read-only sandbox, the audit shape
 node bin/cli-run.mjs codex "<prompt>" --model gpt-6-astra --effort high
+node bin/cli-run.mjs codex "<prompt>" --effort auto                 # medium or high, bounded heuristic
 node bin/cli-run.mjs qwen [--safe-mode] "<prompt>"             # qwen-only flag
 ```
 
@@ -98,6 +99,7 @@ Three rules that keep this honest:
 
 - **A level `cli-run` does not recognise is not rejected here.** Levels are the vendor's, they change, and guessing the valid set would date this tool. An unknown level is refused by the lane and surfaces as that lane's own exit code and stderr.
 - **`--effort` on qwen is a usage error, not a silent drop.** A flag that vanishes leaves you believing a route that never ran.
+- **`--effort auto` is bounded.** It uses prompt size, or an audit's changed-file evidence, and resolves only medium or high. An audit is always high. Auto is a heuristic, not a measurement: name `xhigh` explicitly for security-critical or irreversible work.
 - **Values are charset-bounded** (letters, digits, and `. _ : @ / + -`, no leading dash, 64 characters). A model id becomes an argv element and, on codex, part of a TOML value; bounding it is what stops either from being escaped.
 
 ## Permissions are a separate layer
@@ -106,7 +108,7 @@ Three rules that keep this honest:
 
 ## Log
 
-`~/.ai-orchestrator/cli-run.log.jsonl`, one line per run: lane, verdict, rc, the lane's own exit code, signal, seconds, raw bytes, deliverable bytes, a 12-hex sha256 prefix of the prompt and its length, the route (`model_requested`, `effort_requested`, and `model_source` / `effort_source`, each one of `flag`, `lanes.json` or `lane_default`), and `reason`: one of a fixed set of codes (`ok`, `not_json`, `bad_stop_reason`, `empty_text`, `no_terminal_event`, `bad_status`, `api_error_in_result`, `total_errors`, `contract_unmet`, `exit_nonzero`, `timeout`, `killed`, `disabled`, `lanes_json_malformed`, ...). Never the prompt text, never a provider-supplied value, never free text: a value the log does not recognise is written as `unknown`. The human-readable detail, which may quote the provider, goes to your terminal only (and nowhere with `--quiet`). "This lane is flaky" becomes a query instead of an argument, and so does "we route audits at high effort".
+`~/.ai-orchestrator/cli-run.log.jsonl`, one line per run: lane, verdict, rc, the lane's own exit code, signal, seconds, raw bytes, deliverable bytes, a 12-hex sha256 prefix of the prompt and its length, the route (`model_requested`, `effort_requested`, and `model_source` / `effort_source`, each one of `flag`, `lanes.json` or `lane_default`), auto-sizing evidence (`effort_resolved`, `effort_basis`, `effort_scope`), and `reason`: one of a fixed set of codes (`ok`, `not_json`, `bad_stop_reason`, `empty_text`, `no_terminal_event`, `bad_status`, `api_error_in_result`, `total_errors`, `contract_unmet`, `exit_nonzero`, `timeout`, `killed`, `disabled`, `lanes_json_malformed`, ...). `effort_basis` is exactly one of `explicit`, `prompt_chars`, `audit_floor`, or `none`. Never the prompt text, never a provider-supplied value, never free text: a value the log does not recognise is written as `unknown`. The human-readable detail, which may quote the provider, goes to your terminal only (and nowhere with `--quiet`). "This lane is flaky" becomes a query instead of an argument, and so does "we route audits at high effort".
 
 The log records what was **requested**, on every record including a run refused before the lane started. It does not record an actual. Reporting is inconsistent: grok returns a `modelUsage` block naming a model, the other four lanes return nothing of the kind, so an `actual` field would be populated for one lane and empty for four. It would also be a provider-supplied string, and this log holds fixed codes and bounded caller-supplied values only. `model_source: "lane_default"` is the honest way to say this run inherited something invisible from here.
 

package/templates/intermediate/DELEGATION_MATRIX.md

@@ -6,6 +6,10 @@ Generated {{DATE}} from the AIs you said you have: `{{AI_IDS}}`.
 
 {{LANES_TABLE}}
 
+## Plan guidance
+
+{{PLAN_GUIDANCE}}
+
 ## Task → lane
 
 | Task type | Pick | Why |

package/templates/intermediate/ROUTING.md

@@ -6,6 +6,10 @@ Your lanes:
 
 {{LANES_TABLE}}
 
+## Plan guidance
+
+{{PLAN_GUIDANCE}}
+
 Two kinds of lane. **Lane A** = subscription CLIs: $0 marginal, already paid for, used for interactive and agentic work. **Lane B** = metered APIs: per token, used for programmatic bulk where a subscription CLI cannot serve. **Local** = stays on the machine; a privacy lane, never a cost lane.
 
 Rule of thumb: never spend a frontier token on a task a cheap tier finishes correctly. Escalate on signal (low confidence, explicit complexity, a failed verification), not by default. And an external lane must earn the hop with a real strength; when in doubt, stay in-house.

package/templates/intermediate/TIERS.md

@@ -15,6 +15,8 @@ Non-primary lanes are owned by `DELEGATION_MATRIX.md`.
 
 Tier sets the price per token. Token discipline sets how many tokens. **Effort sets how hard each call thinks.**
 
+`cli-run --effort auto` is a heuristic, not a measurement: prompts below 4,000 characters resolve to medium and longer prompts resolve to high. A codex `--audit` always resolves to high because stakes set the floor. Auto never resolves above high. Name `xhigh` explicitly for a security-critical or irreversible audit.
+
 | Agent | Tier | Effort | Why |
 |---|---|---|---|
 | deep-planner | deep | xhigh | judges every build twice; expensive to get wrong |