@alexeiled/claude-router 1.15.0 → 1.17.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,8 +1,8 @@
1
1
  {
2
2
  "name": "router",
3
3
  "displayName": "Router",
4
- "version": "1.15.0",
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.",
4
+ "version": "1.17.0",
5
+ "description": "Native model and effort routing within your provider. Anthropic, DeepSeek and z.ai defaults, custom provider profiles, classifier advice and one model per subagent.",
6
6
  "author": {
7
7
  "name": "Alexei Ledenev",
8
8
  "url": "https://github.com/alexei-led"
package/CHANGELOG.md CHANGED
@@ -1,5 +1,61 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.17.0 (2026-10-28)
4
+
5
+ Route models and effort within your configured provider. Anthropic remains the default. DeepSeek and z.ai gain built-in profiles, and other Anthropic-compatible providers can use custom profiles without another proxy.
6
+
7
+ ### Added
8
+
9
+ - `CLAUDE_ROUTER_PROVIDER` selects `<provider>-router.json` in the active Claude Code profile. Selection stays fixed for the session, including pane Save/Undo. Missing or invalid selected files warn and preserve Claude Code's model and effort instead of falling back to `router.json`.
10
+ - DeepSeek Flash defaults route `low`, `high`, and `max` effort on one model. z.ai defaults combine GLM-5.3-Flash and GLM-5.3, with activity-specific routes.
11
+ - Custom profiles support OpenRouter, Ollama, other local servers and compatible hosted endpoints. Supply the model catalog and all four routes.
12
+ - [Provider documentation](docs/providers.md) covers names, defaults, custom files and the existing `--settings` flag alternative. There is no dedicated `--provider` flag.
13
+
14
+ ### Changed
15
+
16
+ - Cache accounting supports explicit, automatic and disabled policies. Automatic caches use hit/miss input rates without invented TTLs or write premiums. Unknown counterfactual comparisons are reported separately from known observed costs.
17
+ - Model metadata can declare strength and image support. Provider allowlists use exact model identities, and the `[1m]` context hint is normalized without merging distinct versions.
18
+
19
+ ### Upgrade
20
+
21
+ - Existing Anthropic users need no configuration change.
22
+ - Before selecting `deepseek` or `zai`, create its named router file. Use `{}` for built-in defaults. Other provider names require a complete profile.
23
+ - Set the selector before launching Claude Code. Project/local settings cannot redirect it.
24
+
25
+ ### Limits
26
+
27
+ Routing stays within one configured endpoint. Subagents receive a model, not routed effort. Defaults are starting policies, not measured quality or savings guarantees. Positive z.ai cache hits remain unverified.
28
+
29
+ ## 1.16.0 (2026-10-28)
30
+
31
+ 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).
32
+
33
+ ### Added
34
+
35
+ - 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.
36
+ - 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.
37
+ - 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.
38
+ - 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.
39
+ - The `router decision` debug line names the prompt's origin.
40
+
41
+ ### Changed
42
+
43
+ - 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.
44
+ - 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`.
45
+ - `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.
46
+
47
+ ### Known limitations
48
+
49
+ - 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.
50
+ - 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.
51
+ - 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.
52
+ - 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.
53
+
54
+ ### Migration
55
+
56
+ - No `router.json` change is needed. To keep the old cost upgrade bar, set `"modes": { "cost": { "policy": { "upgradeVotes": 3, "upgradeBase": 0.85 } } }`.
57
+ - 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.
58
+
3
59
  ## 1.15.0 (2026-10-22)
4
60
 
5
61
  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
@@ -5,11 +5,34 @@
5
5
 
6
6
  **A Claude Code Mod that chooses a model and effort for each main-conversation turn, advised by a prompt classifier: Jev; Cloudflare's Clef, Clef Flash or Clef Omni; OpenAI; or a local Ollama model.**
7
7
 
8
- The Mod changes only the model and effort in Claude Code's turn hook. Claude Code sends the request, streams the reply, runs tools, and reports usage. The router does not proxy Anthropic traffic or start a local server; an Ollama classifier calls an Ollama server that you run. Subagents get one model each when they start, chosen the same way: every agent whose definition names no model, says `model: inherit`, or sets `modelRouting: auto`. Their steps are never re-routed. See [Subagent routing](docs/configuration.md#subagent-routing).
8
+ The Mod changes only the model and effort in Claude Code's turn hook. Claude Code sends the request, streams the reply, runs tools, and reports usage. The router does not proxy model traffic or start a local server; an Ollama classifier calls an Ollama server that you run. Subagents get one model each when they start, chosen the same way: every agent whose definition names no model, says `model: inherit`, or sets `modelRouting: auto`. Their steps are never re-routed. See [Subagent routing](docs/configuration.md#subagent-routing).
9
+
10
+ ## Providers
11
+
12
+ Use the provider that already works with Claude Code. Select its router profile, not a new endpoint:
13
+
14
+ ```sh
15
+ CLAUDE_ROUTER_PROVIDER=deepseek claude --model 'deepseek-flash[1m]'
16
+ ```
17
+
18
+ Create `~/.claude/deepseek-router.json` containing `{}` to use DeepSeek defaults.
19
+ With `CLAUDE_CONFIG_DIR`, put the file in that directory instead.
20
+
21
+ | Built-in profile | Router file | Default models |
22
+ | --- | --- | --- |
23
+ | Anthropic, the default | `router.json` | Haiku 5.5, Sonnet 5.5, Opus 5.5 |
24
+ | `deepseek` | `deepseek-router.json` | DeepSeek Flash, routed by effort |
25
+ | `zai` | `zai-router.json` | GLM-5.3-Flash and GLM-5.3 |
26
+
27
+ OpenRouter, Ollama, other local servers and other compatible hosted providers use custom `<provider>-router.json` files.
28
+ They have no built-in model defaults. A selected file must exist and validate, or the router leaves Claude Code's model unchanged.
29
+
30
+ See [Providers](docs/providers.md) for **default routes and activities**, **custom profiles**, and the **`--settings` flag alternative**.
31
+ Execution provider selection is separate from classifier selection.
9
32
 
10
33
  ## Supported classifiers
11
34
 
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.
35
+ 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 the selected router file; 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
36
 
14
37
  | Classifier | Service | Credential | Prompt text goes to | How it is asked for the activity |
15
38
  | ---------- | ------------------------------------------ | ----------------------------------- | ------------------------- | --------------------------------------------------------------------- |
@@ -36,7 +59,7 @@ sequenceDiagram
36
59
  participant Code as Claude Code
37
60
  participant Mod as Router Mod
38
61
  participant Cls as Classifier
39
- participant API as Anthropic
62
+ participant API as Model provider
40
63
  Dev->>Code: Prompt
41
64
  opt Subagent spawn
42
65
  Code->>Mod: agent.spawn
@@ -55,7 +78,9 @@ sequenceDiagram
55
78
  Mod-->>Dev: Status band and router pane
56
79
  ```
57
80
 
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.
81
+ 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.
82
+
83
+ With the Anthropic profile, the base routes are:
59
84
 
60
85
  | Tier | Default model | Effort |
61
86
  | -------- | ------------- | -------- |
@@ -68,6 +93,8 @@ These are routing defaults. They do not claim equal model quality. [Configuratio
68
93
 
69
94
  Activity routing adds a second label: what the turn produces (`code`, `debug`, `explore`, `plan`, `review`, `ops`, or `docs`). A route is then picked by tier and activity. It is on by default since 1.7. A `·` cell uses the tier's own route, the base route:
70
95
 
96
+ The Anthropic profile uses these activity defaults. Other profiles have [their own defaults](docs/providers.md#activity-overrides).
97
+
71
98
  | Activity | `micro` | `low` | `medium` | `high` |
72
99
  | --------------------------------- | -------------- | ----------------- | ---------------- | ------------ |
73
100
  | Base route | Haiku · medium | Haiku · high | Opus · medium | Opus · xhigh |
@@ -88,7 +115,7 @@ claude plugin marketplace add alexei-led/claude-router
88
115
  claude plugin install router@alexei-led-claude-router
89
116
  ```
90
117
 
91
- Start Claude Code on the full baseline model, for example `claude --model claude-haiku-5-5`. Run `/plugin configure router` and save the key. For any other classifier, save its credentials, or run `ollama serve` with a pulled model, then pick the classifier on the pane's Classifier tab. A new 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; on any other model it starts with routing off and says why, and `/router auto` turns routing on.
118
+ For the default Anthropic profile, start on the full baseline model, for example `claude --model claude-haiku-5-5`. For other providers, [select a provider profile](docs/providers.md#select-a-provider). Run `/plugin configure router` and save the key. For any other classifier, save its credentials, or run `ollama serve` with a pulled model, then pick the classifier on the pane's Classifier tab. A new 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; on any other model it starts with routing off and says why, and `/router auto` turns routing on.
92
119
 
93
120
  Claude Code updates the plugin at startup when auto-update is on for this marketplace. Otherwise run `claude plugin marketplace update alexei-led-claude-router`, then `claude plugin update router@alexei-led-claude-router`.
94
121
 
@@ -116,7 +143,8 @@ npm run check && npm run typecheck && npm test && npm run validate && npm run te
116
143
  ## Documentation
117
144
 
118
145
  - [User guide](docs/user-guide.md): install, use the controls, read the panel, and troubleshoot.
119
- - [Configuration](docs/configuration.md): classifiers and keys, the optional profile `router.json`, defaults, and migrations.
146
+ - [Providers](docs/providers.md): provider names, router files, built-in defaults, and custom profiles.
147
+ - [Configuration](docs/configuration.md): router-file settings, classifier keys, cache policies, and migrations.
120
148
  - [Architecture](docs/architecture.md): Mod event flow, state, safeguards, and runtime boundaries.
121
149
  - [Activity routing](docs/activity-routing.md): the default matrix by activity, why each cell, and how to change or turn it off.
122
150
  - [Routing modes](docs/routing-modes.md): `cost`, `balanced` and `quality`, where the mode comes from, and every decision per mode.
@@ -11,7 +11,7 @@ sequenceDiagram
11
11
  participant Code as Claude Code
12
12
  participant Mod as Router Mod
13
13
  participant Cls as Classifier
14
- participant API as Anthropic
14
+ participant API as Model provider
15
15
  Dev->>Code: Prompt
16
16
  Code->>Mod: turn.start and turn.step
17
17
  alt Main conversation, routing on
@@ -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
 
@@ -91,12 +91,12 @@ The router decides on a _cell_: a tier and an activity. The route is `{ ...route
91
91
  1. **Pin.** A pinned tier wins, with no activity: the pin's tier route.
92
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
- 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.
94
+ 4. **Lateral move.** If the tier stays and the route would change, `lateralMove` decides. Routes order by explicit model strength when both models declare it, otherwise by 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
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 excluded from usage comparisons by cause (`unpriced`: `usage`, `model`, `ttl`, `error`, `comparison`, 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
 
@@ -153,7 +157,11 @@ In a 20-process loopback test, timeout fallback had 1,504 ms p95 and 1,505 ms wo
153
157
 
154
158
  ## Cache and cost
155
159
 
156
- Cache identity uses the exact response model ID, plus the effective effort on models that keep one cache per effort. Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 keep one cache across efforts with an API key or a Claude subscription (code.claude.com/docs/en/prompt-caching, "Changing effort level"), so an effort-only move costs no cache write there. The hook gives every effort its own cache when the session runs on Amazon Bedrock, Google Cloud, Microsoft Foundry, a custom `ANTHROPIC_BASE_URL`, or with `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` (`effortSplitsCache`). A HIPAA configuration is not visible to a Mod; there the router prices effort moves as free. The Haiku 4.5 dated snapshot has an explicit mapping; Haiku 5.5 has no dated ID. An unrecognized substituted model gets no cache credit for the requested route.
160
+ Execution profile selection is fixed at session start by `CLAUDE_ROUTER_PROVIDER`: unset/`anthropic` reads `router.json`, another validated ID reads `<provider>-router.json` in the same profile directory. Missing or invalid selected files pass requests through, never fall back to the default file. Save/Undo keep that path. Provider presets replace execution routes, activities, models and subagent defaults, not classifier credentials. See [Providers](providers.md).
161
+
162
+ The explicit-cache rules below describe Anthropic. Automatic prefix-cache providers instead use observed hit/miss input rates, no write premium and no guaranteed TTL. Their future price bounds allow a full miss; counterfactual cache comparisons are omitted unless the observed route is identical. Same-model effort downgrades skip input-only payback, which cannot value generated thinking-token changes, but retain the vote, dwell and cold-input guards. Their cache observations remain effort-specific until sharing is established. `disabled` cache mode uses the uncached input rate throughout.
163
+
164
+ Cache identity uses the response model ID with the `[1m]` context hint removed, plus the effective effort on models that keep one cache per effort. Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 keep one cache across efforts with an API key or a Claude subscription (code.claude.com/docs/en/prompt-caching, "Changing effort level"), so an effort-only move costs no cache write there. The hook gives every effort its own cache when the session runs on Amazon Bedrock, Google Cloud, Microsoft Foundry, a custom `ANTHROPIC_BASE_URL`, or with `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` (`effortSplitsCache`). A HIPAA configuration is not visible to a Mod; there the router prices effort moves as free. The Haiku 4.5 dated snapshot has an explicit mapping; Haiku 5.5 has no dated ID. An unrecognized substituted model gets no cache credit for the requested route.
157
165
 
158
166
  The cached prefix is observed `cache_read + cache_creation`. Output tokens count only toward the next context size. Freshness uses the configured five-minute lifetime with its safety margin. Claude's usage counters do not prove one-hour cache lifetime.
159
167
 
@@ -1,6 +1,6 @@
1
1
  # Configuration
2
2
 
3
- The router works with its built-in defaults. Configure the key of the active classifier to enable advice. Change `router.json` only when you need to change the classifier, routes, activity routing, model prices, cache assumptions, or policy.
3
+ Select a [provider profile](providers.md), then configure the key of the classifier you use. This page describes the settings inside the selected router file.
4
4
 
5
5
  ## Key and profile settings
6
6
 
@@ -10,8 +10,8 @@ The router works with its built-in defaults. Configure the key of the active cla
10
10
  | Cloudflare API token | Sensitive plugin option `cloudflare_api_token` | The same dialog. Used by Clef, Clef Flash and Clef Omni. |
11
11
  | Cloudflare account ID | Plugin option `cloudflare_account_id` | The same dialog, or the config menu row. Not a secret. |
12
12
  | OpenAI API key | Sensitive plugin option `openai_api_key` | The same dialog. Used only by the OpenAI classifier. Ollama needs no key. |
13
- | Router settings and classifier | `router.json` in the active Claude Code profile | Edit the file directly, or use the pane's Routes, Policy and Classifier tabs. |
14
- | Anthropic credentials and API cost | Claude Code | The Mod leaves these to Claude Code. |
13
+ | Router settings and classifier | The selected router file in the active Claude Code profile | Edit the file directly, or use the pane's Routes, Policy and Classifier tabs. |
14
+ | Execution provider credentials and API cost | Claude Code | The Mod leaves these to Claude Code. |
15
15
 
16
16
  The active profile directory is `CLAUDE_CONFIG_DIR` when set. Otherwise it is `~/.claude`. The Mod does not need an Anthropic proxy URL, model alias, hint header, daemon, or custom status line.
17
17
 
@@ -26,7 +26,69 @@ The Mod reads each value from its plugin option first. When the option is empty,
26
26
 
27
27
  Export the variables before you start `claude`. Without the key or the account ID of the active classifier, the Mod keeps Claude's current model and reports which value is missing.
28
28
 
29
- Project and local settings cannot set `HOME` or `CLAUDE_CONFIG_DIR` for this Mod. Those overrides make the router unavailable for the session, so a project cannot redirect the router to another profile's key or configuration.
29
+ Project and local settings cannot set `HOME`, `CLAUDE_CONFIG_DIR`, or `CLAUDE_ROUTER_PROVIDER` for this Mod. Those overrides make the router unavailable for the session, so a project cannot redirect the router to another profile's key or configuration.
30
+
31
+ ## Provider profiles
32
+
33
+ Set `CLAUDE_ROUTER_PROVIDER` to select `<provider>-router.json` in the active Claude Code profile.
34
+ Unset, empty, or `anthropic` selects `router.json`.
35
+ See [Providers](providers.md) for selection examples, built-in defaults and complete custom profiles.
36
+
37
+ The same schema applies to every router file. This reference uses `router.json` as shorthand for the selected file.
38
+ A non-Anthropic file must exist and validate. It never falls back to `router.json` or inherits settings from it.
39
+
40
+ ### Provider prices
41
+
42
+ DeepSeek and z.ai default windows are 1M tokens.
43
+ Price estimates use the [DeepSeek peak API rates](https://api-docs.deepseek.com/quick_start/pricing) and [z.ai API list rates](https://docs.z.ai/guides/overview/pricing.md).
44
+ These rates were checked on 2026-10-28.
45
+
46
+ | Model | Input / output / cached input, USD per million tokens |
47
+ | --- | --- |
48
+ | DeepSeek Flash | 0.30 / 1.20 / 0.006 |
49
+ | GLM-5.3-Flash | 0.15 / 0.50 / 0.03 |
50
+ | GLM-5.3 | 1.40 / 4.40 / 0.26 |
51
+
52
+ These are fixed estimate inputs, not an invoice. DeepSeek off-peak rates differ, and z.ai plan quota uses its own multipliers.
53
+ Both presets use `billing: "credits"`.
54
+ For an included-plan model, set `billing: "plan"` to disable the cold-input cash cap.
55
+ A provider name or URL does not establish its billing product.
56
+
57
+ ### Provider cache behavior
58
+
59
+ `cache.mode` controls the router's cost estimates, not the provider's server cache.
60
+
61
+ | Mode | Use | Estimate |
62
+ | --- | --- | --- |
63
+ | `explicit` | Anthropic default | Configured write multipliers and TTLs |
64
+ | `automatic` | DeepSeek, z.ai and custom-profile default | Reported hit/miss input rates, no separate write premium |
65
+ | `disabled` | No cache discount to model | All input at the uncached rate, never marked warm |
66
+
67
+ Automatic-cache bounds allow a future hit or a full miss, including after an observed miss.
68
+ The router does not assume a five-minute or one-hour lifetime. Payback is unknown.
69
+ Same-model effort changes retain votes, dwell and the cold-input cap.
70
+ They skip fixed-token payback because it cannot value changes in generated thinking tokens.
71
+
72
+ `cache.effortScope` accepts these values:
73
+
74
+ | Value | Meaning |
75
+ | --- | --- |
76
+ | `auto` | Existing Claude cache detection |
77
+ | `shared` | One cache identity across efforts |
78
+ | `separate` | One cache identity per effort |
79
+ | `unknown` | Keep observations separate without claiming that the provider separates caches |
80
+
81
+ Automatic-cache presets use `unknown`. Set `shared` only when the provider contract establishes sharing.
82
+ An unknown cache state is not proof of a miss.
83
+
84
+ [DeepSeek caching](https://api-docs.deepseek.com/guides/kv_cache) is automatic and best-effort. Its Anthropic endpoint ignores explicit cache controls.
85
+ [z.ai caching](https://docs.z.ai/guides/capabilities/cache.md) has no verified model-specific TTL.
86
+ Claude Code's `DISABLE_PROMPT_CACHING` does not establish whether an automatic server cache is disabled.
87
+
88
+ Valid observed usage can still be priced for activity statistics.
89
+ For automatic caches, routing-versus-your-model comparisons require an identical observed route.
90
+ Otherwise the UI reports comparison unavailable. It does not label a known observed cost unpriced or invent another route's hit rate.
91
+ Missing counters remain unknown. See [provider acceptance checks](evaluation.md#provider-profiles).
30
92
 
31
93
  ## Built-in defaults
32
94
 
@@ -251,8 +313,8 @@ The Mod validates the whole file. Unknown keys and invalid values make routing u
251
313
  | `mode` | `cost`, `balanced`, `quality` ([Routing modes](routing-modes.md)) | `balanced` |
252
314
  | `modes.<cost\|quality>.policy` | any `policy` field, used while that mode is active | [Routing modes](routing-modes.md#policy-per-mode); not tuned |
253
315
  | `activities.<activity>.<tier>` | optional `model` and `effort`, as in `routes` | The overrides in [Activity routing](#activity-routing) |
254
- | `models.<alias>` | `id`, `input`, optional `output`, `cacheRead`, optional `longContext` (`above`, `multiplier`, or `null`), `contextWindow`, `billing`, `efforts` | Three defaults above |
255
- | `cache` | `writeMultiplier`, `ttlMs`, `warmMarginMs` | `5m: 1.25`, `1h: 2`; `300000` / `3600000` ms; `30000` ms |
316
+ | `models.<alias>` | `id`, `input`, optional `output`, `cacheRead`, optional `longContext` (`above`, `multiplier`, or `null`), `contextWindow`, `billing`, `efforts`, optional `strength`, `imageInput` | Three defaults above |
317
+ | `cache` | `mode`, `effortScope`, `writeMultiplier`, `ttlMs`, `warmMarginMs` | `5m: 1.25`, `1h: 2`; `300000` / `3600000` ms; `30000` ms |
256
318
  | `policy` | Fields below | Values below |
257
319
  | `classifier` | An id in `classifiers` | `jev` |
258
320
  | `classifiers.<id>` | `label`, `api`, `endpoint`, `model`, `keyOption`, `timeoutMs` | [Classifiers](#classifiers) above |
@@ -4,6 +4,40 @@ The native Mod has no measured savings result. The pane reports Claude's own usa
4
4
 
5
5
  This page separates an older gateway experiment from a shadow replay of native policy. Neither result measures answer quality or proves lower real spend. [Activity routing](#activity-routing) adds two checks of the activity label, with no savings result either.
6
6
 
7
+ ## Provider profiles
8
+
9
+ [Provider defaults](providers.md#built-in-defaults) are starting policies, not measured per-activity quality or savings results.
10
+
11
+ The model and effort choices use official [DeepSeek controls](https://api-docs.deepseek.com/guides/thinking_mode), [z.ai controls](https://docs.z.ai/guides/capabilities/thinking.md), and [Coding Plan mappings](https://docs.z.ai/devpack/latest-model.md).
12
+ The model-cards knowledgebase supplied model-specific controls and prompting constraints.
13
+
14
+ Artificial Analysis profiles informed activity choices:
15
+
16
+ - [GLM-5.3](https://artificialanalysis.ai/models/glm-5-3)
17
+ - [GLM-5.3-Flash](https://artificialanalysis.ai/models/glm-5-3-flash)
18
+ - [DeepSeek-V4.1-Flash](https://artificialanalysis.ai/models/deepseek-v4-1-flash)
19
+
20
+ Terminal engineering and SRE results differ. Neither GLM model leads every activity.
21
+ Measured max-effort results do not establish low/high performance or an optimal routing matrix.
22
+ The original DeepSeek benchmark profile does not establish the quality of its newer hosted 1017 snapshot.
23
+
24
+ ### Compatibility checks
25
+
26
+ On 2026-10-28, six synthetic live requests per provider returned HTTP 200.
27
+ The requests covered `low`, `high`, and `max` on DeepSeek Flash and both GLM models.
28
+ DeepSeek reported 2,688 cache-read tokens on repeated requests. z.ai reported zero hits in that sample.
29
+
30
+ These checks establish accepted request and usage-counter shapes.
31
+ They do not establish a guaranteed cache hit rate, cross-effort cache sharing, answer quality, or savings.
32
+ Claude Code 2.1.312 supplied zero when the z.ai-style response omitted cache-creation tokens.
33
+
34
+ `npm run test:providers` checks the production Mod against a loopback API with synthetic credentials.
35
+ It covers provider selection through a `--settings` environment layer, model/effort switches, tool continuations, and missing/invalid profiles.
36
+ It also covers omitted cache-creation counters. The command makes no paid provider calls.
37
+
38
+ OpenRouter, Ollama and other [custom profiles](providers.md#add-another-provider) have no provider-specific acceptance result here.
39
+ A valid configuration does not establish backend compatibility or model quality.
40
+
7
41
  ## Historical gateway experiment
8
42
 
9
43
  These figures are retained from the earlier gateway implementation. They do not evaluate the native Mod or its current routes. The snapshot covers 26 Claude Code sessions and 1,611 requests from 2026-09-23 09:05 UTC through 2026-09-24 06:00 UTC. Jev advised on 111 prompts.
@@ -56,7 +90,7 @@ The script writes aggregate counts, reason histograms, route transitions, and sh
56
90
 
57
91
  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
92
 
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).
93
+ 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
94
 
61
95
  ### Tool agreement
62
96
 
@@ -66,7 +100,9 @@ Each finished turn is labelled from the tools the assistant used, locally and at
66
100
  | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
67
101
  | `code` | An edit tool (`Edit`, `Write`, `MultiEdit`, `NotebookEdit`) on a path that is not a doc path |
68
102
  | `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 |
103
+ | `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 |
104
+ | `ops` | A Bash command that runs something else: `git commit`, `rm`, `mv`, `mkdir`, a deploy, a check followed by another command |
105
+ | `check` | Bash commands that are only checks (`npm test`, `tsc`, `npm run lint && npm test`) or reads |
70
106
  | `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
107
  | `talk` | No tool calls |
72
108
 
@@ -74,15 +110,17 @@ A subagent's edits and commands never reach the main transcript, so a turn that
74
110
 
75
111
  The classifier's activity agrees with the turn when the bucket is one it allows:
76
112
 
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` |
113
+ | Activity | Allowed buckets |
114
+ | --------- | ------------------------------------------ |
115
+ | `code` | `code`, `shell` |
116
+ | `debug` | `code`, `shell`, `ops`, `check`, `read` |
117
+ | `explore` | `read`, `talk` |
118
+ | `plan` | `talk`, `read`, `docs` |
119
+ | `review` | `read`, `talk`, `check` |
120
+ | `ops` | `ops`, `shell`, `check`, `read` |
121
+ | `docs` | `docs`, `shell` |
122
+
123
+ 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
124
 
87
125
  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
126
 
@@ -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.