@alexeiled/claude-router 1.10.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 +7 -0
- package/README.md +3 -3
- package/docs/activity-routing.md +18 -18
- package/docs/architecture.md +5 -7
- package/docs/configuration.md +20 -18
- package/docs/evaluation.md +8 -9
- package/docs/native-router.md +7 -8
- package/docs/router-band.svg +3 -21
- package/docs/user-guide.md +13 -14
- package/hooks/native-router.mjs +16 -49
- 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 +4 -16
- package/lib/panel.mjs +13 -47
- package/lib/route.mjs +4 -53
- package/lib/subagents.mjs +12 -17
- package/lib/view.mjs +1 -3
- package/package.json +1 -1
- package/types/index.d.ts +5 -35
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "router",
|
|
3
3
|
"displayName": "Router",
|
|
4
|
-
"version": "1.10.
|
|
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,12 @@
|
|
|
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
|
+
|
|
3
10
|
## 1.10.0 (2026-10-10)
|
|
4
11
|
|
|
5
12
|
### Changed
|
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
|
|
@@ -195,27 +196,26 @@ label was right, not the classifier's probabilities.
|
|
|
195
196
|
|
|
196
197
|
## Upgrading from 1.6
|
|
197
198
|
|
|
198
|
-
1.6
|
|
199
|
+
1.6 asked the activity but ran the base routes. 1.7 turns activity routing `on`, with the matrix above.
|
|
199
200
|
|
|
200
|
-
- A `router.json`
|
|
201
|
-
`/router activities
|
|
202
|
-
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`.
|
|
203
203
|
- A session started on Sonnet 5.5 used to start with routing off, because no tier route used Sonnet. Sonnet now runs
|
|
204
204
|
the `code` cell at `low`, so the session starts with routing on and the router may move it to Haiku or Opus. To
|
|
205
205
|
stay on Sonnet in this session, choose it with `/model` or run `/router off`. To make future Sonnet sessions start
|
|
206
|
-
with routing off, also run `/router activities
|
|
206
|
+
with routing off, also run `/router activities off`.
|
|
207
207
|
- Overrides you saved stay as written. An override that sets only one field, such as `"effort"`, takes the other from
|
|
208
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
|
|
209
209
|
`low`). 1.6's overrides in those cells and in `ops` at `medium` were Sonnet · medium, so such a cell can now run
|
|
210
210
|
another model or effort. Write both `model` and `effort` to keep 1.6's route.
|
|
211
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
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
|
|
213
|
+
- 1.6 reads the same keys. A file without `activityRouting` runs 1.6's default under 1.6.
|
|
214
214
|
|
|
215
215
|
## What the estimates mean
|
|
216
216
|
|
|
217
217
|
**In the pane.** The band, the Now tab and the Usage tab report Claude's own readings: cost, context, and cache. The
|
|
218
|
-
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
|
|
219
219
|
at the list prices in `router.json`. They are not your bill: a plan does not charge list prices. They are not measured
|
|
220
220
|
savings: the router does not know what another model would have answered, or how many requests it would have needed.
|
|
221
221
|
|
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
|
@@ -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
|
|
|
@@ -116,11 +117,11 @@ An override for a cell with no built-in names both fields, or inherits the missi
|
|
|
116
117
|
|
|
117
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:
|
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
|
|
package/docs/native-router.md
CHANGED
|
@@ -10,7 +10,7 @@ The classifier receives the current prompt and at most six preceding user or ass
|
|
|
10
10
|
|
|
11
11
|
The default tiers are defined in [Configuration](configuration.md#built-in-defaults). Policy uses vote hysteresis, repeated tool errors, context fit, model availability, and switching-cost estimates. The [architecture](architecture.md#request-flow) explains the event boundary and failure handling.
|
|
12
12
|
|
|
13
|
-
The activity is what the turn produces: `code`, `debug`, `explore`, `plan`, `review`, `ops`, or `docs`. A route is the tier's own route, the base route, with the activity's override on top. In `on`, the default since 1.7, it applies the overrides.
|
|
13
|
+
The activity is what the turn produces: `code`, `debug`, `explore`, `plan`, `review`, `ops`, or `docs`. A route is the tier's own route, the base route, with the activity's override on top. In `on`, the default since 1.7, it applies the overrides. The activity question reuses the same prompt and dialogue; no other text is sent. With `off` the classifier is asked for the tier only. [Route by activity](user-guide.md#route-by-activity) explains the modes, [Activity routing](activity-routing.md) the default matrix and its evidence, and [Configuration](configuration.md#activity-routing) the schema.
|
|
14
14
|
|
|
15
15
|
## Controls and session modes
|
|
16
16
|
|
|
@@ -20,7 +20,7 @@ The activity is what the turn produces: `code`, `debug`, `explore`, `plan`, `rev
|
|
|
20
20
|
| `/router auto` | Enable automatic routing. |
|
|
21
21
|
| `/router off` | Turn routing off and keep Claude's selected model. |
|
|
22
22
|
| `/router pin <tier>` | Pin the next turn and tool continuations. Routing on must already be enabled. |
|
|
23
|
-
| `/router activities <off\|
|
|
23
|
+
| `/router activities <off\|on>` | Set the activity routing mode. Written to `router.json` at once; **Undo** in the pane reverts it. |
|
|
24
24
|
| `/model <name>` | Select a model and turn routing off. `/router auto` turns it back on. |
|
|
25
25
|
|
|
26
26
|
The pane's **Set up** and **Credentials → Edit** buttons open Claude Code's secure plugin configuration. Claude Code refuses `$.command.run` from inside a `command.run` hook, so the Mod starts that dialog from a timer after the press returns.
|
|
@@ -29,18 +29,17 @@ 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. In a subagent's transcript it reads `subagent model chosen at spawn`, or `subagents keep their own model` with subagent routing off
|
|
32
|
+
The status band is one line above the prompt: a tier meter, the activity, the route, a short reason, classifier support, and context and cache use. Segments drop by priority when the band is narrow: classifier support first, then context and cache, then the activity, then the reason. Hovering reveals pins, **Turn off**, and a two-row view; while routing is off, **Turn on** sits on the band itself, so the band carries one routing control at a time. A fresh session that starts with routing off because of its model shows `<model> is not a routing tier` on the band until the mode changes. The band yields to surveys. In a subagent's transcript it reads `subagent model chosen at spawn`, or `subagents keep their own model` with subagent routing off. A model change between turns raises a toast. A pin, or a step that changes only the effort, such as `medium` to `high` on the defaults, raises none. While the classifier runs, the turn's spinner says `Choosing model`. In Manual mode or when routing is unavailable, the prompt footer carries `routing off` or `routing unavailable`. The **Router** button opens the pane. The pane has five tabs, Now, Routes, Policy, Classifier, and Usage, under one line with the routing on/off pair and the classifier state. The [user guide](user-guide.md#open-the-router-pane) describes each tab.
|
|
33
33
|
|
|
34
34
|
| Reading | Meaning and limits |
|
|
35
35
|
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
36
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
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
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
39
|
| 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
40
|
| 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
|
-
| 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
|
|
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
|
|
41
|
+
| 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. |
|
|
42
|
+
| 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, and escalations after a cheaper activity move. The active classifier's p95 latency shows on its **Deadline** line. `/router` text shows the agreement. |
|
|
44
43
|
| Cost | Claude Code's native usage value. A plan's list-price estimates are not subscription cash charges. |
|
|
45
44
|
| Context bar | Maximum available observed and local estimated context, compared with the routed model's window. The fit rule reserves 20%. |
|
|
46
45
|
| 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. |
|
|
@@ -66,7 +65,7 @@ The Routes tab edits each tier's model alias and effort, the activity overrides
|
|
|
66
65
|
| Credits cap | $0.50, $1, $2, $5 | Largest estimated cold write on a `credits` model. |
|
|
67
66
|
| Activity threshold | 50%, 60%, 70%, 80% | `policy.activityMass`: the least probability at which an activity applies. |
|
|
68
67
|
|
|
69
|
-
The Routes tab starts with the **Activity routing** selector, `off ·
|
|
68
|
+
The Routes tab starts with the **Activity routing** selector, `off · on`, and a hint for the mode, and a yellow line when the overrides do not run: activity routing is `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
69
|
|
|
71
70
|
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
71
|
|
|
@@ -75,7 +74,7 @@ The pane refuses to write through a symlink. A failed validation names the setti
|
|
|
75
74
|
## Safety and failure states
|
|
76
75
|
|
|
77
76
|
- A missing key or account ID, a classifier failure, or a policy refusal keeps the current model. Network refusal is never bypassed with a helper process.
|
|
78
|
-
- A missing, malformed, or timed-out activity answer keeps the running activity in `on`; the tier answer still applies.
|
|
77
|
+
- A missing, malformed, or timed-out activity answer keeps the running activity in `on`; the tier answer still applies. It does not count as a classifier failure. If the whole classifier call fails, the running route stays. Activity statistics are written inside a guard: a failed store read or write loses that turn's counts and never fails a turn.
|
|
79
78
|
- Three launched classifier failures open a 60-second pause for that classifier. One in-flight request is allowed per classifier in each active Mod instance. Pending host HTTP work blocks another request until it settles.
|
|
80
79
|
- A `router.json` with v0.8 gateway keys or the 1.1 `jev` section marks the router unavailable until the [migration command](configuration.md#convert-an-older-routerjson) converts it.
|
|
81
80
|
- Unsupported Claude Code versions and leftover v0.8 gateway settings (the `jev-router` model or the `127.0.0.1:43170` base URL) mark the router unavailable. `/router` lists the settings to remove. A local gateway does not run as part of this Mod.
|
package/docs/router-band.svg
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 922
|
|
1
|
+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 922 444" role="img" aria-labelledby="title desc">
|
|
2
2
|
<title id="title">The Router band above the Claude Code prompt</title>
|
|
3
|
-
<desc id="desc">
|
|
3
|
+
<desc id="desc">Six band states drawn by the router code: routed to high, two rows with the hover row, a pending pin, a missing classifier key, routing off, and an activity move with activity routing on.</desc>
|
|
4
4
|
<style>
|
|
5
5
|
text { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace; font-size: 13px; }
|
|
6
6
|
.cap { font-family: system-ui, -apple-system, 'Segoe UI', sans-serif; font-size: 12px; fill: #9a988f; }
|
|
7
7
|
</style>
|
|
8
|
-
<rect width="922" height="
|
|
8
|
+
<rect width="922" height="444" rx="8" fill="#1c1c1c"/>
|
|
9
9
|
<text class="cap" x="20" y="30">Routing on: routed to the high tier on a clear jump</text>
|
|
10
10
|
<rect x="12" y="38" width="897.6" height="29" rx="5" fill="#232323"/>
|
|
11
11
|
<text x="24.0" y="56" fill="#e0708a" xml:space="preserve">▂</text>
|
|
@@ -135,22 +135,4 @@
|
|
|
135
135
|
<text x="531.0" y="419" fill="#d0d0d0" xml:space="preserve"> · cache hit </text>
|
|
136
136
|
<text x="632.4" y="419" fill="#87d787" xml:space="preserve">100%</text>
|
|
137
137
|
<text x="679.2" y="419" fill="#d0d0d0" xml:space="preserve">Router</text>
|
|
138
|
-
<text class="cap" x="20" y="458">Activity routing in shadow: the label is shown, the base route still runs</text>
|
|
139
|
-
<rect x="12" y="466" width="897.6" height="29" rx="5" fill="#232323"/>
|
|
140
|
-
<text x="24.0" y="484" fill="#5f9fe0" xml:space="preserve">▂</text>
|
|
141
|
-
<text x="31.8" y="484" fill="#5f9fe0" xml:space="preserve">▄</text>
|
|
142
|
-
<text x="39.6" y="484" fill="#7c7c7c" xml:space="preserve">▆</text>
|
|
143
|
-
<text x="47.4" y="484" fill="#7c7c7c" xml:space="preserve">█</text>
|
|
144
|
-
<rect x="55.2" y="470" width="39.0" height="18" rx="4" fill="#5f9fe0"/>
|
|
145
|
-
<text x="55.2" y="484" fill="#0d1016" font-weight="700" xml:space="preserve"> low </text>
|
|
146
|
-
<text x="102.0" y="484" fill="#7c7c7c" xml:space="preserve">coding (shadow) → </text>
|
|
147
|
-
<text x="242.4" y="484" fill="#d0d0d0" xml:space="preserve">Haiku 5.5 · high</text>
|
|
148
|
-
<text x="367.2" y="484" fill="#7c7c7c" xml:space="preserve"> · </text>
|
|
149
|
-
<text x="406.2" y="484" fill="#7c7c7c" xml:space="preserve">= fits</text>
|
|
150
|
-
<text x="453.0" y="484" fill="#7c7c7c" xml:space="preserve"> · </text>
|
|
151
|
-
<text x="492.0" y="484" fill="#d0d0d0" xml:space="preserve">ctx </text>
|
|
152
|
-
<text x="523.2" y="484" fill="#87d787" xml:space="preserve">40%</text>
|
|
153
|
-
<text x="546.6" y="484" fill="#d0d0d0" xml:space="preserve"> · cache hit </text>
|
|
154
|
-
<text x="648.0" y="484" fill="#87d787" xml:space="preserve">100%</text>
|
|
155
|
-
<text x="694.8" y="484" fill="#d0d0d0" xml:space="preserve">Router</text>
|
|
156
138
|
</svg>
|