@alexeiled/claude-router 1.24.0 → 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 (78) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/CHANGELOG.md +44 -0
  3. package/README.md +39 -7
  4. package/docs/architecture.md +27 -4
  5. package/docs/configuration.md +23 -14
  6. package/docs/evaluation.md +3 -3
  7. package/docs/native-router.md +11 -3
  8. package/docs/router-band.svg +124 -133
  9. package/docs/router-pane-classifier.svg +24 -23
  10. package/docs/router-pane-now.svg +9 -7
  11. package/docs/router-pane-policy.svg +4 -4
  12. package/docs/router-pane-routes.svg +8 -8
  13. package/docs/router-pane-usage-whatif.svg +14 -14
  14. package/docs/router-pane-usage.svg +20 -20
  15. package/docs/routing-modes.md +10 -8
  16. package/docs/user-guide.md +70 -17
  17. package/hooks/native-router.mjs +333 -80
  18. package/lib/activity-stats.mjs +23 -4
  19. package/lib/activity.mjs +7 -5
  20. package/lib/auto-engine.mjs +13 -6
  21. package/lib/auto-route.mjs +10 -4
  22. package/lib/band.mjs +35 -440
  23. package/lib/classifier-client.mjs +12 -8
  24. package/lib/config-file.mjs +7 -2
  25. package/lib/config.mjs +24 -9
  26. package/lib/cost.mjs +5 -1
  27. package/lib/costs.mjs +4 -2
  28. package/lib/decisions.mjs +13 -9
  29. package/lib/display.mjs +69 -20
  30. package/lib/facts.mjs +3 -0
  31. package/lib/modes.mjs +8 -4
  32. package/lib/panel.mjs +75 -2167
  33. package/lib/policy.mjs +7 -6
  34. package/lib/replay-trace.mjs +5 -2
  35. package/lib/replay.mjs +7 -1
  36. package/lib/route-line.mjs +46 -0
  37. package/lib/route.mjs +21 -16
  38. package/lib/savings.mjs +14 -3
  39. package/lib/subagents.mjs +41 -11
  40. package/lib/subcommands.mjs +60 -0
  41. package/lib/ui/fallback.mjs +22 -0
  42. package/lib/ui/graphical/band.mjs +256 -0
  43. package/lib/ui/graphical/charts.mjs +163 -0
  44. package/lib/ui/graphical/classifier.mjs +153 -0
  45. package/lib/ui/graphical/frame.mjs +227 -0
  46. package/lib/ui/graphical/kit.mjs +156 -0
  47. package/lib/ui/graphical/meter.mjs +25 -0
  48. package/lib/ui/graphical/now.mjs +353 -0
  49. package/lib/ui/graphical/policy.mjs +56 -0
  50. package/lib/ui/graphical/routes.mjs +264 -0
  51. package/lib/ui/graphical/squares.mjs +29 -0
  52. package/lib/ui/graphical/usage.mjs +376 -0
  53. package/lib/ui/model/band.mjs +439 -0
  54. package/lib/ui/model/classifier.mjs +308 -0
  55. package/lib/ui/model/draft.mjs +62 -0
  56. package/lib/ui/model/format.mjs +41 -0
  57. package/lib/ui/model/frame.mjs +359 -0
  58. package/lib/ui/model/now.mjs +390 -0
  59. package/lib/ui/model/policy.mjs +194 -0
  60. package/lib/ui/model/routes.mjs +392 -0
  61. package/lib/ui/model/usage-agents.mjs +311 -0
  62. package/lib/ui/model/usage-breakdown.mjs +237 -0
  63. package/lib/ui/model/usage-shared.mjs +58 -0
  64. package/lib/ui/model/usage.mjs +330 -0
  65. package/lib/ui/terminal/band.mjs +220 -0
  66. package/lib/ui/terminal/classifier.mjs +142 -0
  67. package/lib/ui/terminal/frame.mjs +169 -0
  68. package/lib/ui/terminal/kit.mjs +133 -0
  69. package/lib/ui/terminal/now.mjs +300 -0
  70. package/lib/ui/terminal/policy.mjs +52 -0
  71. package/lib/ui/terminal/routes.mjs +167 -0
  72. package/lib/ui/terminal/usage.mjs +363 -0
  73. package/lib/ui/terminal/wrap.mjs +37 -0
  74. package/lib/ui/tokens.mjs +106 -0
  75. package/lib/usage.mjs +5 -5
  76. package/lib/view.mjs +5 -2
  77. package/package.json +3 -2
  78. package/types/index.d.ts +15 -0
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "router",
3
3
  "displayName": "Router",
4
- "version": "1.24.0",
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,49 @@
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
+
3
47
  ## 1.24.0 (2026-11-17)
4
48
 
5
49
  ### Added
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
 
@@ -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. |
@@ -127,19 +127,21 @@ Missing counters remain unknown. See [provider acceptance checks](evaluation.md#
127
127
 
128
128
  ## Routing engine
129
129
 
130
- Set `"routingEngine": "shadow"` in the selected profile file to record one-step automatic-routing proposals alongside
131
- the table's decisions. The default, `"table"`, does not run the automatic engine. Shadow uses the real incumbent and
132
- cache for each proposal; the table still chooses every request. The Now pane and `/router decisions` show demand,
133
- target, capability (or unknown), outcome and a next-turn cost estimate. Shadow requests no extra classifier advice.
134
- The proposal is not a prediction of a stateful automatic-routing session.
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.
135
133
 
136
- Set `"routingEngine": "auto"` to opt in to stateful automatic routing. It selects from the configured model and
137
- effort catalog using demand, a mode margin, hard constraints and observed cache economics. It does not use route
138
- tables or mode policy patches. Tier pins override demand for one turn without a margin, but still obey hard constraints.
139
- If no candidate fits, the original native request runs with reason `no-route-native`. Auto quality evaluation and
140
- default cutover remain pending; see [evaluation](evaluation.md). After an observed fallback, the rest of its turn
141
- stays native. The next turn can re-enter an eligible target without confidence, dwell or payback gates; hard constraints
142
- and the cash cap still apply, and escalation holds survive. The three values are case-sensitive.
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.
143
145
 
144
146
  ## Built-in defaults
145
147
 
@@ -340,7 +342,8 @@ These agents always keep their model:
340
342
  - a fork;
341
343
  - an Agent call that names a `model`;
342
344
  - a teammate;
343
- - 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;
344
347
  - a built-in agent other than Explore, Plan and general-purpose: its definition is not on disk.
345
348
 
346
349
  ```json
@@ -358,6 +361,12 @@ These agents always keep their model:
358
361
 
359
362
  The values above are the defaults.
360
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
+
361
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.
362
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.
363
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.
@@ -397,7 +397,7 @@ Method, per main reply that routing chose:
397
397
 
398
398
  Checks:
399
399
 
400
- - Unit tests (`test/savings.test.mjs`) cover a session that saves, one that costs more with Haiku as your model, equal routes at exactly 0, cache expiry at 5m and 1h, a compaction, a change of your model or effort, the 100K surcharge, an unpriced model, and a corrupted store. `test/hook-routing.test.mjs` covers two sessions finishing turns at the same moment, a `/model` change mid-session that keeps each reply against its own model, and a running turn's replies counted once before and after the turn is recorded. `test/usage.test.mjs` covers calendar days across month ends and daylight saving changes, the periods, the record cap and expiry, the trend buckets and what is worth a look; `test/usage-view.test.mjs` covers the Usage tab.
400
+ - Unit tests (`test/savings.test.mjs`) cover a session that saves, one that costs more with Haiku as your model, equal routes at exactly 0, cache expiry at 5m and 1h, a compaction, a change of your model or effort, the 100K surcharge, an unpriced model, and a corrupted store. `test/hook-usage.test.mjs` covers two sessions finishing turns at the same moment, a `/model` change mid-session that keeps each reply against its own model, and a running turn's replies counted once before and after the turn is recorded. `test/usage.test.mjs` covers calendar days across month ends and daylight saving changes, the periods, the record cap and expiry, the trend buckets and what is worth a look; `test/usage-view.test.mjs` covers the Usage tab.
401
401
  - A one-off replay, not checked in, of this machine's main-conversation transcripts from 2026-10-01 to 2026-10-10 (nine sessions with 10 or more replies) gave $0.00 for every session that ran only on the model it was compared with: three on Opus 5.5, one on Haiku 5.5. Every main-conversation cache write in them was a one-hour write, which is what the lifetime rule gives on this Max plan.
402
402
  - A live Claude Code 2.1.296 session on 2026-10-10, Opus 5.5 at `high` with turns pinned to Haiku 5.5, showed **Routed replies $0.48** beside **Cost $0.480 reported by Claude** for the same 16 replies; its last Haiku reply had a 114K-token prompt, which agrees only at the 5x rate. A Haiku 5.5 session with a pinned Opus turn showed $0.45 routed against $0.446 reported.
403
403
 
@@ -427,7 +427,7 @@ Method:
427
427
  Checks:
428
428
 
429
429
  - `test/subagents.test.mjs` covers each pass reason, the pin rule, the classify mapping, core's model estimate, the router's move, the subagent lifetime, Haiku's long-context price, and the store's days, merge, reset, bad values and records from before 1.14.0. `test/hook-subagents.test.mjs` covers `on` (the routed model), a fork, an explicit model, a teammate, a workflow agent and a pinned project agent (each passes), a classifier failure (core's model), parallel spawns, a spawn-path pause that leaves main routing alone, respawns, session end, Delete history, and the Usage and Now tabs. `test/usage-view.test.mjs` covers the block by period, an open row, a narrow pane and undated records; `test/hook-band.test.mjs` the band in a subagent's transcript.
430
- - `experiments/mod-router/results/agent-spawn-probe.json` records what Claude Code 2.1.296 does with a spawn's model, frontmatter and workflow agents.
430
+ - `experiments/mod-router/results/agent-spawn-probe.json` records what Claude Code 2.1.296 does with a spawn's model, frontmatter and workflow agents. On 2.1.321 a live probe showed that a model rewrite applies to workflow agents, and that a resumed subagent raises `agent.spawn` with `e.resume` and keeps its first model.
431
431
  - `experiments/mod-router/results/subagent-routing-live.json` is a live `on` run on 2026-10-10 with Sonnet as the parent. Explore was sent Haiku and ran on it. general-purpose was classified `standard`. A pinned project agent and an explicit `opus` call passed through. The store counted each one.
432
432
 
433
433
  When to turn it `on`:
@@ -441,7 +441,7 @@ Keep it if requests per agent and respawns per type stay no higher than before y
441
441
  Limits:
442
442
 
443
443
  - Answer quality is not measured.
444
- - Workflow agents cannot be routed. In the maintainer's sessions they were 22 of 24 Opus subagents (`workflow-subagent-models.json`), so most inherited Opus spend there is out of reach. `CLAUDE_CODE_SUBAGENT_MODEL` is the lever for them.
444
+ - Workflow agents are classified by default (`subagents.types['workflow-subagent']`). In the maintainer's sessions they were 22 of 24 Opus subagents (`workflow-subagent-models.json`), so this reaches most of the inherited Opus spend. The routed effect is not measured yet, and answer quality is not either.
445
445
  - `on` estimates core's model. It does not apply the family-alias rule or the `availableModels` substitution.
446
446
  - Respawns are a proxy. A parent may spawn the same type twice on purpose.
447
447
  - Records follow the savings records' storage, with the same gaps.
@@ -1,11 +1,13 @@
1
1
  # Native router: behavior and evidence
2
2
 
3
- This guide describes the Mod shipped in the plugin. Claude Code 2.1.289 is the minimum tested version. The router changes `model` and `effort` on main-conversation steps. Claude Code handles the Anthropic request, credentials, stream, tool execution, and cost ledger. Subagent steps keep their model and effort; the router chooses an agent's model once, at spawn, unless its definition pins one ([configuration](configuration.md#subagent-routing)).
3
+ This guide describes the Mod shipped in the plugin. Claude Code 2.1.321 is the minimum tested version. The router changes `model` and `effort` on main-conversation steps. Claude Code handles the Anthropic request, credentials, stream, tool execution, and cost ledger. Subagent steps keep their model and effort; the router chooses an agent's model once, at spawn, unless its definition pins one ([configuration](configuration.md#subagent-routing)).
4
4
 
5
5
  ## Turn behavior
6
6
 
7
7
  At the first main step of a logical turn, the Mod reads recent message text and asks the active classifier (Jev, Clef, Clef Flash, Clef Omni, OpenAI, or Ollama) for a tier, and for the turn's activity unless `activityRouting` is `off`. It applies local policy and saves the route. Tool continuations reuse that route, except that a turn whose tool calls edit code moves up to the `code` route, and every `policy.reviewEveryRequests` requests a background classifier review may move it either way ([Changes during a task](user-guide.md#changes-during-a-task)). Before each continuation, context fit is checked again. A large tool result can move the step to a model with a larger window.
8
8
 
9
+ Claude Code sends a model change on every step, but an effort change on a tool-result step only when `CLAUDE_CODE_MODEL_CAPABILITIES=per_turn_effort` is set in its environment (the router does not set it). Without it a turn keeps the effort of its first request, so the band and the decision record can name an effort that did not run; see [what we do not know yet](activity-routing.md#what-we-do-not-know-yet).
10
+
9
11
  The classifier receives the current prompt and at most six preceding user or assistant text messages. Each item is limited to 1,200 characters. It does not receive system messages, tool inputs, or tool results. Claude Code's Anthropic credentials never enter the classifier request. Jev, Clef, Clef Flash, Clef Omni, and OpenAI receive the text on their services; Ollama receives it on this machine. [Configuration](configuration.md#classifiers) lists each host.
10
12
 
11
13
  The default tiers are defined in [Configuration](configuration.md#built-in-defaults). Policy uses vote hysteresis, repeated tool errors, context fit, model availability, and switching-cost estimates. The [architecture](architecture.md#request-flow) explains the event boundary and failure handling.
@@ -23,15 +25,20 @@ The activity is what the turn produces: `code`, `debug`, `explore`, `plan`, `rev
23
25
  | `/router activities <off\|on>` | Set the activity routing mode. Written to `router.json` at once; **Undo** in the pane reverts it. |
24
26
  | `/router mode <cost\|balanced\|quality\|default>` | Set or clear this session's [routing mode](routing-modes.md), from the next turn. Kept for a resume in `$.store` `routing-mode:<session id>`. Never aborts a turn. |
25
27
  | `/router decisions [n]` | Print this session's last `n` routing decisions (default 20, at most 60): origin, classifier answer, task, tier, route, reason with the mass and bar it compared, and each turn's end. No text. |
28
+ | `/router line <off\|moves\|all>` | Set when a turn leaves a route line (default `moves`: only when its route moved). Kept in `$.store` as `route:line`, across sessions. |
26
29
  | `/model <name>` | Select a model and turn routing off. `/router auto` turns it back on. |
27
30
 
28
- The pane's **Set up** and **Credentials → Edit** buttons open Claude Code's secure plugin configuration. Claude Code refuses `$.command.run` from inside a `command.run` hook, so the Mod starts that dialog from a timer after the press returns.
31
+ The prompt's typeahead (`prompt.autocomplete`) offers these words after `/router ` and their values after `pin `, `mode `, `activities ` and `line `. It starts with the first typed character, because the engine passes a token that is never empty. The command, the typeahead and the argument hint all read one table, `lib/subcommands.mjs`, and a test runs the command with every word and value in it.
32
+
33
+ The route line is one `$.ui.place` row per routed turn, drawn by a `ui.render` hook on `Placed`. At `turn.complete` of the main loop, skipping an aborted turn, a subagent's turn and a turn with routing off, the router writes the route that ran (model, effort, tier, reason, activity and the policy's estimate, never text) to `$.state` under `router.lines` with the row's id (`rl-` and the turn id, made safe for `$.ui.place`), then places the row. The hook draws only rows whose `plugin` is the router's and leaves the rest to `next(e)`. A surface that cannot draw the row at that moment (`isPlaced: false`) is logged to the debug log and the turn goes on. Claude Code does not bring rows back on `--resume` and ends them at a compaction, so the records are not read again.
34
+
35
+ In a terminal, the pane's **Set up** and **Credentials → Edit** buttons open Claude Code's secure plugin configuration. The desktop app, VS Code and mobile cannot open that dialog, so there both buttons show a card with the command to run in a terminal (the band's **Set up** does the same). Claude Code refuses `$.command.run` from inside a `command.run` hook, so the Mod starts that dialog from a timer after the press returns.
29
36
 
30
37
  Mode belongs to a Claude Code session. Clear starts a new session with routing on. Resume restores the saved mode for that session. A new or forked session has a new ID: it starts with routing on for a model that one of the tiers routes to and with routing off for any other model, as a fresh launch does. With activity routing `on`, a model that only an activity override uses also starts the session with routing on. A pin applies to one logical turn, then the prior route resumes. A history reset clears votes and cache evidence; the current turn keeps its route, pin and any native fallback.
31
38
 
32
39
  ## Router pane
33
40
 
34
- The status band is one line above the prompt: a tier meter, the model, the activity, a short reason, classifier support and the switch cost, and context and cache use. Segments drop by priority when the band is narrow: classifier support and the switch cost first, then context and cache, then the activity, then the reason. Hovering reveals a pin per tier, **Turn off**, and a two-row view whose second row shows the plan windows on a Claude plan and the session's cost against no routing; while routing is off, **Turn on** sits on the band itself, so the band carries one routing control at a time. A fresh session that starts with routing off because of its model shows `not a routing tier` on the band until the mode changes. The band yields to surveys. In a subagent's transcript it names the agent's model and who picked it, such as `agent ■ Haiku 5.5 ↓ from Opus 5.5 (Claude Code’s pick)`; without a record of the agent it reads `agent · model chosen at spawn`, or `agent · keeps its own model (subagent routing off)`. A model change between turns raises a toast. A pin, or a step that changes only the effort, such as `medium` to `high` on the defaults, raises none. While the classifier runs, the turn's spinner says `Choosing model`. In Manual mode or when routing is unavailable, the prompt footer carries `routing off` or `routing unavailable`. The **Router** button opens the pane. The pane has five numbered tabs, Now, Routes, Policy, Classifier, and Usage, under one `ROUTER` line with the routing on/off pair and the classifier state. The [user guide](user-guide.md#open-the-router-pane) describes each tab.
41
+ In the terminal, the status band is one line above the prompt: a tier meter, the model, the activity, a short reason, classifier support and the switch cost, and context and cache use. Segments drop by priority when the band is narrow: classifier support and the switch cost first, then context and cache, then the activity, then the reason. Hovering shows, on the same row, a pin per tier, **Turn off**, and a two-row view whose second row shows the plan windows on a Claude plan and the session's cost against no routing; while routing is off, **Turn on** sits on the band itself, so the band carries one routing control at a time. A fresh session that starts with routing off because of its model shows `not a routing tier` on the band until the mode changes. The band yields to surveys. While subagents that the router routed are running, a row under the band lists them (`agents 2 ▸ ■ Haiku 5.5 Explore · retry usages ●`, at most three and then `+N`, never a teammate); pressing one opens that agent's transcript through `$.ui.view`, which Claude Code allows only as an answer to the person's own input, and a refusal is shown as a toast. The row is read from `$.agent.list()` joined with the router's spawn records, and redraws when the set of running agents changes (`subagentIds` in the view). In an agent's transcript the band starts with `◂ main`, which returns to the main conversation. In a subagent's transcript it names the agent's model and who picked it, such as `agent ■ Haiku 5.5 ↓ from Opus 5.5 (Claude Code’s pick)`; without a record of the agent it reads `agent · model chosen at spawn`, or `agent · keeps its own model (subagent routing off)`. A model change between turns raises a toast. A pin, or a step that changes only the effort, such as `medium` to `high` on the defaults, raises none. While the classifier runs, the turn's spinner says `Choosing model`. In Manual mode or when routing is unavailable, the prompt footer carries `routing off` or `routing unavailable`. The **Router** button opens the pane. In the terminal the pane has five numbered tabs, Now, Routes, Policy, Classifier, and Usage, under one `ROUTER` line with the routing on/off pair and the classifier state. The desktop app, VS Code and mobile draw a fixed one-row band, with nothing revealed on hover, and tabs without digits; see [the user guide](user-guide.md#in-the-desktop-app-vs-code-and-mobile). The [user guide](user-guide.md#open-the-router-pane) describes each tab.
35
42
 
36
43
  | Reading | Meaning and limits |
37
44
  | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -84,6 +91,7 @@ The pane refuses to write through a symlink. A failed validation names the setti
84
91
  - Three launched classifier failures open a 60-second pause for that classifier. One in-flight request is allowed per classifier in each active Mod instance. Pending host HTTP work blocks another request until it settles.
85
92
  - A `router.json` with v0.8 gateway keys or the 1.1 `jev` section marks the router unavailable until the [migration command](configuration.md#convert-an-older-routerjson) converts it.
86
93
  - Unsupported Claude Code versions and leftover v0.8 gateway settings (the `jev-router` model or the `127.0.0.1:43170` base URL) mark the router unavailable. `/router` lists the settings to remove. A local gateway does not run as part of this Mod.
94
+ - A session that starts with the router unavailable shows one toast with the reason (`$.ui.toast`, not `$.ui.notify`, which is a native terminal notification). It repeats at most once a day per cause: the time is kept in `$.store` as `notice:unavailable:<version|gateway|config>`. A `claude -p` run shows none.
87
95
  - While the router is unavailable, the pane header reads `ROUTER unavailable Claude’s model is kept` with the reason, and offers no on/off pair or pins. `/router` without a surface starts with `Routing unavailable: <reason>. Claude’s model is kept.`, and `/router auto`, `off`, `pin`, and `activities` reply the same and change nothing.
88
96
  - A context-window error makes that model ineligible until the next history reset. The Mod does not retry an Anthropic request after a stream begins.
89
97
  - Unknown context retains the current model. There is no characters-to-tokens fallback.