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