@alexeiled/claude-router 1.23.1 → 1.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/CHANGELOG.md +62 -1
  3. package/README.md +39 -7
  4. package/docs/architecture.md +27 -4
  5. package/docs/auto-engine.md +152 -0
  6. package/docs/configuration.md +47 -3
  7. package/docs/evaluation.md +222 -3
  8. package/docs/native-router.md +11 -3
  9. package/docs/providers.md +28 -0
  10. package/docs/router-band.svg +124 -133
  11. package/docs/router-pane-classifier.svg +24 -23
  12. package/docs/router-pane-now.svg +9 -7
  13. package/docs/router-pane-policy.svg +4 -4
  14. package/docs/router-pane-routes.svg +8 -8
  15. package/docs/router-pane-usage-whatif.svg +14 -14
  16. package/docs/router-pane-usage.svg +20 -20
  17. package/docs/routing-modes.md +13 -4
  18. package/docs/user-guide.md +79 -19
  19. package/hooks/native-router.mjs +1194 -215
  20. package/lib/activity-stats.mjs +23 -4
  21. package/lib/activity.mjs +7 -5
  22. package/lib/auto-engine.mjs +414 -0
  23. package/lib/auto-route.mjs +253 -0
  24. package/lib/band.mjs +35 -440
  25. package/lib/classifier-client.mjs +12 -8
  26. package/lib/config-file.mjs +7 -2
  27. package/lib/config.mjs +64 -15
  28. package/lib/cost.mjs +5 -1
  29. package/lib/costs.mjs +4 -2
  30. package/lib/decisions.mjs +80 -5
  31. package/lib/display.mjs +69 -20
  32. package/lib/facts.mjs +30 -0
  33. package/lib/modes.mjs +8 -4
  34. package/lib/panel.mjs +75 -2163
  35. package/lib/policy.mjs +7 -6
  36. package/lib/providers.mjs +7 -0
  37. package/lib/replay-trace.mjs +550 -0
  38. package/lib/replay.mjs +718 -0
  39. package/lib/route-line.mjs +46 -0
  40. package/lib/route.mjs +35 -21
  41. package/lib/savings.mjs +14 -3
  42. package/lib/subagents.mjs +41 -11
  43. package/lib/subcommands.mjs +60 -0
  44. package/lib/ui/fallback.mjs +22 -0
  45. package/lib/ui/graphical/band.mjs +256 -0
  46. package/lib/ui/graphical/charts.mjs +163 -0
  47. package/lib/ui/graphical/classifier.mjs +153 -0
  48. package/lib/ui/graphical/frame.mjs +227 -0
  49. package/lib/ui/graphical/kit.mjs +156 -0
  50. package/lib/ui/graphical/meter.mjs +25 -0
  51. package/lib/ui/graphical/now.mjs +353 -0
  52. package/lib/ui/graphical/policy.mjs +56 -0
  53. package/lib/ui/graphical/routes.mjs +264 -0
  54. package/lib/ui/graphical/squares.mjs +29 -0
  55. package/lib/ui/graphical/usage.mjs +376 -0
  56. package/lib/ui/model/band.mjs +439 -0
  57. package/lib/ui/model/classifier.mjs +308 -0
  58. package/lib/ui/model/draft.mjs +62 -0
  59. package/lib/ui/model/format.mjs +41 -0
  60. package/lib/ui/model/frame.mjs +359 -0
  61. package/lib/ui/model/now.mjs +390 -0
  62. package/lib/ui/model/policy.mjs +194 -0
  63. package/lib/ui/model/routes.mjs +392 -0
  64. package/lib/ui/model/usage-agents.mjs +311 -0
  65. package/lib/ui/model/usage-breakdown.mjs +237 -0
  66. package/lib/ui/model/usage-shared.mjs +58 -0
  67. package/lib/ui/model/usage.mjs +330 -0
  68. package/lib/ui/terminal/band.mjs +220 -0
  69. package/lib/ui/terminal/classifier.mjs +142 -0
  70. package/lib/ui/terminal/frame.mjs +169 -0
  71. package/lib/ui/terminal/kit.mjs +133 -0
  72. package/lib/ui/terminal/now.mjs +300 -0
  73. package/lib/ui/terminal/policy.mjs +52 -0
  74. package/lib/ui/terminal/routes.mjs +167 -0
  75. package/lib/ui/terminal/usage.mjs +363 -0
  76. package/lib/ui/terminal/wrap.mjs +37 -0
  77. package/lib/ui/tokens.mjs +106 -0
  78. package/lib/usage.mjs +5 -5
  79. package/lib/view.mjs +5 -2
  80. package/package.json +3 -2
  81. package/types/index.d.ts +15 -0
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "router",
3
3
  "displayName": "Router",
4
- "version": "1.23.1",
4
+ "version": "1.25.0",
5
5
  "description": "Native model and effort routing within your provider. Anthropic, DeepSeek, z.ai, MiniMax, MiMo and Kimi defaults, custom provider profiles, classifier advice and one model per subagent.",
6
6
  "author": {
7
7
  "name": "Alexei Ledenev",
package/CHANGELOG.md CHANGED
@@ -1,5 +1,66 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.25.0 (2026-11-18)
4
+
5
+ ### Summary
6
+
7
+ The router's band and pane are now drawn natively in the Claude desktop app, VS Code and mobile instead of as terminal text. Running subagents show in the band, a quiet route line follows each turn, `/router` completes in the prompt, and workflow agents are routed. Claude Code 2.1.321 or newer is required.
8
+
9
+ ### Upgrade
10
+
11
+ 1. Update Claude Code to 2.1.321 or newer before you update the router (it was 2.1.289). Older builds refuse the new pane and band: routing stays off and the band says why.
12
+ 2. Workflow agents are now classified like `general-purpose` agents: Haiku for exploration, Opus for clearly hard tasks, Sonnet for the rest. To keep Claude Code's pick for them, set `subagents.types['workflow-subagent']` to `null` in `router.json`. A workflow `agent({ model })` call keeps the script's model.
13
+ 3. Terminal colours follow your Claude Code theme. Tiers, models and activities keep their colours.
14
+
15
+ ### Added
16
+
17
+ - **Desktop app, VS Code and mobile:** the band is one fixed row (tier meter, route, reason; readings, a **Pin next turn** dropdown and **Router**), and all five pane tabs (Now, Routes, Policy, Classifier, Usage) are laid out as cards. **Set up** and **Edit credentials** show a copyable terminal line that saves the key with `claude plugin configure … --values-stdin`, because these surfaces cannot open the plugin settings dialog.
18
+ - **Subagents in the band:** while subagents run, a row lists them (three, then `+N`). Pressing one opens its transcript, and `◂ main` or **← Main** returns.
19
+ - **Route line:** one quiet row after a turn with the model, effort and why, such as `▂▄▆█ Sonnet 5.5 · high ↓ cheaper fits code`. By default it appears only when the route moved; `/router line all` shows every turn and `/router line off` hides it. It is not restored by `--resume`.
20
+ - **`/router` completion:** type `/router a` and the matching words appear (`auto`, `off`, `pin <tier>`, `mode <mode>`, `activities`, `line`, `decisions`, `trace export`), then their values.
21
+ - **Unavailable toast:** a session that starts with routing unavailable shows the reason once, at most once a day per cause.
22
+ - **Undrawable pane:** a **Router** press that opens a pane the surface cannot draw says why instead of showing nothing.
23
+ - **Workflow agents are routed** (see Upgrade). Claude Code 2.1.321 applies a model rewrite to them; this was checked live.
24
+
25
+ ### Changed
26
+
27
+ - **Terminal layout:** warnings sit in one slot under the tab row on every tab; a pending pin shows on its pin button (press again to unpin); the band's hover controls draw on its own row instead of adding a line; a tab row too wide drops its digits before it squeezes. Details are in the [user guide](docs/user-guide.md).
28
+ - A resumed subagent is left alone: it keeps the model and record of its first spawn.
29
+ - **Contributing:** CI runs Lint, Types, Unit tests and Plugin as separate jobs with annotations on the changed lines. A maintainer can request an AI review with the `ai-review` label. Biome warnings and `tsc` strict null checks now fail the check.
30
+
31
+ ### Fixed
32
+
33
+ - A pin's label names what pressing it runs: the tier's configured route on `table` and `shadow` in every routing mode (the dropdown, the pending-pin chip, the Now tab and the `/router pin` completion used to show the mode's adjusted route), and the tier alone on `auto`, which picks the model when the turn runs.
34
+ - A subagent's start no longer takes over the main turn's goal. Claude Code 2.1.321 raises that event for subagent loops too.
35
+ - Two turns that end together no longer lose each other's decision rows, two view updates at session start no longer drop one another, and a later turn no longer reads its origin as `unknown`.
36
+ - The pane no longer writes state while it draws, and a graphical render failure reaches the debug log instead of disappearing.
37
+ - The Set up command quotes the plugin id.
38
+
39
+ ### Thanks
40
+
41
+ Thanks to @spark2ignite for the native band and pane for the desktop app, VS Code and mobile (#92), the largest change in this release.
42
+
43
+ ### Notes
44
+
45
+ - A person has not yet checked light mode, VS Code, mobile, or the Usage tab's data views on screen, and the docs show terminal pictures only.
46
+
47
+ ## 1.24.0 (2026-11-17)
48
+
49
+ ### Added
50
+
51
+ - Opt in to stateful main-turn routing with `routingEngine: "auto"`. The default `table` behavior is unchanged; opt-in `shadow` records proposals while the table routes. Auto evaluation and default cutover remain pending. See [configuration](docs/configuration.md#routing-engine).
52
+ - Per-effort capability declarations guide auto and shadow. Anthropic seeds four balanced base-route pairs: Haiku 5.5 medium 0 and high 1; Opus 5.5 medium 2 and xhigh 3. These are user-derived policy judgments, not quality calibration. Other pairs and provider presets remain unknown. A supplied map replaces the preset; changing a model ID clears inherited capability. See [providers](docs/providers.md#capability-evidence).
53
+ - Shadow collects bounded, text-free replay inputs. Traces exclude prompts, tool results, filesystem-path fields, classifier endpoints and credentials, but retain routing aliases and model IDs, including path-shaped IDs. `/router trace export` merges retained traces into JSON, overwriting the previous export and rolling over near 3 MiB. **Delete history** does not delete exported files. See [trace limits and privacy](docs/evaluation.md#replay-trace-recorder).
54
+ - Offline replay from a checkout checks table fidelity before simulating auto. Coverage and exposure gates remain unavailable or not established; costs are conditional estimates, not savings or quality evidence. The recorded benchmark smoke checks harness mechanics on installed Router 1.23.1 only, not this checkout or an engine comparison. See [evaluation](docs/evaluation.md#offline-automatic-engine-replay).
55
+
56
+ ### Changed
57
+
58
+ - Equal-cost auto candidates favor the incumbent, then the lower sufficient declared capability. Estimates do not model unseen effort-dependent thinking tokens; mode margin supplies headroom. See [selection](docs/auto-engine.md#demand-target-and-move).
59
+
60
+ ### Upgrade
61
+
62
+ Restart Claude Code after updating. Auto and shadow require explicit opt-in.
63
+
3
64
  ## 1.23.1 (2026-11-15)
4
65
 
5
66
  ### Fixed
@@ -323,7 +384,7 @@ The Now tab shows this session and today instead of the last 30 replies, a windo
323
384
 
324
385
  ## 1.12.0 (2026-10-13)
325
386
 
326
- The Usage tab now shows any period, not only this session and the time since the last reset. See [Compare routing with your model](docs/user-guide.md#compare-routing-with-your-model).
387
+ The Usage tab now shows any period, not only this session and the time since the last reset. See [Compare routing with no routing](docs/user-guide.md#compare-routing-with-no-routing).
327
388
 
328
389
  ### Added
329
390
 
package/README.md CHANGED
@@ -52,7 +52,15 @@ Jev 1.14 is the default; a configured model override stays in force. [Configurat
52
52
 
53
53
  The band above the prompt shows the tier, activity, model, and reason for each turn. `/router` opens a pane to pin a tier, edit the model and effort of each tier, and tune the policy. See the [user guide](docs/user-guide.md#read-the-status-band).
54
54
 
55
- The router needs Claude Code 2.1.289 or newer. Savings are not measured. The pane's Usage tab estimates what routing cost against no routing (your own model on the main thread, Claude Code's pick for each subagent) for the same tokens at configured list prices, for this session, today, 7 or 30 days, this month or all; it is not a bill and does not judge answer quality. See the [evaluation](docs/evaluation.md).
55
+ In the desktop app, VS Code and mobile, the band is one fixed row with nothing revealed on hover: a tier meter icon, the route, activity and reason on the left; the readings, a **Pin next turn** dropdown and **Router** on the right. The pane has a header, five tabs (Now, Routes, Policy, Classifier, Usage), one warnings slot and a save bar. Colours follow the app's theme. These surfaces cannot open the plugin settings dialog, so **Set up** shows a card with the command that saves the classifier's key from a terminal.
56
+
57
+ <!-- TODO: capture desktop screenshots: band, Now, Routes, Policy, Classifier, Usage, key card (dark and light) -->
58
+
59
+ In the terminal, the picture above shows the band, whose controls appear on its own row on hover; the colours follow your Claude Code theme. The pane's warnings share one slot under the tab row, and a pending pin shows on its pin button (press it again to unpin).
60
+
61
+ On every surface, a row under the band lists running subagents (press one to open its transcript; **Back** returns), `/router` completes its words as you type where the prompt box offers completions, and a quiet route line after a turn says which model ran and why (`/router line off|moves|all`; by default only when the route moved). A session that starts with routing unavailable shows one toast with the reason, at most once a day.
62
+
63
+ The router needs Claude Code 2.1.321 or newer. Savings are not measured. The pane's Usage tab estimates what routing cost against no routing (your own model on the main thread, Claude Code's pick for each subagent) for the same tokens at configured list prices, for this session, today, 7 or 30 days, this month or all; it is not a bill and does not judge answer quality. See the [evaluation](docs/evaluation.md).
56
64
 
57
65
  ## How it works
58
66
 
@@ -81,7 +89,7 @@ sequenceDiagram
81
89
  Mod-->>Dev: Status band and router pane
82
90
  ```
83
91
 
84
- The active classifier labels each new logical turn, and the router checks the route again while the task runs: a turn labelled `ops` that edits code moves up to the `code` route at once, and a background classifier review every 4 requests can move the tier or the activity either way. A cheaper route on the same task waits for a dwell and a checkpoint its work can show: a passed test, build or lint run, or for commands, docs and read-only work the success the router can see. A notification is treated as progress, but cannot justify a downgrade because it may belong to an older task. `/router decisions` lists why each turn ran where it did. See [Changes during a task](docs/user-guide.md#changes-during-a-task). A local policy applies vote, context, failure, and cache-cost rules before the Mod changes the next step. Claude Code owns request construction, model credentials, tools, streaming, and the API cost ledger.
92
+ The active classifier labels each new logical turn. With `table` or `shadow`, the router checks tier and activity routes as the task runs: a turn labelled `ops` that edits code can move up to the `code` route, and a background classifier review can move the tier or activity. With `auto`, it keeps its own demand and route state instead of using activity route-table moves. A cheaper route on the same task waits for a dwell and a checkpoint its work can show: a passed test, build or lint run, or for commands, docs and read-only work the success the router can see. A notification is treated as progress, but cannot justify a downgrade because it may belong to an older task. `/router decisions` lists why each turn ran where it did. See [Changes during a task](docs/user-guide.md#changes-during-a-task). A local policy applies vote, context, failure, and cache-cost rules before the Mod changes the next step. Claude Code owns request construction, model credentials, tools, streaming, and the API cost ledger.
85
93
 
86
94
  With the Anthropic profile, the base routes are:
87
95
 
@@ -107,20 +115,28 @@ The Anthropic profile uses these activity defaults. Other profiles have [their o
107
115
 
108
116
  `/router activities off` stops asking and keeps the base routes. [Activity routing](docs/activity-routing.md) explains each cell and how to change it. The label is optional: on `uncertain` or a weak label the base route is used if the move passes the cache check, when the activity answer fails the running activity stays and the tier answer still applies, and when the classifier fails the running route stays. See [Route by activity](docs/user-guide.md#route-by-activity), and [Evaluation](docs/evaluation.md#activity-routing) for how it is checked. Its default overrides rest on published vendor results and a list-price replay of one developer's sessions, not measured savings.
109
117
 
110
- A [routing mode](docs/routing-modes.md) trades cost against answer quality without new routes: `cost` takes a cheaper model or one effort level less where a turn allows it, `quality` one effort level more or the tier above, and `balanced`, the default, runs the routes as configured. Set it per session with `/router mode cost`, per project in `.claude/router.json`, or for the profile with `"mode"` in `router.json`.
118
+ ## Choose a routing engine
119
+
120
+ Set `routingEngine` in the selected profile file: `table` (default), `shadow` or `auto`. For example, use `{"routingEngine":"shadow"}` or `{"routingEngine":"auto"}`; omit it for `table`. `/router auto` turns routing on for the session; it does not select the engine. `/router off` turns it off, while `/router mode cost|balanced|quality` selects the routing mode.
121
+
122
+ - **`table` (default):** uses deterministic tier-by-activity routes. The routing mode transforms those routes before the table policy.
123
+ - **`shadow`:** table requests remain unchanged. `/router decisions` shows one-step `alt` proposals. `/router trace export` writes bounded replay inputs; for the work profile (`CLAUDE_CONFIG_DIR=~/.claude-team`), from a source checkout, replay `~/.claude-team/router-traces.json` and any dated rollover files with `node scripts/replay-traces.mjs`.
124
+ - **`auto`:** selects a model and effort from declared per-effort capabilities, classifier demand, mode margins and hard/cache constraints. Configure a classifier credential when its provider requires a key; Ollama needs none. Without classifier advice, demand cannot be updated, but a qualifying startup move may still occur. Capability declarations determine whether candidate adequacy is known. Evaluation and cutover remain pending.
125
+
126
+ See [routing engines](docs/configuration.md#routing-engine) for startup, fallback and pin behavior, and [routing modes](docs/routing-modes.md) for mode effects.
111
127
 
112
128
  For mixed Anthropic and DeepSeek sessions, use the explicit [model-proxy profile](docs/providers.md#mix-anthropic-and-deepseek-with-model-proxy) with a separately started local proxy. No built-in mixed-provider defaults are installed.
113
129
 
114
130
  ## Install
115
131
 
116
- You need Claude Code 2.1.289 or newer and credentials for one [supported classifier](#supported-classifiers).
132
+ You need Claude Code 2.1.321 or newer and credentials for one [supported classifier](#supported-classifiers).
117
133
 
118
134
  ```sh
119
135
  claude plugin marketplace add alexei-led/claude-router
120
136
  claude plugin install router@alexei-led-claude-router
121
137
  ```
122
138
 
123
- For the default Anthropic profile, start on the full baseline model, for example `claude --model claude-haiku-5-5`. For other providers, [select a provider profile](docs/providers.md#select-a-provider). Run `/plugin configure router` and save the key. For any other classifier, save its credentials, or run `ollama serve` with a pulled model, then pick the classifier on the pane's Classifier tab. A new session on a model that a tier routes to, or with activity routing `on` a model an activity override uses (Sonnet 5.5 on the defaults), starts with routing on; on any other model it starts with routing off and says why, and `/router auto` turns routing on.
139
+ For the default Anthropic profile, start on a catalog model such as `claude --model claude-haiku-5-5`. For other providers, [select a provider profile](docs/providers.md#select-a-provider). Run `/plugin configure router` and save credentials for the active classifier, or run `ollama serve` with a pulled local model and select Ollama. With `table` or `shadow`, a new session starts with routing on only when its model is used by a tier or enabled activity override. With `auto`, any model in the selected catalog starts with routing on. `/router auto` turns routing on for the selected engine; see [engine selection](docs/configuration.md#routing-engine).
124
140
 
125
141
  Claude Code updates the plugin at startup when auto-update is on for this marketplace. Otherwise run `claude plugin marketplace update alexei-led-claude-router`, then `claude plugin update router@alexei-led-claude-router`.
126
142
 
@@ -136,7 +152,7 @@ claude --plugin-dir "$PWD" --model claude-haiku-5-5
136
152
 
137
153
  In Claude Code, run `/plugin configure router` and save your classifier key in the sensitive plugin option. The Mod adds its status band and `/router` pane. No status-line setup or gateway environment variables are needed.
138
154
 
139
- Run `/router` to open the pane: route status, per-tier controls, tuning, and usage, including routing vs no routing. Run `/model` to select a model and turn routing off, and `/router auto` to turn it back on. For controls, metrics, tuning, and troubleshooting, see the [user guide](docs/user-guide.md).
155
+ Run `/router` to open the pane. `/router auto` turns routing on for the session; `/router off` turns it off, and `/router mode cost|balanced|quality` selects the routing mode. None changes `routingEngine`, which stays in the selected profile file. Run `/model` to select a model (which turns routing off). See the [user guide](docs/user-guide.md).
140
156
 
141
157
  Before a push, run the same checks as CI. `npm run setup` installs Biome and TypeScript into `tools/`; the plugin root keeps no lockfile, so Claude Code installs nothing with the plugin. `npm run validate` and `npm run test:plugin` need the `claude` CLI: they load the Mod in the Claude Code engine, which refuses some faults that lint and unit tests miss.
142
158
 
@@ -145,6 +161,22 @@ npm run setup
145
161
  npm run check && npm run typecheck && npm test && npm run validate && npm run test:plugin
146
162
  ```
147
163
 
164
+ ## Contributing
165
+
166
+ Pull requests from forks run CI automatically (a maintainer may have to approve the first run). Each check is its own job, and failures show as annotations on the changed lines: `Lint (biome)`, `Types (tsc)`, `Unit tests (node --test)`, and `Plugin (validate and engine tests)`. Run them locally before pushing:
167
+
168
+ ```sh
169
+ npm run setup
170
+ npm run check && npm run typecheck && npm test && npm run validate && npm run test:plugin
171
+ ```
172
+
173
+ `npm test` runs the unit tests; CI runs the same files as `npm run test:ci`, which adds a reporter that annotates failures on the changed lines. `npm run format` fixes biome formatting. A maintainer can request an AI review by adding the `ai-review` label.
174
+
175
+ ### Code quality
176
+
177
+ - `npm run check` is Biome with `--error-on-warnings`, so a warning fails like an error. Besides the recommended rules it catches unawaited or misused promises, an `await` on a non-promise, an incomplete `switch` over a union, unused imports and variables, import cycles, throws of non-Error values, a lost `cause` when an error is rethrown, shadowed bindings, conditions the types prove constant, and read-modify-write updates split by an `await` (`useAtomicUpdates`). Use `biome-ignore` only with a one-line reason for code that is deliberate.
178
+ - `npm run typecheck` is `tsc` over `lib` and `hooks` with `strictNullChecks`, `noUncheckedIndexedAccess`, `useUnknownInCatchVariables`, `strictFunctionTypes`, `noImplicitReturns`, `noFallthroughCasesInSwitch`, `noUnusedLocals`/`noUnusedParameters`, `verbatimModuleSyntax` and `erasableSyntaxOnly`.
179
+
148
180
  ## Documentation
149
181
 
150
182
  - [User guide](docs/user-guide.md): install, use the controls, read the panel, and troubleshoot.
@@ -154,5 +186,5 @@ npm run check && npm run typecheck && npm test && npm run validate && npm run te
154
186
  - [Activity routing](docs/activity-routing.md): the default matrix by activity, why each cell, and how to change or turn it off.
155
187
  - [Routing modes](docs/routing-modes.md): `cost`, `balanced` and `quality`, where the mode comes from, and every decision per mode.
156
188
  - [Native router details](docs/native-router.md): panel semantics, tuning, and accepted limits.
157
- - [Evaluation](docs/evaluation.md): historical gateway results and the native shadow replay.
189
+ - [Evaluation](docs/evaluation.md): limits, text-free trace export and replay, and the paired benchmark proposal.
158
190
  - [Changelog](CHANGELOG.md): user-visible changes by version.
@@ -64,14 +64,37 @@ Claude Code builds each request for the model the Mod selects, so no request rew
64
64
  | [Prices](../lib/prices.mjs) | Built-in list prices with each vendor's page and check date; rewritten by `scripts/check-prices.mjs`. |
65
65
  | [Router view](../lib/view.mjs) | The view's initial shape and the usage readings each reply adds to it. |
66
66
  | [Config file](../lib/config-file.mjs) | Pane writes to `router.json`: the validated rewrite and what Undo restores. |
67
- | [Panel](../lib/panel.mjs) | Tabbed pane: route status, tier pins, the route editor, tuning, and usage. |
68
- | [Router band](../lib/band.mjs) | Status band segments fitted to the band's width, and route-change toasts. |
67
+ | [Panel](../lib/panel.mjs) | The tab table (id, hotkey, label, model, renderers) and `renderPanel`, which draws the pane for the surface. |
68
+ | [Router band](../lib/band.mjs) | `renderBand` and `renderRouteLine`, which draw the band and the route line for the surface, and route-change toasts. |
69
+ | [UI](../lib/ui/) | What the band and the pane show: models (plain data), one renderer per surface kind, and every colour. See [UI layout](#ui-layout). |
69
70
  | Claude Code | API requests, tools, authentication, stream output, and usage ledger. |
70
71
 
71
72
  Every function that takes the engine interface `$` lives in the hooks module: the engine does not follow `$` across an import, so the modules in `lib/` stay pure.
72
73
 
73
74
  Node.js is not part of routing. It is used for development, the optional configuration migration, and the classifier probe.
74
75
 
76
+ ## UI layout
77
+
78
+ The band, the pane and the route line are built in three steps: the router state becomes a model, a renderer turns the model into elements, and the host draws them. All of it is under `lib/ui/`, with two entry points, `renderPanel` in `lib/panel.mjs` and `renderBand` (and `renderRouteLine`) in `lib/band.mjs`.
79
+
80
+ ```
81
+ lib/ui/tokens.mjs every colour, by tone, and the surface helpers (isGraphical, toneColor)
82
+ lib/ui/fallback.mjs orTerminal: the terminal tree when a graphical renderer throws
83
+ lib/ui/model/ plain data, no elements and no widths: now, routes, policy, classifier, usage (with
84
+ usage-breakdown, usage-agents, usage-shared), frame (notices, save bar, help, key help),
85
+ draft (the Routes and Policy draft), band (segments, fitting, agent rows), format
86
+ lib/ui/terminal/ kit.mjs, frame.mjs, band.mjs, wrap.mjs and one renderer per tab
87
+ lib/ui/graphical/ kit.mjs, frame.mjs, band.mjs, charts.mjs, meter.mjs, squares.mjs and one renderer per tab
88
+ ```
89
+
90
+ **Surface dispatch.** Every `ui.render` event carries `e.surface`, which the hook passes on. `terminal`, or no surface, picks the terminal tree. `desktop`, `vscode` and `mobile` pick the graphical tree, which is one tree for all three. If a graphical renderer throws and the caller passed `onFallback`, `orTerminal` hands it the error and draws the terminal tree; the hook's callback writes the error to the debug log. Without `onFallback` the throw propagates, so a test sees a broken renderer instead of the terminal tree standing in for it. The terminal's own throw is never caught.
91
+
92
+ **Data flow.** `renderPanel` builds a context from the config, the stored view, the usage readings and `e.surface`. The selected tab's `modelOf` turns it into a model in which every condition, word and number format is already decided; where the words differ by surface the model holds a `{ terminal, graphical }` pair. The renderer only lays the model out with its kit. A tab renderer never reads `view` or the config; if it needs a fact, the model carries it. The frame (header, tabs, notices slot, save bar) has its own model, `frameOf`, and its own renderer per surface kind. The band follows the same idea with less separation: `lib/ui/model/band.mjs` returns segments of parts with a priority (`bandSegments`, `sessionSegments`, `agentSegments`, `routeLineSegments`), and `fitSegments` drops them by priority to fit `columns`. The terminal band draws the segments, adds the hover controls as absolutely placed Boxes, and still takes `config` and `view` for those controls; the graphical band splits the segments into a left group that shrinks and a right group that never does. A graphical band never adds anything on hover.
93
+
94
+ **State.** `lib/ui/` keeps no module state. A function takes the elements it draws with (`$.ui.resolve(e)` in the hook), the model, and the actions it binds to a `Button` or `Select`; the hook owns the view, the config and every host call.
95
+
96
+ **Colour.** `lib/ui/tokens.mjs` is the one place a colour is written. A model names a tone (`primary`, `muted`, `accent`, `success`, `warning`, `danger`, `activity`, `tier:<tier>` or `model:<family>`); the kit turns it into a colour with `toneColor(tone, surface)`. The terminal and the graphical surfaces draw the six theme tones as Claude Code theme keys (`text`, `subtle`, `suggestion`, `success`, `warning`, `error`), so the person's theme, light or dark, decides them. Tiers, model families and the activity have no theme key and are hexes, with a mid-lightness set on a graphical surface so each reads on a white and a dark ground. An `Svg` cannot take a theme key, so its colours are hexes from the same file (`svgColor`). A renderer that wrote its own colour would escape the theme and the contrast checks in `test/ui-tokens.test.mjs`.
97
+
75
98
  ## Decision and context
76
99
 
77
100
  A logical turn is classified at its first step, and again every `reviewEveryRequests` requests in the background (see Review inside a turn below). Other tool continuations reuse the decision and add no votes. Before each step, the controller checks whether the selected model still fits after new tool output.
@@ -174,10 +197,10 @@ prune unreadable newer records.
174
197
  A subagent's model is chosen once, in the `agent.spawn` hook, before its cache exists. Its `turn.step` events pass through unchanged: a subagent runs on the 5-minute cache lifetime by default, and a switch between its steps would rewrite a 50,000–300,000-token context cold. The facts below are from the Claude Code 2.1.296 types (`AgentSpawnInput`, `HookBudget`) and a probe Mod's observed events, `experiments/mod-router/results/agent-spawn-probe.json`. The [plan](plans/2026-10-10-subagent-routing-plan.md#2-verified-facts) cites each one.
175
198
 
176
199
  - A model the hook sets beats the agent's `model:` frontmatter and `CLAUDE_CODE_SUBAGENT_MODEL`. Frontmatter is not in the spawn input. The Agent call's own `model` is, as `e.model`.
177
- - Workflow `agent()` calls raise `agent.spawn` with `e.workflow`, but a model rewrite there is ignored.
200
+ - Workflow `agent()` calls raise `agent.spawn` with `e.workflow`, and a model rewrite there applies (2.1.321, checked live). A resumed subagent raises it with `e.resume`; a hook can only refuse that, so `spawnAgent` returns `next(e)` at once.
178
201
  - The hook has 10 seconds of its own time. `$` calls do not count against it, but a `$.clock.sleep` does.
179
202
 
180
- `spawnAgent` in `hooks/native-router.mjs` passes the spawn through unchanged for a fork, a workflow agent (before the explicit check, since a workflow `agent({ model })` has `e.model` set), an explicit `e.model`, or a teammate (`passReason` in `lib/subagents.mjs`). Then `typeRoute` decides. A `subagents.types` entry wins; a key without a colon matches only the engine's built-in of that name. An unlisted built-in passes (`unlisted`), since its definition is not on disk. Any other agent is routed by its definition. `agentDefinition` finds the file once per provider and type in a session; a read that fails is tried again at the next spawn of the type. A plugin agent's `provider.plugin` is `plugin@marketplace`, the key of `<profile>/plugins/installed_plugins.json`, whose `installPath` entries hold `agents/*.md`. Other agents are looked up under the session's `.claude/agents`, then `<profile>/agents`. `agentFrontmatter` reads `name`, `model` and `modelRouting` from YAML or a one-line JSON object. No model, `inherit`, or `modelRouting: auto` is routed; any other model passes (`pinned`); a file not found, unreadable, or matches that disagree pass (`unknown`). A routed agent's type uses its models key, or for `classify` the active classifier is asked with the description and prompt alone, clipped to `context.maxTextChars`, with no history and no tool results. The answer maps to `subagents.heavy` when `P(high) ≥ heavyMass`, to `light` for an `explore` activity above `activityMass` or tier `micro`, else to `standard`. The spawn path has its own classifier client per classifier: its own failure count and pause, and no in-flight slot, so parallel spawns each get an answer and spawn failures never pause main-turn routing. Its deadline is the classifier's, capped at 3 seconds. That bounds how long a subagent waits to start. No advice, a missing key, a model `availableModels` blocks, or settings that cannot be read keep core's model. The router sends the configured full id, never an alias, because a family alias resolves to the parent's exact model when the families match. A `.catch` runs `next(e)`, so a failing hook spawns the agent as Claude Code would. Routing off (`/router off`, `/model`) or unavailable passes every spawn through and records nothing.
203
+ `spawnAgent` in `hooks/native-router.mjs` passes the spawn through unchanged for a resume, a fork, a workflow agent that sets its own model (checked before the explicit test, since a workflow `agent({ model })` has `e.model` set) or whose `workflow-subagent` entry in `subagents.types` is `null`, which is routed by default, an explicit `e.model`, or a teammate (`passReason` in `lib/subagents.mjs`). Then `typeRoute` decides. A `subagents.types` entry wins; a key without a colon matches only the engine's built-in of that name. An unlisted built-in passes (`unlisted`), since its definition is not on disk. Any other agent is routed by its definition. `agentDefinition` finds the file once per provider and type in a session; a read that fails is tried again at the next spawn of the type. A plugin agent's `provider.plugin` is `plugin@marketplace`, the key of `<profile>/plugins/installed_plugins.json`, whose `installPath` entries hold `agents/*.md`. Other agents are looked up under the session's `.claude/agents`, then `<profile>/agents`. `agentFrontmatter` reads `name`, `model` and `modelRouting` from YAML or a one-line JSON object. No model, `inherit`, or `modelRouting: auto` is routed; any other model passes (`pinned`); a file not found, unreadable, or matches that disagree pass (`unknown`). A routed agent's type uses its models key, or for `classify` the active classifier is asked with the description and prompt alone, clipped to `context.maxTextChars`, with no history and no tool results. The answer maps to `subagents.heavy` when `P(high) ≥ heavyMass`, to `light` for an `explore` activity above `activityMass` or tier `micro`, else to `standard`. The spawn path has its own classifier client per classifier: its own failure count and pause, and no in-flight slot, so parallel spawns each get an answer and spawn failures never pause main-turn routing. Its deadline is the classifier's, capped at 3 seconds. That bounds how long a subagent waits to start. No advice, a missing key, a model `availableModels` blocks, or settings that cannot be read keep core's model. The router sends the configured full id, never an alias, because a family alias resolves to the parent's exact model when the families match. A `.catch` runs `next(e)`, so a failing hook spawns the agent as Claude Code would. Routing off (`/router off`, `/model`) or unavailable passes every spawn through and records nothing.
181
204
 
182
205
  Every spawn in `on` gets a record keyed by `agentId`, from `next(e)`'s answer. Its replies are priced in `turn.step` (`addAgentReply`), on the model they ran on and on core's model as `coreModelOf` estimates it (the definition's own model, else `CLAUDE_CODE_SUBAGENT_MODEL` except for Explore and Plan without `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`, else `parentModel`). Cache writes are priced at the subagent lifetime (`subagentCacheTtl`). The spawn record also keeps `move` (`moveOf`): `up` or `down` when the routed model's declared strength rank is above or below core's, `moved` when either rank is unknown or both are equal, null for the same model. The record's counts go to this session's `$.store` key `subagents:v1:<session id>` at each of the agent's `turn.complete`s, and at session end for agents still running. Since 1.14.0 the value is version 2, by local calendar day like the usage records, and days past 400 leave it when it is written: per day, per type and per pass-through reason, the agents, requests, priced requests, respawns (a spawn of the type its parent loop finished one of in the last 10 minutes) and classifier failures, and per model id the agents ran on, the agents, the agents moved, up and down, the routed cost and core's. An agent counts on the day of its first flush; its later requests and cost on the day of each flush. A version 1 value has no days or models: it reads as `undated` agents and cost, which only the Session and All periods add. The records follow the usage records: one writer per key, the view's `subagentStore` is every session's sum and `subagentSession` this session's, and the same reset marker applies. **Delete history** clears them too. The view's `subagentsRunning` counts the agents with a record between a spawn or a step and their turn's end; it is in memory, so a reload starts it over. The band in a subagent's transcript reads the agent's record from memory too.
183
206
 
@@ -0,0 +1,152 @@
1
+ # Pure automatic routing engine
2
+
3
+ `lib/auto-engine.mjs` implements the [automatic routing design](plans/2026-11-16-auto-routing-design.md).
4
+ It has no I/O. Opt-in `routingEngine: "auto"` uses the stateful adapter `lib/auto-route.mjs` in the main-turn hook; the default table engine is unchanged. Shadow remains a one-step proposal and offline replay has its own state. Evaluation and default cutover remain pending.
5
+
6
+ ## Inputs
7
+
8
+ All functions take one object. Pass the original validated config, including its catalog, cache settings and
9
+ base `policy`. Do not pass `applyMode(config, mode)`: per-mode policy patches belong to the table engine only.
10
+ The automatic mode changes only the capability requirement.
11
+
12
+ A route is `{ model: alias, effort: string | number | null }`. Generated candidates use only supported strings,
13
+ or `null` for a model with `efforts: []`. A real native incumbent with an unresolved null or finite numeric effort
14
+ is valid but has unknown capability. An unsupported explicit string is not silently clamped.
15
+ Capability comes only from `models[alias].capability[effort]`, or `capability.default` on a no-effort model.
16
+ No declaration means unknown, not zero. Anthropic includes user-derived balanced base-route policy seeds, not
17
+ measured quality; all other pairs remain unknown. Users can replace them as described in
18
+ [Providers](providers.md#capability-evidence).
19
+
20
+ The facts object uses the existing controller shapes:
21
+
22
+ - `contextTokens`, `historyMeasured`, `hasImages`;
23
+ - `models`: cache key → `{ prefixTokens, lastAt, ... }`;
24
+ - `effort`: native session effort, and `lastRequest: { tokens, outputTokens, ... }`;
25
+ - `ineligible`: model IDs excluded for this history;
26
+ - `dwellAllowed`: a separate boolean for physical downgrades, required even on a new task. Set it to
27
+ `requests - switchedAt.requests >= config.policy.minDwellRequests`, using the actual route's last switch and
28
+ request counter. At session start, before any request/switch exists, set it to true. Missing means false.
29
+ - `downAllowed`: the existing combined dwell/checkpoint fact, required in addition to `dwellAllowed` only on the
30
+ same task; `midTurn`, `progress` and advice continuation identify that task. Off the same task no checkpoint
31
+ is required. Upgrades, forced refits, escalation and explicit stronger mode/catalog moves bypass dwell.
32
+ - `failure: { signature, index }` or null. The same signature at a new index is a new occurrence.
33
+ Re-reading the same occurrence does not escalate again. History reset must reset engine state.
34
+
35
+ Advice uses the existing `{ choice, probabilities, continuation, ... }` classifier shape, or null.
36
+ `now` is the caller's timestamp in milliseconds. `availableModels` and `nativeModel` use the existing
37
+ `isModelAllowed` semantics. Pass the active provider's cache configuration, including effort-cache separation.
38
+ If the host has resolved a configured model ID to a response ID, project those IDs into the supplied catalog
39
+ before assessing cache state, as the table controller's economic config does.
40
+
41
+ ## Demand, target and move
42
+
43
+ | Export | Input | Output |
44
+ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
45
+ | `initialAutoState` | `{ demand = 2, routedDemand = demand, cause = 'classifier' }` | Initial state |
46
+ | `initialIncumbentState` | `{ config, incumbent, facts }` | Baseline demand with actual known incumbent capability as routed demand |
47
+ | `advanceDemand` | `{ config, state, advice = null, facts, pin = null, boundedExecute = false }` | `{ raw, level, reason, headroom, escalated, state }` |
48
+ | `assessCandidates` | `{ config, facts, now, incumbent, contextKnown = Number.isFinite(facts.contextTokens), availableModels, nativeModel }` | Candidate facts array |
49
+ | `selectTarget` | `{ candidates, demand, mode = 'balanced', headroom = false, escalation = false }` | `{ outcome, route, capability, requirement, estimate, reason, headroom }` |
50
+ | `decideMove` | `{ config, state, demandResult, target, candidates, advice = null, facts, now, changeCause = null, startup = false }` | `{ move, route, reason, evidence, estimate, state }` |
51
+ | `proposeAutoRoute` | Combined inputs above, using `incumbent` and optional `state` | `{ demand, candidates, target, move, state }` |
52
+
53
+ The facade initializes missing state with `initialIncumbentState`. Raw demand starts at `config.baselineTier`;
54
+ routed demand starts at the actual incumbent's declared capability for its supported/resolved native effort.
55
+ Unknown capability, an unlisted model, or unresolved/unsupported effort conservatively keeps baseline routed
56
+ demand; it is never inferred from a route table, mode offset or a guessed effort. Runtime and replay use the
57
+ same initializer. `initialAutoState` remains available for callers supplying explicit state.
58
+ State includes integer `demand`, `turn`, `votes`, `holdUntilTurn`, `escalatedSignature`, `escalatedIndex`,
59
+ `headroom`, `demandCause`, `routedDemand` and `routeCause`.
60
+ `raw` is integer demand; `level` is effective demand after the noncumulative half-step bounded-execute discount.
61
+ The caller supplies `boundedExecute: true` only for an already accepted bounded execute/ops phase, never
62
+ for a goal label alone or verify/report phases. An escalation hold protects the raised demand.
63
+
64
+ Each candidate has `route`, `requestKey` (canonical physical identity), `capability` (number or null), `eligible`, `reasons`, `incumbent`, `selectable`,
65
+ `cache`, `coldWriteUsd` and `estimate`. The incumbent is assessed even if it left the catalog.
66
+ A native unresolved effort is included in normal target comparison so it wins equal estimates, but cannot be
67
+ nominated as a new non-incumbent route. Declared-below-demand candidates still precede an unknown incumbent.
68
+ On a no-effort model, numeric native effort and the generated null-effort candidate have the same request key.
69
+
70
+ All availability, context, image, effort and cold-write cash constraints run before fallback.
71
+ An invalid incumbent and no eligible candidate produce explicit `no-route`, never an invented native route.
72
+ Target outcomes are `meets-demand`, `declared-below-demand`, `unknown-only`, `incumbent` and `no-route`.
73
+
74
+ Estimates are absolute next-turn `{ minUsd, maxUsd }` ranges: `cost.inputBounds` plus the last reply's output
75
+ length at `cost.ratesAt` prices. This estimate is effort-blind; it does not model additional thinking tokens.
76
+ Selection uses the conservative `maxUsd` bound, then the incumbent, lower sufficient declared capability and
77
+ config order. The mode margin supplies headroom through the requirement, not a tie preference. Automatic prefix
78
+ caches have no assumed TTL or warm-cache exemption.
79
+ Switch gates use the existing route-to-route `switchingTaxUsd` and `downgradeTaxUsd` math.
80
+ These are conditional estimates, not expected costs or measured savings.
81
+
82
+ ## State ownership
83
+
84
+ Shadow needs only `advanceDemand → assessCandidates → selectTarget`. Retain the returned demand state and
85
+ always assess the real incumbent/cache; do not retain a hypothetical target as route history.
86
+ Pass `escalation: demand.escalated` and `headroom: demand.headroom` to `selectTarget`. After either escalation or
87
+ pending-headroom selection, copy `target.headroom` back to the returned demand state's `headroom` field.
88
+ It is true only on exhausted escalation, permitting retry if a stronger candidate becomes eligible.
89
+ Target reasons are null, `escalation`, `escalation-unknown` (unknown capability) and `escalation-exhausted`.
90
+ A declared stronger eligible request precedes unknown alternatives; neither search can return the same physical
91
+ request via another alias. The facade performs this headroom feedback automatically.
92
+
93
+ Stateful replay/auto compares effective demand with `state.routedDemand`, not the previous turn's demand.
94
+ A physical move updates routed demand and route cause. A `same-route` selection instead accepts the current
95
+ effective demand (including zero) as routed demand without a switch: `move: false`, route cause, hold, votes
96
+ and failure markers remain unchanged. Canonically identical physical requests under different aliases count
97
+ as same-route. Pins, no-route, exhausted escalation and blocked moves do not adopt demand.
98
+ The facade returns accepted state in `result.state` and `result.move.state`; its demand-only state remains in
99
+ `result.demand.state`. A held proposal leaves routed demand and cause unchanged, so it remains pending.
100
+ Runtime and offline replay use the same `decideMove` transition.
101
+ `changeCause` is null, `mode` or `catalog`; it cannot relabel a demand change as an explicit configuration move.
102
+ The separate `startup` input defaults to false and must come from genuine per-history routing evidence,
103
+ never `state.turn === 0` or the physical request count. A first tier pin consumes eligibility even though its
104
+ demand state remains unchanged. Manual/off native requests do not consume it; their cache and dwell observations
105
+ still count normally. The loop persists `hasRoutedDecision` with the same state write as the routed decision,
106
+ including table decisions and pins. Reload, off/on, engine changes and compaction preserve it; a new session or
107
+ `/clear` new history starts false. Legacy unmarked histories with request, decision or auto-state evidence
108
+ conservatively count as consumed. This adds no configuration flag or state version.
109
+ Startup qualification uses the selector's existing `target.requirement`: effective demand after any accepted
110
+ bounded-execute discount plus the mode margin. It does not cancel that discount or invent an undiscounted floor.
111
+ Only a declared known incumbent below that requirement and a declared target meeting it can qualify; unknown
112
+ capability never grants startup evidence. After unchanged demand voting, qualifying startup movement takes
113
+ priority over classifier upgrade/downgrade movement and uses mass 1 through the same base-policy explicit-up
114
+ switch-tax gate. All candidate hard constraints and the cash cap still apply; this is not a forced move.
115
+ A blocked first decision consumes the chance, so there is no second-turn startup retry. For example, native
116
+ capability 0, baseline 1 and first low probability 0.57 can move with startup mass 1; the same probability on an
117
+ ordinary later demand upgrade still needs the unchanged classifier mass gate. Fresh micro advice that reduces
118
+ effective demand to 0 does not authorize startup when capability 0 already meets the resulting requirement.
119
+ Startup move reason and route cause are `startup`, not `mode`. Replay compares accepted automatic mode/catalog
120
+ evidence rather than treating table-only pin config snapshots as catalog edits; genuine edits survive pins.
121
+ The live adapter and replay fingerprint the actual allowed configured aliases, including native `default` resolution.
122
+ An allowlist expansion is catalog evidence; reordering it, cache warmth and routine response-ID resolution are not.
123
+
124
+ Tier pins accept a tier string or integer 0..3. They are one-turn overrides: no mode margin and no move gates,
125
+ but normal candidate constraints, outcome precedence and incumbent ties. The facade returns the pinned route
126
+ with `move: false`, reason `pinned` and unchanged state. The caller resumes the pre-pin incumbent and state on
127
+ the next unpinned turn. With the lower-level API, pass `mode: 'balanced'` to `selectTarget` for a pinned demand.
128
+ Exact model/effort pins remain the controller's separate responsibility.
129
+
130
+ An observed native fallback records `incumbentOrigin: 'external-fallback'` and rebases the physical incumbent without
131
+ resetting demand, votes, hold or routed demand. Substituted effort remains unknown. The current turn stays native;
132
+ on the next turn, `decideMove` takes `incumbentOrigin` and permits `reentry` to a different eligible target without
133
+ mass, dwell or payback gates. Hard constraints and the cash cap still apply. Re-entry sets routed demand and cause
134
+ `reentry`, retaining the escalation hold; an equal physical target accepts current effective demand and clears
135
+ origin without changing route cause or counting a switch. Pinned fallbacks retain normal state and
136
+ apply the physical fallback provenance after restoring the pin. Replay counts external requests separately.
137
+
138
+ ## Reloads
139
+
140
+ Before routing after a Mod reload without `session.start`, the hook lazily loads and validates the selected
141
+ provider profile and project mode. Constructor defaults never choose a main-turn route. A failed load marks
142
+ routing unavailable and passes the native request unchanged, without resetting persisted auto state to table.
143
+ A real repeated `session.start` invalidates old turn-config and classifier/review jobs before using the reloaded
144
+ profile. Compatible persisted automatic state survives; an actual engine change resets incompatible engine state.
145
+ Lazy profile loading is not a fresh-session signal: shadow recording remains explicitly incomplete mid-session.
146
+
147
+ ## Checks
148
+
149
+ Run `node --test test/auto-engine.test.mjs` for the design's §5.4 invariants and §3.3 move-evidence cases.
150
+ The tests also cover failure occurrence deduplication, raw/effective demand, pins, native efforts, cache semantics,
151
+ range/cash/context boundaries and a capability-monotonicity matrix across sparse catalogs and differing prices.
152
+ No paid API calls or classifier calls are needed.
@@ -6,7 +6,7 @@ Select a [provider profile](providers.md), then configure the key of the classif
6
6
 
7
7
  | Item | Where it lives | How to change it |
8
8
  | ---------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------- |
9
- | Jev API key | Sensitive plugin option `typesafe_api_key` | Run `/plugin configure router`, or use **Set up** or **Credentials → Edit** in the router pane. |
9
+ | Jev API key | Sensitive plugin option `typesafe_api_key` | Run `/plugin configure router`, or use **Set up** or **Credentials → Edit** in the router pane (on the desktop app, VS Code and mobile they show the command to run in a terminal). |
10
10
  | Cloudflare API token | Sensitive plugin option `cloudflare_api_token` | The same dialog. Used by Clef, Clef Flash and Clef Omni. |
11
11
  | Cloudflare account ID | Plugin option `cloudflare_account_id` | The same dialog, or the config menu row. Not a secret. |
12
12
  | OpenAI API key | Sensitive plugin option `openai_api_key` | The same dialog. Used only by the OpenAI classifier. Ollama needs no key. |
@@ -37,6 +37,25 @@ See [Providers](providers.md) for selection examples, built-in defaults and comp
37
37
  The same schema applies to every router file. This reference uses `router.json` as shorthand for the selected file.
38
38
  A non-Anthropic file must exist and validate. It never falls back to `router.json` or inherits settings from it.
39
39
 
40
+ ### Model capability declarations
41
+
42
+ `models.<alias>.capability` is an optional map of supported efforts to adequacy levels: 0 (micro),
43
+ 1 (low), 2 (medium), or 3 (high), with half-steps allowed. For example:
44
+
45
+ ```json
46
+ { "models": { "sonnet": { "capability": { "medium": 1.5, "high": 2 } } } }
47
+ ```
48
+
49
+ These example values illustrate the shape, not measured model performance. Anthropic has user-derived built-in
50
+ policy seeds; see [Providers](providers.md#capability-evidence). Users may replace or clear them. Missing maps and entries are
51
+ unknown, not 0. For a model with `efforts: []`, use only `"default"` for its no-effort candidate. Other keys,
52
+ unsupported efforts, non-numbers and values outside 0–3 or between half-steps are invalid.
53
+
54
+ A user-supplied map replaces the preset map in full; `{}` clears it. Replacing a model ID clears inherited
55
+ capability, even if the same alias is kept; the `[1m]` context hint alone does not change identity. Changing
56
+ `efforts` prunes unsupported inherited entries; unsupported explicitly supplied entries are rejected. Capability
57
+ is separate from `strength`, which still controls the current table routing. Capability declarations affect `auto` and `shadow`; the default `table` uses strength. Built-in declarations and their evidence limits are listed in [Providers](providers.md#capability-evidence).
58
+
40
59
  ### Provider prices
41
60
 
42
61
  All non-Anthropic built-in model windows are at least 1M tokens.
@@ -106,6 +125,24 @@ The router never substitutes zero savings or invents another route's cache hit r
106
125
  Models with `efforts: []`, including MiMo, ignore session effort in the comparison identity.
107
126
  Missing counters remain unknown. See [provider acceptance checks](evaluation.md#provider-profiles).
108
127
 
128
+ ## Routing engine
129
+
130
+ Set `routingEngine` in the selected profile file (`router.json` or `<provider>-router.json`); the default is `table`.
131
+ For example, set `{"routingEngine":"shadow"}` or `{"routingEngine":"auto"}`; omit the key to use `table`.
132
+ The engine is selected in this file, not by a `/router` command.
133
+
134
+ - **`table` (default):** the deterministic tier-by-activity routes are used. Routing modes transform those routes before the table policy.
135
+ - **`shadow`:** the table still sends every request. The automatic engine records one-step proposals against the real incumbent and cache, without keeping a separate route history or asking the classifier again. The Now pane and `/router decisions` show demand, target, capability (or unknown), outcome and a next-turn estimate. While shadow is enabled, the main-turn hook also records bounded replay traces. Export with `/router trace export`; for the work profile (`CLAUDE_CONFIG_DIR=~/.claude-team`) the file is `~/.claude-team/router-traces.json`. Retain all incremental export and rollover files. From a source checkout, run `node scripts/replay-traces.mjs ~/.claude-team/router-traces.json`, adding every rollover file as another argument. The export lives beside the selected profile config; the replay CLI is not included in the npm package. Replay checks table fidelity first; evaluation and exposure gates remain unestablished. See [evaluation](evaluation.md#replay-trace-recorder).
136
+ - **`auto`:** the stateful engine selects each main-turn model and effort from the configured catalog using classifier demand, a mode margin, and hard/cache constraints. It does not use route tables or mode policy patches. Tier pins set exact demand for one turn, without a mode margin, and still obey hard constraints. A first routed decision can move from a known below-requirement native model to a declared qualifying candidate under the normal switch-tax and cash gates; failures can escalate to stronger eligible candidates. Demand, votes, holds and routed demand persist across turns. If no eligible candidate fits, the native request is kept with reason `no-route-native`; after an observed provider fallback, the rest of that turn stays native, and the next turn can re-enter an eligible route.
137
+
138
+ Auto asks the active classifier for demand. Configure a classifier credential when the provider requires a key; local Ollama needs no key. Without classifier advice, the engine cannot detect demand and holds the startup route; a qualifying startup capability move based on the prompt tier may still occur.
139
+
140
+ Useful auto routing depends on the profile's per-effort `models.<alias>.capability` declarations: unknown is not zero or proof of adequacy. Without declarations, auto cannot identify a known adequate target. Built-in Haiku declares `medium: 0` and `high: 1`; Opus declares `medium: 2` and `xhigh: 3`. These are policy seeds, not measured quality. Other efforts and provider presets remain unknown. Capability maps replace inherited maps atomically; changing a model ID clears stale inherited capabilities. See [capability evidence](providers.md#capability-evidence).
141
+
142
+ Auto decision rows show demand, target, outcome and move reasons such as `startup`, `upgrade`, `escalation`, `same-route`, `reentry` and `no-route-native`.
143
+
144
+ `/router auto` turns routing on for the session; `/router off` turns it off. Neither changes `routingEngine`. `/router mode cost|balanced|quality` selects the mode, and `/router pin <tier>` pins one turn. Evaluation and default cutover remain pending; see [evaluation](evaluation.md). Engine values are case-sensitive.
145
+
109
146
  ## Built-in defaults
110
147
 
111
148
  The default baseline is tier `low`. Each route refers to an alias in `models`.
@@ -305,7 +342,8 @@ These agents always keep their model:
305
342
  - a fork;
306
343
  - an Agent call that names a `model`;
307
344
  - a teammate;
308
- - a workflow `agent()`: Claude Code ignores a rewrite of its model, so workflow agents get only `CLAUDE_CODE_SUBAGENT_MODEL`;
345
+ - a workflow `agent({ model })`: the script chose it. A workflow `agent()` without a model is classified like `general-purpose`, unless you set `workflow-subagent` to `null` under `subagents.types`;
346
+ - a resumed subagent: it runs on the model of its first spawn, and Claude Code lets a hook only refuse a resume;
309
347
  - a built-in agent other than Explore, Plan and general-purpose: its definition is not on disk.
310
348
 
311
349
  ```json
@@ -323,6 +361,12 @@ These agents always keep their model:
323
361
 
324
362
  The values above are the defaults.
325
363
 
364
+ Workflow agents are routed by default, classified like `general-purpose`. The key is the engine's own name for them, `workflow-subagent` (whatever type the script gives an agent does not apply to it); its value is a models key, `classify`, or `null` to keep Claude Code's pick:
365
+
366
+ ```json
367
+ { "subagents": { "types": { "workflow-subagent": null } } }
368
+ ```
369
+
326
370
  - `types` overrides the rule for an agent type: a models key, `classify`, or `null` to never route it. A user file adds to the defaults. A key without a colon matches only Claude Code's built-in of that name, such as `Explore`; a project agent named `Explore` replaces the built-in and follows its own definition. A `plugin:name` key matches only that plugin's agent. A listed type is routed even if its definition pins a model.
327
371
  - `classify` asks the active classifier, once, with the task's description and prompt. It sends no history and no tool results. The task runs on `heavy` when the classifier gives `high` at least `heavyMass`. It runs on `light` for exploration (the `explore` activity above `policy.activityMass`) or the `micro` tier. Everything else runs on `standard`. Every routed agent not listed in `types` is classified. In `on` the spawn waits up to the classifier's `timeoutMs`, at most 3 seconds.
328
372
  - A classifier failure or a missing key keeps the model Claude Code gives the agent, and so does a model that `availableModels` blocks, or settings the router cannot read. So does routing off: `/router off`, or a `/model` choice.
@@ -351,7 +395,7 @@ The Mod validates the whole file. Unknown keys and invalid values make routing u
351
395
  | `mode` | `cost`, `balanced`, `quality` ([Routing modes](routing-modes.md)) | `balanced` |
352
396
  | `modes.<cost\|quality>.policy` | any `policy` field, used while that mode is active | [Routing modes](routing-modes.md#policy-per-mode); not tuned |
353
397
  | `activities.<activity>.<tier>` | optional `model` and `effort`, as in `routes` | The overrides in [Activity routing](#activity-routing) |
354
- | `models.<alias>` | `id`, `input`, optional `output`, `cacheRead`, optional `longContext` (`above`, `multiplier`, or `null`), optional `offPeak` (`multiplier`, `peakDays` as UTC weekdays 0–6 from Sunday, `peakHoursUtc` as `[from, to)` hour ranges, or `null`), `contextWindow`, `billing`, `efforts`, optional `strength`, `imageInput` | Three defaults above |
398
+ | `models.<alias>` | `id`, `input`, optional `output`, `cacheRead`, optional `longContext` (`above`, `multiplier`, or `null`), optional `offPeak` (`multiplier`, `peakDays` as UTC weekdays 0–6 from Sunday, `peakHoursUtc` as `[from, to)` hour ranges, or `null`), `contextWindow`, `billing`, `efforts`, optional `strength`, optional `capability`, `imageInput` | Three defaults above |
355
399
  | `cache` | `mode`, `effortScope`, `writeMultiplier`, `ttlMs`, `warmMarginMs` | `5m: 1.25`, `1h: 2`; `300000` / `3600000` ms; `30000` ms |
356
400
  | `policy` | Fields below | Values below |
357
401
  | `classifier` | An id in `classifiers` | `jev` |