@alexeiled/claude-router 1.15.0 → 1.16.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.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "router",
3
3
  "displayName": "Router",
4
- "version": "1.15.0",
4
+ "version": "1.16.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,35 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.16.0 (2026-10-28)
4
+
5
+ Routing is now explainable after the fact, task notifications route as progress on the task they report on, and `cost` mode moves a hard task off Haiku. See [Routing decisions](docs/user-guide.md#routing-decisions) and [Changes during a task](docs/user-guide.md#changes-during-a-task).
6
+
7
+ ### Added
8
+
9
+ - Every routed turn records its routing decisions in `$.store` (`decisions:v1:<session id>`): the prompt's origin, the classifier's tier and activity with their shares, whether the turn counted as the running task, the tier, activity, route and reason chosen, and at the end the turn's tool bucket and how many of its replies were priced. No prompt, tool or path text. `/router decisions [n]` prints them. Each session keeps 60 rows; other sessions' records stay for 30 days, 20 at most. **Delete history** deletes them.
10
+ - Routed replies the usage record leaves out are counted by cause (no usage, no configured price, unknown cache lifetime, failed comparison) in the activity metrics. The Classifier tab's **ACROSS SESSIONS** block and `/router` show **Unpriced**. Before, such replies left no trace, and a session whose replies were all unpriced had no usage record.
11
+ - The band shows `effort only` beside the mode when `cost` or `quality` kept the cell's model and changed only its effort. The cost estimates price the same tokens on both routes, so such a change shows no difference there.
12
+ - The tool check behind activity agreement has two more buckets: `shell` for a Bash command that writes a file (a redirect, `tee`, `sed -i`, `perl -i`, `patch`, `git apply`), a candidate for code, docs or routine work, and `check` for a turn that only ran checks and reads. A review that ran the tests and an edit made through the shell no longer count as misses. Routing reads both as `ops`, as before.
13
+ - The `router decision` debug line names the prompt's origin.
14
+
15
+ ### Changed
16
+
17
+ - The router reads where each prompt came from (`prompt.submit`'s origin). A task notification, an observer's report or a programmatic follow-up is now always progress on the running task. The classifier is asked about your last request, with the notification as the newest dialogue line, instead of about the notification's text. A cheaper route still waits for the checkpoint. After a resume, until you send a prompt, a notification is asked about as it reads.
18
+ - A cheaper route on the same task waits for a checkpoint that fits the work the route runs for, not only a passed test, build or lint run. Without a passed check, `ops` needs the last command to have succeeded with no edit or delegation since; `docs` needs a successful doc-only edit with no command beside it; `explore`, `plan` and `review` need a finished turn that changed, ran and delegated nothing and ended without a tool error. `code`, `debug` and a route with no activity still need the passed check. A check that failed, or ran in a form whose status is not its own (`npm test && git push`, `npm test > log`, `npm test | tail`, the background), blocks every one of these. The band's held reason now reads `… down after a checkpoint`.
19
+ - `cost` upgrades on balanced's bar: `modes.cost.policy.upgradeVotes` 3 → 2 and `upgradeBase` 0.85 → 0.75. With the old values the cache write of a cold stronger model raised the bar to about 0.92 from 60k tokens and 0.97 at 250k, so a cost turn on Haiku kept a task the classifier scored hard at 90% through any number of answers. Cost still moves down sooner than balanced. This spends more on hard tasks in cost mode; it is not tuned on outcomes.
20
+
21
+ ### Known limitations
22
+
23
+ - The active goal a notification is judged against is held in memory, for the session: it is not kept across a resume or a plugin reload.
24
+ - A prompt is matched to its turn by the engine's order of events and by its text. A turn the router cannot match records origin `unknown` and routes as before.
25
+ - The classifier still reads text only. The tool calls, errors and edits of a turn reach the policy (the observed move, repeated-failure escalation, the checkpoint), not the classifier.
26
+ - A `shell` turn agrees with every activity that may produce it, so the agreement check cannot catch a cheap route on code written through the shell.
27
+
28
+ ### Migration
29
+
30
+ - No `router.json` change is needed. To keep the old cost upgrade bar, set `"modes": { "cost": { "policy": { "upgradeVotes": 3, "upgradeBase": 0.85 } } }`.
31
+ - An activity stats record holding the new `shell` or `check` buckets reads as empty in an older version. Agreement from before 1.16 is not comparable with agreement after it.
32
+
3
33
  ## 1.15.0 (2026-10-22)
4
34
 
5
35
  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).
package/README.md CHANGED
@@ -55,7 +55,7 @@ sequenceDiagram
55
55
  Mod-->>Dev: Status band and router pane
56
56
  ```
57
57
 
58
- 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
+ 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 checkpoint its work can show: a passed test, build or lint run, or for commands, docs and read-only work the success the router can see. A task notification is routed as progress on your last request. `/router decisions` lists why each turn ran where it did. 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.
59
59
 
60
60
  | Tier | Default model | Effort |
61
61
  | -------- | ------------- | -------- |
@@ -76,7 +76,7 @@ A logical turn is classified at its first step, and again every `reviewEveryRequ
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. 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.
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, a turn whose prompt has a progress origin, 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 a checkpoint since then (`completedSince`). The last verification command (`verifiedSince`: a Bash test, build, lint or type-check run) passing always counts. Without one, the running route's activity decides: for `ops` the last command that ran something succeeded with no edit or delegation since, for `docs` the last edit succeeded and touched only doc paths with no command run beside it, and for `explore`, `plan` and `review` a turn finished with nothing edited, written, run or delegated and no error as the last tool result. `code`, `debug` and a route with no activity need the passed check, and a check that ran in any form (chained, redirected, piped, after `;` or `||`, in the background) without passing last blocks every shortcut (`runsAnyCheck`). Each rule asks for a success it can see; the absence of an edit alone is never evidence.
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
 
@@ -96,7 +96,7 @@ The router decides on a _cell_: a tier and an activity. The route is `{ ...route
96
96
 
97
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
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.
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 classifier reads text only: the dialogue holds user and assistant text, not tool calls, results or edits. The policy reads those itself (`observedMove`, repeated failures, `completedSince`). 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
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
 
@@ -106,9 +106,13 @@ The routing mode (`lib/modes.mjs`) is a fixed transform of the configured routes
106
106
 
107
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
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.
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 checkpoint), as a tier downgrade does, and the downgrade tax must still be paid back.
110
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.
111
+ The turn-start decision (`decideTurn`) writes `router decision {mode, modeSource, origin, 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.
112
+
113
+ **Prompt origin.** `turn.start` carries the prompt text but not its origin; `prompt.submit` carries `origin` (`PromptOrigin`), stamped by the engine. The hook keeps the kind (`originKind` in `lib/decisions.mjs`). An idle submission starts its turn inside `next(e)`, so that turn takes it; a submission queued behind a running turn waits (`queueOrigin`, at most 16 for at most 10 minutes) and names the later turn that starts with its text (`takeOrigin`), or expires when it was delivered into the running turn. Unmatched turns are `unknown` and route as before. A progress origin (`task-notification`, `observer`, `observer-activity`, `auto-continuation`) sets `facts.progress`, so the turn is the same task (`sameTaskOf`), and `progressInput` asks the classifier about the session's active goal, with the notification as the newest dialogue line. The goal is the last prompt from a goal origin (`composer`, `peer`, `plugin`, …), held in memory for the session only: after a resume or a reload a notification is asked about as it reads. `unclassified` and kinds a later engine adds route as before and leave the goal.
114
+
115
+ **Decision record.** Each routed turn collects rows (`decisionRow`): its start, each applied review, each observed move, at most 10 per turn (`addTurnRow`), and at `turn.complete` an end row (`endRow`) with the turn's tool bucket, routed requests, priced requests and unpriced ones by cause. `flushDecisions` adds them to the session's own `decisions:v1:<session id>` record (newest 60 rows) under the reset marker, like the usage records. Session start deletes other sessions' records past 30 days or beyond the 20 newest (`prunedDecisions`), each read again before its delete. Rows hold labels, shares and counts, never prompt, tool or path text. `/router decisions [n]` prints them; **Delete history** deletes them. `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
116
 
113
117
  ## State and controls
114
118
 
@@ -123,7 +127,7 @@ When a turn completes, the Mod labels it from the tool calls the assistant made
123
127
  Two stores hold counts:
124
128
 
125
129
  - **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 `strip`, every reply since Claude Code started the session by tier in at most 48 cells that merge in pairs, with when its first reply arrived, and `lastSwitch`, the last route change with its tiers, routes and activity.
126
- - **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 **Delete history** 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 usage 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 **Delete history**. 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. **Delete history** clears the session counts, every stats and metrics record, and the usage records below.
130
+ - **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 **Delete history** 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, the routed replies left unpriced by cause (`unpriced`: `usage`, `model`, `ttl`, `error`, from `unpricedCause` in `lib/savings.mjs`; 1.16), 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 usage 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 **Delete history**. 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. **Delete history** clears the session counts, every stats and metrics record, and the usage records below.
127
131
 
128
132
  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.
129
133
 
@@ -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 Classifier 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). The active classifier's p95 wait is on its **Deadline** line on the same tab, above that block. 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).
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 Classifier 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), **Unpriced** for the routed replies the usage record left out, by cause: no usage in the reply, a model without a configured price, an unknown cache lifetime, or a failed comparison. Before 1.16 those replies were dropped without a count, so usage covered only the priced part of the routed traffic, and a session whose replies were all unpriced left no usage record at all. The active classifier's p95 wait is on its **Deadline** line on the same tab, above that block. 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
 
@@ -66,7 +66,9 @@ Each finished turn is labelled from the tools the assistant used, locally and at
66
66
  | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
67
67
  | `code` | An edit tool (`Edit`, `Write`, `MultiEdit`, `NotebookEdit`) on a path that is not a doc path |
68
68
  | `docs` | Edits only to paths ending `.md`, `.mdx`, `.rst`, or `.txt`, or under a `docs/` directory |
69
- | `ops` | A Bash command that is not read-only |
69
+ | `shell` | A Bash command that writes a file's content: an output redirect to a file, `tee`, `sed -i`, `perl -i`, `patch` or `git apply`. A candidate for code, docs or routine work, not proof of code |
70
+ | `ops` | A Bash command that runs something else: `git commit`, `rm`, `mv`, `mkdir`, a deploy, a check followed by another command |
71
+ | `check` | Bash commands that are only checks (`npm test`, `tsc`, `npm run lint && npm test`) or reads |
70
72
  | `read` | Other tool use: reads, searches, web fetches, Task, TodoWrite, MCP tools, and Bash commands that only read, such as `ls`, `grep`, `cat`, or `git status` and `git diff` |
71
73
  | `talk` | No tool calls |
72
74
 
@@ -74,15 +76,17 @@ A subagent's edits and commands never reach the main transcript, so a turn that
74
76
 
75
77
  The classifier's activity agrees with the turn when the bucket is one it allows:
76
78
 
77
- | Activity | Allowed buckets |
78
- | --------- | ---------------------- |
79
- | `code` | `code` |
80
- | `debug` | `code`, `ops`, `read` |
81
- | `explore` | `read`, `talk` |
82
- | `plan` | `talk`, `read`, `docs` |
83
- | `review` | `read`, `talk` |
84
- | `ops` | `ops`, `read` |
85
- | `docs` | `docs` |
79
+ | Activity | Allowed buckets |
80
+ | --------- | ------------------------------------------ |
81
+ | `code` | `code`, `shell` |
82
+ | `debug` | `code`, `shell`, `ops`, `check`, `read` |
83
+ | `explore` | `read`, `talk` |
84
+ | `plan` | `talk`, `read`, `docs` |
85
+ | `review` | `read`, `talk`, `check` |
86
+ | `ops` | `ops`, `shell`, `check`, `read` |
87
+ | `docs` | `docs`, `shell` |
88
+
89
+ Before 1.16 a shell write, a check run and any other command were all `ops`. A `code` turn that edited through the shell therefore read as a miss, and so did a review that ran the tests. The finer buckets keep that apart. Because a shell write cannot be told from routine work, it agrees with every activity that may produce it, so it cannot catch a cheap route on shell-written code. Agreement from before 1.16 and after it is not comparable, and a store holding the new buckets reads as empty in an older version. Routing reads `shell` and `check` as `ops`, as before.
86
90
 
87
91
  Agreement is a weak check. It tells `code` from `ops` and `explore` well, but not `ops` from `explore` when the commands only read. It cannot tell `plan` from `review`, and it says nothing about whether the route was good enough. It does catch the costly mistake, a cheap route on a coding turn. The Classifier tab shows the session's count as `Agreement` under **THIS SESSION**, over the turns where the classifier gave an activity at or above `activityMass`, in `on` too when the route kept another activity. The counts kept across sessions hold the classifier's raw answer, `uncertain` and no answer included, against the bucket. The pane's **ACROSS SESSIONS** block counts agreement over the answers that name an activity; `uncertain` and no answer appear only in **Labelled**.
88
92
 
@@ -22,6 +22,7 @@ The activity is what the turn produces: `code`, `debug`, `explore`, `plan`, `rev
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
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. |
25
+ | `/router decisions [n]` | Print this session's last `n` routing decisions (default 20, at most 60): origin, classifier answer, task, tier, route, reason, and each turn's end. No text. |
25
26
  | `/model <name>` | Select a model and turn routing off. `/router auto` turns it back on. |
26
27
 
27
28
  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.
@@ -36,18 +36,22 @@ names a mode other than balanced.
36
36
 
37
37
  A change applies from the next turn. It changes the route the router prefers; the route in use moves through the
38
38
  same checks as any other switch. On the same task a cheaper route waits until `minDwellRequests` requests have run on
39
- the route in use and a check (tests, build, lint) has passed since. A move must also pay back its cache write. Until
39
+ the route in use and a checkpoint since: a passed check (tests, build, lint), or the success the route's activity can
40
+ show ([Changes during a task](user-guide.md#changes-during-a-task)). A move must also pay back its cache write. Until
40
41
  then the band says why the route stays. Pin a tier to run its configured route now.
41
42
 
42
43
  ## Policy per mode
43
44
 
44
- Each mode except `balanced` replaces some `policy` fields while it is active. The built-in values come from
45
- codex-router and are **not tuned** on this router:
45
+ Each mode except `balanced` replaces some `policy` fields while it is active. The built-in values started as
46
+ codex-router's and are **not tuned** on outcomes. Since 1.16, `cost` upgrades on balanced's bar (2 votes from 0.75):
47
+ with 3 votes from 0.85, the cache write of a cold stronger model raised the bar to about 0.92 from 60k tokens and 0.97
48
+ at 250k, so a cost turn on Haiku kept a task the classifier scored hard at 90%. `cost` still moves down sooner than
49
+ `balanced` (one vote, 80% support, a 4-request dwell):
46
50
 
47
51
  ```json
48
52
  {
49
53
  "modes": {
50
- "cost": { "policy": { "upgradeVotes": 3, "upgradeBase": 0.85, "jumpConfidence": 0.98, "downgradeVotes": 1,
54
+ "cost": { "policy": { "upgradeVotes": 2, "upgradeBase": 0.75, "jumpConfidence": 0.98, "downgradeVotes": 1,
51
55
  "downgradeMass": 0.8, "minDwellRequests": 4, "escalationHoldTurns": 1 } },
52
56
  "quality": { "policy": { "upgradeVotes": 1, "upgradeBase": 0.6, "jumpConfidence": 0.9, "downgradeVotes": 3,
53
57
  "downgradeMass": 0.95, "minDwellRequests": 16, "escalationHoldTurns": 4 } }
@@ -194,12 +194,18 @@ The classifier labels a turn from its prompt, and the work can change after that
194
194
 
195
195
  - **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`.
196
196
  - **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.
197
- - **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.
197
+ - **A new prompt that continues the task** is decided the same way as a review. Claude Code stamps each prompt with where it came from. A task notification, an observer's report or a programmatic follow-up is always progress on the running task: the classifier is asked about your last request, with the notification as the newest dialogue line, so it judges the work still to do rather than the notification's wording. A message from you or another agent, or "go on", counts as the running task when the classifier scores it as a continuation. After a resume the router does not know your last request yet, so a notification is judged as it reads.
198
198
 
199
199
  On the running task:
200
200
 
201
201
  - 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.
202
- - 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`).
202
+ - A cheaper tier or activity also waits for a checkpoint: at least 8 requests since the last model change (`policy.minDwellRequests`), and a success since then that fits the work the route runs for. A passed test, build, lint or type-check always counts. 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. Without a passed check, the route's activity decides what counts:
203
+ - `ops`: the last command that ran something succeeded, with no file edit or delegated agent since.
204
+ - `docs`: the last edit succeeded and touched only Markdown, text or `docs/` files, with no command run beside it.
205
+ - `explore`, `plan`, `review`: a turn finished, nothing was edited, written, run or delegated, and the last tool result was not an error.
206
+ - `code`, `debug` and a route with no activity: only a passed check counts.
207
+
208
+ A failed check blocks every one of these, and so does a check whose result is not the check's own (chained, redirected, piped, after `;` or `||`, or in the background). While no checkpoint is met, the route stays: for a tier the band shows `… down after a checkpoint`; a held activity keeps the running one and shows `= fits`. A cheaper activity also needs 90% probability (`policy.downgradeMass`).
203
209
  - 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%.
204
210
  - 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.
205
211
 
@@ -227,12 +233,17 @@ On the **Classifier** tab, **ACROSS SESSIONS · since the last reset** shows the
227
233
  | `/router activities <off\|on>` | Set the [activity routing](#route-by-activity) mode. Saved to `router.json` at once; **Undo** reverts it. |
228
234
  | `/router mode <cost\|balanced\|quality>` | Set this session's [routing mode](routing-modes.md) from the next turn. A resume keeps it. |
229
235
  | `/router mode default` | Clear the session's mode: the project's or the profile's applies again. |
236
+ | `/router decisions [n]` | Print this session's last `n` routing decisions, 20 by default. See [Routing decisions](#routing-decisions). |
230
237
  | `/model <name>` | Select a model and turn routing off. Use `/router auto` to turn it back on. |
231
238
  | **Turn on** / **Turn off** on the band | The same as `/router auto` and `/router off`. |
232
239
  | **on** / **off** on the pane (`o` / `f`) | The same as `/router auto` and `/router off`. |
233
240
  | **pin** on the Now tab | Pin that tier for the next turn. Routing on must already be enabled. |
234
241
 
235
- A routing mode moves each tier's route one step toward cost or quality; pins and `micro` turns are not moved. The band and the Now tab show the mode and where it comes from, such as `cost (session)`. A change applies from the next turn, and the route in use moves only through the usual checks, so on a running task a cheaper route can wait a few requests and for a passed test. **Mode** on the Policy tab sets the profile's mode. See [Routing modes](routing-modes.md).
242
+ A routing mode moves each tier's route one step toward cost or quality; pins and `micro` turns are not moved. The band and the Now tab show the mode and where it comes from, such as `cost (session)`. When the mode kept the cell's model and changed only its effort, as `cost` does for Opus at `high`, the band adds `effort only`: the cost estimates price the same tokens on both routes, so that change shows no difference there, though real output length can differ. A change applies from the next turn, and the route in use moves only through the usual checks, so on a running task a cheaper route can wait a few requests and for a checkpoint. **Mode** on the Policy tab sets the profile's mode. See [Routing modes](routing-modes.md).
243
+
244
+ ### Routing decisions
245
+
246
+ Each routed turn adds rows to the session's decision record in `$.store` (`decisions:v1:<session id>`): one when the turn starts, one per classifier review or tool-based move inside it, and one when it ends. A row holds the prompt's origin (`composer`, `task-notification`, …, or `unknown`), the classifier's tier and activity with their shares, whether it counted as the running task, the tier, activity, route and reason chosen, and at the end the turn's tool bucket and how many replies were priced. It holds no prompt, tool or file text. `/router decisions [n]` prints them. Each session keeps its newest 60 rows; records of the 20 most recent other sessions stay, for at most 30 days. **Delete history** deletes them all.
236
247
 
237
248
  A pin does not change the next turn after the pinned turn finishes. A fresh session on a model that a tier routes to, or with activity routing `on` a model an activity override uses (Sonnet 5.5 on the defaults), starts with routing on. A fresh session on any other model starts with routing off. `/clear` starts the new session with routing on. Resuming a saved session restores its saved routing on or off.
238
249