model-orchestrator 0.1.18 → 0.1.20

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,39 @@ All notable changes to this project are documented here. The format follows [Kee
 
 ## [Unreleased]
 
+## [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
+
+- **The `route-gate.mjs` non-regular-file guard is now tested on every OS, not only where `mkfifo` exists.** The FIFO test is the only one that can prove the HANG the guard exists to prevent (a naive `readFileSync` on a writer-less FIFO blocks forever), and Windows has no `mkfifo` to build one, so that test was skipped there and nothing exercised `!st.isFile()` on Windows at all. A directory at the same rules path reaches the same guard before any `open` or `read` call, on every OS, so the guard itself is covered everywhere and the win32 skip is no longer its only coverage.
+- **A guard that refuses an undocumented test skip.** `test/prose.test.js` pins each skip to its file, its exact marker and a phrase the README has to carry, then counts every `{ skip:` in the suite and fails if the totals disagree. Proved in both directions: adding a skip anywhere fails it, and removing a skip's explanation from the README fails it.
+
+### Fixed
+
+- **The README's Windows skip list named three of the four skips.** The `mkfifo` skip in `test/hooks.test.js` had never been documented, in the README or the changelog, while the sentence above it read "a few narrow skips remain" and enumerated the rest. A skipped test reads as a test that passed, so an undocumented skip is a coverage claim nobody made deliberately. All four are named now, the conditional `statSync().mode` assertion is labelled as the one-assertion case it is rather than a skipped test, and the sentence says outright that the list is enforced by a test rather than maintained by hand.
+
 ## [0.1.18] - 2026-09-11
 
 ### Fixed
@@ -282,7 +315,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.18...HEAD
+[Unreleased]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.20...HEAD
+[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
 [0.1.16]: https://github.com/aunysillyme/model-orchestrator/compare/v0.1.15...v0.1.16

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.
@@ -90,6 +91,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 +134,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 +278,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). A few narrow skips remain on Windows, each for a POSIX behavior the OS or the CI shell genuinely does not have: `statSync().mode`'s executable bit (NTFS has none), a lane dying mid-run from a real POSIX signal (a real Windows lane cannot die "by signal"), and 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).
+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.
 
 **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/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,6 +18,7 @@ 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
 - [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "model-orchestrator",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "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-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/install.js

@@ -532,7 +532,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('')
   };
 }
 

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.