@alexeiled/claude-router 1.10.2 → 1.10.5
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 +36 -0
- package/README.md +2 -2
- package/docs/activity-routing.md +13 -4
- package/docs/architecture.md +11 -7
- package/docs/configuration.md +9 -7
- package/docs/evaluation.md +1 -1
- package/docs/native-router.md +1 -1
- package/docs/user-guide.md +43 -26
- package/hooks/native-router.mjs +328 -211
- package/lib/activity-stats.mjs +54 -20
- package/lib/activity.mjs +14 -12
- package/lib/config.mjs +9 -0
- package/lib/display.mjs +7 -3
- package/lib/facts.mjs +82 -0
- package/lib/panel.mjs +12 -2
- package/lib/policy.mjs +38 -14
- package/lib/records.mjs +14 -0
- package/lib/route.mjs +93 -7
- package/lib/savings.mjs +4 -8
- package/lib/subagents.mjs +3 -6
- package/package.json +1 -1
- package/scripts/migrate-config.mjs +23 -3
- package/types/index.d.ts +4 -1
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "router",
|
|
3
3
|
"displayName": "Router",
|
|
4
|
-
"version": "1.10.
|
|
4
|
+
"version": "1.10.5",
|
|
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,41 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.10.5 (2026-10-11)
|
|
4
|
+
|
|
5
|
+
The route now follows the task while it runs, for the tier and the activity, in both directions. Before, a turn was
|
|
6
|
+
routed once, from its prompt, and a continuation prompt could only keep the route. A team worker whose `/goal` brief
|
|
7
|
+
read as `ops` ran on Haiku · high and kept it for 100+ requests of coding. See
|
|
8
|
+
[Changes during a task](docs/user-guide.md#changes-during-a-task).
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- A turn whose own tool calls edit a code file moves at once to the tier's `code` route (`docs` for doc-only edits), shown as `↗ coding` with a toast. The tools are the evidence, so no classifier support is needed and the cache cost does not hold the move back; only the cash cap on a credits-billed model can, priced at the route the context fits. It only goes up and skips pinned turns and `activityRouting: off`.
|
|
13
|
+
- Classifier reviews inside a turn: every `policy.reviewEveryRequests` requests (default 4; `0` turns them off) the classifier is asked again in the background, with the turn's prompt and recent dialogue. A step never waits; the answer applies at the next step and can move the tier or the activity either way. Each review sends the classifier the same kind of text a new turn does.
|
|
14
|
+
- `policy.minDwellRequests` (default 8) and a checkpoint for cheaper routes on the running task: a downgrade or a cheaper activity waits for that many requests after the last model change and for the last test, build, lint or type-check command since then to pass. Until then the route stays: a tier shows `… down after a passed check` (reason `downgrade-held`), a held activity keeps the running one. A check is a test runner, type checker or linter, or a launcher running one (`npm test`, `go test`, `make lint`), alone or after `&&`; a piped check (`npm test | tail`), `;`, `|| true`, package names and paths do not count. A cheaper activity also needs `policy.downgradeMass` probability.
|
|
15
|
+
|
|
16
|
+
### Changed
|
|
17
|
+
|
|
18
|
+
- A downgrade lands on the cheapest tier the answer supports as a whole, not only on the chosen tier. A split answer (micro 0.63, low 0.3) on `high` now moves to `low` instead of staying until `micro` alone reaches 0.9, and a cold candidate can give way to a warm tier between it and the incumbent.
|
|
19
|
+
- A prompt the classifier scores as a continuation of the task no longer keeps the route by itself. It is decided like a review: up on the usual votes, down past the checkpoint. The `continuation` reason is gone. `policy.continuationMass` now only decides whether a prompt counts as the running task.
|
|
20
|
+
|
|
21
|
+
### Fixed
|
|
22
|
+
|
|
23
|
+
- Replies after an in-turn move are labelled with the activity they ran on, not the turn's first label; the classifier's answer stays as recorded for the stats.
|
|
24
|
+
|
|
25
|
+
The review interval, the dwell and the checkpoint are starting values, not tuned on data.
|
|
26
|
+
|
|
27
|
+
## 1.10.3 (2026-10-11)
|
|
28
|
+
|
|
29
|
+
### Fixed
|
|
30
|
+
|
|
31
|
+
- Activity stats kept across sessions (classifier vs tools, runs, activity moves) no longer lose counts when two sessions finish turns at the same moment, and a session that read them before **Reset stats** can no longer write them back. Each session now keeps its own `activity:stats:v1:<session id>` record, summed on read like the other counts. The single key earlier versions shared still counts until the next **Reset stats** deletes it. After running this version, 1.10.2 or earlier shows only the counts in that shared key.
|
|
32
|
+
- A one-turn pin is no longer lost when the turn is interrupted before its route is set, and a pin pressed again while a pinned turn chooses its model now serves the next turn.
|
|
33
|
+
- A subagent spawn keeps core's model when the router cannot read the settings, since they may limit the models through `availableModels`.
|
|
34
|
+
- An agent definition file that could not be read is read again at the next spawn of its type, instead of passing that type through for the rest of the session.
|
|
35
|
+
- The Now tab's **Why** line gives a sentence, not a raw key, for a turn routing did not choose, routing off, a model fallback by Claude Code, and an interrupted turn.
|
|
36
|
+
- The Classifier tab names the host a request actually reaches: user info before `@` in an endpoint is not shown as the host, and an endpoint on `[::1]` shows as this machine.
|
|
37
|
+
- `scripts/migrate-config.mjs` refuses to write through a symlink, writes the converted file beside `router.json` and renames it into place, and removes its backup after a failed write, so the next run starts clean.
|
|
38
|
+
|
|
3
39
|
## 1.10.2 (2026-10-11)
|
|
4
40
|
|
|
5
41
|
### Fixed
|
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
|
|
12
|
+
The active classifier is asked at the start of each logical turn, for the tier and for the turn's activity, and again in the background every 4 requests while the turn runs (`policy.reviewEveryRequests`). 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
|
| ---------- | ------------------------------------------ | ----------------------------------- | ------------------------- | --------------------------------------------------------------------- |
|
|
@@ -54,7 +54,7 @@ sequenceDiagram
|
|
|
54
54
|
Mod-->>Dev: Status band and router pane
|
|
55
55
|
```
|
|
56
56
|
|
|
57
|
-
The active classifier labels
|
|
57
|
+
The active classifier labels each new logical turn, and the router checks the route again while the task runs: a turn labelled `ops` that edits code moves up to the `code` route at once, and a background classifier review every 4 requests can move the tier or the activity either way. A cheaper route on the same task waits for a dwell and a passed test, build or lint run. See [Changes during a task](docs/user-guide.md#changes-during-a-task). A local policy applies vote, context, failure, and cache-cost rules before the Mod changes the next step. Claude Code owns request construction, model credentials, tools, streaming, and the API cost ledger.
|
|
58
58
|
|
|
59
59
|
| Tier | Default model | Effort |
|
|
60
60
|
| -------- | ------------- | -------- |
|
package/docs/activity-routing.md
CHANGED
|
@@ -32,6 +32,13 @@ The router compares routes, not labels. If the new activity resolves to the rout
|
|
|
32
32
|
A move to a cheaper route must pay back its cache write first. A move to a stronger route needs the classifier's
|
|
33
33
|
support. The [user guide](user-guide.md#route-by-activity) has the full rules.
|
|
34
34
|
|
|
35
|
+
The label comes from the prompt, so it can be wrong. A prompt such as "run the worker brief" reads as `ops` and the
|
|
36
|
+
turn may then spend 80 requests writing code. The router therefore also watches the turn's own tool calls. Once the
|
|
37
|
+
turn edits a file, it moves to the `code` route of its tier (or `docs` for doc files) if that route is stronger. This
|
|
38
|
+
move only goes up. The cache cost does not hold it back; only the cash cap on a credits-billed model can. A later
|
|
39
|
+
classifier review in the same turn can move it down again, past the checks in
|
|
40
|
+
[Changes during a task](user-guide.md#changes-during-a-task). The next turn starts from the route the turn ended on.
|
|
41
|
+
|
|
35
42
|
## The default matrix
|
|
36
43
|
|
|
37
44
|
A `·` cell uses the base route.
|
|
@@ -51,7 +58,7 @@ Why each row:
|
|
|
51
58
|
scores well above Haiku on coding tests. Sonnet at `medium` does not, so it is not used.
|
|
52
59
|
- **`ops` at `medium`: Haiku · high.** Command runs last many requests, so Haiku pays back its cache write. Haiku is
|
|
53
60
|
weaker on multi-step tool work, so `ops` at `high` stays on Opus. Repeated tool errors move an `ops` turn to the
|
|
54
|
-
`high` route, Opus · xhigh.
|
|
61
|
+
`high` route, Opus · xhigh. An `ops` turn that starts editing code moves to Opus · medium.
|
|
55
62
|
- **`explore` and `docs`.** Moving them saved nothing in the replay. Haiku also scores lower on research
|
|
56
63
|
benchmarks: 50.1% on Humanity's Last Exam with tools against 63.0% for Opus at `medium`. They keep the base routes.
|
|
57
64
|
|
|
@@ -163,7 +170,9 @@ model** in the pane, which writes that for you. The cell keeps that route if you
|
|
|
163
170
|
again then:
|
|
164
171
|
|
|
165
172
|
```json
|
|
166
|
-
{
|
|
173
|
+
{
|
|
174
|
+
"activities": { "ops": { "medium": { "model": "opus", "effort": "medium" } } }
|
|
175
|
+
}
|
|
167
176
|
```
|
|
168
177
|
|
|
169
178
|
Two other directions, with what they trade:
|
|
@@ -187,8 +196,8 @@ Two other directions, with what they trade:
|
|
|
187
196
|
```
|
|
188
197
|
|
|
189
198
|
**Activity threshold.** An activity applies only when the classifier gives it at least this probability. Below it, a
|
|
190
|
-
new task goes back to the base route if that move passes the usual checks
|
|
191
|
-
|
|
199
|
+
new task goes back to the base route if that move passes the usual checks; the running task follows
|
|
200
|
+
[Changes during a task](user-guide.md#changes-during-a-task). The default is 60% (`policy.activityMass: 0.6`). Change it on the Policy tab under **Activities**,
|
|
192
201
|
or in `router.json`. There is no data to tune it on yet: the probe results record whether the
|
|
193
202
|
label was right, not the classifier's probabilities.
|
|
194
203
|
|
package/docs/architecture.md
CHANGED
|
@@ -72,11 +72,11 @@ Node.js is not part of routing. It is used for development, the optional configu
|
|
|
72
72
|
|
|
73
73
|
## Decision and context
|
|
74
74
|
|
|
75
|
-
|
|
75
|
+
A logical turn is classified at its first step, and again every `reviewEveryRequests` requests in the background (see Review inside a turn below). Other tool continuations reuse the decision and add no votes. Before each step, the controller checks whether the selected model still fits after new tool output.
|
|
76
76
|
|
|
77
77
|
Repeated tool-error escalation needs matching non-empty error output and an intervening edit attempt within a 40-message lookback. A bounded fingerprint covers the full output, not only the runner header. It removes ANSI colors, normalizes line endings, and normalizes source positions in stack frames and TAP `location` fields. TAP durations and Jest `✕ ... (N ms)` timings are also normalized. Other test names, case, whitespace, and numeric error values are kept. Unrecognized runner noise remains part of the signature: changed output can miss a repeat rather than trigger a false escalation.
|
|
78
78
|
|
|
79
|
-
An upgrade or downgrade needs a streak of supporting votes (`upgradeVotes`, `downgradeVotes`), because staying keeps a warm cache. Before the first measured reply of a history (session start, clear, rewind, committed compaction), no cache from it exists yet, so one vote is enough. The mass bars, the cash gate, escalation
|
|
79
|
+
An upgrade or downgrade needs a streak of supporting votes (`upgradeVotes`, `downgradeVotes`), because staying keeps a warm cache. A downgrade lands on the cheapest tier from the choice up to just below the incumbent whose mass at or below it, with its streak, clears that tier's bar: a split answer (micro 0.63, low 0.3) on `high` moves to `low` rather than waiting for `micro` alone, and a cold candidate can give way to a warm one in between, such as the same model at a lower effort. Before the first measured reply of a history (session start, clear, rewind, committed compaction), no cache from it exists yet, so one vote is enough. The mass bars, the cash gate, escalation and holds apply as usual. On the same task (`sameTaskOf`: a review inside a turn, or a prompt with advice `continuation` at or above `continuationMass`) an upgrade proceeds as usual, but a downgrade that has its votes stays as `downgrade-held` until `facts.downAllowed`: at least `minDwellRequests` requests since the last model change (`loop.switchedAt`), and the last verification command since then (`verifiedSince`: a Bash test, build, lint or type-check run) passed.
|
|
80
80
|
|
|
81
81
|
A move to a smaller context window needs a main-response measurement from the current history and Claude's local context estimate. The router uses the larger available reading and reserves 20% of the model window. If it cannot establish fit, it keeps the current model with `context-unknown`. It does not infer token count from character count.
|
|
82
82
|
|
|
@@ -84,16 +84,20 @@ An explicit context-window failure marks that model ineligible until the next hi
|
|
|
84
84
|
|
|
85
85
|
## Activity routing
|
|
86
86
|
|
|
87
|
-
The router decides on a
|
|
87
|
+
The router decides on a _cell_: a tier and an activity. The route is `{ ...routes[tier], ...activities[activity][tier] }`; the (model, effort) pair, not the label, is what Claude Code receives and what owns a cache. Two cells that resolve to the same route never switch.
|
|
88
88
|
|
|
89
|
-
`chooseRoute`
|
|
89
|
+
`chooseRoute` decides at a turn's first step, and again on each review answered inside the turn:
|
|
90
90
|
|
|
91
91
|
1. **Pin.** A pinned tier wins, with no activity: the pin's tier route.
|
|
92
|
-
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
|
|
92
|
+
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 the same task (`sameTaskOf`; Ollama gives no continuation answer, so only reviews count for it) a label whose route at the incumbent tier is stronger applies at once, and a weaker one only with at least `downgradeMass` probability once `facts.downAllowed` holds; an unclear label keeps the running 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.
|
|
93
93
|
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.
|
|
94
94
|
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.
|
|
95
95
|
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.
|
|
96
96
|
|
|
97
|
+
**Observed move.** On each later step of the turn, `observedMove` reads the turn's tool calls since its prompt, or since the transcript snapshot of the last review applied inside the turn (`loop.observedFrom`), since the review already judged the earlier ones, (`observedActivity`: `code` after an edit to a non-doc file, `docs` after edits to doc files only, else `ops`, `read` or `talk`). When that activity's route at the decision's tier is stronger than the running one, the remaining steps take it, with reason `activity-up` and `lastActivity` set, so the next turn starts there. The tier is fitted to the context first, so the gates price the route that will run. It goes through `lateralMove` with probability 1: the tools are the evidence, so the switching tax never holds it back (the upgrade bar tops out near 0.9), and only the cash gate can. The turn's reply label (`turnActivities.label`) follows the move; the classifier's answer stays as recorded. It never moves down, and skips pinned turns and `off`. `canMoveUp` skips the transcript read when no activity's route at the tier is stronger, so a step on the strongest route costs nothing. A move to a smaller window waits for a measured context, as in `routeTurn`. Context fit and model availability then apply as for any continuation.
|
|
98
|
+
|
|
99
|
+
**Review inside a turn.** Every `reviewEveryRequests` requests after the last classifier answer (`loop.reviewedAt`, counted in `loop.requests`), `reviewMidTurn` reads the transcript and asks the active classifier in the background, with the turn's prompt and recent dialogue and `facts.midTurn` set. The step does not wait. The first step after the answer arrives runs `chooseRoute` on it, before the observed move, with only the advice taken from the review: the checkpoint, context and cache facts are read at that step. Tier and activity move by the same rules as a continuation prompt: up on votes, down only past `downAllowed`. A pinned turn, a failed read or ask, an answer without advice, and an answer about a replaced history (another `generation`) change nothing; turn completion and session end abort a review in flight. `observeResponse` counts each request and records the request and message count at which the served (model, effort) last changed (`switchedAt`), which the dwell and the verification window start from. A failed transcript read keeps the running route. A verification is a Bash command whose status is the check's: a checker (`pytest`, `tsc`, `eslint`, …) or a launcher whose subcommand names a check (`npm test`, `npm run lint`, `go test`, `make lint`, `uv run pytest`), alone or in an `&&` list. A pipeline, `;`, `||` or background job does not count, since its status can hide a failed check; neither do a `--version` or `--help` run, an option before the subcommand (`npm --prefix test install`), package names, paths and file names, nor a command Claude Code sent to the background, by request or after a timeout. The first response a loop serves also sets `switchedAt`, so checks from before the router chose a route do not count. When compaction or a rewind shortens the history, `prepareLoop` moves `switchedAt.messageCount` and `observedFrom` back to its end and keeps the request-based dwell.
|
|
100
|
+
|
|
97
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.
|
|
98
102
|
|
|
99
103
|
## State and controls
|
|
@@ -109,7 +113,7 @@ When a turn completes, the Mod labels it from the tool calls the assistant made
|
|
|
109
113
|
Two stores hold counts:
|
|
110
114
|
|
|
111
115
|
- **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.
|
|
112
|
-
- **Across sessions**:
|
|
116
|
+
- **Across sessions**: two `$.store` records per session. Each session's `activity:stats:v1:<session id>` 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), and `since`, its first count. 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. Before 1.10.3 every session shared one `activity:stats:v1` key, read-modified-written each turn, so two sessions finishing turns together could lose a count and a stale write could undo a reset; that key now counts as one more record in the sum until **Reset stats** deletes it, and 1.10.2 and earlier read only it. 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. Both 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 count; the readout the sum of all records, latency kept to the first 8 classifier ids; and the same reset marker. Each record is bounded, and the records grow by one per session that recorded a count until **Reset stats**, as the savings records do. The view keeps the last sums read or written as `activityStore` and `activityMetrics`: 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, every stats and metrics record, and the routing-vs-your-model totals below.
|
|
113
117
|
|
|
114
118
|
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
119
|
|
|
@@ -125,7 +129,7 @@ A subagent's model is chosen once, in the `agent.spawn` hook, before its cache e
|
|
|
125
129
|
- Workflow `agent()` calls raise `agent.spawn` with `e.workflow`, but a model rewrite there is ignored.
|
|
126
130
|
- The hook has 10 seconds of its own time. `$` calls do not count against it, but a `$.clock.sleep` does.
|
|
127
131
|
|
|
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. That bounds how long a subagent waits to start. No advice, a missing key,
|
|
132
|
+
`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.
|
|
129
133
|
|
|
130
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. 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
135
|
|
package/docs/configuration.md
CHANGED
|
@@ -70,7 +70,7 @@ The classifier also names the activity of a turn: what the turn produces. `activ
|
|
|
70
70
|
|
|
71
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
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
|
|
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. On the running task the activity can move either way during the turn; see [Changes during a task](user-guide.md#changes-during-a-task). 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.
|
|
74
74
|
|
|
75
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:
|
|
76
76
|
|
|
@@ -170,7 +170,7 @@ To check a classifier outside Claude Code, run `node scripts/probe-classifier.mj
|
|
|
170
170
|
|
|
171
171
|
### Ollama
|
|
172
172
|
|
|
173
|
-
`ollama` needs no key and keeps the text on this machine. Run `ollama serve`, pull the model named in `model`, and select the classifier. `model` is any tag you have pulled, such as `qwen3.5:9b`; change it under `classifiers.ollama.model`.
|
|
173
|
+
`ollama` needs no key and keeps the text on this machine. Run `ollama serve`, pull the model named in `model`, and select the classifier. `model` is any tag you have pulled, such as `qwen3.5:9b`; change it under `classifiers.ollama.model`. Plain `http` works only on `localhost`, `127.0.0.1`, or `[::1]`, so a server on another machine needs an `https` endpoint, and the prompt text then leaves this machine. Each request turns thinking off. The activity is a second request, sent after the route answer parses and only when at least 300 ms of the deadline remain; if it fails, the turn keeps the running activity and the classifier is not counted as failed. If Ollama rejects that setting for a model, the request fails and the router keeps the baseline. Ollama unloads an idle model after its keep-alive period, and the first request after that can exceed `timeoutMs` while the model loads; the router then keeps the baseline for that turn.
|
|
174
174
|
|
|
175
175
|
## Subagent routing
|
|
176
176
|
|
|
@@ -224,7 +224,7 @@ The values above are the defaults.
|
|
|
224
224
|
|
|
225
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.
|
|
226
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.
|
|
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.
|
|
227
|
+
- A classifier failure or a missing key keeps the model Claude Code gives the agent, and so does a model that `availableModels` blocks, or settings the router cannot read. So does routing off: `/router off`, or a `/model` choice.
|
|
228
228
|
- A spawn sets a model, not an effort. An agent's `effort` frontmatter still applies.
|
|
229
229
|
|
|
230
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.
|
|
@@ -267,14 +267,16 @@ Policy defaults:
|
|
|
267
267
|
| `upgradePivotUsd` | `0.5` | Cost scale used by the upgrade bar. Must be positive. |
|
|
268
268
|
| `jumpConfidence` | `0.95` | Support for a two-tier jump without waiting for votes. |
|
|
269
269
|
| `downgradeVotes` | `2` | Consecutive supporting votes before a downgrade; one before a history's first measured reply. |
|
|
270
|
-
| `downgradeMass` | `0.9` | Minimum probability mass required for a downgrade.
|
|
270
|
+
| `downgradeMass` | `0.9` | Minimum probability mass at or below the target tier required for a downgrade. |
|
|
271
271
|
| `downgradeSlope` | `0.08` | Maximum increase to the downgrade bar from estimated switching cost. |
|
|
272
272
|
| `downgradePivotUsd` | `0.5` | Cost scale used by the downgrade bar. Must be positive. |
|
|
273
273
|
| `downgradeHorizonTurns` | `5` | Later turns included in a downgrade payback estimate. |
|
|
274
|
-
| `continuationMass` | `0.7` | Advice probability
|
|
275
|
-
| `escalationHoldTurns` | `2` |
|
|
274
|
+
| `continuationMass` | `0.7` | Advice probability at which a new prompt counts as the running task, not a new one. |
|
|
275
|
+
| `escalationHoldTurns` | `2` | Decisions held after a repeated tool error escalates the route; each turn and in-turn review counts. |
|
|
276
276
|
| `cashCapUsd` | `2` | Maximum estimated cold cache write for a `credits` model. It does not cap output or session spend. |
|
|
277
277
|
| `activityMass` | `0.6` | Minimum probability for the classifier's activity to apply. Not tuned on any classifier. |
|
|
278
|
+
| `reviewEveryRequests` | `4` | Requests between classifier reviews inside a turn; `0` turns them off. Not tuned. |
|
|
279
|
+
| `minDwellRequests` | `8` | Requests after a model change before a cheaper route on the same task. Not tuned. |
|
|
278
280
|
|
|
279
281
|
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.
|
|
280
282
|
|
|
@@ -306,7 +308,7 @@ node ~/.claude/plugins/cache/alexei-led-claude-router/router/1.2.0/scripts/migra
|
|
|
306
308
|
|
|
307
309
|
Use the installed version in the path. From a checkout, run `node scripts/migrate-config.mjs ~/.claude/router.json`.
|
|
308
310
|
|
|
309
|
-
Pass the file under your active profile instead when `CLAUDE_CONFIG_DIR` points elsewhere. The command validates the converted configuration before writing it and creates an exact-byte `router.json.v0.8.backup` for a v0.8 file, or `router.json.v1.1.backup` for a 1.1 file. It refuses to overwrite an existing backup. Route, model-price, cache, and policy overrides remain in the converted file.
|
|
311
|
+
Pass the file under your active profile instead when `CLAUDE_CONFIG_DIR` points elsewhere. The command validates the converted configuration before writing it and creates an exact-byte `router.json.v0.8.backup` for a v0.8 file, or `router.json.v1.1.backup` for a 1.1 file. It refuses to overwrite an existing backup and to write through a symlink; it writes the converted file beside the original and renames it into place. Route, model-price, cache, and policy overrides remain in the converted file.
|
|
310
312
|
|
|
311
313
|
The converter removes old gateway and logging settings, request-feature fields, and model output caps. It moves `gateway.baselineTier` to top-level `baselineTier` and the `jev` section to `classifiers.jev`. It stops without writing when it finds an unsupported old field or invalid setting.
|
|
312
314
|
|
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, 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
|
|
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 per-session `activity:stats:v1:<session id>` and `activity:metrics:v1:<session id>` records described in [Architecture](architecture.md).
|
|
60
60
|
|
|
61
61
|
### Tool agreement
|
|
62
62
|
|
package/docs/native-router.md
CHANGED
|
@@ -4,7 +4,7 @@ This guide describes the Mod shipped in the plugin. Claude Code 2.1.289 is the m
|
|
|
4
4
|
|
|
5
5
|
## Turn behavior
|
|
6
6
|
|
|
7
|
-
At the first main step of a logical turn, the Mod reads recent message text and asks the active classifier (Jev, Clef, Clef Flash, OpenAI, or Ollama) for a tier, and for the turn's activity unless `activityRouting` is `off`. It applies local policy and saves the route. Tool continuations reuse that route. Before each continuation, context fit is checked again. A large tool result can move the step to a model with a larger window.
|
|
7
|
+
At the first main step of a logical turn, the Mod reads recent message text and asks the active classifier (Jev, Clef, Clef Flash, OpenAI, or Ollama) for a tier, and for the turn's activity unless `activityRouting` is `off`. It applies local policy and saves the route. Tool continuations reuse that route, except that a turn whose tool calls edit code moves up to the `code` route, and every `policy.reviewEveryRequests` requests a background classifier review may move it either way ([Changes during a task](user-guide.md#changes-during-a-task)). Before each continuation, context fit is checked again. A large tool result can move the step to a model with a larger window.
|
|
8
8
|
|
|
9
9
|
The classifier receives the current prompt and at most six preceding user or assistant text messages. Each item is limited to 1,200 characters. It does not receive system messages, tool inputs, or tool results. Claude Code's Anthropic credentials never enter the classifier request. Jev, Clef, Clef Flash, and OpenAI receive the text on their services; Ollama receives it on this machine. [Configuration](configuration.md#classifiers) lists each host.
|
|
10
10
|
|
package/docs/user-guide.md
CHANGED
|
@@ -43,35 +43,35 @@ Read the first line of the picture from left to right:
|
|
|
43
43
|
- **Switch cost**: `switch cost ≈ $0.37`, the policy's price for the switch it weighed this turn, mostly the prompt cache the other model must write. For a move to a cheaper model it is net of what that model saves over the next turns. The higher the cost, the higher the bar a stronger model must clear.
|
|
44
44
|
- **ctx** and **cache hit**: context use and the share of input read from the cache on the last reply. They turn yellow at 60% context and red at 80%.
|
|
45
45
|
|
|
46
|
-
| Band shows | Meaning
|
|
47
|
-
| ----------------------------------------------- |
|
|
48
|
-
| `Routing on · ready` | Routing is on and ready for a new turn.
|
|
49
|
-
| `choosing for this turn…` | The classifier and local policy are running. The spinner says `Choosing model`.
|
|
50
|
-
| `⏵ next turn: high ✕` | A pin is set. **✕** cancels it.
|
|
51
|
-
| `⚠ Jev: no API key · keeping model` | The active classifier lacks a setting. **Set up** opens the secure plugin dialog.
|
|
52
|
-
| `⚠ Clef: no account ID · keeping model` | Clef has its API token but no Cloudflare account ID. **Set up** opens the dialog.
|
|
53
|
-
| `⚠ Jev timed out · keeping model` | The classifier failed: timed out, unreachable, rejected the key, or paused.
|
|
54
|
-
| `○ Routing off [ Turn on ] · every turn uses …` | Routing is off: Claude's model answers every turn. **Turn on** turns it back on. The footer also shows `routing off`.
|
|
55
|
-
| `✕ Routing unavailable` | Nothing routes: an old Claude Code or leftover v0.8 settings. **Fix** opens the pane.
|
|
46
|
+
| Band shows | Meaning |
|
|
47
|
+
| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
|
48
|
+
| `Routing on · ready` | Routing is on and ready for a new turn. |
|
|
49
|
+
| `choosing for this turn…` | The classifier and local policy are running. The spinner says `Choosing model`. |
|
|
50
|
+
| `⏵ next turn: high ✕` | A pin is set. **✕** cancels it. |
|
|
51
|
+
| `⚠ Jev: no API key · keeping model` | The active classifier lacks a setting. **Set up** opens the secure plugin dialog. |
|
|
52
|
+
| `⚠ Clef: no account ID · keeping model` | Clef has its API token but no Cloudflare account ID. **Set up** opens the dialog. |
|
|
53
|
+
| `⚠ Jev timed out · keeping model` | The classifier failed: timed out, unreachable, rejected the key, or paused. |
|
|
54
|
+
| `○ Routing off [ Turn on ] · every turn uses …` | Routing is off: Claude's model answers every turn. **Turn on** turns it back on. The footer also shows `routing off`. |
|
|
55
|
+
| `✕ Routing unavailable` | Nothing routes: an old Claude Code or leftover v0.8 settings. **Fix** opens the pane. |
|
|
56
56
|
| `○ Router · subagents keep their own model` | You are viewing a subagent's transcript. Its steps are not routed; in `on` the band reads `subagent model chosen at spawn`. |
|
|
57
57
|
|
|
58
58
|
The band shows one routing control at a time. While routing is on, hover over the band for a second row: pin a tier for the next turn, **Turn off** routing, or show two rows. While routing is off, **Turn on** sits on the first line next to `Routing off` and stays at any width: a narrow band drops the explanation and the model first. On a narrow band the hover row drops `routing on`, then **2 rows**, then `pin next turn`, then the pins; it keeps **Turn off**, and **1 row** when the band shows two. The hover row needs a pointer: from the keyboard, run `/router off`, or open the pane and press `f`. The two-row band adds this session against your model, the one `/model` selects now: `session saved $1.84 (22%) vs Opus 5.5 · xhigh · 64 replies · cold-cache writes +$0.47`, or `session extra $2.48 (×5.0) vs Haiku 5.5 · high · 41 replies · stronger models +$2.31` when routing cost more. The last part names the larger of the two costs behind the result, when there is one. After a `/model` change the row shows the whole session against the new model. Before the tenth routed reply it reads `session 3 replies · too early to compare`. When the row is short, the cost part drops first, then the reply count. Router remembers that choice across sessions. When Router changes the model between turns, a toast reads `Model changed: old → new · reason`. A pin does not raise one, and neither does a change of effort alone.
|
|
59
59
|
|
|
60
60
|
The band steps aside while a survey needs the space.
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
Inside a turn the router checks the route again as the work changes; see [Changes during a task](#changes-during-a-task). A subagent gets at most one model, when it starts, and keeps it for every step: Haiku for exploration, Opus for clearly hard tasks, Sonnet for the rest. An agent that pins a model in its definition keeps it, unless it sets `modelRouting: auto`. The Usage tab's **SUBAGENTS** section shows what each agent type ran on and cost. See [Subagent routing](configuration.md#subagent-routing).
|
|
63
63
|
|
|
64
64
|
## Open the router pane
|
|
65
65
|
|
|
66
66
|
Run `/router` or select **Router** above the prompt. Without a UI surface, as in `claude -p`, `/router` prints a short status instead. The pane has five tabs. Select a tab or press its digit while the pane has focus.
|
|
67
67
|
|
|
68
|
-
| Tab | What it answers
|
|
69
|
-
| ------------ |
|
|
70
|
-
| 1 Now | What runs next turn, and why: tier, model, activity, the reason with the support it weighed; classifier support per tier with **pin**; the last 30 replies.
|
|
71
|
-
| 2 Routes | Which model runs: one grid of tiers by activities, the activity routing mode, and an editor for the selected cell.
|
|
72
|
-
| 3 Policy | How readily the router changes models: the start tier, going down, going up, the activity threshold, the credits cap; the `router.json` path.
|
|
73
|
-
| 4 Classifier | Which classifier to ask: one row per classifier to compare, the active one's deadline, wait, health and credentials, and the counts kept across sessions.
|
|
74
|
-
| 5 Usage | What routing cost: routing vs your model, plan quota, this session by activity, and Claude's readings with the estimates behind **details**.
|
|
68
|
+
| Tab | What it answers |
|
|
69
|
+
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
70
|
+
| 1 Now | What runs next turn, and why: tier, model, activity, the reason with the support it weighed; classifier support per tier with **pin**; the last 30 replies. |
|
|
71
|
+
| 2 Routes | Which model runs: one grid of tiers by activities, the activity routing mode, and an editor for the selected cell. |
|
|
72
|
+
| 3 Policy | How readily the router changes models: the start tier, going down, going up, the activity threshold, the credits cap; the `router.json` path. |
|
|
73
|
+
| 4 Classifier | Which classifier to ask: one row per classifier to compare, the active one's deadline, wait, health and credentials, and the counts kept across sessions. |
|
|
74
|
+
| 5 Usage | What routing cost: routing vs your model, plan quota, this session by activity, and Claude's readings with the estimates behind **details**. |
|
|
75
75
|
|
|
76
76
|
The top line of every tab, `ROUTING [ ◉ on ] [ ○ off ] Jev ready · 347 ms`, shows the routing mode, switches it, and says whether the classifier is ready. Press `o` or `f` while the pane has focus. **?** shows what the estimates leave out. When routing is unavailable, the top line reads `ROUTING unavailable Claude’s model is kept` with the reason under it, and offers no on or off: see [Troubleshooting](#troubleshooting).
|
|
77
77
|
|
|
@@ -97,7 +97,7 @@ The Usage tab opens with the answer, such as `Routing saved $1.84 (22%) this ses
|
|
|
97
97
|
| Line | What it is |
|
|
98
98
|
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
99
99
|
| Routed replies | What the routed replies cost on the models that served them. |
|
|
100
|
-
| Same tokens on your model | What the same input and output tokens cost on your model, with one cache that never switched.
|
|
100
|
+
| Same tokens on your model | What the same input and output tokens cost on your model, with one cache that never switched. |
|
|
101
101
|
| Difference | Routed minus yours. Green with a percentage when routing cost less; amber with `+$` when it cost more, `×N` once it is twice yours or more. |
|
|
102
102
|
| cheaper models | The part from replies on models cheaper than yours. |
|
|
103
103
|
| stronger than yours | The part from replies on stronger models, with how many replies ran on them. |
|
|
@@ -141,10 +141,10 @@ A mixed turn such as "fix it and commit" takes the hardest part, here `code`. Th
|
|
|
141
141
|
|
|
142
142
|
The mode decides what happens with the label:
|
|
143
143
|
|
|
144
|
-
| Mode
|
|
145
|
-
|
|
|
146
|
-
| `on`
|
|
147
|
-
| `off`
|
|
144
|
+
| Mode | What the router does |
|
|
145
|
+
| ----- | ------------------------------------------------------------------------------------------ |
|
|
146
|
+
| `on` | The default. Applies the activity overrides. |
|
|
147
|
+
| `off` | Does not ask the activity: the classifier is asked for the tier only. The base routes run. |
|
|
148
148
|
|
|
149
149
|
To turn activity routing off, run `/router activities off`, or set **Activity routing** at the top of the Routes tab and press **Save**. Routing itself stays on: only the activity overrides stop. Upgrading from 1.6, which asked the activity but ran the base routes, run `/router activities off` to keep 1.6's routes. A `router.json` that still sets `"shadow"`, for activity or subagent routing, is read as not setting it, so the default, `on`, runs.
|
|
150
150
|
|
|
@@ -154,13 +154,30 @@ How the router moves inside a tier:
|
|
|
154
154
|
|
|
155
155
|
- It compares routes, not labels. If the new activity resolves to the route already running, nothing switches.
|
|
156
156
|
- A move to a stronger route needs the classifier's support, as an upgrade between tiers does. A move to a cheaper one must pay back its cache write within the payback horizon. One vote is enough for either, because the activity is a fact about this turn.
|
|
157
|
-
- An activity applies only when the classifier gives it at least 60% probability (`policy.activityMass`). Below that, or on `uncertain`, a new task goes back to its base route if the move passes the same checks
|
|
157
|
+
- An activity applies only when the classifier gives it at least 60% probability (`policy.activityMass`). Below that, or on `uncertain`, a new task goes back to its base route if the move passes the same checks. On the running task the activity can move either way while the turn runs; see [Changes during a task](#changes-during-a-task).
|
|
158
158
|
- A pinned turn uses the pin's base route and shows no activity.
|
|
159
159
|
- When the classifier gives no answer at all (a timeout, a failure, a pause, or a missing key), the running route stays. When it answers the tier but gives no usable activity, only the running activity stays: the tier answer still applies, so the turn can change tier and keeps its activity there. In `off` the base route always runs.
|
|
160
160
|
- A fresh session starts with routing on when the session model is a tier's route. With activity routing `on`, a model that only an activity override uses also counts: Sonnet 5.5 on the defaults. In `off` it does not.
|
|
161
161
|
|
|
162
162
|
The band's activity label appears only when the activity applies, so a weak or `uncertain` answer shows none. The two-row band and the **Replies** strip show the activities of recent replies.
|
|
163
163
|
|
|
164
|
+
### Changes during a task
|
|
165
|
+
|
|
166
|
+
The classifier labels a turn from its prompt, and the work can change after that: a brief that reads as `ops` may turn into an hour of coding, and a hard fix may end in routine commands. The router therefore checks the route again while a task runs, for the tier and the activity, in both directions.
|
|
167
|
+
|
|
168
|
+
- **On every later step of a turn** it reads the turn's tool calls. A turn labelled `ops` or `explore` that edits a code file moves at once to the tier's `code` route (`docs` when it edits only Markdown or `docs/` files). The tools are the evidence, so this needs no classifier support, and the cache cost does not hold it back; only the cash cap on a credits-billed model can. This move only goes up. The toast and the band show it as `↗ coding`.
|
|
169
|
+
- **Every 4 requests inside a turn** (`policy.reviewEveryRequests`) it asks the classifier again, in the background, with the turn's prompt and the recent dialogue. A step never waits for the answer: it applies at the first step after it arrives. Each review sends the classifier the same kind of text a new turn does. `0` turns reviews off.
|
|
170
|
+
- **A new prompt that continues the task**, such as a task notification, a message from another agent, or "go on", is decided the same way as a review.
|
|
171
|
+
|
|
172
|
+
On the running task:
|
|
173
|
+
|
|
174
|
+
- A stronger tier takes the usual votes: two agreeing answers, or one for a clear two-tier jump. A stronger activity takes one answer whose probability clears the cache check. Repeated tool errors still escalate at once.
|
|
175
|
+
- A cheaper tier or activity also waits for a checkpoint: at least 8 requests since the last model change (`policy.minDwellRequests`), and the last test, build, lint or type-check command since then passed. A check is a test runner, type checker or linter (`pytest`, `tsc`, `eslint`), or a launcher running one (`npm test`, `go test`, `make lint`), alone or after `&&`. A check piped into another command (`npm test | tail`), followed by `;` or `|| true`, or sent to the background does not count, because its exit status can hide a failure or is not known yet. While none ran, or the last one failed, the route stays: for a tier the band shows `… down after a passed check`; a held activity keeps the running one and shows `= fits`. A cheaper activity also needs 90% probability (`policy.downgradeMass`).
|
|
176
|
+
- A cheaper tier lands where the answer as a whole points: when the classifier says `micro` 63% and `low` 30%, the turn moves to `low`, which 93% of the answer supports, instead of staying until `micro` alone reaches 90%.
|
|
177
|
+
- A pinned turn does not move. A new task, a prompt the classifier does not score as a continuation, is routed as a fresh turn. Ollama does not answer the continuation question, so every prompt is a new task to it; reviews inside a turn still apply.
|
|
178
|
+
|
|
179
|
+
These thresholds are starting values. They are not tuned on data yet.
|
|
180
|
+
|
|
164
181
|
### Read the activity on the pane
|
|
165
182
|
|
|
166
183
|
- **Now**: the **Activity** line names the classifier's choice as a verb with its share, the two next-best answers, and the threshold at which an activity applies, such as `coding 84% debugging 8% · planning 5% applies at 60%+`. An `uncertain` answer is shown dim: it applies no activity. In `on`, **Why** names the cell when the activity moved the route or the route is an override, such as `coding at low runs on Sonnet 5.5 · high`, or `low runs on its base route, Haiku 5.5 · high` for a move without an activity; a refused move, a hold, or a tier change keeps its reason. **Last replies** counts the replies per activity under the strip.
|
|
@@ -179,7 +196,7 @@ On the **Classifier** tab, **ACROSS SESSIONS · since the last reset** shows the
|
|
|
179
196
|
| `/router auto` | Resume automatic routing. |
|
|
180
197
|
| `/router off` | Turn routing off and keep Claude's selected model. |
|
|
181
198
|
| `/router pin <micro\|low\|medium\|high>` | Pin the next turn and its tool continuations. Routing on must already be enabled. |
|
|
182
|
-
| `/router activities <off\|on>`
|
|
199
|
+
| `/router activities <off\|on>` | Set the [activity routing](#route-by-activity) mode. Saved to `router.json` at once; **Undo** reverts it. |
|
|
183
200
|
| `/model <name>` | Select a model and turn routing off. Use `/router auto` to turn it back on. |
|
|
184
201
|
| **Turn on** / **Turn off** on the band | The same as `/router auto` and `/router off`. |
|
|
185
202
|
| **on** / **off** on the pane (`o` / `f`) | The same as `/router auto` and `/router off`. |
|
|
@@ -217,7 +234,7 @@ The **Policy** tab writes each control inside the sentence it completes, and nam
|
|
|
217
234
|
- **Start** at a tier: the tier a session starts from when its model is no tier's model (`baselineTier`).
|
|
218
235
|
- **Going down** after 1, 2, or 3 agreeing turns in a row, and only if a cache write pays back within 1, 3, 5, or 10 later turns. A new or reset history needs one vote.
|
|
219
236
|
- **Going up** needs the classifier's support at 75%, raised up to 90% as the switch costs more. Read-only here; see [Configuration](configuration.md).
|
|
220
|
-
- **Activities** apply at 50%, 60%, 70%, or 80% certainty or more. Below it a new task runs its tier's model
|
|
237
|
+
- **Activities** apply at 50%, 60%, 70%, or 80% certainty or more. Below it a new task runs its tier's model; the running task follows [Changes during a task](#changes-during-a-task). See [Activity routing](activity-routing.md#change-a-cell).
|
|
221
238
|
- **Credits** caps one cold cache write on a `credits` model at $0.50, $1, $2, or $5. With no `credits` model in `router.json`, the tab says the cap has no effect.
|
|
222
239
|
|
|
223
240
|
**Reset policy to defaults** loads the built-in values; **Save** then removes your policy overrides. The current turn keeps the settings it started with. A save preserves unrelated `router.json` keys and refuses to write through a symlink. When validation fails, the pane names the setting and leaves the file unchanged. The tab ends with the `router.json` path, a **copy** button, and the [subagent routing](configuration.md#subagent-routing) mode, which is set in `router.json`.
|