@alexeiled/claude-router 1.13.0 → 1.15.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.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "router",
3
3
  "displayName": "Router",
4
- "version": "1.13.0",
4
+ "version": "1.15.0",
5
5
  "description": "Model and effort routing for the main conversation by task difficulty and activity, advised by a prompt classifier (Jev, Clef, Clef Flash, OpenAI or local Ollama). Subagents get one model at spawn: every agent that does not pin one.",
6
6
  "author": {
7
7
  "name": "Alexei Ledenev",
package/CHANGELOG.md CHANGED
@@ -1,5 +1,51 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.15.0 (2026-10-22)
4
+
5
+ A routing mode trades cost against answer quality without new routes: `cost`, `balanced` (the default, unchanged) or `quality`. See [Routing modes](docs/routing-modes.md).
6
+
7
+ ### Added
8
+
9
+ - `cost` takes the route of the tier below when its model has a lower input price, else one effort level less; `quality` one effort level more, else the route of the tier above. `micro` turns and pins keep the configured route. `docs/routing-modes.md` lists the route of every classifier tier and activity in each mode.
10
+ - Choose the mode for this session with `/router mode cost|balanced|quality` (`/router mode default` clears it; a resume keeps it), for a project with `{ "mode": "cost" }` in `.claude/router.json`, or for the profile with `"mode"` in `router.json` or **Mode** on the Policy tab. A project file with any other key is ignored with a notice.
11
+ - `modes.cost.policy` and `modes.quality.policy` replace those `policy` fields while that mode is active. The built-in values are not tuned on this router.
12
+ - The band, the Now tab and `/router` show the mode and its source, such as `cost (session)`; the prompt footer names a mode other than balanced.
13
+ - The routing decision at the start of each turn writes one `router decision` line to Claude Code's debug log: mode, source, the classifier's tier, the tier and reason chosen, and the route. Moves later in the turn write none.
14
+
15
+ ### Changed
16
+
17
+ - The router keeps the route a turn ran instead of rebuilding it from `router.json`. A mode change, or a route edited mid-session, now reaches the request through the usual checks, not on the next request.
18
+ - A cheaper route inside the same tier on the same task now waits for `minDwellRequests` and a passed check, as a move to a cheaper tier does.
19
+
20
+ ### Fixed
21
+
22
+ - The switching cost of two routes that share a prompt cache (one model at two efforts, on an API key or a subscription) is now zero, as the configuration docs said. The estimate charged the new tokens of the next request as a switch cost, though either route writes them. A cheaper effort on the same model was therefore refused on any measured history. In `balanced` a tier switch between such routes, such as Opus at `medium` and at `xhigh`, now needs only the base support (`upgradeBase`, `downgradeMass`); before, the bar rose with that estimate, up to about 0.82 on a cold cache.
23
+
24
+ ### Known limitations
25
+
26
+ - The Policy tab shows the base policy bars; in `cost` or `quality` the band shows the bar actually in use, such as `Jev 46% < 85%`.
27
+
28
+ ### Migration
29
+
30
+ - `router.json` needs no change: without `mode` it runs `balanced`.
31
+ - Usage records are version 2 under the same `usage:v1:<session id>` keys, with the mode in each cell. Records from before read as `balanced`. A session of an older version reads a version 2 record as empty and never deletes it. Going back to 1.14 and resuming a session that 1.15 recorded replaces that session's record with a new one: its 1.15 days are lost.
32
+ - A project's `.claude/router.json` can choose the mode for anyone who runs Claude Code there, with no trust prompt. It cannot change routes, models or the classifier; keep it out of a repo you share if the choice is yours alone.
33
+
34
+ ## 1.14.0 (2026-10-14)
35
+
36
+ Subagents now show which model each agent ran on, who picked it, and for which period. See [Understand usage and estimates](docs/user-guide.md#understand-usage-and-estimates).
37
+
38
+ ### Changed
39
+
40
+ - **SUBAGENTS** on the Usage tab follows the period row instead of summing every session since the last reset, and says its scope: `this session`, or `all projects` and the dates. Each agent is a square colored by the model it ran on, filled when the router moved it off Claude Code's pick. The routed types and the pass-throughs are one row each with agents, cost and the difference against Claude Code's pick, so a row no longer wraps; a row opens to its models. Each pass-through says why Claude Code picked the model.
41
+ - The band in a subagent's transcript names the agent's model and who picked it: `■ Haiku 5.5 · moved down by the router · Claude Code: Opus 5.5`, or `□ Opus 5.5 · Claude Code’s pick: the workflow sets it`.
42
+ - The Usage tab's scope line says `all projects` instead of `all sessions`: the records cover every project that uses this router install.
43
+ - Subagent records are kept by day and by model, version 2 under the same `subagents:v1:<session id>` keys. Records from before this version have no date or model: Session and All add them as one line.
44
+
45
+ ### Added
46
+
47
+ - **SUBAGENTS** on the Now tab, once this session started a subagent: how many run now, the squares, and what routing saved on them.
48
+
3
49
  ## 1.13.0 (2026-10-13)
4
50
 
5
51
  The Now tab shows this session and today instead of the last 30 replies, a window that matched no session, hour or day. See [Open the router pane](docs/user-guide.md#open-the-router-pane).
package/README.md CHANGED
@@ -77,6 +77,8 @@ Activity routing adds a second label: what the turn produces (`code`, `debug`, `
77
77
 
78
78
  `/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.
79
79
 
80
+ 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`.
81
+
80
82
  ## Install
81
83
 
82
84
  You need Claude Code 2.1.289 or newer and credentials for one [supported classifier](#supported-classifiers).
@@ -117,6 +119,7 @@ npm run check && npm run typecheck && npm test && npm run validate && npm run te
117
119
  - [Configuration](docs/configuration.md): classifiers and keys, the optional profile `router.json`, defaults, and migrations.
118
120
  - [Architecture](docs/architecture.md): Mod event flow, state, safeguards, and runtime boundaries.
119
121
  - [Activity routing](docs/activity-routing.md): the default matrix by activity, why each cell, and how to change or turn it off.
122
+ - [Routing modes](docs/routing-modes.md): `cost`, `balanced` and `quality`, where the mode comes from, and every decision per mode.
120
123
  - [Native router details](docs/native-router.md): panel semantics, tuning, and accepted limits.
121
124
  - [Evaluation](docs/evaluation.md): historical gateway results and the native shadow replay.
122
125
  - [Changelog](CHANGELOG.md): user-visible changes by version.
@@ -100,6 +100,16 @@ The router decides on a _cell_: a tier and an activity. The route is `{ ...route
100
100
 
101
101
  At session start the incumbent is the session's model. `cellForModel` looks for it in the base routes, baseline first, and only with `activityRouting: on` in the activity overrides too, so a session that starts on an override route keeps its cell until the classifier says otherwise. The start mode uses the same lookup: with `on`, a start model that only an override uses (Sonnet 5.5 on the defaults) starts with routing on.
102
102
 
103
+ ## Routing modes
104
+
105
+ The routing mode (`lib/modes.mjs`) is a fixed transform of the configured routes, applied before policy. At `turn.start` the hook resolves the mode (session override in `$.store` `routing-mode:<session id>`, then the project's `.claude/router.json`, then `mode` in the profile `router.json`, then `balanced`) and stores `applyMode(router.config, mode)` as the turn's config: every tier's and activity's route as `modeRoute` gives it, and `modes[mode].policy` over `policy`. Every later read of the turn (policy, escalation, cache keys, activity order, the request) uses that one table. `modeRoute` always starts from the configured routes, so a turn never steps from a route a mode already moved. `cost` takes the route of the tier below (never below `low`) when its model has a lower input price, else one listed effort level less; `quality` one listed effort level more, else the tier above's route. `micro` and pins keep the configured route.
106
+
107
+ **Route in use.** The loop keeps the route the last decision ran (`loop.route`, models key and effort) instead of rebuilding it from config. The incumbent's price, cache key and order come from it, and a decision that stays on the incumbent's cell keeps running it. So a mode change, or a route edit, reaches the request only through a gate: a tier switch, a taken lateral move, or a pin. A loop saved before 1.15 has no `loop.route` and rebuilds it once.
108
+
109
+ **Same-tier gate.** A mode can change the route without changing the tier or the activity. `lateralMove` therefore holds a cheaper route on the same task with `downgrade-held` until `facts.downAllowed` (dwell and a passed check), as a tier downgrade does, and the downgrade tax must still be paid back.
110
+
111
+ The turn-start decision (`decideTurn`) writes `router decision {mode, modeSource, classified, tier, reason, route, pinned}` to the debug log (`$.ui.log`, `to: 'debug'`), with no prompt text, and the turn record, view and usage cells carry the mode. `experiments/mod-router/scripts/trace-eval.mjs` replays the gateway trace once per mode at tier level; it cannot replay moves inside a tier.
112
+
103
113
  ## State and controls
104
114
 
105
115
  `$.state` stores route decisions, response observations, and UI state for the active session. Version-checked writes reject stale turn results. A private in-memory view merges state writes during one dispatch because state reads are frozen for that dispatch.
@@ -131,7 +141,7 @@ A subagent's model is chosen once, in the `agent.spawn` hook, before its cache e
131
141
 
132
142
  `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.
133
143
 
134
- 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 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. They are counted per type and per pass-through reason, with respawns: a spawn of the type its parent loop finished one of in the last 10 minutes. The records follow the usage records: one writer per key, the readout `subagentStore` in the view is the sum, and the same reset marker applies. **Delete history** clears them too.
144
+ 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 output price is above or below core's, `moved` when either has no price, 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.
135
145
 
136
146
  ## Classifier deadline and failure handling
137
147
 
@@ -41,7 +41,7 @@ The default baseline is tier `low`. Each route refers to an alias in `models`.
41
41
 
42
42
  Every default route names its effort, so no default tier keeps the effort Claude Code sends. The ladder follows Anthropic's published charts. On the OSWorld 2.1 effort chart, Haiku 5.5 at `high` scored above Sonnet 5.5 at `low`, and Haiku at `xhigh` near Sonnet at `medium`, for a fraction of the cost per attempt; OSWorld measures computer use, not coding. On Terminal-Bench 4.0, FrontierCode v1.1, and CursorBench 4.0, Opus 5.5 at `medium` matched or beat Sonnet 5.5 at `xhigh` at 25 to 50% lower cost per task (chart data on anthropic.com/claude-sonnet-5-5). These are routing defaults, not a claim of equal model quality.
43
43
 
44
- `micro` and `low` share a model, so a step between them changes only the effort. The policy prices it as a new messages cache, as it does `medium` to `high`.
44
+ `micro` and `low` share a model, so a step between them changes only the effort, as does `medium` to `high`. The policy prices such a step as no cache write, unless effort splits the cache (see [Optional `router.json`](#optional-routerjson)).
45
45
 
46
46
  To restore the 1.3 ladder, with Sonnet 5.5 at `low` on the session effort and Haiku 5.5 at `low` effort for `micro`:
47
47
 
@@ -248,6 +248,8 @@ The Mod validates the whole file. Unknown keys and invalid values make routing u
248
248
  | `baselineTier` | `micro`, `low`, `medium`, `high` | `low` |
249
249
  | `routes.<tier>` | `model`, optional `effort` (a level, or `null` for the session effort) | As in the route table above |
250
250
  | `activityRouting` | `off`, `on` | `on` |
251
+ | `mode` | `cost`, `balanced`, `quality` ([Routing modes](routing-modes.md)) | `balanced` |
252
+ | `modes.<cost\|quality>.policy` | any `policy` field, used while that mode is active | [Routing modes](routing-modes.md#policy-per-mode); not tuned |
251
253
  | `activities.<activity>.<tier>` | optional `model` and `effort`, as in `routes` | The overrides in [Activity routing](#activity-routing) |
252
254
  | `models.<alias>` | `id`, `input`, optional `output`, `cacheRead`, optional `longContext` (`above`, `multiplier`, or `null`), `contextWindow`, `billing`, `efforts` | Three defaults above |
253
255
  | `cache` | `writeMultiplier`, `ttlMs`, `warmMarginMs` | `5m: 1.25`, `1h: 2`; `300000` / `3600000` ms; `30000` ms |
@@ -279,7 +281,9 @@ Policy defaults:
279
281
  | `reviewEveryRequests` | `4` | Requests between classifier reviews inside a turn; `0` turns them off. Not tuned. |
280
282
  | `minDwellRequests` | `8` | Requests after a model change before a cheaper route on the same task. Not tuned. |
281
283
 
282
- The pane writes a subset of these settings. The **Routes** and **Policy** tabs set `routes`, `activities`, `activityRouting`, `baselineTier`, `policy.downgradeVotes`, `policy.downgradeHorizonTurns`, `policy.cashCapUsd`, and `policy.activityMass` in one save: it writes only values that differ from the defaults and removes the rest. `/router activities <mode>` writes `activityRouting` at once, with **Undo**. The **Classifier** tab sets `classifier` and the active classifier's `timeoutMs` at once. **Undo** reverts the settings the last pane write changed. Each save validates the whole file, keeps other keys, and applies from the next turn. A failed check names the setting and leaves the file unchanged. The pane refuses to write through a symlink. Model aliases and the other settings require a direct edit.
284
+ The pane writes a subset of these settings. The **Routes** and **Policy** tabs set `routes`, `activities`, `activityRouting`, `baselineTier`, `policy.downgradeVotes`, `policy.downgradeHorizonTurns`, `policy.cashCapUsd`, and `policy.activityMass` in one save: it writes only values that differ from the defaults and removes the rest. `/router activities <mode>` writes `activityRouting` at once, with **Undo**. **Mode** on the Policy tab writes `mode` at once, with **Undo**; `/router mode` changes only the session and writes no file. The **Classifier** tab sets `classifier` and the active classifier's `timeoutMs` at once. **Undo** reverts the settings the last pane write changed. Each save validates the whole file, keeps other keys, and applies from the next turn. A failed check names the setting and leaves the file unchanged. The pane refuses to write through a symlink. Model aliases and the other settings require a direct edit.
285
+
286
+ A project can set the routing mode, and only that, in `.claude/router.json` in the directory Claude Code runs in: `{ "mode": "cost" }`. Any other content is ignored with a notice; it never makes routing unavailable. A session's `/router mode` beats it, and it beats the profile's `mode`. See [Routing modes](routing-modes.md).
283
287
 
284
288
  Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 keep one prompt cache across effort levels, so the policy prices an effort-only move, such as Opus at `medium` to Opus at `high`, as no cache write. On Amazon Bedrock, Google Cloud, Microsoft Foundry, a custom `ANTHROPIC_BASE_URL`, or with `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`, each effort has its own cache and the move pays its write. A HIPAA configuration cannot be detected; the router then prices those moves as free.
285
289
 
@@ -136,27 +136,28 @@ Limits:
136
136
 
137
137
  ## Subagent routing
138
138
 
139
- Subagent routing has no measured result over time yet. It is `on` by default since 1.9. The Usage tab's **SUBAGENTS** section shows the counts kept across sessions since the last reset:
139
+ Subagent routing has no measured result over time yet. It is `on` by default since 1.9. The Usage tab's **SUBAGENTS** section shows the counts for the chosen period:
140
140
 
141
- - Per routed type: agents; **moved**, the agents whose decided model differs from the one they ran on; requests per agent; respawns; the choices by model; classifier failures; and `core → routed`, the list price of the agents' tokens on core's model against the decided one.
142
- - **Not routed**, the spawns that passed through, by reason (`fork`, `workflow`, `explicit`, `teammate`, `unlisted`, `pinned`, `unknown`), priced on the model they ran on. This is the share of subagent spend that routing cannot reach.
141
+ - Every agent by the model it ran on, filled when the router moved it off core's model, and what routing saved or cost on the routed agents.
142
+ - **ROUTED**, per type: agents, routed cost, and **vs CC**, the same tokens on core's model. Open, per model: the agents the router kept, moved up or moved down by output price, and their cost; requests per agent, respawns and classifier failures.
143
+ - **NOT ROUTED**, the spawns that passed through, by reason (`fork`, `workflow agent`, `explicit model`, `teammate`, `type not routed`, `pinned model`, `no definition`), priced on the model they ran on. This is the share of subagent spend that routing cannot reach.
143
144
 
144
145
  Method:
145
146
 
146
- - `routed` is the reply on the routed model and `core` the same tokens on core's model as the router estimates it: `CLAUDE_CODE_SUBAGENT_MODEL`, except for Explore and Plan without `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`, else the parent's model. A subagent starts with a cold cache on one model and keeps it, so its own token counts on another model are a fair counterfactual. `ratesAt` applies Haiku 5.5's 5x rate above 100,000 prompt tokens. Explore agents often pass that, so Haiku can cost more than its base price suggests.
147
+ - The routed cost is the reply on the routed model and **vs CC** the same tokens on core's model as the router estimates it: `CLAUDE_CODE_SUBAGENT_MODEL`, except for Explore and Plan without `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`, else the parent's model. A subagent starts with a cold cache on one model and keeps it, so its own token counts on another model are a fair counterfactual. `ratesAt` applies Haiku 5.5's 5x rate above 100,000 prompt tokens. Explore agents often pass that, so Haiku can cost more than its base price suggests.
147
148
  - Cache writes are priced at the subagent lifetime: five minutes unless `FORCE_PROMPT_CACHING_5M`, `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`, `subagentPromptCacheTtl` or `ENABLE_PROMPT_CACHING_1H` say otherwise, on a subscription too.
148
149
  - The counts cannot see quality. Two proxies stand in for it: requests per agent, and **respawns**, a spawn of the same type by the same parent within 10 minutes after one finished.
149
150
 
150
151
  Checks:
151
152
 
152
- - `test/subagents.test.mjs` covers each pass reason, the pin rule, the classify mapping, core's model estimate, the subagent lifetime, Haiku's long-context price, and the store's merge, reset and bad values. `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 tab.
153
+ - `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.
153
154
  - `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.
154
155
  - `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.
155
156
 
156
157
  When to turn it `on`:
157
158
 
158
- - `routed` is below `core` for the routed types, by enough to matter;
159
- - the choices look right for the tasks: `light` for searches and reads, `heavy` rarely;
159
+ - **vs CC** is below zero for the routed types, by enough to matter;
160
+ - the models look right for the tasks: Haiku for searches and reads, Opus rarely;
160
161
  - **Not routed** leaves enough routable spend to bother.
161
162
 
162
163
  Keep it if requests per agent and respawns per type stay no higher than before you turned it on. Otherwise change `types` or `heavyMass`, exclude a type with `null`, or set `subagentRouting` to `off`.
@@ -21,6 +21,7 @@ The activity is what the turn produces: `code`, `debug`, `explore`, `plan`, `rev
21
21
  | `/router off` | Turn routing off and keep Claude's selected model. |
22
22
  | `/router pin <tier>` | Pin the next turn and tool continuations. Routing on must already be enabled. |
23
23
  | `/router activities <off\|on>` | Set the activity routing mode. Written to `router.json` at once; **Undo** in the pane reverts it. |
24
+ | `/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. |
24
25
  | `/model <name>` | Select a model and turn routing off. `/router auto` turns it back on. |
25
26
 
26
27
  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.
@@ -29,7 +30,7 @@ Mode belongs to a Claude Code session. Clear starts a new session with routing o
29
30
 
30
31
  ## Router pane
31
32
 
32
- The status band is one line above the prompt: a tier meter, the activity, the route, a short reason, classifier support, and context and cache use. Segments drop by priority when the band is narrow: classifier support first, then context and cache, then the activity, then the reason. Hovering reveals pins, **Turn off**, and a two-row view; 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 `<model> is not a routing tier` on the band until the mode changes. The band yields to surveys. In a subagent's transcript it reads `subagent model chosen at spawn`, or `subagents keep their own model` with 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 tabs, Now, Routes, Policy, Classifier, and Usage, under one line with the routing on/off pair and the classifier state. The [user guide](user-guide.md#open-the-router-pane) describes each tab.
33
+ The status band is one line above the prompt: a tier meter, the activity, the route, a short reason, classifier support, and context and cache use. Segments drop by priority when the band is narrow: classifier support first, then context and cache, then the activity, then the reason. Hovering reveals pins, **Turn off**, and a two-row view; 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 `<model> is 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 `■ Haiku 5.5 · moved down by the router · Claude Code: Opus 5.5`; without a record of the agent it reads `subagent model chosen at spawn`, or `subagents keep their own model` with 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 tabs, Now, Routes, Policy, Classifier, and Usage, under one line with the routing on/off pair and the classifier state. The [user guide](user-guide.md#open-the-router-pane) describes each tab.
33
34
 
34
35
  | Reading | Meaning and limits |
35
36
  | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -1,11 +1,11 @@
1
- <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 922 444" role="img" aria-labelledby="title desc">
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 922 509" role="img" aria-labelledby="title desc">
2
2
  <title id="title">The Router band above the Claude Code prompt</title>
3
- <desc id="desc">Six band states drawn by the router code: routed to high, two rows with the hover row, a pending pin, a missing classifier key, routing off, and an activity move with activity routing on.</desc>
3
+ <desc id="desc">Seven band states drawn by the router code: routed to high, two rows with the hover row, a pending pin, a missing classifier key, routing off, an activity move with activity routing on, and cost mode set for the session.</desc>
4
4
  <style>
5
5
  text { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace; font-size: 13px; }
6
6
  .cap { font-family: system-ui, -apple-system, 'Segoe UI', sans-serif; font-size: 12px; fill: #9a988f; }
7
7
  </style>
8
- <rect width="922" height="444" rx="8" fill="#1c1c1c"/>
8
+ <rect width="922" height="509" rx="8" fill="#1c1c1c"/>
9
9
  <text class="cap" x="20" y="30">Routing on: routed to the high tier on a clear jump</text>
10
10
  <rect x="12" y="38" width="897.6" height="29" rx="5" fill="#232323"/>
11
11
  <text x="24.0" y="56" fill="#e0708a" xml:space="preserve">▂</text>
@@ -39,11 +39,13 @@
39
39
  <text x="304.8" y="121" fill="#7c7c7c" xml:space="preserve"> · </text>
40
40
  <text x="343.8" y="121" fill="#7c7c7c" xml:space="preserve">↑ jump</text>
41
41
  <text x="390.6" y="121" fill="#7c7c7c" xml:space="preserve"> · </text>
42
- <text x="429.6" y="121" fill="#d0d0d0" xml:space="preserve">ctx </text>
43
- <text x="460.8" y="121" fill="#87d787" xml:space="preserve">40%</text>
44
- <text x="484.2" y="121" fill="#d0d0d0" xml:space="preserve"> · cache hit </text>
45
- <text x="585.6" y="121" fill="#87d787" xml:space="preserve">100%</text>
46
- <text x="632.4" y="121" fill="#d0d0d0" xml:space="preserve">Router</text>
42
+ <text x="429.6" y="121" fill="#7c7c7c" xml:space="preserve">balanced (default)</text>
43
+ <text x="570.0" y="121" fill="#7c7c7c" xml:space="preserve"> · </text>
44
+ <text x="609.0" y="121" fill="#d0d0d0" xml:space="preserve">ctx </text>
45
+ <text x="640.2" y="121" fill="#87d787" xml:space="preserve">40%</text>
46
+ <text x="663.6" y="121" fill="#d0d0d0" xml:space="preserve"> · cache hit </text>
47
+ <text x="765.0" y="121" fill="#87d787" xml:space="preserve">100%</text>
48
+ <text x="811.8" y="121" fill="#d0d0d0" xml:space="preserve">Router</text>
47
49
  <text x="24.0" y="140" fill="#7c7c7c" xml:space="preserve">session </text>
48
50
  <text x="94.2" y="140" fill="#6fcf97" font-weight="700" xml:space="preserve">saved $1.84 (22%)</text>
49
51
  <text x="226.8" y="140" fill="#d0d0d0" xml:space="preserve"> vs Opus 5.5 · xhigh</text>
@@ -135,4 +137,24 @@
135
137
  <text x="531.0" y="419" fill="#d0d0d0" xml:space="preserve"> · cache hit </text>
136
138
  <text x="632.4" y="419" fill="#87d787" xml:space="preserve">100%</text>
137
139
  <text x="679.2" y="419" fill="#d0d0d0" xml:space="preserve">Router</text>
140
+ <text class="cap" x="20" y="458">Cost mode for this session: high runs Opus at high instead of xhigh</text>
141
+ <rect x="12" y="466" width="897.6" height="29" rx="5" fill="#232323"/>
142
+ <text x="24.0" y="484" fill="#e0708a" xml:space="preserve">▂</text>
143
+ <text x="31.8" y="484" fill="#e0708a" xml:space="preserve">▄</text>
144
+ <text x="39.6" y="484" fill="#e0708a" xml:space="preserve">▆</text>
145
+ <text x="47.4" y="484" fill="#e0708a" xml:space="preserve">█</text>
146
+ <rect x="55.2" y="470" width="46.8" height="18" rx="4" fill="#e0708a"/>
147
+ <text x="55.2" y="484" fill="#0d1016" font-weight="700" xml:space="preserve"> high </text>
148
+ <text x="109.8" y="484" fill="#d77757" font-style="italic" xml:space="preserve">coding → </text>
149
+ <text x="180.0" y="484" fill="#d0d0d0" xml:space="preserve">Opus 5.5 · high</text>
150
+ <text x="297.0" y="484" fill="#7c7c7c" xml:space="preserve"> · </text>
151
+ <text x="336.0" y="484" fill="#7c7c7c" xml:space="preserve">= fits</text>
152
+ <text x="382.8" y="484" fill="#7c7c7c" xml:space="preserve"> · </text>
153
+ <text x="421.8" y="484" fill="#7c7c7c" xml:space="preserve">cost (session)</text>
154
+ <text x="531.0" y="484" fill="#7c7c7c" xml:space="preserve"> · </text>
155
+ <text x="570.0" y="484" fill="#d0d0d0" xml:space="preserve">ctx </text>
156
+ <text x="601.2" y="484" fill="#87d787" xml:space="preserve">40%</text>
157
+ <text x="624.6" y="484" fill="#d0d0d0" xml:space="preserve"> · cache hit </text>
158
+ <text x="726.0" y="484" fill="#87d787" xml:space="preserve">100%</text>
159
+ <text x="772.8" y="484" fill="#d0d0d0" xml:space="preserve">Router</text>
138
160
  </svg>