# PLAN — model-router wave 1-A: the mod (dispatch-ready) — REVISED r3

r3 changes (confirmation pass, 4 MAJOR + minors): explicit Agent params are
frozen on the Loop and never overridden by in-agent `route`/`Skill(effort-*)`;
`pendingPrompt` honours `e.wait`; tests assert on the `main:` line of `show`
only, with full typed inputs; haiku gets `effort: undefined`; `userMain`
beats every turn route including a typed `/effort-<l>` (the text says so);
`skill.prompt` acts only when no Skill call is in flight; route tool handles
`clear` first and answers "off" in place; `turn.step` catch is a generator;
windows keyed by resolved id; validate user entries BEFORE merging; truthful
answers; unpinned-skill reset accepted and documented.
Contract: .claude/tasks/contracts/2026-10-08-model-router-w1a-1533.md
Wave plan + harness facts: .claude/tasks/plans/2026-10-08-model-router-mod.md
Base: the spike `~/.claude/dev-mods/385f7190-70f5-4bdd-b0d8-e4566cd412fd/model-router/hooks/register.ts`
(read it first; keep its proven hook shapes; drop its spike levers `via`,
`stepModel`, `agentsDefault`, the tool's `model`/`scope`/`mainModelSwitch`
params and the hardcoded PHASES).
API reference: `<spike>/.claude-plugin/types/claude-code/index.d.ts` (grep the
event or noun; `declare module 'claude-code/testing'` for the test kit) and
`<spike>/.claude-plugin/types/claude-code-tools/index.d.ts` (`Skill: {`,
`Agent: {`, and the Skill RESULT schema near line 5139).

r2 changes (challenge round, 3 lenses): agents table = built-ins only; one
writer per agent model (spawn), no per-step model rewrite unless an in-agent
`route` call changed it and the engine did not fall back; every write goes
to the CALLING loop; `agentsNext` / `scope` / `/route agents` / tool `model`
dropped; Skill bridge answers in the tool's output shape; unconditional
skill-load reset (prompt route kept); config validated at load, refs
resolved once; state in the `register` closure, cloned defaults; `/route off`
kill switch; queued `ultrathink` promoted to its own turn; AC1/AC5 amended.

## Files
- [ ] mods/model-router/.claude-plugin/plugin.json — `{ "name": "model-router", "version": "0.1.0", "description": "<one line>", "author": { "name": "bchanot" } }`
- [ ] mods/model-router/hooks/hooks.json — `{ "modules": ["./register.ts"] }`
- [ ] mods/model-router/hooks/register.ts — the hooks module (below)
- [ ] mods/model-router/hooks/register.test.ts — `claude plugin test` suite (below)
The engine lays `./tsconfig.json` and `.claude-plugin/types/` beside a loaded
mod; both are ignored by AC1 and gitignored in wave 1-B. Never commit them.

## Config (one shape, defaults in code, optional override on disk)
```ts
type Level = 'low' | 'medium' | 'high' | 'xhigh' | 'max'
type Route = { model?: string; effort?: Level }   // model = alias OR full id
type Config = {
  models: Record<string, string>      // alias → full id
  windows: Record<string, number>     // alias → context window (tokens)
  phases: Record<string, Route>
  agents: Record<string, string>      // built-in subagentType → phase name
  skills: Record<string, string>      // skill name → phase name
  prompt: { pattern: string; phase: string }[]   // regex source, flag i
  mainModelSwitch: boolean; verbose: boolean; spinner: boolean
}
```
DEFAULT_CONFIG values:
- models: haiku→`claude-haiku-4-5-20251001`, sonnet→`claude-sonnet-5-5`,
  opus→`claude-opus-5-5`, fable→`claude-fable-5-1`.
- windows: `claude-haiku-4-5-20251001`→200000 (keyed by FULL id; others
  unknown: absent = no check).
- phases: plan {effort xhigh}, reflect {effort high}, orchestrate {effort medium},
  escalate {effort max}, judge {opus, xhigh}, implement {sonnet, medium},
  write {sonnet, medium}, verify {sonnet, xhigh}, explore {sonnet, medium},
  mechanical {haiku, low}. A phase without `model` keeps the loop's model.
- agents: Explore→explore, Plan→judge. NOTHING else in wave 1: every repo
  agent keeps its frontmatter pin (the engine applies it); the pins move into
  this table in wave 2, in the same change that deletes the frontmatter.
- skills: {} (wave 2 fills it).
- prompt: [{ pattern: '\\bultrathink\\b', phase: 'escalate' }].
- mainModelSwitch false, verbose false, spinner true. (Pass B, user
  2026-10-08: verbose default off but ON for now through the override file,
  spinner on, user `/route` sticky, Explore → sonnet/medium.)

`loadConfig($, log)` → `Config` (never throws):
1. `home = await $.env.get('HOME')`; path `${home}/.claude/model-router.json`;
   `$.fs.exists` then `$.fs.read`; `JSON.parse`. Any failure → the defaults.
2. `mergeConfig(D, u, log)`: FIXED merge, no recursion, VALIDATE EACH USER
   ENTRY BEFORE IT REPLACES A DEFAULT (an invalid user `models.sonnet` is
   dropped and the default kept, so the phases on `sonnet` stay valid):
   for each table (`models`, `windows`, `phases`, `agents`, `skills`) take
   `u.<table>` only when it is a plain object, then per key: valid → over
   the default, invalid → `log(...)` and keep the default. Scalars
   (`mainModelSwitch`, `verbose`, `spinner`) taken only when boolean.
   `prompt` taken only when an array; each rule validated or dropped.
   Type guards on `unknown`, no `any`.
3. Validity rules (`log(...)` ALWAYS, not only verbose: a config error must
   be seen once):
   - models value: string matching `/^claude-[a-z0-9.-]+$/`;
   - windows: key a full id (same regex), value a positive integer;
   - phase: plain object; `effort` absent or in LEVELS; `model` absent, a
     `models` key or a full id; at least one of the two;
   - agents / skills value: a phase name (checked after phases merged);
   - prompt rule: `{ pattern: string, phase: <phase name> }` whose pattern
     compiles (`new RegExp(p, 'i')` in try/catch).
   Lookups use `Object.hasOwn`, never bare indexing on user keys.
4. Returns `structuredClone`d data: the defaults constant is never handed
   out by reference.
`compileRules(cfg)` → `{ re: RegExp; phase: string }[]` once per load.
`resolveModel(cfg, name)`: `Object.hasOwn(cfg.models, name) ? cfg.models[name] : name`.
`isModelName(cfg, v)`: a `models` key or the full-id regex. `isLevel(v)`.

## State — ONE object built inside `register`, passed to every helper
```ts
type Source = 'user' | 'model' | 'skill' | 'prompt' | 'slash'
type Routed = { phase: string; route: Route; source: Source }
type Loop = {
  effort?: Level; model?: string      // routed by the table or an in-agent call
  spawnModel: string; frozen: boolean // engine's model at spawn; fork/workflow
  explicitModel: boolean; explicitEffort: boolean // Agent params given → axis frozen
}
type State = {
  cfg: Config; rules: Rule[]
  userMain: Routed | null      // /route by the user; sticky until /route clear
  turnMain: Routed | null      // tool / skill / prompt / slash; dropped at turn end
  pendingPrompt: Routed | null // prompt rule typed mid-turn, promoted next turn
  loops: Map<string, Loop>     // agentId → that loop's routing
  explicitEffort: Map<string, Level>  // Agent tool_use_id → explicit effort param
  skillCalls: number           // Skill tool calls in flight (hook 4 ± around next)
  off: boolean                 // /route off: every hook passes through
  lastMain: string             // "model/effort" of the last main step (spinner)
}
```
`newState(cfg)` builds it; `register` calls it once; `session.start` reloads
`cfg` + `rules` into it; `session.end` rebuilds it (`/clear` fires no
`session.start`, so sticky routes must not survive a clear).
Effective main route `mainRoute(st)`: `st.userMain ?? st.turnMain`. ONE
order, transitive: user `/route` (sticky) > the latest turn route (tool,
skill, slash, prompt all share `turnMain`; last writer wins) > session. A
typed `/effort-<l>` while a sticky route is in force does not apply; its
text says so (hook 5).
Loop lookups: `loopOf(st, e.agentId)`; a missing entry is created on first
write as `{ spawnModel: '', frozen: false, explicitModel: false,
explicitEffort: false }`. In-agent writes (hooks 3 and 4) never set an axis
whose `explicit*` flag is true: an explicit Agent param wins for the whole
run.

## Hooks
Rule for failures: hooks that only observe or rewrite carry
`.catch(($, e, next) => next(e))`; `turn.step` streams, so its catch is the
generator form `async function* ($, e, next) { return yield* next(e) }` (a
plain function there is a type error). The four hooks that ANSWER without `next`
(command.run, the route tool, the Skill `effort-*` bridge, `skill.prompt`)
carry a `.catch` that answers in place: `{ text: 'route failed (<kind>)' }`,
`{ result: 'route failed (<kind>); nothing routed' }`, and for the two skill
hooks `next(e)` (the skill then loads normally — a safe fallback). State is
mutated only AFTER the input validated.
1. `session.start`: `st.cfg = await loadConfig(...)`, `st.rules = compileRules`;
   `registerTool($, st)` (`$.tool.register({ name: 'route', description,
   inputSchema })`: properties `phase` (enum = Object.keys(st.cfg.phases)),
   `effort` (enum LEVELS), `clear` (boolean); no `required`). The description
   tells the model: declare the phase before a span changes nature; acts on
   the calling loop only; no model choice here. `$.command.register({ name:
   'route', description, argumentHint: '[show|clear|off|on|reload|<phase>|
   model=<alias|id> effort=<level>|switch on|off|verbose on|off]', immediate:
   true })` in try/catch (log on failure, keep going). `$.ui.status(statusLine(st))`.
2. `command.run {command:'route'}` → `{ text: handleCommand($, st, e.args) }`:
   `show`/empty → `show(st)`; `clear` → userMain = turnMain = pendingPrompt =
   null; `off` / `on` → st.off; `reload` → loadConfig + compileRules +
   `registerTool` again (the phase enum follows the config) + 'config
   reloaded' + show; `switch on|off` → cfg.mainModelSwitch; `verbose on|off`;
   otherwise `parseRoute(st.cfg, args)`: a phase name, or tokens `model=<m>`
   / `effort=<l>` / bare alias / bare level, each validated by `isModelName`
   / `isLevel` → `st.userMain = { phase, route, source: 'user' }`; any
   unknown token → error text listing the phases and the levels. Never
   calls `next`.
3. `tool.call {tool:'mcp__model-router__route'}` → `handleRouteTool`, in
   this order: (i) `st.off` → `{ result: 'model-router is off (/route on to
   resume); nothing routed' }`; (ii) `clear` → main: `turnMain = null`; agent:
   unset the loop's `effort`/`model` → `{ result: 'route cleared for <loop>' }`;
   (iii) validate: `phase` given and not a `phases` key → `{ deny: 'unknown
   phase "<p>"; phases: …' }` (even with a valid `effort`); `effort` given and
   not a level → deny naming the levels; neither given → deny. (iv) route =
   `{ ...phases[phase], ...(effort ? { effort } : {}) }` (an explicit effort
   overrides the phase's). Target = the CALLING loop: main → `turnMain = {
   phase: phase ?? 'effort-' + effort, route, source: 'model' }`; agent →
   `loop.effort = route.effort` unless `loop.explicitEffort`; `loop.model =
   route.model` unless `loop.explicitModel` (applied at step only under the
   fallback guard, never on a frozen loop). (v) Answer on the EFFECTIVE
   outcome: main with a sticky `userMain` → `'recorded <phase> for this turn,
   but a sticky /route <userMain.phase> is in force; it wins until /route
   clear'`; otherwise `'routed <main|this agent> to <phase>: effort <level|
   unchanged>, model <resolved id|unchanged>'`, and when a model is part of
   the route on main while `mainModelSwitch` is off, say `model unchanged
   (switch off)`. Verbose → log.
4. `tool.call {tool:'Skill'}`:
   a. `e.skill` matches `/^effort-(low|medium|high|xhigh|max)$/` → the
      CALLING loop: main → `turnMain = { phase: e.skill, route: { ...st.turnMain?.route, effort }, source: 'skill' }`
      (effort merged over the current turn route, last loaded wins); agent →
      `loopOf(...).effort = level` unless `loop.explicitEffort` (entry created
      if missing: an untabled agent's shift must still land). Answer WITHOUT
      `next`, in the Skill tool's output shape (claude-code-tools ~5139; a
      string result is refused and the skill would load):
      `{ result: { success: true, commandName: e.skill, status: 'inline' },
         context: [<line>] }` where `<line>` states the effective outcome:
      `'model-router: effort → <l> for this loop from the next request on; the
      effort-<l> skill text was not loaded.'`, or when main has a sticky
      `userMain`: `'model-router: effort-<l> recorded, but a sticky /route
      <phase> is in force and wins until /route clear.'`, or when the agent
      axis is explicit: `'model-router: this agent was dispatched with an
      explicit effort; the shift does not apply.'`
   b. Any other skill: `st.skillCalls += 1` before `next(e)`, `-= 1` after
      (try/finally). Main → `turnMain = null` when its source is 'model',
      'skill' or 'slash' (a 'prompt' route such as `ultrathink` stays unless
      the skill has a table entry); `Object.hasOwn(cfg.skills, e.skill)` →
      `turnMain = { phase, route, source: 'skill' }`. Agent → unset the loop's
      non-explicit `effort`/`model`; table entry → `loop.effort = route.effort`
      unless explicit (never model). Accepted change vs the legacy shifters:
      loading an UNPINNED skill after a shift returns main to the harness
      level (orchestrators already re-assert after a nested skill,
      lib/effort-shift.md § Re-assert). Then `return next(e)`.
5. `skill.prompt {skill: /^effort-/}`: `st.skillCalls > 0` (reached through
   the bridge's fallback or a Skill call) → `next(e)`. Otherwise it is a
   user-typed `/effort-<l>` (or a preload, unsupported: treated the same):
   level parse; `turnMain = { phase: e.skill, route: { effort }, source:
   'slash' }`; return `{ text: <line> + '\n' + e.text }` (prepend, never
   replace: args ride in the text) where `<line>` is `'Effort shifted to <l>
   by model-router for this turn.'` or, with a sticky `userMain`, `'Effort
   <l> recorded; the sticky /route <phase> wins until /route clear.'`.
   Unknown suffix → `next(e)`.
6. `tool.call {tool:'Agent'}`: `isLevel(e.effort) && typeof e.tool_use_id ===
   'string'` → `st.explicitEffort.set(e.tool_use_id, e.effort)`; always
   `return next(e)` unchanged (params are never rewritten).
7. `agent.spawn`: `frozen = e.fork || e.workflow !== undefined`. Route:
   `!frozen && e.provider.plugin === 'engine' && Object.hasOwn(cfg.agents, e.subagentType)`
   → `cfg.phases[cfg.agents[e.subagentType]]`, else none. Model rewrite ONLY
   when route?.model is set AND `e.model === undefined` (an explicit param
   wins): `next({ ...e, model: resolveModel(cfg, route.model) })`, else
   `next(e)`. On a non-deny result with `agentId`: `loops.set(agentId, {
   spawnModel: result.model, frozen, explicitModel: e.model !== undefined,
   explicitEffort: given !== undefined, effort: given ? undefined : route?.effort })`
   where `given = explicitEffort.get(e.tool_use_id)` (then deleted). `model`
   is NOT stored at spawn: the engine already runs the agent on it. Verbose
   log `spawn <type>: <e.model ?? '-'> → <result.model>`. Known limit,
   documented in a comment: `provider.plugin === 'engine'` is the best
   available test for a built-in at spawn; a user agent named `Explore` in a
   foreign project would also match (wave 1 impact: sonnet/medium on it).
8. `turn.step` (async generator). `st.off` → log when verbose, `yield* next(e)`.
   Agent loop (`e.agentId`): `loop = loops.get(...)`; `effort = loop?.effort ??
   e.effort`; `model = loop?.model && !loop.frozen && e.model === loop.spawnModel
   ? resolveModel(cfg, loop.model) : e.model` (an engine fallback — `e.model`
   differs from the spawn model — is never fought). Main: `set = mainRoute(st)`;
   `effort = set?.route.effort ?? e.effort`; `model = set?.route.model &&
   cfg.mainModelSwitch && windowOk ? resolved : e.model`, where `resolved =
   resolveModel(cfg, set.route.model)` and `windowOk` = no
   `cfg.windows[resolved]` entry (windows are keyed by FULL id; the defaults
   key haiku's full id) or `(await $.session.usage()).context.tokens` is a
   number below it; an absent `tokens` or a failed `usage()` → no switch,
   logged once per turn. If the model actually sent starts with
   `claude-haiku`, send `effort: undefined` (omit it entirely; haiku takes
   none and a hook-set effort on it is unproven). Main → `lastMain =
   '<model without claude->/<effort>'`, `$.ui.status(statusLine(st))`. Verbose →
   log before (`step <i> <loop>: <from> → <to>`) and after (`answered by
   <usage.model>`). `const r = yield* next(changed ? { ...e, model, effort } : e); return r`.
9. `prompt.submit`: `e.origin.kind !== 'composer'` → `next(e)`. First rule in
   `st.rules` whose `re.test(e.text)` → `routed = { phase, route, source: 'prompt' }`;
   `e.turnId !== undefined && e.wait` (typed mid-turn and asked to wait: it
   belongs to the NEXT turn) → `st.pendingPrompt = routed`; otherwise
   (idle, or delivered INTO the running turn) → `st.turnMain = routed`.
   `return next(e)`.
10. `turn.complete`: `e.agentId` → `loops.delete(e.agentId)`. Main →
    `turnMain = pendingPrompt; pendingPrompt = null; explicitEffort.clear();
    lastMain = ''`; `$.ui.status(statusLine(st))`. `return next(e)`.
11. `ui.render {component:'Spinner'}`: `cfg.spinner && lastMain` →
    `next({ ...e, props: { ...e.props, suffix: ' · ' + lastMain + '…' } })` else `next(e)`.
12. `session.end`: `Object.assign(st, newState(st.cfg))` (keeps the loaded
    config, drops every route and map). `return next(e)`.
`statusLine(st)`: `'route: ' + (st.off ? 'off' : describe(mainRoute(st)) )`
where `describe` = `'<source> <phase>'` or `'session defaults'`, plus
`' · switch on'` when `cfg.mainModelSwitch`.
`show(st)`: main (effective, with its source), off/on, switch, verbose,
spinner, live loops count, phases as `name=<resolved id|session>/<effort>`
(resolved ids printed, so a wrong `models` entry is visible), config source
line (`defaults` or the override path).

## Tests (register.test.ts, `import { test, expect } from 'claude-code/testing'`)
Read the kit's declarations first (`declare module 'claude-code/testing'`):
`test(name, async ($, on) => …)`; events are fired as calls on `$` with the
event's FULL input (the kit's `$` is `EngineCall<E> = (e: Args<E>)`, and
AC2 type-checks the test file): `$.command.run({ command: 'route', args:
'show', origin: { kind: 'composer' }, presentation: <a valid value from the
types> })`, `$.prompt.submit({ text: 'ultrathink please', wait: false,
origin: { kind: 'composer' } })`, `$.agent.spawn({ tool_use_id: 't1',
prompt: 'x', description: 'd', subagentType: 'Explore', provider: { plugin:
'engine', tier: 'core' }, parentModel: 'claude-fable-5-1', background: false,
fork: false })`, `$.tool.call({ tool: 'Skill', skill: 'effort-low' })`. Read
each input type and fill every required field; never relax a test to dodge
a type. Establish from the kit whether `session.start` fires at load; if
not, fire `$.session.start(...)` first in every test. An event whose hook
calls `next` needs a BOTTOM hook registered by the test through its `on`
(the kit's bottom throws otherwise), e.g. `on('prompt.submit', ($, e) => ({
text: e.text }))`, `on('agent.spawn', ($, e) => ({ model: e.model, agentId:
'a1' }))`. A helper `mainLine(text)` returns the `main:` line of `show`;
EVERY assertion on a route reads that line only (the phases listing always
contains every id and level, so matching the whole text proves nothing).
Tests (one per contract item 3a-3g):
- 3a `Skill(effort-low)` via `$.tool.call`: resolves with `result.success ===
  true` and `result.commandName === 'effort-low'`; a bottom `on('tool.call',
  { tool: 'Skill' })` registered by the test is NOT reached (flag); `mainLine`
  contains `skill effort-low` and `low`.
- 3b route tool `{ phase: 'orchestrate' }` → `mainLine` contains `model
  orchestrate` and `medium`.
- 3c `/route clear` → `mainLine` contains `session defaults`.
- 3d `/route bogus` → text contains `unknown` and every phase name.
- 3e `$.prompt.submit` with `ultrathink`, `wait: false`, no `turnId` →
  `mainLine` contains `prompt escalate`.
- 3f `/route model=sonnet` → `mainLine` contains `claude-sonnet-5-5`; `/route
  model=claude-x-9` → `mainLine` contains `claude-x-9`; `/route model=sonet` →
  text contains `unknown`.
- 3g spawn path: `$.agent.spawn(...)` for `Explore` without `model`, bottom
  hook captures `e.model === 'claude-sonnet-5-5'`; with `model: 'opus'` given
  → captured `e.model === 'opus'`.
No fs, network or process in tests: the defaults path is the one exercised.

## Edge cases
- `$.command.register` throws when `/route` is taken → log, keep the tool.
- `loadConfig` never throws out of `session.start`; invalid entries dropped with a log.
- `/clear` → `session.end` rebuilds the state; `/route reload` re-registers the tool.
- Remote agents raise no `turn.complete`; denied Agent calls never spawn: both
  maps are bounded by `explicitEffort.clear()` at main turn end and `loops`
  entries only for started agents (a leak of a few entries per turn is accepted).
- `loops.delete` at an agent's `turn.complete`: a resumed agent (SendMessage,
  woken teammate) runs its later turns at the engine's effort. Accepted in
  wave 1 (built-ins only); revisit with the pins in wave 2.
- Spawn-vs-first-step race: the loop entry is set after `next(e)` resolves,
  so step 0 of a tabled built-in may run at the engine's effort. Accepted in
  wave 1 (Explore/Plan only); wave 2 verifies the ordering before pins move.
- Unpinned agents (general-purpose, interviewer, client-handover-writer) no
  longer inherit a shifted level: the bridge does not move the harness
  level. Accepted: BDR-077 already requires explicit call-site params for
  built-ins; the two inline-load agents run on main's own route.
- The word `any` must not appear as a TypeScript type in register.ts
  (AC5 greps `: any`, `<any>`, `as any`).

## Disposition (STEP 0.6)
- honors BDR-066/076/077 (tiers): wave 1 touches only the two built-ins that
  carry no pin (Explore sonnet/medium, Plan opus/xhigh); every repo agent
  keeps its frontmatter as the single writer; explicit call-site params win.
- honors BDR-107/108: levels and aliases unchanged; aliases stay the config's
  vocabulary, full ids are resolved by the mod (LRN-203, BLK-029).
- LRN-180/181 made moot: the bridge answers `Skill(effort-*)` itself, no
  pairing rule. "Last loaded wins" holds among pinned skills and shifts; the
  one behaviour change, accepted: loading an UNPINNED skill after a shift
  returns main to the harness level (orchestrators re-assert after nested
  skills already, lib/effort-shift.md § Re-assert).
- LRN-204: main-loop model switch behind `mainModelSwitch` (default false) and
  a context-window guard.
- BDR-044 not contradicted: the mod routes model/effort, never skills.
- Deferred (minor, challenge r1): a ceiling on model-declared efforts; the
  spawn-vs-step race.