@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.
- package/.claude-plugin/plugin.json +2 -2
- package/CHANGELOG.md +25 -0
- package/README.md +7 -3
- package/docs/activity-routing.md +22 -20
- package/docs/architecture.md +13 -3
- package/docs/configuration.md +68 -8
- package/docs/evaluation.md +39 -3
- package/docs/native-router.md +14 -14
- package/docs/router-pane-classifier.svg +82 -63
- package/docs/router-pane-now.svg +95 -109
- package/docs/router-pane-policy.svg +70 -0
- package/docs/router-pane-routes.svg +103 -0
- package/docs/router-pane-usage.svg +100 -124
- package/docs/user-guide.md +58 -43
- package/hooks/native-router.mjs +343 -34
- package/lib/band.mjs +10 -1
- package/lib/classifier-client.mjs +6 -3
- package/lib/config.mjs +37 -1
- package/lib/cost.mjs +14 -3
- package/lib/display.mjs +10 -25
- package/lib/panel.mjs +707 -425
- package/lib/route.mjs +2 -2
- package/lib/savings.mjs +11 -3
- package/lib/subagents.mjs +280 -0
- package/lib/view.mjs +2 -0
- package/package.json +1 -1
- package/types/index.d.ts +34 -1
- package/docs/router-pane-routing.svg +0 -151
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "router",
|
|
3
3
|
"displayName": "Router",
|
|
4
|
-
"version": "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).
|
|
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.
|
|
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
|
package/docs/activity-routing.md
CHANGED
|
@@ -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.
|
|
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
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
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 **
|
|
159
|
-
the pane, which writes that for you. The cell keeps that route if you later change the tier's route;
|
|
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
|
|
189
|
-
|
|
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`,
|
|
210
|
-
"same as
|
|
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
|
|
239
|
-
tools they used.
|
|
240
|
-
- Whether an effort change on the same model keeps the cache. We found only 6 cases.
|
|
241
|
-
|
|
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
|
package/docs/architecture.md
CHANGED
|
@@ -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.
|
|
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
|
-
|
|
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
|
|
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
|
|
package/docs/configuration.md
CHANGED
|
@@ -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
|
|
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`.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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 **
|
|
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
|
|
package/docs/evaluation.md
CHANGED
|
@@ -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
|
|
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.
|
package/docs/native-router.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
-
|
|
|
37
|
-
| Classifier support | Per-tier probabilities from the last classification
|
|
38
|
-
| Activity | The classifier's activity choice with its share
|
|
39
|
-
|
|
|
40
|
-
|
|
|
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
|
-
|
|
|
43
|
-
| Across sessions (
|
|
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 |
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|