@alexeiled/claude-router 1.9.0 → 1.10.1
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 +1 -1
- package/CHANGELOG.md +22 -0
- package/README.md +3 -3
- package/docs/activity-routing.md +35 -34
- package/docs/architecture.md +5 -7
- package/docs/configuration.md +25 -23
- package/docs/evaluation.md +8 -9
- package/docs/native-router.md +15 -16
- package/docs/router-band.svg +3 -21
- 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 -127
- package/docs/user-guide.md +63 -49
- package/hooks/native-router.mjs +20 -50
- package/lib/activity-stats.mjs +21 -70
- package/lib/band.mjs +3 -6
- package/lib/config.mjs +11 -8
- package/lib/cost.mjs +3 -3
- package/lib/display.mjs +14 -41
- package/lib/panel.mjs +651 -477
- package/lib/route.mjs +4 -53
- package/lib/subagents.mjs +12 -17
- package/lib/view.mjs +3 -3
- package/package.json +1 -1
- package/types/index.d.ts +10 -36
- package/docs/router-pane-routing.svg +0 -150
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "router",
|
|
3
3
|
"displayName": "Router",
|
|
4
|
-
"version": "1.
|
|
4
|
+
"version": "1.10.1",
|
|
5
5
|
"description": "Model and effort routing for the main conversation by task difficulty and activity, advised by a prompt classifier (Jev, Clef, Clef Flash, OpenAI or local Ollama). Subagents get one model at spawn: every agent that does not pin one.",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "Alexei Ledenev",
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,27 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.10.1 (2026-10-11)
|
|
4
|
+
|
|
5
|
+
### Removed
|
|
6
|
+
|
|
7
|
+
- `shadow` mode, from both `activityRouting` and `subagentRouting`. Each now takes `off` or `on`. A `router.json` that still sets `"shadow"` is read as not setting the key, so the default, `on`, runs; the next save from the pane drops it. To keep the base routes, set `off`. `/router activities` takes `off` or `on`. Gone with it: the Shadow line on the Now tab, the `(shadow)` label on the band, the "if activity routing were on" estimate and the Shadow counts on the Usage and Classifier tabs, and the shadow section of SUBAGENTS.
|
|
8
|
+
- Counts kept across sessions drop their shadow figures and keep the rest. After running this version, 1.10.0 or earlier resets the activity counts kept across sessions.
|
|
9
|
+
|
|
10
|
+
## 1.10.0 (2026-10-10)
|
|
11
|
+
|
|
12
|
+
### Changed
|
|
13
|
+
|
|
14
|
+
- 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.
|
|
15
|
+
- **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.
|
|
16
|
+
- **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.
|
|
17
|
+
- **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`.
|
|
18
|
+
- **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.
|
|
19
|
+
- **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**.
|
|
20
|
+
|
|
21
|
+
### Fixed
|
|
22
|
+
|
|
23
|
+
- The Now picture in the docs showed `0 switches` next to a strip with three tier changes.
|
|
24
|
+
|
|
3
25
|
## 1.9.0 (2026-10-10)
|
|
4
26
|
|
|
5
27
|
### Added
|
package/README.md
CHANGED
|
@@ -9,7 +9,7 @@ The Mod changes only the model and effort in Claude Code's turn hook. Claude Cod
|
|
|
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. With subagent routing `on` (the default)
|
|
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), 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
|
| ---------- | ------------------------------------------ | ----------------------------------- | ------------------------- | --------------------------------------------------------------------- |
|
|
@@ -39,7 +39,7 @@ sequenceDiagram
|
|
|
39
39
|
Dev->>Code: Prompt
|
|
40
40
|
opt Subagent spawn
|
|
41
41
|
Code->>Mod: agent.spawn
|
|
42
|
-
Mod-->>Code: One model for the agent (on), or none (
|
|
42
|
+
Mod-->>Code: One model for the agent (on), or none (off)
|
|
43
43
|
end
|
|
44
44
|
Code->>Mod: Main or subagent step
|
|
45
45
|
alt Main conversation, routing on
|
|
@@ -74,7 +74,7 @@ Activity routing adds a second label: what the turn produces (`code`, `debug`, `
|
|
|
74
74
|
| `ops` | · | · | **Haiku · high** | · |
|
|
75
75
|
| `explore`, `docs` | · | · | · | · |
|
|
76
76
|
|
|
77
|
-
`/router activities
|
|
77
|
+
`/router activities off` stops asking and keeps the base routes. [Activity routing](docs/activity-routing.md) explains each cell and how to change it. The label is optional: on `uncertain` or a weak label the base route is used if the move passes the cache check, when the activity answer fails the running activity stays and the tier answer still applies, and when the classifier fails the running route stays. See [Route by activity](docs/user-guide.md#route-by-activity), and [Evaluation](docs/evaluation.md#activity-routing) for how it is checked. Its default overrides rest on published vendor results and a list-price replay of one developer's sessions, not measured savings.
|
|
78
78
|
|
|
79
79
|
## Install
|
|
80
80
|
|
package/docs/activity-routing.md
CHANGED
|
@@ -46,7 +46,7 @@ A `·` cell uses the base route.
|
|
|
46
46
|
Why each row:
|
|
47
47
|
|
|
48
48
|
- **Base route.** The tier ladder, unchanged since 1.4. It runs for every cell without an override, and for every
|
|
49
|
-
turn when activity routing is `off
|
|
49
|
+
turn when activity routing is `off`.
|
|
50
50
|
- **`code`, `debug`, `plan`, `review` at `low`: Sonnet · high.** Code is where Haiku trails most. Sonnet at `high`
|
|
51
51
|
scores well above Haiku on coding tests. Sonnet at `medium` does not, so it is not used.
|
|
52
52
|
- **`ops` at `medium`: Haiku · high.** Command runs last many requests, so Haiku pays back its cache write. Haiku is
|
|
@@ -112,24 +112,25 @@ taken only when it pays back within the payback horizon. A move down a tier weig
|
|
|
112
112
|
classifier's confidence: a costly write needs a more confident answer, but a confident enough answer can still move. Like the table, it prices Haiku at five times its list rates above 100,000 tokens
|
|
113
113
|
(`models.haiku.longContext` in [Configuration](configuration.md)).
|
|
114
114
|
|
|
115
|
-
## Turn it off
|
|
115
|
+
## Turn it off
|
|
116
116
|
|
|
117
|
-
| Mode
|
|
118
|
-
|
|
|
119
|
-
| `on`
|
|
120
|
-
| `
|
|
121
|
-
|
|
117
|
+
| Mode | What the router does |
|
|
118
|
+
| ----- | ------------------------------------------------------------------------------------------ |
|
|
119
|
+
| `on` | The default. Asks the activity and runs the override when the cell has one. |
|
|
120
|
+
| `off` | Does not ask the activity: the classifier is asked for the tier only. The base routes run. |
|
|
121
|
+
|
|
122
|
+
A `router.json` that still sets `"shadow"`, a mode removed in 1.10.1, is read as not setting it: the default, `on`, runs, and the next save from the pane drops the value.
|
|
122
123
|
|
|
123
124
|
Pick one of:
|
|
124
125
|
|
|
125
|
-
- Run `/router activities
|
|
126
|
+
- Run `/router activities off`. It is saved to `router.json` at once. **Undo** in the
|
|
126
127
|
pane reverts it.
|
|
127
|
-
- Open the pane with `/router`, press `2` for the **
|
|
128
|
-
**
|
|
128
|
+
- Open the pane with `/router`, press `2` for the **Routes** tab, set **Activity routing** at the top, and press
|
|
129
|
+
**Save** (`s`).
|
|
129
130
|
- Write it in `router.json`:
|
|
130
131
|
|
|
131
132
|
```json
|
|
132
|
-
{ "activityRouting": "
|
|
133
|
+
{ "activityRouting": "off" }
|
|
133
134
|
```
|
|
134
135
|
|
|
135
136
|
Routing as a whole has its own on/off pair at the top of the pane. Turning routing off keeps Claude's model for every
|
|
@@ -137,13 +138,14 @@ turn, whatever the activity mode.
|
|
|
137
138
|
|
|
138
139
|
## Change a cell
|
|
139
140
|
|
|
140
|
-
**In the pane.** Open `/router` and press `2
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
141
|
+
**In the pane.** Open `/router` and press `2` for the **Routes** tab. It starts with the mode, then one grid: a column
|
|
142
|
+
per tier, the **every turn** row with each tier's own model, and a row per activity. A cell shows the model the activity
|
|
143
|
+
runs at that tier, such as `sonnet·high`, or `·` for the tier's model; `°` marks a built-in default. Select a cell to
|
|
144
|
+
edit its model and effort under the grid. **Use tier model** drops the override; **Restore default** puts a built-in
|
|
145
|
+
one back. Edits are a draft: the tab reads **Routes ●** and lists the `router.json` lines they change. **Save** (`s`)
|
|
146
|
+
writes them, **Discard** (`d`) drops them, and **Undo** (`u`) reverts the last write. A yellow note flags a cell
|
|
147
|
+
stronger than the tier above, or the only cell on its cache, which adds one. A selected cell whose override
|
|
148
|
+
changes nothing says `same as the tier’s model: no effect`.
|
|
147
149
|
|
|
148
150
|
**In `router.json`.** `activities.<activity>.<tier>` takes `model`, `effort`, or both. A field you leave out keeps its
|
|
149
151
|
default. This runs `code` at `low` on Sonnet at `xhigh` and adds `max` effort for hard code:
|
|
@@ -156,9 +158,9 @@ default. This runs `code` at `low` on Sonnet at `xhigh` and adds `max` effort fo
|
|
|
156
158
|
}
|
|
157
159
|
```
|
|
158
160
|
|
|
159
|
-
A cell cannot be `null`. To drop a built-in override, set the cell to the tier's base route, or press **
|
|
160
|
-
the pane, which writes that for you. The cell keeps that route if you later change the tier's route;
|
|
161
|
-
then:
|
|
161
|
+
A cell cannot be `null`. To drop a built-in override, set the cell to the tier's base route, or press **Use tier
|
|
162
|
+
model** in the pane, which writes that for you. The cell keeps that route if you later change the tier's route; drop it
|
|
163
|
+
again then:
|
|
162
164
|
|
|
163
165
|
```json
|
|
164
166
|
{ "activities": { "ops": { "medium": { "model": "opus", "effort": "medium" } } } }
|
|
@@ -186,35 +188,34 @@ Two other directions, with what they trade:
|
|
|
186
188
|
|
|
187
189
|
**Activity threshold.** An activity applies only when the classifier gives it at least this probability. Below it, a
|
|
188
190
|
new task goes back to the base route if that move passes the usual checks, and a continuation of the running task
|
|
189
|
-
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
|
|
190
|
-
|
|
191
|
+
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**,
|
|
192
|
+
or in `router.json`. There is no data to tune it on yet: the probe results record whether the
|
|
191
193
|
label was right, not the classifier's probabilities.
|
|
192
194
|
|
|
193
195
|
[Configuration](configuration.md#activity-routing) has the full schema.
|
|
194
196
|
|
|
195
197
|
## Upgrading from 1.6
|
|
196
198
|
|
|
197
|
-
1.6
|
|
199
|
+
1.6 asked the activity but ran the base routes. 1.7 turns activity routing `on`, with the matrix above.
|
|
198
200
|
|
|
199
|
-
- A `router.json`
|
|
200
|
-
`/router activities
|
|
201
|
-
chose `shadow` in 1.6, run `/router activities shadow` again after upgrading.
|
|
201
|
+
- A `router.json` with `activityRouting: "off"` keeps it. Any other file now runs `on`. To keep 1.6's routes, run
|
|
202
|
+
`/router activities off`.
|
|
202
203
|
- A session started on Sonnet 5.5 used to start with routing off, because no tier route used Sonnet. Sonnet now runs
|
|
203
204
|
the `code` cell at `low`, so the session starts with routing on and the router may move it to Haiku or Opus. To
|
|
204
205
|
stay on Sonnet in this session, choose it with `/model` or run `/router off`. To make future Sonnet sessions start
|
|
205
|
-
with routing off, also run `/router activities
|
|
206
|
+
with routing off, also run `/router activities off`.
|
|
206
207
|
- Overrides you saved stay as written. An override that sets only one field, such as `"effort"`, takes the other from
|
|
207
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
|
|
208
209
|
`low`). 1.6's overrides in those cells and in `ops` at `medium` were Sonnet · medium, so such a cell can now run
|
|
209
210
|
another model or effort. Write both `model` and `effort` to keep 1.6's route.
|
|
210
|
-
- If you removed a 1.6 built-in override that 1.7 no longer has, such as `docs` at `low`,
|
|
211
|
-
"same as
|
|
212
|
-
- 1.6 reads the same keys. A file without `activityRouting` runs
|
|
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.
|
|
213
|
+
- 1.6 reads the same keys. A file without `activityRouting` runs 1.6's default under 1.6.
|
|
213
214
|
|
|
214
215
|
## What the estimates mean
|
|
215
216
|
|
|
216
217
|
**In the pane.** The band, the Now tab and the Usage tab report Claude's own readings: cost, context, and cache. The
|
|
217
|
-
dollar figures next to them, such as the switch cost,
|
|
218
|
+
dollar figures next to them, such as the switch cost, and the payback, are estimates
|
|
218
219
|
at the list prices in `router.json`. They are not your bill: a plan does not charge list prices. They are not measured
|
|
219
220
|
savings: the router does not know what another model would have answered, or how many requests it would have needed.
|
|
220
221
|
|
|
@@ -236,8 +237,8 @@ Limits:
|
|
|
236
237
|
|
|
237
238
|
- The answer quality of routed sessions.
|
|
238
239
|
- How well the classifier labels real turns. On 70 synthetic prompts, Jev and OpenAI labelled all 70 right; see
|
|
239
|
-
[Evaluation](evaluation.md#activity-probe-set). The
|
|
240
|
-
tools they used.
|
|
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.
|
|
241
242
|
- Whether an effort change on the same model keeps the cache. We found only 6 cases. Claude Code's prompt-caching
|
|
242
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.
|
|
243
244
|
- How many requests a turn needs on each model.
|
package/docs/architecture.md
CHANGED
|
@@ -87,13 +87,11 @@ The router decides on a *cell*: a tier and an activity. The route is `{ ...route
|
|
|
87
87
|
`chooseRoute` runs one decision per logical turn:
|
|
88
88
|
|
|
89
89
|
1. **Pin.** A pinned tier wins, with no activity: the pin's tier route.
|
|
90
|
-
2. **Activity.** Only in `on`; `off`
|
|
90
|
+
2. **Activity.** Only in `on`; `off` uses none, and ignores the activity a turn in `on` ran with before the mode changed. With no advice, or advice without an activity answer, the incumbent's activity stays. On a new prompt the classifier scores as a continuation of the task (advice `continuation` at or above `continuationMass`; Ollama gives none), the advice's activity applies only if its route at the incumbent tier is stronger than the running route, so a task can move from `explore` up to `code` but a weaker label never takes over. Tool continuations inside a turn do not reclassify: they keep the turn's route and activity. Otherwise the activity with probability at least `activityMass` applies; below that, or for `uncertain`, there is none and the tier's base route is used.
|
|
91
91
|
3. **Tier.** The tier policy runs as before, with every candidate tier priced at its route for the activity and the incumbent at the route it runs. Repeated tool errors move to the lowest tier above whose route is stronger than the running one, or sends a request that cannot be ordered against it. With no activity that is one tier up, as in 1.5. If no tier above helps, nothing escalates and the failure signature is kept.
|
|
92
92
|
4. **Lateral move.** If the tier stays and the route would change, `lateralMove` decides. Routes order by configured output price, then effort; a session effort counts as the effort Claude Code sends. Two routes that send the same request do not switch. A pair that cannot be ordered (an unpriced model, a numeric effort, two models at one price) counts as a move up, so the base route is always reachable. A stronger route needs the activity's probability to clear the upgrade bar for its switching tax (a base route with no activity counts as probability 1). A cheaper route needs its downgrade tax to be paid back within `downgradeHorizonTurns`, except before the first measured reply of a history, when there is no cache to protect. The cash gate applies to both. The result is `activity-up`, `activity-down`, `activity-pending` (stay on the running route and its activity), `cash-gate`, or `hold`. While an escalation hold lasts, only a stronger route may be taken. One vote is enough: an activity is a fact about the turn, not a noisy estimate. If the tier changes, the tier gates have already priced the new route, and no lateral rule applies.
|
|
93
93
|
5. **Fit.** Context fit and model availability resolve through `route(tier, activity)`. A fallback tries the last cell, the native model's cell, then each tier with the activity. The last and the native cell count only when they carry no activity or the turn's; otherwise, or when nothing fits, the native model runs at the session effort.
|
|
94
94
|
|
|
95
|
-
`activityRouting: shadow` runs the decision twice. The applied one uses no activity, so it is the 1.5 decision. The second runs as `on` and is kept only as `decision.wouldRoute`, shown on the pane and counted in the stats. It never changes a route. The second run keeps its own cell and policy state in `loop.would`, so each would-route starts from the previous would-route, as `on` would, not from the route actually running. Its limit: the would-route never runs, so its cache is never observed; the switching estimates price it as any cache of unknown state. A tool continuation keeps the turn's route and activity.
|
|
96
|
-
|
|
97
95
|
At session start the incumbent is the session's model. `cellForModel` looks for it in the base routes, baseline first, and only with `activityRouting: on` in the activity overrides too, so a session that starts on an override route keeps its cell until the classifier says otherwise. The start mode uses the same lookup: with `on`, a start model that only an override uses (Sonnet 5.5 on the defaults) starts with routing on.
|
|
98
96
|
|
|
99
97
|
## State and controls
|
|
@@ -108,8 +106,8 @@ When a turn completes, the Mod labels it from the tool calls the assistant made
|
|
|
108
106
|
|
|
109
107
|
Two stores hold counts:
|
|
110
108
|
|
|
111
|
-
- **Session**: `activityStats` in the view, reset when the session ends. It has turns, requests, tokens, the list price of priced replies with their count, and routed replies by `model@effort` per activity, switches by tier and by activity, lateral moves taken and refused
|
|
112
|
-
- **Across sessions**: one `$.store` key and one record per session. `activity:stats:v1` holds a confusion matrix of the classifier's raw answer (including `uncertain` and `none`) against the observed bucket, run lengths per activity in five buckets, lateral switches taken and refused (from the decision's `lateral` field, so a hold or the cash gate counts)
|
|
109
|
+
- **Session**: `activityStats` in the view, reset when the session ends. It has turns, requests, tokens, the list price of priced replies with their count, and routed replies by `model@effort` per activity, switches by tier and by activity, lateral moves taken and refused, and tool agreement. The label counted per activity is the applied activity in `on`. Tool agreement compares the answer that cleared `activityMass`, so it measures the classifier in both modes. The view also keeps an `activities` array aligned with the last 30 replies.
|
|
110
|
+
- **Across sessions**: one `$.store` key and one record per session. `activity:stats:v1` holds a confusion matrix of the classifier's raw answer (including `uncertain` and `none`) against the observed bucket, run lengths per activity in five buckets, and lateral switches taken and refused (from the decision's `lateral` field, so a hold or the cash gate counts). A value with an unknown key or shape reads as empty; the `shadow` key that versions before 1.10.1 wrote is dropped on read and the rest is kept. 1.10.0 and earlier need that key, so they reset the store. Each session's `activity:metrics:v1:<session id>` holds a classifier latency histogram per classifier id (22 buckets, at most 8 ids), the cheaper activity moves taken in `on` with the escalations that followed one, and `since`, its first reading; each part reads as empty on its own when its shape is wrong, as after a change of buckets. Keeping them apart from the stats key lets 1.7.0, which never reads them, keep the counts across a downgrade. The metrics follow the savings records below: one writer per key, so sessions that finish turns at the same moment do not overwrite each other; this session's record held in memory and written after each turn that adds a reading; the readout the sum of all records, latency kept to the first 8 classifier ids; and the same reset marker. The stats key has a fixed key set; each metrics record is bounded, and the records grow by one per session that recorded a reading until **Reset stats**, as the savings records do. The view keeps the last values read or written as `activityStore` and `activityMetrics` (the sum): read at session start and when the pane opens, replaced after each turn's write and after a reset. The open run is written when the session ends. **Reset stats** clears the session counts, the stats key and every metrics record, and the routing-vs-your-model totals below.
|
|
113
111
|
|
|
114
112
|
Nothing is recorded with `activityRouting: off`. Stats run inside a guard: a failed transcript read or store access loses that turn's counts and never fails the turn. Readings already in the session's metrics record stay in memory after a failed write and go out with the next turn that adds a reading. A turn from a session that has since changed is dropped.
|
|
115
113
|
|
|
@@ -125,9 +123,9 @@ A subagent's model is chosen once, in the `agent.spawn` hook, before its cache e
|
|
|
125
123
|
- Workflow `agent()` calls raise `agent.spawn` with `e.workflow`, but a model rewrite there is ignored.
|
|
126
124
|
- The hook has 10 seconds of its own time. `$` calls do not count against it, but a `$.clock.sleep` does.
|
|
127
125
|
|
|
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.
|
|
126
|
+
`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. That bounds how long a subagent waits to start. 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
127
|
|
|
130
|
-
Every spawn in `
|
|
128
|
+
Every spawn in `on` gets a record keyed by `agentId`, from `next(e)`'s answer. Its replies are priced in `turn.step` (`addAgentReply`), on the model they ran on and on core's model as `coreModelOf` estimates it (the definition's own model, else `CLAUDE_CODE_SUBAGENT_MODEL` except for Explore and Plan without `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`, else `parentModel`). Cache writes are priced at the subagent lifetime (`subagentCacheTtl`). The record's counts go to this session's `$.store` key `subagents:v1:<session id>` at each of the agent's `turn.complete`s, and at session end for agents still running. They are counted per type and per pass-through reason, with respawns: a spawn of the type its parent loop finished one of in the last 10 minutes. The records follow the 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.
|
|
131
129
|
|
|
132
130
|
## Classifier deadline and failure handling
|
|
133
131
|
|
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.
|
|
@@ -63,13 +63,14 @@ Prices are configured list-price inputs for estimates. They are not a subscripti
|
|
|
63
63
|
|
|
64
64
|
The classifier also names the activity of a turn: what the turn produces. `activityRouting` decides what the router does with it. [Activity routing](activity-routing.md) explains the defaults for end users.
|
|
65
65
|
|
|
66
|
-
| `activityRouting` | Behavior
|
|
67
|
-
| ----------------- |
|
|
68
|
-
| `off` | Does not ask the activity: the classifier is asked for the tier only. The base routes run.
|
|
69
|
-
| `
|
|
70
|
-
| `on` | The default since 1.7. Applies the `activities` overrides below. |
|
|
66
|
+
| `activityRouting` | Behavior |
|
|
67
|
+
| ----------------- | ------------------------------------------------------------------------------------------ |
|
|
68
|
+
| `off` | Does not ask the activity: the classifier is asked for the tier only. The base routes run. |
|
|
69
|
+
| `on` | The default since 1.7. Applies the `activities` overrides below. |
|
|
71
70
|
|
|
72
|
-
|
|
71
|
+
A `router.json` that still sets `"shadow"`, a mode removed in 1.10.1, is read as not setting it: the default, `on`, runs, and the next save from the pane drops the value.
|
|
72
|
+
|
|
73
|
+
The seven activities are `code`, `debug`, `explore`, `plan`, `review`, `ops`, and `docs`. The classifier may also answer `uncertain`. In `on`, an activity applies only when its probability is at least `policy.activityMass`. Below that, or on `uncertain`, a new task goes back to its base route if the move passes the cache checks; a continuation of the running task keeps its activity, or moves to the classifier's activity when that route is stronger. When the classifier gives no usable activity answer, the running activity stays and the tier answer still applies. When it gives no answer at all, the running route stays. In `off`, the base route runs.
|
|
73
74
|
|
|
74
75
|
`activities` maps an activity to a tier to a route override. An override may set `model`, `effort`, or both. A field it leaves out comes from the built-in override for that cell, or from the tier's own route, the **base route**, where there is none:
|
|
75
76
|
|
|
@@ -109,18 +110,18 @@ An override for a cell with no built-in names both fields, or inherits the missi
|
|
|
109
110
|
```
|
|
110
111
|
|
|
111
112
|
- `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
|
|
113
|
+
- 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
114
|
- 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
115
|
- 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
|
|
116
|
+
- 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
117
|
|
|
117
|
-
`policy.activityMass` (default `0.6`) is the lowest probability at which an activity applies. The
|
|
118
|
+
`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
119
|
|
|
119
|
-
Switch the mode with `/router activities off|
|
|
120
|
+
Switch the mode with `/router activities off|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
121
|
|
|
121
|
-
**Upgrade from 1.6.** 1.6
|
|
122
|
+
**Upgrade from 1.6.** 1.6 asked the activity but ran the base routes, with Sonnet at `medium` in every override. A file with `"activityRouting": "off"` keeps it; any other file now runs `on`. Run `/router activities off` after upgrading to keep 1.6's routes. 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 off` 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
123
|
|
|
123
|
-
**Rollback.** To go back to 1.6 behavior without downgrading, set `"activityRouting": "
|
|
124
|
+
**Rollback.** To go back to 1.6 behavior without downgrading, set `"activityRouting": "off"`. Router 1.6 reads the same keys; under 1.6 a file without `activityRouting` runs 1.6's default. Router 1.10.0 and earlier reset the activity stats store that this version writes without a `shadow` key. 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`, change the activity threshold, or edit or remove an override.
|
|
124
125
|
|
|
125
126
|
## Classifiers
|
|
126
127
|
|
|
@@ -175,11 +176,12 @@ To check a classifier outside Claude Code, run `node scripts/probe-classifier.mj
|
|
|
175
176
|
|
|
176
177
|
`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
|
|
|
178
|
-
| `subagentRouting` | Behavior
|
|
179
|
-
| ----------------- |
|
|
180
|
-
| `off` | Asks nothing, records nothing. Every agent runs on the model Claude Code gives it.
|
|
181
|
-
| `
|
|
182
|
-
|
|
179
|
+
| `subagentRouting` | Behavior |
|
|
180
|
+
| ----------------- | ----------------------------------------------------------------------------------------- |
|
|
181
|
+
| `off` | Asks nothing, records nothing. Every agent runs on the model Claude Code gives it. |
|
|
182
|
+
| `on` | The default. Sends the decided model, which Claude Code uses in place of the agent's own. |
|
|
183
|
+
|
|
184
|
+
A file that still sets `"shadow"` is read as not setting it, so subagents are routed (`on`).
|
|
183
185
|
|
|
184
186
|
**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
187
|
|
|
@@ -221,11 +223,11 @@ These agents always keep their model:
|
|
|
221
223
|
The values above are the defaults.
|
|
222
224
|
|
|
223
225
|
- `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
|
|
226
|
+
- `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.
|
|
225
227
|
- 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
228
|
- A spawn sets a model, not an effort. An agent's `effort` frontmatter still applies.
|
|
227
229
|
|
|
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
|
|
230
|
+
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 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
231
|
|
|
230
232
|
## Optional `router.json`
|
|
231
233
|
|
|
@@ -244,7 +246,7 @@ The Mod validates the whole file. Unknown keys and invalid values make routing u
|
|
|
244
246
|
| ------------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------- |
|
|
245
247
|
| `baselineTier` | `micro`, `low`, `medium`, `high` | `low` |
|
|
246
248
|
| `routes.<tier>` | `model`, optional `effort` (a level, or `null` for the session effort) | As in the route table above |
|
|
247
|
-
| `activityRouting` | `off`, `
|
|
249
|
+
| `activityRouting` | `off`, `on` | `on` |
|
|
248
250
|
| `activities.<activity>.<tier>` | optional `model` and `effort`, as in `routes` | The overrides in [Activity routing](#activity-routing) |
|
|
249
251
|
| `models.<alias>` | `id`, `input`, optional `output`, `cacheRead`, optional `longContext` (`above`, `multiplier`, or `null`), `contextWindow`, `billing`, `efforts` | Three defaults above |
|
|
250
252
|
| `cache` | `writeMultiplier`, `ttlMs`, `warmMarginMs` | `5m: 1.25`, `1h: 2`; `300000` / `3600000` ms; `30000` ms |
|
|
@@ -252,7 +254,7 @@ The Mod validates the whole file. Unknown keys and invalid values make routing u
|
|
|
252
254
|
| `classifier` | An id in `classifiers` | `jev` |
|
|
253
255
|
| `classifiers.<id>` | `label`, `api`, `endpoint`, `model`, `keyOption`, `timeoutMs` | [Classifiers](#classifiers) above |
|
|
254
256
|
| `context` | `recentTurns`, `maxTextChars` | `6`, `1200` |
|
|
255
|
-
| `subagentRouting` | `off`, `
|
|
257
|
+
| `subagentRouting` | `off`, `on` | `on` |
|
|
256
258
|
| `subagents` | `types` (type → models key, `classify` or `null`), `light`, `standard`, `heavy`, `heavyMass` | [Subagent routing](#subagent-routing) |
|
|
257
259
|
|
|
258
260
|
Policy defaults:
|
|
@@ -274,7 +276,7 @@ Policy defaults:
|
|
|
274
276
|
| `cashCapUsd` | `2` | Maximum estimated cold cache write for a `credits` model. It does not cap output or session spend. |
|
|
275
277
|
| `activityMass` | `0.6` | Minimum probability for the classifier's activity to apply. Not tuned on any classifier. |
|
|
276
278
|
|
|
277
|
-
The pane writes a subset of these settings. The **
|
|
279
|
+
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
280
|
|
|
279
281
|
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.
|
|
280
282
|
|
package/docs/evaluation.md
CHANGED
|
@@ -56,7 +56,7 @@ The script writes aggregate counts, reason histograms, route transitions, and sh
|
|
|
56
56
|
|
|
57
57
|
Activity routing has no measured result. The replay above predates it and covers tiers only. It is `on` by default since 1.7, with defaults chosen from Anthropic's published benchmarks and a list-price replay of one developer's sessions; [Activity routing](activity-routing.md#what-the-estimates-mean) gives that replay and its limits. The pane counts turns, requests, switches, and the turns `on` would route differently, with a configured list-price estimate of those turns' next requests, not a measured saving. Two checks look at the classifier's activity label.
|
|
58
58
|
|
|
59
|
-
The figures plan §11 tracks (tool agreement of at least 80% on `code` against `ops` and `explore`, Jev p95 latency of at most 450 ms, at most 1 tool-error escalation in 10 cheaper activity moves,
|
|
59
|
+
The figures plan §11 tracks (tool agreement of at least 80% on `code` against `ops` and `explore`, Jev p95 latency of at most 450 ms, at most 1 tool-error escalation in 10 cheaper activity moves, the number of activity switches) are read from the Usage tab's **ACROSS SESSIONS** block, which shows the counts kept since the last reset: **Code/ops/explore** for the tool agreement on turns the classifier answered `code`, `ops` or `explore`, **Agreement** and **Mismatch** for all of them, **Activity moves** for moves inside a tier taken and refused (a refusal by a hold or the credits cap included), **Escalations** for the tool-error escalations that followed a cheaper activity move in `on` while the turns stayed on its route in `on` (turning routing off, a turn with routing off, or a turn in `off` ends the watch, a pin in between does not, and an escalation the credits cap held counts), **Latency** for the active classifier's p95 wait. Latency is kept in fixed buckets, so the p95 reads as a bound (`≤ 350 ms`); it is the wait for the classifier's answer, transient retries included, without the routing after it, so it compares with the probe's p95 below, and is not recorded with activity routing `off`. `/router` without a UI surface prints both agreements. The underlying counts are the `activity:stats:v1` store and the per-session `activity:metrics:v1:<session id>` records described in [Architecture](architecture.md).
|
|
60
60
|
|
|
61
61
|
### Tool agreement
|
|
62
62
|
|
|
@@ -94,7 +94,7 @@ Agreement is a weak check. It tells `code` from `ops` and `explore` well, but no
|
|
|
94
94
|
node scripts/probe-activity.mjs [classifier]
|
|
95
95
|
```
|
|
96
96
|
|
|
97
|
-
The script sends each prompt to one classifier as the router would ask it, with activity routing forced to `
|
|
97
|
+
The script sends each prompt to one classifier as the router would ask it, with activity routing forced to `on`. It reads credentials as `probe-classifier.mjs` does and needs a classifier you can reach. The run is billed on a paid classifier, and it is run by hand, not in CI. It writes accuracy, an expected-by-answered confusion matrix, p50 and p95 latency against the classifier's deadline, and error counts to `experiments/mod-router/results/activity-probe-<classifier>.json`. For Ollama the latency covers both requests. It never prints a key.
|
|
98
98
|
|
|
99
99
|
Five probe results are checked in, run on 2026-10-09 and 2026-10-10 (UTC) with the synthetic set above: Jev against the live typesafe.ai API, OpenAI against the live Decisions API, Clef and Clef Flash against the live Cloudflare API, Ollama with `qwen3.5:9b` on an Apple M2 Pro laptop:
|
|
100
100
|
|
|
@@ -136,21 +136,20 @@ Limits:
|
|
|
136
136
|
|
|
137
137
|
## Subagent routing
|
|
138
138
|
|
|
139
|
-
Subagent routing has no measured result over time yet. It is `on` by default since 1.9
|
|
139
|
+
Subagent routing has no measured result over time yet. It is `on` by default since 1.9. The Usage tab's **SUBAGENTS** section shows the counts kept across sessions since the last reset:
|
|
140
140
|
|
|
141
|
-
- Per routed type
|
|
141
|
+
- Per routed type: agents; **moved**, the agents whose decided model differs from the one they ran on; requests per agent; respawns; the choices by model; classifier failures; and `core → routed`, the list price of the agents' tokens on core's model against the decided one.
|
|
142
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
143
|
|
|
144
144
|
Method:
|
|
145
145
|
|
|
146
|
-
-
|
|
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.
|
|
146
|
+
- `routed` is the reply on the routed model and `core` the same tokens on core's model as the router estimates it: `CLAUDE_CODE_SUBAGENT_MODEL`, except for Explore and Plan without `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`, else the parent's model. A subagent starts with a cold cache on one model and keeps it, so its own token counts on another model are a fair counterfactual. `ratesAt` applies Haiku 5.5's 5x rate above 100,000 prompt tokens. Explore agents often pass that, so Haiku can cost more than its base price suggests.
|
|
148
147
|
- 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
|
-
-
|
|
148
|
+
- The counts cannot see quality. Two proxies stand in for it: requests per agent, and **respawns**, a spawn of the same type by the same parent within 10 minutes after one finished.
|
|
150
149
|
|
|
151
150
|
Checks:
|
|
152
151
|
|
|
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 `
|
|
152
|
+
- `test/subagents.test.mjs` covers each pass reason, the pin rule, the classify mapping, core's model estimate, the subagent lifetime, Haiku's long-context price, and the store's merge, reset and bad values. `test/hook-subagents.test.mjs` covers `on` (the routed model), a fork, an explicit model, a teammate, a workflow agent and a pinned project agent (each passes), a classifier failure (core's model), parallel spawns, a spawn-path pause that leaves main routing alone, respawns, session end, Reset stats and the Usage tab.
|
|
154
153
|
- `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
154
|
- `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
155
|
|
|
@@ -160,7 +159,7 @@ When to turn it `on`:
|
|
|
160
159
|
- the choices look right for the tasks: `light` for searches and reads, `heavy` rarely;
|
|
161
160
|
- **Not routed** leaves enough routable spend to bother.
|
|
162
161
|
|
|
163
|
-
|
|
162
|
+
Keep it if requests per agent and respawns per type stay no higher than before you turned it on. Otherwise change `types` or `heavyMass`, exclude a type with `null`, or set `subagentRouting` to `off`.
|
|
164
163
|
|
|
165
164
|
Limits:
|
|
166
165
|
|