@alexeiled/claude-router 1.8.1 → 1.10.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,8 +1,8 @@
1
1
  {
2
2
  "name": "router",
3
3
  "displayName": "Router",
4
- "version": "1.8.1",
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). Preserves subagent model choices.",
4
+ "version": "1.10.0",
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",
8
8
  "url": "https://github.com/alexei-led"
package/CHANGELOG.md CHANGED
@@ -1,5 +1,30 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.10.0 (2026-10-10)
4
+
5
+ ### Changed
6
+
7
+ - The pane has five tabs: Now, Routes, Policy, Classifier, Usage (`1`–`5`). The old Routing tab is split in two, and each tab now answers one question.
8
+ - **Routes** is one grid of tiers by activities. Each cell shows the model it runs: `·` for the tier's model, `°` for a built-in default, **●** for an unsaved edit. Select a cell to edit it. **remove** is now **Use tier model**, and **Restore default** puts a built-in override back. `5 distinct routes · 3 caches` now reads `3 prompt caches in use: one per model`, with what a cold cache costs.
9
+ - **Policy** writes each control as a sentence, such as `Going down after 2 ▾ agreeing turns`, shows the default beside a changed value, and says when the credits cap has no effect.
10
+ - **Now** leads with the next turn's model and why. The letter row under the replies strip (`eeccoo…`) is gone; replies are counted per tier and per activity instead, such as `coding 12 · exploring 4`.
11
+ - **Classifier** compares the classifiers in one table (where the prompt goes, probe, p95 wait, status) and flags a deadline shorter than the real wait. The counts across sessions moved here from Usage.
12
+ - **Usage** opens with the answer, such as `Routing saved $1.84 (22%) this session vs Opus 5.5 · xhigh`. Claude's readings fold to one line behind **details**.
13
+
14
+ ### Fixed
15
+
16
+ - The Now picture in the docs showed `0 switches` next to a strip with three tier changes.
17
+
18
+ ## 1.9.0 (2026-10-10)
19
+
20
+ ### Added
21
+
22
+ - Subagent routing, on by default (`subagentRouting`: `off`, `shadow`, `on`). A subagent gets one model when it starts and keeps it for every step: Haiku for exploration, Opus for clearly hard tasks, Sonnet for the rest. The router reads each agent's definition and routes it when it names no model, says `model: inherit`, or sets the new frontmatter key `modelRouting: auto`; an agent that pins a model keeps it. The built-in Explore runs on Haiku, and Plan and general-purpose are classified. Forks, Agent calls that name a model, teammates and workflow agents keep their model. `subagents.types` overrides the rule per agent type. The active classifier now also receives the description and prompt of each routed subagent, as it receives main-turn prompts; set `"subagentRouting": "off"` to stop that. The Usage tab's new **SUBAGENTS** section shows, per type, what routing cost against the model Claude Code would have used, and what passed through and why. A classified spawn waits up to 3 seconds for the classifier; `shadow` records without changing models or delaying a spawn. Checked on Claude Code 2.1.293 and 2.1.296; unverified on older builds. See [Subagent routing](docs/configuration.md#subagent-routing).
23
+
24
+ ### Changed
25
+
26
+ - An effort-only move on Opus 5.5, Sonnet 5.5, Haiku 5.5 or Fable 5.1, such as Opus at `medium` to `high`, is no longer priced as a cache write. These models keep one prompt cache across efforts with an API key or a Claude subscription, so the policy stops holding back moves that cost nothing, and Routing vs your model stops counting them as off your cache. On Amazon Bedrock, Google Cloud, Microsoft Foundry, a custom `ANTHROPIC_BASE_URL` or with `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`, each effort still has its own cache.
27
+
3
28
  ## 1.8.1 (2026-10-10)
4
29
 
5
30
  ### Changed
package/README.md CHANGED
@@ -5,11 +5,11 @@
5
5
 
6
6
  **A Claude Code Mod that chooses a model and effort for each main-conversation turn, advised by a prompt classifier: Jev, Cloudflare's Clef and Clef Flash, OpenAI, or a local Ollama model.**
7
7
 
8
- The Mod changes only the model and effort in Claude Code's turn hook. Claude Code sends the request, streams the reply, runs tools, and reports usage. The router does not proxy Anthropic traffic or start a local server; an Ollama classifier calls an Ollama server that you run. Subagent model choices pass through unchanged.
8
+ The Mod changes only the model and effort in Claude Code's turn hook. Claude Code sends the request, streams the reply, runs tools, and reports usage. The router does not proxy Anthropic traffic or start a local server; an Ollama classifier calls an Ollama server that you run. Subagents get one model each when they start, chosen the same way: every agent whose definition names no model, says `model: inherit`, or sets `modelRouting: auto`. Their steps are never re-routed. See [Subagent routing](docs/configuration.md#subagent-routing).
9
9
 
10
10
  ## Supported classifiers
11
11
 
12
- The active classifier is asked once per logical turn, for the tier and for the turn's activity. Pick one on the pane's **Classifier** tab or in `router.json`; only the active one receives prompt text.
12
+ The active classifier is asked once per logical turn, for the tier and for the turn's activity. Pick one on the pane's **Classifier** tab or in `router.json`; only the active one receives prompt text. With subagent routing `on` (the default) or `shadow`, it is also asked once per routed subagent, with the task's description and prompt; set `"subagentRouting": "off"` to keep that text local.
13
13
 
14
14
  | Classifier | Service | Credential | Prompt text goes to | How it is asked for the activity |
15
15
  | ---------- | ------------------------------------------ | ----------------------------------- | ------------------------- | --------------------------------------------------------------------- |
@@ -37,12 +37,16 @@ sequenceDiagram
37
37
  participant Cls as Classifier
38
38
  participant API as Anthropic
39
39
  Dev->>Code: Prompt
40
+ opt Subagent spawn
41
+ Code->>Mod: agent.spawn
42
+ Mod-->>Code: One model for the agent (on), or none (shadow, off)
43
+ end
40
44
  Code->>Mod: Main or subagent step
41
45
  alt Main conversation, routing on
42
46
  Mod->>Cls: Bounded prompt and dialogue
43
47
  Cls-->>Mod: Tier advice
44
48
  Mod-->>Code: Selected model and effort
45
- else Routing off or subagent
49
+ else Routing off or subagent step
46
50
  Mod-->>Code: Original model and effort
47
51
  end
48
52
  Code->>API: Native request and tools
@@ -55,8 +55,9 @@ Why each row:
55
55
  - **`explore` and `docs`.** Moving them saved nothing in the replay. Haiku also scores lower on research
56
56
  benchmarks: 50.1% on Humanity's Last Exam with tools against 63.0% for Opus at `medium`. They keep the base routes.
57
57
 
58
- The matrix uses five routes on three models. The router counts each (model, effort) pair as its own cache, so this is
59
- one more than the base routes alone.
58
+ The matrix uses five routes on three models. Opus 5.5, Sonnet 5.5 and Haiku 5.5 keep one cache across efforts, so the
59
+ five routes use three caches, one more (Sonnet) than the base routes alone. On a provider that caches each effort apart,
60
+ each (model, effort) pair is its own cache.
60
61
 
61
62
  ## Which model fits which work
62
63
 
@@ -136,13 +137,14 @@ turn, whatever the activity mode.
136
137
 
137
138
  ## Change a cell
138
139
 
139
- **In the pane.** Open `/router` and press `2`. **ACTIVITIES** shows the mode, then the route each cell runs, with `·`
140
- for the base route, and counts the routes. Routes are abbreviated, such as `S·high` for Sonnet · high, and activities
141
- with the same cells share a row. **OVERRIDES** lists each override with a model, an effort, and **remove**.
142
- **add an override…** adds one for an activity and tier. Edits are a draft: the status bar lists the `router.json`
143
- lines they change. **Save** (`s`) writes them, **Discard** (`d`) drops them, and **Undo** (`u`) reverts the last
144
- write. A yellow note flags an override that has no effect, one stronger than the tier above, or the only cell or tier
145
- on its (model, effort) pair, which adds a cache.
140
+ **In the pane.** Open `/router` and press `2` for the **Routes** tab. It starts with the mode, then one grid: a column
141
+ per tier, the **every turn** row with each tier's own model, and a row per activity. A cell shows the model the activity
142
+ runs at that tier, such as `sonnet·high`, or `·` for the tier's model; `°` marks a built-in default. Select a cell to
143
+ edit its model and effort under the grid. **Use tier model** drops the override; **Restore default** puts a built-in
144
+ one back. Edits are a draft: the tab reads **Routes ●** and lists the `router.json` lines they change. **Save** (`s`)
145
+ writes them, **Discard** (`d`) drops them, and **Undo** (`u`) reverts the last write. A yellow note flags a cell
146
+ stronger than the tier above, or the only cell on its cache, which adds one. A selected cell whose override
147
+ changes nothing says `same as the tier’s model: no effect`.
146
148
 
147
149
  **In `router.json`.** `activities.<activity>.<tier>` takes `model`, `effort`, or both. A field you leave out keeps its
148
150
  default. This runs `code` at `low` on Sonnet at `xhigh` and adds `max` effort for hard code:
@@ -155,9 +157,9 @@ default. This runs `code` at `low` on Sonnet at `xhigh` and adds `max` effort fo
155
157
  }
156
158
  ```
157
159
 
158
- A cell cannot be `null`. To drop a built-in override, set the cell to the tier's base route, or press **remove** in
159
- the pane, which writes that for you. The cell keeps that route if you later change the tier's route; remove it again
160
- then:
160
+ A cell cannot be `null`. To drop a built-in override, set the cell to the tier's base route, or press **Use tier
161
+ model** in the pane, which writes that for you. The cell keeps that route if you later change the tier's route; drop it
162
+ again then:
161
163
 
162
164
  ```json
163
165
  { "activities": { "ops": { "medium": { "model": "opus", "effort": "medium" } } } }
@@ -185,8 +187,8 @@ Two other directions, with what they trade:
185
187
 
186
188
  **Activity threshold.** An activity applies only when the classifier gives it at least this probability. Below it, a
187
189
  new task goes back to the base route if that move passes the usual checks, and a continuation of the running task
188
- keeps its activity, or moves to the classifier's activity when that route is stronger. The default is 60% (`policy.activityMass: 0.6`). Change it on the Routing tab under **POLICY**,
189
- **Activity threshold**, or in `router.json`. There is no data to tune it on yet: the probe results record whether the
190
+ keeps its activity, or moves to the classifier's activity when that route is stronger. The default is 60% (`policy.activityMass: 0.6`). Change it on the Policy tab under **Activities**,
191
+ or in `router.json`. There is no data to tune it on yet: the probe results record whether the
190
192
  label was right, not the classifier's probabilities.
191
193
 
192
194
  [Configuration](configuration.md#activity-routing) has the full schema.
@@ -206,8 +208,8 @@ label was right, not the classifier's probabilities.
206
208
  1.7's built-in for that cell, or from the base route where 1.7 has none (`explore` and `docs` at `medium`, `docs` at
207
209
  `low`). 1.6's overrides in those cells and in `ops` at `medium` were Sonnet · medium, so such a cell can now run
208
210
  another model or effort. Write both `model` and `effort` to keep 1.6's route.
209
- - If you removed a 1.6 built-in override that 1.7 no longer has, such as `docs` at `low`, the pane lists it with
210
- "same as base: no effect". Press **remove** and **Save** to drop it.
211
+ - If you removed a 1.6 built-in override that 1.7 no longer has, such as `docs` at `low`, its cell on the Routes tab
212
+ says "same as the tier’s model: no effect". Press **Use tier model** and **Save** to drop it.
211
213
  - 1.6 reads the same keys. A file without `activityRouting` runs `shadow` under 1.6.
212
214
 
213
215
  ## What the estimates mean
@@ -235,10 +237,10 @@ Limits:
235
237
 
236
238
  - The answer quality of routed sessions.
237
239
  - How well the classifier labels real turns. On 70 synthetic prompts, Jev and OpenAI labelled all 70 right; see
238
- [Evaluation](evaluation.md#activity-probe-set). The Usage tab's **Agreement** line checks your own turns against the
239
- tools they used.
240
- - Whether an effort change on the same model keeps the cache. We found only 6 cases. The router counts each
241
- (model, effort) pair as its own cache.
240
+ [Evaluation](evaluation.md#activity-probe-set). The **Agreement** lines, on the Usage tab for this session and on the
241
+ Classifier tab across sessions, check your own turns against the tools they used.
242
+ - Whether an effort change on the same model keeps the cache. We found only 6 cases. Claude Code's prompt-caching
243
+ docs say it does on the 5.5 models and Fable 5.1 with an API key or a subscription, and the router now prices it so.
242
244
  - How many requests a turn needs on each model.
243
245
 
244
246
  ## Sources
@@ -1,6 +1,6 @@
1
1
  # Architecture
2
2
 
3
- Claude Code owns the model request. The router Mod asks the active classifier (Jev by default; Cloudflare's Clef or Clef Flash; OpenAI; or a local Ollama model) for tier advice and, unless `activityRouting` is `off`, the turn's activity, applies local routing policy, and changes only the next main-conversation step's model and effort. Every subagent step passes through with Claude's model selection unchanged.
3
+ Claude Code owns the model request. The router Mod asks the active classifier (Jev by default; Cloudflare's Clef or Clef Flash; OpenAI; or a local Ollama model) for tier advice and, unless `activityRouting` is `off`, the turn's activity, applies local routing policy, and changes only the next main-conversation step's model and effort. Subagent steps pass through unchanged; `subagentRouting` may choose a subagent's model once, at `agent.spawn` (see [Subagents](#subagents)).
4
4
 
5
5
  ## Request flow
6
6
 
@@ -117,7 +117,17 @@ Nothing is recorded with `activityRouting: off`. Stats run inside a guard: a fai
117
117
 
118
118
  After each main reply, where the response is observed, `savings.mjs` prices the reply on the model that served it and the same tokens on "your model": the session's model and the effort Claude Code sent on the turn's first request. `compareModels` prices each reply against every model in `router.json` as "your model", at the session effort. Each keeps a simulated single cache in the loop under its models key in `yoursBy` (`{ total, at, onYours, model, effort }`), which a history reset clears; after an effort change the next reply finds it cold. The session's totals per model are `savingsBy` in the view, and `updateView` sets `savings` to the entry for the model `/model` selects whenever the model or the totals change, so a `/model` change re-prices the whole session without a replay. At turn completion the turn's totals against the model selected then are added to the session's own `$.store` key `savings:v1:<session id>` (replies, five sums and `since`), under the same reset guard as the activity stats. Each key has one writer, and Claude Code 2.1.296 writes one key under a file lock (observed in its code; the `$.store` types do not promise it), so sessions that finish turns at the same moment do not overwrite each other. The view's `savingsStore` adds up two parts: every other session's key, read at session start and when the pane opens, and this session's record, which the router reads once, holds in memory, adds each finished turn to and then writes, so a pane opened during that write counts the turn once. **Reset stats** first writes the time in `savings:reset:v1`, then deletes every such key and every activity metrics record. A record whose first reply is older than that time reads as empty, and each session reads the time before it adds a turn, so a session that still holds its record from before a Reset in another session drops it instead of writing it back. The comparison is by milliseconds: a record whose first reply has the reset's millisecond, or one written while the clock had moved back, still counts. A stored value of any other shape reads as empty. A reply with routing off or after an engine fallback is not counted, but it still moves your model's cache. A reply whose cache lifetime cannot be read loses its prices only, and your model's cache still follows it; a usage without rate limits prices writes at five minutes. No failure here fails the turn. [Evaluation](evaluation.md#routing-vs-your-model) gives the method and its limits.
119
119
 
120
- Subagent events pass directly to Claude Code. They do not create classifier requests or change main-conversation metrics. This is the selected scope because Mods do not expose whether a subagent model was explicit or inherited.
120
+ ### Subagents
121
+
122
+ 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.
123
+
124
+ - 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`.
125
+ - Workflow `agent()` calls raise `agent.spawn` with `e.workflow`, but a model rewrite there is ignored.
126
+ - The hook has 10 seconds of its own time. `$` calls do not count against it, but a `$.clock.sleep` does.
127
+
128
+ `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 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. In `on` that bounds how long a subagent waits to start. In `shadow` the spawn goes ahead at once and the decision is recorded when it lands; replies and a `turn.complete` that come first wait in a pending entry and are counted then. No advice, a missing key, or a model `availableModels` blocks keeps 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.
129
+
130
+ Every spawn in `shadow` and `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 the other side of the comparison: the decided model in `shadow`, and in `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 mode and 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 savings records: one writer per key, the readout `subagentStore` in the view is the sum, and the same reset marker applies. **Reset stats** clears them too.
121
131
 
122
132
  ## Classifier deadline and failure handling
123
133
 
@@ -129,7 +139,7 @@ In a 20-process loopback test, timeout fallback had 1,504 ms p95 and 1,505 ms wo
129
139
 
130
140
  ## Cache and cost
131
141
 
132
- Cache identity uses the exact response model ID and effective effort. The Haiku 4.5 dated snapshot has an explicit mapping; Haiku 5.5 has no dated ID. An unrecognized substituted model gets no cache credit for the requested route.
142
+ Cache identity uses the exact response model ID, plus the effective effort on models that keep one cache per effort. Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 keep one cache across efforts with an API key or a Claude subscription (code.claude.com/docs/en/prompt-caching, "Changing effort level"), so an effort-only move costs no cache write there. The hook gives every effort its own cache when the session runs on Amazon Bedrock, Google Cloud, Microsoft Foundry, a custom `ANTHROPIC_BASE_URL`, or with `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` (`effortSplitsCache`). A HIPAA configuration is not visible to a Mod; there the router prices effort moves as free. The Haiku 4.5 dated snapshot has an explicit mapping; Haiku 5.5 has no dated ID. An unrecognized substituted model gets no cache credit for the requested route.
133
143
 
134
144
  The cached prefix is observed `cache_read + cache_creation`. Output tokens count only toward the next context size. Freshness uses the configured five-minute lifetime with its safety margin. Claude's usage counters do not prove one-hour cache lifetime.
135
145
 
@@ -10,7 +10,7 @@ The router works with its built-in defaults. Configure the key of the active cla
10
10
  | Cloudflare API token | Sensitive plugin option `cloudflare_api_token` | The same dialog. Used by Clef and Clef Flash. |
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. |
13
- | Router settings and classifier | `router.json` in the active Claude Code profile | Edit the file directly, or use the pane's Routing and Classifier tabs. |
13
+ | Router settings and classifier | `router.json` in the active Claude Code profile | Edit the file directly, or use the pane's Routes, Policy and Classifier tabs. |
14
14
  | Anthropic credentials and API cost | Claude Code | The Mod leaves these to Claude Code. |
15
15
 
16
16
  The active profile directory is `CLAUDE_CONFIG_DIR` when set. Otherwise it is `~/.claude`. The Mod does not need an Anthropic proxy URL, model alias, hint header, daemon, or custom status line.
@@ -90,7 +90,7 @@ The built-in overrides run only with `activityRouting: "on"`. A `·` cell uses t
90
90
  - `ops` at `medium` runs on Haiku at `high`. Command runs last long enough for Haiku to repay its cache write: about 4 requests from Opus at 350,000 tokens of context, against a median run of 6 to 11 requests in one developer's sessions. Haiku is weaker on multi-step tool work (OSWorld 2.1: about 61% against 79% for Opus at `medium`), so `ops` at `high` stays on Opus, and repeated tool errors move an `ops` turn to the `high` route.
91
91
  - `explore` and `docs` keep the base routes: moving them saved nothing in that replay, and Haiku scores lower on research benchmarks (Humanity's Last Exam with tools: 50.1% against 63.0% for Opus at `medium`).
92
92
 
93
- These are vendor benchmarks and a list-price replay, not measurements of this router, and they are not a claim of equal quality. The overrides add one (model, effort) pair the base routes do not use, Sonnet at `high`. The router counts each pair as its own cache, so activity routing adds one. [Activity routing](activity-routing.md) has the evidence per cell and its limits.
93
+ These are vendor benchmarks and a list-price replay, not measurements of this router, and they are not a claim of equal quality. The overrides add one (model, effort) pair the base routes do not use, Sonnet at `high`. It is the only route on Sonnet, so activity routing adds one cache. [Activity routing](activity-routing.md) has the evidence per cell and its limits.
94
94
 
95
95
  A user file merges over these overrides one field at a time, as `routes` does. This sets only the effort of the built-in `code` override at `low`, so the cell runs Sonnet at `xhigh`, and adds a new override at `high`:
96
96
 
@@ -109,16 +109,16 @@ An override for a cell with no built-in names both fields, or inherits the missi
109
109
  ```
110
110
 
111
111
  - `effort: null` keeps the session effort, as in `routes`.
112
- - A cell cannot be `null`. To drop a built-in override, set it to the base route, for example `"ops": { "medium": { "model": "opus", "effort": "medium" } }`. The pane writes this for you when you remove an override. The cell keeps that route if you later change the tier's route; remove it again then.
112
+ - A cell cannot be `null`. To drop a built-in override, set it to the base route, for example `"ops": { "medium": { "model": "opus", "effort": "medium" } }`. The pane writes this for you when you press **Use tier model** on a built-in cell. The cell keeps that route if you later change the tier's route; drop it again then.
113
113
  - An override applies to whatever the tier's route is. If you move `routes.low` to Opus, the built-in `code` override at `low` still runs Sonnet. Set it to match, or remove it.
114
114
  - Unknown activities and tiers, unknown model aliases, and invalid efforts make the file invalid, like any other invalid setting. The pane refuses to save one and names it, such as `activities.code.low.model is not in models`.
115
- - The router counts each distinct (model, effort) pair as its own cache. The Routing tab counts them.
115
+ - The Routes tab counts the prompt caches the routes use: one per model on Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1, one per (model, effort) pair on a provider that caches each effort apart.
116
116
 
117
- `policy.activityMass` (default `0.6`) is the lowest probability at which an activity applies. The Routing tab sets it as **Activity threshold** under POLICY, from 50% to 80%. It has not been tuned on any classifier, and the probe results do not record probabilities, so there is no data to tune it on yet.
117
+ `policy.activityMass` (default `0.6`) is the lowest probability at which an activity applies. The Policy tab sets it under **Activities**, from 50% to 80%. It has not been tuned on any classifier, and the probe results do not record probabilities, so there is no data to tune it on yet.
118
118
 
119
- Switch the mode with `/router activities off|shadow|on`, or with the **Activity routing** selector at the top of the Routing tab's ACTIVITIES section. The command writes `router.json` at once; the selector joins the Routing draft and writes on **Save**. Choosing `on`, the default, removes the key from the file.
119
+ Switch the mode with `/router activities off|shadow|on`, or with the **Activity routing** selector at the top of the Routes tab. The command writes `router.json` at once; the selector joins the routing draft and writes on **Save**. Choosing `on`, the default, removes the key from the file.
120
120
 
121
- **Upgrade from 1.6.** 1.6 defaulted to `shadow` with Sonnet at `medium` in every override. A file without `activityRouting` now runs `on`; a file that sets it keeps its mode. Choosing `shadow` in 1.6 removed the key, because `shadow` was the default then: if you chose `shadow` in 1.6, run `/router activities shadow` again after upgrading. A session started on Sonnet 5.5 now starts with routing on, because Sonnet runs the `code` cell at `low`; to stay on Sonnet in that session, choose it with `/model` or run `/router off`, and run `/router activities shadow` to make future Sonnet sessions start with routing off. Cells you saved stay as written. A cell that sets one field takes the other from 1.7's built-in for that cell, or from the base route where 1.7 has none (`explore` and `docs` at `medium`, `docs` at `low`). 1.6's overrides in those cells and in `ops` at `medium` were Sonnet · medium, so such a cell can now run another model or effort; write both fields to keep 1.6's route. A 1.6 removal of a built-in that 1.7 no longer has, such as `docs` at `low`, stays in the file as the tier's route; the pane lists it as "same as base: no effect", and **remove** drops it.
121
+ **Upgrade from 1.6.** 1.6 defaulted to `shadow` with Sonnet at `medium` in every override. A file without `activityRouting` now runs `on`; a file that sets it keeps its mode. Choosing `shadow` in 1.6 removed the key, because `shadow` was the default then: if you chose `shadow` in 1.6, run `/router activities shadow` again after upgrading. A session started on Sonnet 5.5 now starts with routing on, because Sonnet runs the `code` cell at `low`; to stay on Sonnet in that session, choose it with `/model` or run `/router off`, and run `/router activities shadow` to make future Sonnet sessions start with routing off. Cells you saved stay as written. A cell that sets one field takes the other from 1.7's built-in for that cell, or from the base route where 1.7 has none (`explore` and `docs` at `medium`, `docs` at `low`). 1.6's overrides in those cells and in `ops` at `medium` were Sonnet · medium, so such a cell can now run another model or effort; write both fields to keep 1.6's route. A 1.6 removal of a built-in that 1.7 no longer has, such as `docs` at `low`, stays in the file as the tier's route; its cell on the Routes tab says "same as the tier’s model: no effect", and **Use tier model** drops it.
122
122
 
123
123
  **Rollback.** To go back to 1.6 behavior without downgrading, set `"activityRouting": "shadow"`, or `off`. Router 1.6 reads the same keys; under 1.6 a file without `activityRouting` runs `shadow` with 1.6's overrides. Router 1.5 rejects unknown keys and makes routing unavailable. Before you install 1.5 again, remove `activities`, `activityRouting`, and `policy.activityMass` from `router.json`. The pane writes them when you set the mode to `off` or `shadow`, change the activity threshold, or edit or remove an override.
124
124
 
@@ -171,6 +171,62 @@ To check a classifier outside Claude Code, run `node scripts/probe-classifier.mj
171
171
 
172
172
  `ollama` needs no key and keeps the text on this machine. Run `ollama serve`, pull the model named in `model`, and select the classifier. `model` is any tag you have pulled, such as `qwen3.5:9b`; change it under `classifiers.ollama.model`. The endpoint must stay on `localhost`, `127.0.0.1`, or `[::1]`, so a server on another machine on your network is not reachable through this entry. Each request turns thinking off. The activity is a second request, sent after the route answer parses and only when at least 300 ms of the deadline remain; if it fails, the turn keeps the running activity and the classifier is not counted as failed. If Ollama rejects that setting for a model, the request fails and the router keeps the baseline. Ollama unloads an idle model after its keep-alive period, and the first request after that can exceed `timeoutMs` while the model loads; the router then keeps the baseline for that turn.
173
173
 
174
+ ## Subagent routing
175
+
176
+ `subagentRouting` gives each subagent one model when it starts, as the router gives each main turn one. It never changes the model between a subagent's steps: that would rewrite its context cold. With `CLAUDE_CODE_SUBAGENT_MODEL=sonnet`, agents that name no model already run on Sonnet. The router chooses per task instead: Haiku for exploration, Opus only for clearly hard work, Sonnet for the rest. It also routes the built-in Explore and Plan agents, which ignore that variable.
177
+
178
+ | `subagentRouting` | Behavior |
179
+ | ----------------- | --------------------------------------------------------------------------------------------------- |
180
+ | `off` | Asks nothing, records nothing. Every agent runs on the model Claude Code gives it. |
181
+ | `shadow` | Decides and records the choice and its list-price cost in the Usage tab; the agent runs unchanged. |
182
+ | `on` | The default. Sends the decided model, which Claude Code uses in place of the agent's own. |
183
+
184
+ **Which agents are routed.** The router reads the definition file of the agent being started: a plugin agent's file under the plugin's install path, a project agent's under `.claude/agents`, your own under `~/.claude/agents`. It routes the agent when its frontmatter:
185
+
186
+ - names no `model`;
187
+ - says `model: inherit`, which means "the main conversation's model", and the router routes that too;
188
+ - or sets `modelRouting: auto`. The agent's `model` is then what it runs on without the router.
189
+
190
+ An agent whose `model` names a model, such as `model: haiku`, keeps it. The Usage tab counts it as `pinned`. An agent whose file the router cannot find or read keeps its model as `unknown`; so does a plugin that keeps its agents outside `agents/`. Claude Code ignores frontmatter keys it does not know, so `modelRouting: auto` changes nothing without the router. To let the router choose a pinned agent's model, add the key to the agent's frontmatter:
191
+
192
+ ```yaml
193
+ ---
194
+ name: runner
195
+ model: haiku # without the router
196
+ modelRouting: auto # the router may choose
197
+ ---
198
+ ```
199
+
200
+ These agents always keep their model:
201
+
202
+ - a fork;
203
+ - an Agent call that names a `model`;
204
+ - a teammate;
205
+ - a workflow `agent()`: Claude Code ignores a rewrite of its model, so workflow agents get only `CLAUDE_CODE_SUBAGENT_MODEL`;
206
+ - a built-in agent other than Explore, Plan and general-purpose: its definition is not on disk.
207
+
208
+ ```json
209
+ {
210
+ "subagentRouting": "on",
211
+ "subagents": {
212
+ "types": { "Explore": "haiku", "Plan": "classify", "general-purpose": "classify" },
213
+ "light": "haiku",
214
+ "standard": "sonnet",
215
+ "heavy": "opus",
216
+ "heavyMass": 0.8
217
+ }
218
+ }
219
+ ```
220
+
221
+ The values above are the defaults.
222
+
223
+ - `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.
224
+ - `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; `shadow` never delays a spawn.
225
+ - A classifier failure or a missing key keeps the model Claude Code gives the agent, and so does a model that `availableModels` blocks. So does routing off: `/router off`, or a `/model` choice.
226
+ - A spawn sets a model, not an effort. An agent's `effort` frontmatter still applies.
227
+
228
+ The Usage tab's **SUBAGENTS** section shows, per agent type, what routing cost against the model Claude Code would have used, and which agents passed through and why. [Evaluation](evaluation.md#subagent-routing) says what to look for. To compare before you trust it, set `"subagentRouting": "shadow"`. To stop it, set `"off"`. Router 1.8 rejects both keys as unknown, so remove `subagentRouting` and `subagents` before you downgrade. Subagent routing needs the `agent.spawn` hook: it is checked on Claude Code 2.1.293 and 2.1.296, and unverified on older builds.
229
+
174
230
  ## Optional `router.json`
175
231
 
176
232
  Start with the setting you need and leave the rest at defaults. For example, require three votes before moving to a cheaper tier and allow Jev up to two seconds:
@@ -196,6 +252,8 @@ The Mod validates the whole file. Unknown keys and invalid values make routing u
196
252
  | `classifier` | An id in `classifiers` | `jev` |
197
253
  | `classifiers.<id>` | `label`, `api`, `endpoint`, `model`, `keyOption`, `timeoutMs` | [Classifiers](#classifiers) above |
198
254
  | `context` | `recentTurns`, `maxTextChars` | `6`, `1200` |
255
+ | `subagentRouting` | `off`, `shadow`, `on` | `on` |
256
+ | `subagents` | `types` (type → models key, `classify` or `null`), `light`, `standard`, `heavy`, `heavyMass` | [Subagent routing](#subagent-routing) |
199
257
 
200
258
  Policy defaults:
201
259
 
@@ -216,7 +274,9 @@ Policy defaults:
216
274
  | `cashCapUsd` | `2` | Maximum estimated cold cache write for a `credits` model. It does not cap output or session spend. |
217
275
  | `activityMass` | `0.6` | Minimum probability for the classifier's activity to apply. Not tuned on any classifier. |
218
276
 
219
- The pane writes a subset of these settings. The **Routing** tab sets `routes`, `baselineTier`, `activities`, `activityRouting`, `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.
277
+ 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.
278
+
279
+ 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.
220
280
 
221
281
  Native cache freshness is unknown after 270 seconds or after a history reset. Claude usage does not report the cache TTL. The policy evaluates price bounds for five-minute and one-hour writes, but the one-hour case is not observed fact. See the [architecture](architecture.md#cache-and-cost) for the estimate rules.
222
282
 
@@ -115,7 +115,7 @@ The Usage tab compares what routed replies cost with what the same tokens would
115
115
  Method, per main reply that routing chose:
116
116
 
117
117
  - **Routed** prices the usage Claude reported (uncached input, cache read, cache write, output) on the model that served it.
118
- - **Yours** prices the same tokens on each model in `router.json` at the session effort, and the readout shows the one `/model` selects now, so a `/model` change shows the whole session against the new model. While this reply and the one before it ran on that model's route, it is the reply's own usage, so a session on your model differs by exactly $0.00. Otherwise each model keeps one cache that never switched: it reads the previous prompt, up to this one less its uncached input, inside the cache lifetime, unless a compaction shrank the history or the effort changed since, and never less than the API actually read; it writes the rest. Output tokens are the same. The totals kept across sessions price each reply against the model selected when it ran.
118
+ - **Yours** prices the same tokens on each model in `router.json` at the session effort, and the readout shows the one `/model` selects now, so a `/model` change shows the whole session against the new model. While this reply and the one before it ran on that model's route, it is the reply's own usage, so a session on your model differs by exactly $0.00. Otherwise each model keeps one cache that never switched: it reads the previous prompt, up to this one less its uncached input, inside the cache lifetime, unless a compaction shrank the history or, on a model that keeps one cache per effort, the effort changed since, and never less than the API actually read; it writes the rest. Output tokens are the same. The totals kept across sessions price each reply against the model selected when it ran.
119
119
  - **Parts**: the served model on your cache against yours is the model price, under cheaper models when negative and stronger than yours when positive; routed against the served model on your cache is the cache the switches cost, never negative. They sum to the difference. The pane rounds to cents and gives the remainder only to a part that is not zero: a surplus to the switch part, else the stronger part, else the cheaper part toward $0.00; a shortfall comes off the stronger part, down to $0.00, then the cheaper part. The shown parts add up, none changes sign, and none appears from rounding alone.
120
120
  - **Prices**: `router.json` list prices through `ratesAt`, so Haiku 5.5 above 100,000 prompt tokens is priced at 5x. Claude Code reports no 5m/1h split to a Mod, so cache writes use the lifetime Claude Code 2.1.296 gives the main conversation by its own rule: one hour on a Claude plan unless an environment variable or the `promptCacheTtl` setting says otherwise, five minutes with an API key.
121
121
 
@@ -130,10 +130,46 @@ Limits:
130
130
  - Output length is held the same. A stronger model may write less, or finish in fewer tool steps; a cheaper one may need more. The readout cannot see either.
131
131
  - Answer quality is not measured. A saving bought with worse answers would read the same.
132
132
  - Your model's cache is simulated, and a five-minute session that the lifetime rule takes for one hour (a plan subscriber billed as overage) would read too much cache on your side.
133
- - A route that changes only the effort costs the same per token; it shows only its cache writes.
134
- - Subagents, classifier charges and replies with routing off are not counted. On a Claude plan the dollars stand for quota, not cash.
133
+ - A route that changes only the effort costs the same per token. On Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 it shares your cache and reads $0.00; on a provider that caches each effort apart, it shows its cache writes.
134
+ - Subagents (see [Subagent routing](#subagent-routing)), classifier charges and replies with routing off are not counted. On a Claude plan the dollars stand for quota, not cash.
135
135
  - The saved column keeps one record per session, so sessions finishing turns at the same moment both count. Claude Code's store has no atomic update, which leaves these gaps: the same session open in two Claude Code processes at once can lose one's turn; a turn finishing in another process during **Reset stats** can be lost; a session's total from before a reset comes back if its first saved reply has the same millisecond as the reset, or if the system clock moved back across the reset; and the activity counts across sessions are still one shared record, where two sessions finishing turns at the same moment can lose one turn's counts. The router reads every session's record at session start and when the pane opens, so that read grows with the number of sessions since the last reset.
136
136
 
137
+ ## Subagent routing
138
+
139
+ Subagent routing has no measured result over time yet. It is `on` by default since 1.9; `shadow` makes and records the decision while the agent runs on the model Claude Code gives it. The Usage tab's **SUBAGENTS** section shows the counts kept across sessions since the last reset:
140
+
141
+ - Per routed type and mode: 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.
143
+
144
+ Method:
145
+
146
+ - In `shadow`, `core` prices each reply on the model it ran on, and `routed` prices the same tokens on the decided 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
+ - In `on`, `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.
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.
149
+ - Shadow cannot see quality. The decided model never ran, so a retry or an escalation it would have caused is invisible. Two proxies are recorded in both modes, so an `on` period can be compared with the shadow baseline: requests per agent, and **respawns**, a spawn of the same type by the same parent within 10 minutes after one finished.
150
+
151
+ Checks:
152
+
153
+ - `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 `shadow` (no change, decision recorded), `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, Reset stats and the Usage tab.
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.
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.
156
+
157
+ When to turn it `on`:
158
+
159
+ - `routed` is below `core` for the routed types, by enough to matter;
160
+ - the choices look right for the tasks: `light` for searches and reads, `heavy` rarely;
161
+ - **Not routed** leaves enough routable spend to bother.
162
+
163
+ With `on`, keep it if requests per agent and respawns per type stay no higher than in a `shadow` week. Otherwise go back to `shadow` and change `types` or `heavyMass`, or exclude a type with `null`.
164
+
165
+ Limits:
166
+
167
+ - Answer quality is not measured.
168
+ - 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.
169
+ - `on` estimates core's model. It does not apply the family-alias rule or the `availableModels` substitution.
170
+ - Respawns are a proxy. A parent may spawn the same type twice on purpose.
171
+ - Records follow the savings records' storage, with the same gaps.
172
+
137
173
  ## Historical method and limits
138
174
 
139
175
  - Costs use configured USD list prices per million tokens. They are not subscription cash charges.
@@ -1,6 +1,6 @@
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 original model and effort.
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)).
4
4
 
5
5
  ## Turn behavior
6
6
 
@@ -29,24 +29,24 @@ Mode belongs to a Claude Code session. Clear starts a new session with routing o
29
29
 
30
30
  ## Router pane
31
31
 
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 and does not describe subagent transcripts. 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 four tabs, Now, Routing, Classifier, and Usage, with the routing on/off pair at the top of every tab. The [user guide](user-guide.md#open-the-router-pane) describes each tab.
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 or in shadow. 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
33
 
34
34
  | Reading | Meaning and limits |
35
35
  | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
36
- | Now / Served | The requested model and effort. **Served** appears only when the engine answered with another model. Actual effort is not reported. |
37
- | Classifier support | Per-tier probabilities from the last classification, and the switch bar the policy required. Pins and skipped calls leave it empty. |
38
- | Activity | The classifier's activity choice with its share and the two next-best answers. Empty with routing off, a pin, or no answer. |
39
- | Route (activity) | With `on`: the route for the tier and activity, marked `(override)` with the base route beside it, or `(base)`. With `shadow`: what `on` would use, and the route in use (`shadow; same route` when they agree). |
40
- | Replies | The tier that served each of the last 30 main-conversation replies; a dot where the router did not choose. A second row of letters names each reply's activity: `c` code, `d` debug, `e` explore, `p` plan, `r` review, `o` ops, `w` docs. |
36
+ | Next turn / Served | The requested model and effort, with the tier's own model beside an activity override. **Served** appears only when the engine answered with another model. Actual effort is not reported. |
37
+ | Classifier support | Per-tier probabilities from the last classification; under **Why**, the support for the switch against the bar the policy required, and the switch cost. Pins and skipped calls leave it empty. |
38
+ | Activity | The classifier's activity choice as a verb with its share, the two next-best answers, and the threshold at which an activity applies; `uncertain` shown dim. Empty with routing off, a pin, or no answer. |
39
+ | Shadow (activity) | With `shadow`: what `on` would use, and the route in use (`shadow; same route` when they agree). |
40
+ | Last replies | The tier that served each of the last 30 main-conversation replies, a dot where the router did not choose, the model switches between them, and the replies per tier and per activity. |
41
41
  | Routing vs your model (Usage) | Routed replies at configured list prices against the same tokens on your model (the model `/model` selects now, at the session effort; after a `/model` change, the whole session against the new one), this session and since the last reset (each reply against the model selected when it ran); the session against the other configured models; the difference split into cheaper models, stronger than yours, and cache writes from switches. `too early` below 10 replies. Output length is held the same; answer quality is not measured. |
42
- | Activity stats (Usage) | Counts for this session: turns, requests and share per activity, its `est. cost` at configured list prices (`—` unless every reply had a price) and the route it was `mostly on`; switches by tier and by activity, and activity moves refused in `on`; tool agreement; in `shadow`, turns `on` would route differently with their summed next-request estimate at configured list prices. |
43
- | Across sessions (Usage) | The counts kept since the last reset: labelled turns, tool agreement on the classifier's raw answer, overall and for `code`, `ops` and `explore`, the two largest mismatches, activity moves inside a tier taken and refused, escalations after a cheaper activity move, the active classifier's p95 latency, and the shadow readout. `/router` text shows the agreement. |
42
+ | By activity (Usage) | Counts for this session: turns, requests and share per activity, its `est. cost` at configured list prices (`—` unless every reply had a price) and the route it was `mostly on`; switches by tier and by activity, and activity moves refused in `on`; tool agreement; in `shadow`, turns `on` would route differently with their summed next-request estimate at configured list prices. |
43
+ | Across sessions (Classifier) | The counts kept since the last reset: labelled turns, tool agreement on the classifier's raw answer, overall and for `code`, `ops` and `explore`, the two largest mismatches, activity moves inside a tier taken and refused, escalations after a cheaper activity move, and the shadow readout. The active classifier's p95 latency shows on its **Deadline** line. `/router` text shows the agreement. |
44
44
  | Cost | Claude Code's native usage value. A plan's list-price estimates are not subscription cash charges. |
45
45
  | Context bar | Maximum available observed and local estimated context, compared with the routed model's window. The fit rule reserves 20%. |
46
- | Observed / estimated input | Claude's local context reading and the router's best current context estimate. `unknown` blocks a move to a smaller window. |
46
+ | Observed / estimated input | Under **details** on Usage: Claude's local context reading and the router's best current context estimate. `unknown` blocks a move to a smaller window. |
47
47
  | Cache reuse | Last response's cache-read tokens divided by its reported input counters. |
48
48
  | Cache read / written; Output | Response usage counters. Cache warmth does not prove a particular TTL. |
49
- | Input per reply | Up to 30 observed main-conversation input sizes, scaled from the lowest to the highest reading. |
49
+ | Input per reply | Under **details** on Usage: up to 30 observed main-conversation input sizes, scaled from the lowest to the highest reading. |
50
50
  | Classifier header | Active classifier state and elapsed time. Missing-key, missing-account, busy, and paused skips have no network latency reading. |
51
51
  | Next-turn difference | Configured-price range for the suggested tier versus the incumbent on the next request. Negative means estimated lower cost. |
52
52
  | Conservative payback | Conditional later-turn estimate based on configured cache prices, future reads, and the last output size. It is not measured savings. |
@@ -56,7 +56,7 @@ The router keeps no bill. Routing vs your model is a configured-price estimate,
56
56
 
57
57
  ## Routing and classifier settings
58
58
 
59
- The Routing tab edits each tier's model alias and effort, the baseline tier, the activity overrides and mode, and four policy controls as one draft. The draft does not affect the active turn, survives a tab change or closing the pane, and is dropped at a new session. **Save** validates the whole file with the same loader the Mod starts with, writes `router.json` for future turns, and keeps unrelated keys. A route, activity override, or policy value equal to the built-in default is removed from the file, so later default changes still reach it. The Classifier tab writes the classifier choice and its deadline at once, and shows each classifier's last checked-in activity probe on the model it ran, from `lib/probe-results.mjs`. **Undo** reverts the settings the last pane write changed, from any tab, until the next write or a new session.
59
+ The Routes tab edits each tier's model alias and effort, the activity overrides and mode; the Policy tab edits the baseline tier and four policy controls. Both share one draft. The draft does not affect the active turn, survives a tab change or closing the pane, and is dropped at a new session. **Save** validates the whole file with the same loader the Mod starts with, writes `router.json` for future turns, and keeps unrelated keys. A route, activity override, or policy value equal to the built-in default is removed from the file, so later default changes still reach it. The Classifier tab writes the classifier choice and its deadline at once, and shows each classifier's last checked-in activity probe on the model it ran, from `lib/probe-results.mjs`, as columns beside its host and status. **Undo** reverts the settings the last pane write changed, from any tab, until the next write or a new session.
60
60
 
61
61
  | Control | Values in the pane | Effect |
62
62
  | ------------------ | ---------------------------------- | ---------------------------------------------------------------------------------------- |
@@ -66,9 +66,9 @@ The Routing tab edits each tier's model alias and effort, the baseline tier, the
66
66
  | Credits cap | $0.50, $1, $2, $5 | Largest estimated cold write on a `credits` model. |
67
67
  | Activity threshold | 50%, 60%, 70%, 80% | `policy.activityMass`: the least probability at which an activity applies. |
68
68
 
69
- Under the routes, **ACTIVITIES** starts with the **Activity routing** selector, `off · shadow · on`, and a hint for the mode. Below it is the effective matrix of the draft: one row per distinct set of cells, `·` where a cell uses the base route, routes abbreviated such as `S·high` for Sonnet · high, and the count of distinct routes, each counted as its own cache. Until the mode is `on` the count carries `once activity routing is on`. **OVERRIDES** reads `in use`, or in yellow `not in use:` with the reason: activity routing is `shadow` or `off`, routing is off, or routing is unavailable. Each override is a row with a model, an effort, and **remove**, and a selector adds one for a free activity and tier. A removed built-in override is saved as the tier's own route, because a file that only omitted it would get the built-in back. Yellow notes flag an override equal to its base route, one stronger than the tier above, and the only cell or tier on its (model, effort) pair, which adds a cache. **Reset routes to defaults** resets the routes only; pending override and mode edits stay in the draft. The Usage tab's **ACTIVITY** table adds each activity's `est. cost`, its replies at list prices, and the route it was `mostly on`; **ACROSS SESSIONS** adds the escalations after a cheaper activity move and the active classifier's p95 latency. The Usage tab's **Reset stats** clears the activity counts and routing vs your model, for this session and across sessions.
69
+ The Routes tab starts with the **Activity routing** selector, `off · shadow · on`, and a hint for the mode, and a yellow line when the overrides do not run: activity routing is `shadow` or `off`, routing is off, or routing is unavailable. Below it is one grid of the draft: a column per tier, the **every turn** row with each tier's own route, and a row per activity whose cells show the route it runs (`models key·effort`, such as `sonnet·high`), `·` for the tier's route, `°` for a built-in default, and **●** for an unsaved edit. Each cell is a plain Button; selecting one opens its editor under the grid: a model and an effort Select, the cell's state, **Use tier model** to drop an override, and **Restore default** for a changed or dropped built-in one. A dropped built-in override is saved as the tier's own route, because a file that only omitted it would get the built-in back. Yellow notes flag a cell stronger than the tier above, and the only cell on its cache, which adds one; a cell equal to its tier's route but saved in the file says `no effect`. A line counts the prompt caches the routes use, one per model where efforts share a cache and one per (model, effort) pair where they do not, counting only tier routes until the mode is `on`, and another flags two neighbouring tiers with the same route. **Reset routes to defaults** resets the tier routes and the baseline tier; pending override and mode edits stay in the draft. The Policy tab writes each control inside its sentence and names the default beside a changed value, and ends with the `subagentRouting` mode, which is set in `router.json`. The Usage tab's **BY ACTIVITY** table adds each activity's `est. cost`, its replies at list prices, and the route it was `mostly on`; the Classifier tab's **ACROSS SESSIONS** adds the escalations after a cheaper activity move. The Usage tab's **Reset stats** clears the activity counts and routing vs your model, for this session and across sessions.
70
70
 
71
- The classifier section lists every configured classifier as a row with its service host and whether its key and endpoint settings are complete. Selecting a row writes `classifier` to `router.json` at once, or removes it for the default, through the same validation, and resets the new classifier's failure count. A turn already being classified finishes with its own classifier; its readings stay off the pane. **Undo** returns to the previous classifier. The deadline saves at once too, and a built-in classifier's default deadline is written as no override. **Sends** names the host that receives prompt text.
71
+ The Classifier tab lists every configured classifier as a row with its service host (`this machine` for a local one), its activity probe and p95 wait, and whether its key and endpoint settings are complete. Selecting a row writes `classifier` to `router.json` at once, or removes it for the default, through the same validation, and resets the new classifier's failure count. A turn already being classified finishes with its own classifier; its readings stay off the pane. **Undo** returns to the previous classifier. The deadline saves at once too, and a built-in classifier's default deadline is written as no override. **Sends** names the host that receives prompt text. The **Deadline** line shows the active classifier's p95 wait across sessions, or its probe's before any turn, in yellow when it is slower than the deadline.
72
72
 
73
73
  The pane refuses to write through a symlink. A failed validation names the setting and leaves the file unchanged. New model aliases and the other supported fields need an edit to the active profile's `router.json`.
74
74