@alexeiled/claude-router 1.6.1 → 1.7.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.6.1",
4
+ "version": "1.7.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). Preserves subagent model choices.",
6
6
  "author": {
7
7
  "name": "Alexei Ledenev",
package/CHANGELOG.md CHANGED
@@ -1,5 +1,37 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.7.0 (2026-10-10)
4
+
5
+ Activity routing is now on by default, with a new default matrix that uses Opus, Sonnet and Haiku. The Usage tab shows what routing cost against running every reply on your own model. The band has one routing on/off control.
6
+
7
+ ### Changed
8
+
9
+ - Activity routing is on by default. At `low`, `code`, `debug`, `plan` and `review` run on Sonnet 5.5 at `high`; at `medium`, `ops` runs on Haiku 5.5 at `high`. Every other cell, and every turn without an activity, uses the base route, which is unchanged: `micro` Haiku 5.5 · `medium`, `low` Haiku 5.5 · `high`, `medium` Opus 5.5 · `medium`, `high` Opus 5.5 · `xhigh`. 1.6's Sonnet 5.5 · `medium` cells for `docs`, `explore` and `ops` are gone. [Activity routing](docs/activity-routing.md) gives the reason for each cell, from Anthropic's model cards and a list-price replay of real sessions; it does not measure answer quality.
10
+ - Haiku 5.5 is priced at 5x on every rate above 100,000 prompt tokens, as Anthropic lists it. Switch-tax estimates and comparisons for Haiku routes rise there, and a decision near its bar can change: for example, an effort-only `micro` → `low` upgrade at 400K tokens now waits. The new model field `longContext` (`above`, `multiplier`, or `null`) holds it.
11
+ - The band has one routing control at a time. While routing is on, **Turn off** sits on the hover row next to the pins. While it is off, the first line reads `○ Routing off [ Turn on ] · every turn uses <model>`, and **Turn on** stays at any width. The pane header is one radio pair, `ROUTING [ ◉ on ] [ ○ off ]`; its hotkeys `o` and `f`, and the `/router` commands, are unchanged.
12
+ - The Now tab's **Replies** count and the two-row band count a switch as a change of model or effort, so a move from Sonnet to Haiku inside `low` counts.
13
+ - Wording: "base route" replaces "tier route", the Usage tab's "Lateral" line is now **Activity moves**, and **Reset activity stats** is now **Reset stats**, which also clears routing vs your model.
14
+
15
+ ### Added
16
+
17
+ - **Routing vs your model**, the Usage tab's first section: routed replies against the same tokens on your model (the session's model and effort before routing), for this session and since the last reset, at configured list prices. The difference splits into cheaper models, stronger than yours, and cache writes from switches. It reads `too early` under 10 routed replies. It is an estimate, not a bill: output length is held the same, on a Claude plan it stands for quota, and answer quality is not measured. The two-row band shows the session figure, such as `vs your model −22% (−$1.84, list prices)`, and `/router` without a pane prints one line with it.
18
+ - **Activity threshold** (`policy.activityMass`) on the Routing tab under **POLICY**. Every activity-routing setting is now editable in the pane: the mode, each cell's model and effort, adding or removing a cell, and the threshold.
19
+ - The Routing tab leads **ACTIVITIES** with the mode, and **OVERRIDES** says whether the overrides are in use and, if not, why.
20
+ - [Activity routing](docs/activity-routing.md): what it does, the default matrix with its reasons, how to change any cell in `router.json` or the pane, and the limits of the estimates.
21
+
22
+ ### Fixed
23
+
24
+ - When routing is unavailable (an old Claude Code, v0.8 gateway settings, an invalid `router.json`), the pane header and `/router` say so with the reason instead of offering on and off.
25
+ - When the routed model is not available, the fallback no longer takes another activity's cell: a session limited to Sonnet keeps its session effort on such a turn instead of running Sonnet · `high` labelled `code`.
26
+
27
+ ### Upgrade notes
28
+
29
+ - A `router.json` without `activityRouting` now runs `on`. 1.6 removed the key when you chose its default, `shadow`, so if you chose `shadow` in 1.6, run `/router activities shadow` again.
30
+ - An activity override that sets only `model` or only `effort` takes the other field from 1.7's built-in cell, or from the base route where 1.7 has none (`explore` and `docs` at `medium`, `docs` at `low`). Write both fields to keep a 1.6 Sonnet · `medium` cell.
31
+ - A session started on Sonnet 5.5 starts with routing on, because Sonnet runs the `code` cell at `low`. To stay on Sonnet, use `/model` or `/router off`.
32
+ - If your `router.json` points the `haiku` alias at another model by setting only `id`, add `"longContext": null`, or it inherits the 5x surcharge.
33
+ - 1.6 does not read `models.<alias>.longContext`; remove it before downgrading.
34
+
3
35
  ## 1.6.1 (2026-10-10)
4
36
 
5
37
  ### Added
package/README.md CHANGED
@@ -25,7 +25,7 @@ Jev is the default. [Configuration](docs/configuration.md#classifiers) gives the
25
25
 
26
26
  The band above the prompt shows the tier, activity, model, and reason for each turn. `/router` opens a pane to pin a tier, edit the model and effort of each tier, and tune the policy. See the [user guide](docs/user-guide.md#read-the-status-band).
27
27
 
28
- The router needs Claude Code 2.1.289 or newer. Current savings are not measured. The panel shows Claude's reported usage and configured-price scenarios, not a savings total. See the [evaluation](docs/evaluation.md).
28
+ The router needs Claude Code 2.1.289 or newer. Savings are not measured. The pane's Usage tab estimates what routing cost against your own model for the same tokens at configured list prices; it is not a bill and does not judge answer quality. See the [evaluation](docs/evaluation.md).
29
29
 
30
30
  ## How it works
31
31
 
@@ -61,7 +61,16 @@ The active classifier labels a new logical turn once. Tool continuations keep th
61
61
 
62
62
  These are routing defaults. They do not claim equal model quality. [Configuration](docs/configuration.md#built-in-defaults) gives the published results behind them and the `router.json` lines that restore the 1.3 Sonnet ladder.
63
63
 
64
- 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, so a `low` coding turn can run on Sonnet 5.5 while a `low` git turn stays on Haiku 5.5. It ships in `shadow` mode: the band and pane show the activity and what it would route, and the tier routes still run. Opt in with `/router activities on`. The label is optional: on `uncertain` or a weak label the tier route is used, when the activity answer fails the running activity stays and the tier answer still applies, and when the classifier fails the running route stays. See [Route by activity](docs/user-guide.md#route-by-activity), and [Evaluation](docs/evaluation.md#activity-routing) for how it is checked. Its default overrides rest on published vendor results, not measured savings.
64
+ 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:
65
+
66
+ | Activity | `micro` | `low` | `medium` | `high` |
67
+ | --------------------------------- | -------------- | ----------------- | ---------------- | ------------ |
68
+ | Base route | Haiku · medium | Haiku · high | Opus · medium | Opus · xhigh |
69
+ | `code`, `debug`, `plan`, `review` | · | **Sonnet · high** | · | · |
70
+ | `ops` | · | · | **Haiku · high** | · |
71
+ | `explore`, `docs` | · | · | · | · |
72
+
73
+ `/router activities shadow` shows what it would route and keeps the base routes; `/router activities off` stops asking. [Activity routing](docs/activity-routing.md) explains each cell and how to change it. The label is optional: on `uncertain` or a weak label the base route is used if the move passes the cache check, when the activity answer fails the running activity stays and the tier answer still applies, and when the classifier fails the running route stays. See [Route by activity](docs/user-guide.md#route-by-activity), and [Evaluation](docs/evaluation.md#activity-routing) for how it is checked. Its default overrides rest on published vendor results and a list-price replay of one developer's sessions, not measured savings.
65
74
 
66
75
  ## Install
67
76
 
@@ -72,7 +81,7 @@ claude plugin marketplace add alexei-led/claude-router
72
81
  claude plugin install router@alexei-led-claude-router
73
82
  ```
74
83
 
75
- 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 one of the tiers routes to starts with routing on; on another model it starts with routing off and says why, and `/router auto` turns routing on.
84
+ 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.
76
85
 
77
86
  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`.
78
87
 
@@ -88,7 +97,7 @@ claude --plugin-dir "$PWD" --model claude-haiku-5-5
88
97
 
89
98
  In Claude Code, run `/plugin configure router` and save your classifier key in the sensitive plugin option. The Mod adds its status band and `/router` pane. No status-line setup or gateway environment variables are needed.
90
99
 
91
- Run `/router` to open the pane: route status, per-tier controls, tuning, and usage. Run `/model` to select a model and turn routing off, and `/router auto` to turn it back on. For controls, metrics, tuning, and troubleshooting, see the [user guide](docs/user-guide.md).
100
+ Run `/router` to open the pane: route status, per-tier controls, tuning, and usage, including routing vs your model. Run `/model` to select a model and turn routing off, and `/router auto` to turn it back on. For controls, metrics, tuning, and troubleshooting, see the [user guide](docs/user-guide.md).
92
101
 
93
102
  Before a push, run the same checks as CI. `npm run setup` installs Biome and TypeScript into `tools/`; the plugin root keeps no lockfile, so Claude Code installs nothing with the plugin. `npm run validate` and `npm run test:plugin` need the `claude` CLI: they load the Mod in the Claude Code engine, which refuses some faults that lint and unit tests miss.
94
103
 
@@ -102,6 +111,7 @@ npm run check && npm run typecheck && npm test && npm run validate && npm run te
102
111
  - [User guide](docs/user-guide.md): install, use the controls, read the panel, and troubleshoot.
103
112
  - [Configuration](docs/configuration.md): classifiers and keys, the optional profile `router.json`, defaults, and migrations.
104
113
  - [Architecture](docs/architecture.md): Mod event flow, state, safeguards, and runtime boundaries.
114
+ - [Activity routing](docs/activity-routing.md): the default matrix by activity, why each cell, and how to change or turn it off.
105
115
  - [Native router details](docs/native-router.md): panel semantics, tuning, and accepted limits.
106
116
  - [Evaluation](docs/evaluation.md): historical gateway results and the native shadow replay.
107
117
  - [Changelog](CHANGELOG.md): user-visible changes by version.
@@ -0,0 +1,254 @@
1
+ # Activity routing
2
+
3
+ The router picks a model for each turn from two labels. The **tier** says how hard the work is. The **activity** says
4
+ what the turn produces: changed code, a found cause, an answer, a plan, review findings, executed commands, or prose.
5
+ Since 1.7 activity routing is `on` by default. This page shows the default choices, why each one is there, and how to
6
+ change them.
7
+
8
+ The numbers below come from Anthropic's system cards and from a replay of one developer's sessions at list prices.
9
+ They do not measure this router's answer quality or your bill.
10
+
11
+ ## What it does
12
+
13
+ For each new turn the classifier answers two questions, the tier and the activity, in the same request (Ollama makes
14
+ a second call). The router looks up the route for that pair. A route is a model and an effort.
15
+
16
+ | Activity | The turn produces |
17
+ | --------- | --------------------------------------------------------------- |
18
+ | `code` | Changed code or config, including tests |
19
+ | `debug` | A found cause: failing tests, stack traces, "why does X..." |
20
+ | `explore` | An answer: explain code, find where something happens, research |
21
+ | `plan` | A decision or plan: design, task breakdown, trade-offs |
22
+ | `review` | Findings about existing code: a PR, a diff, an audit |
23
+ | `ops` | Executed commands: git, builds, test runs, CI, deploys |
24
+ | `docs` | Prose for people: README, docs, comments, commit messages |
25
+
26
+ Most cells use the tier's own route, the **base route**. A few cells have an **override**. When the activity is
27
+ unclear, or the classifier gives it less than 60% probability, the router moves back to the base route if the move
28
+ passes the cache check below. When the classifier gives no activity answer at all, the running activity stays. A pinned
29
+ turn uses the pinned tier's base route.
30
+
31
+ The router compares routes, not labels. If the new activity resolves to the route already running, nothing changes.
32
+ A move to a cheaper route must pay back its cache write first. A move to a stronger route needs the classifier's
33
+ support. The [user guide](user-guide.md#route-by-activity) has the full rules.
34
+
35
+ ## The default matrix
36
+
37
+ A `·` cell uses the base route.
38
+
39
+ | Activity | `micro` | `low` | `medium` | `high` |
40
+ | --------------------------------- | -------------- | ----------------- | ---------------- | ------------ |
41
+ | Base route | Haiku · medium | Haiku · high | Opus · medium | Opus · xhigh |
42
+ | `code`, `debug`, `plan`, `review` | · | **Sonnet · high** | · | · |
43
+ | `ops` | · | · | **Haiku · high** | · |
44
+ | `explore`, `docs` | · | · | · | · |
45
+
46
+ Why each row:
47
+
48
+ - **Base route.** The tier ladder, unchanged since 1.4. It runs for every cell without an override, and for every
49
+ turn when activity routing is `off` or `shadow`.
50
+ - **`code`, `debug`, `plan`, `review` at `low`: Sonnet · high.** Code is where Haiku trails most. Sonnet at `high`
51
+ scores well above Haiku on coding tests. Sonnet at `medium` does not, so it is not used.
52
+ - **`ops` at `medium`: Haiku · high.** Command runs last many requests, so Haiku pays back its cache write. Haiku is
53
+ weaker on multi-step tool work, so `ops` at `high` stays on Opus. Repeated tool errors move an `ops` turn to the
54
+ `high` route, Opus · xhigh.
55
+ - **`explore` and `docs`.** Moving them saved nothing in the replay. Haiku also scores lower on research
56
+ benchmarks: 50.1% on Humanity's Last Exam with tools against 63.0% for Opus at `medium`. They keep the base routes.
57
+
58
+ The matrix uses five routes on three models. The router counts each (model, effort) pair as its own cache, so this is
59
+ one more than the base routes alone.
60
+
61
+ ## Which model fits which work
62
+
63
+ **Haiku 5.5**: running commands, lookups, quick answers, commit messages, routine edits.
64
+
65
+ - It is weakest at code. Terminal-Bench 4.0: Haiku 39.2%, Sonnet 70.6%, Opus 66.4%. SWE-bench Pro: 64.8%, 81.3%,
66
+ 89.9%.
67
+ - Its quality depends on effort more than the larger models do. The defaults use `medium` and `high`.
68
+ - Avoid `xhigh` in multi-turn chats. Anthropic reports that Haiku then sometimes puts the whole answer in its thinking
69
+ and shows no reply.
70
+ - Above 100,000 tokens of context, Anthropic charges 5 times Haiku's list price. Even then it costs at most a quarter
71
+ of what Sonnet or Opus costs per token.
72
+
73
+ **Sonnet 5.5**: small, well-defined code changes.
74
+
75
+ - At `high` it scored about 49% on FrontierCode Main and 47.8% on CursorBench 4.0. Haiku at `high` scored about 42%
76
+ on FrontierCode Main.
77
+ - At `medium` it scored about 37% and 39.2%, below Haiku at `high` on FrontierCode Main. That is why the defaults use
78
+ `high`.
79
+ - It reads cached context at the same price as Opus. In long sessions a request costs only about 20% less than on
80
+ Opus.
81
+
82
+ **Opus 5.5**: ordinary and hard engineering, design, review, and research answers.
83
+
84
+ - At `medium` it has the best FrontierCode Main score on Anthropic's chart, 54.6%. On CursorBench 4.0 it scored
85
+ 52.5%, close to Sonnet at `xhigh` (53.1%).
86
+ - At `high` and `xhigh` it scored the same on CursorBench 4.0 (56.0%). `xhigh` gains a little on research and long
87
+ knowledge work.
88
+
89
+ These are Anthropic's results, mostly at `max` effort and in other harnesses. They are not a claim of equal quality.
90
+
91
+ ## What a model change costs
92
+
93
+ Each model keeps its own cache of the conversation. A model change writes the whole conversation into the new model's
94
+ cache. In the sample below Claude Code always wrote a one-hour cache, which costs twice the input price.
95
+
96
+ At 350,000 tokens of context, the typical size in that sample, at list prices:
97
+
98
+ | Cost | Haiku 5.5 | Sonnet 5.5 | Opus 5.5 |
99
+ | ---------------------------- | ----------- | ----------- | ----------- |
100
+ | Write the whole context once | $0.35 | $1.40 | $2.80 |
101
+ | One request on a warm cache | about $0.03 | about $0.10 | about $0.13 |
102
+
103
+ - A move from Opus to Haiku pays back after about 4 requests, from Sonnet after about 5. Command runs lasted 6 to 11
104
+ requests at the median, so the `ops` move pays back. Question-and-answer runs lasted 1 to 3, so moving `explore`
105
+ does not.
106
+ - A move from Opus to Sonnet saves about $0.03 per request and costs $1.40 to start. It rarely pays back. That is why
107
+ the defaults do not move `medium` or `high` work to Sonnet.
108
+
109
+ The router does this sum for every move with the prices in `router.json`. A move to a cheaper route inside a tier is
110
+ taken only when it pays back within the payback horizon. A move down a tier weighs the same cost against the
111
+ classifier's confidence: a costly write needs a more confident answer, but a confident enough answer can still move. Like the table, it prices Haiku at five times its list rates above 100,000 tokens
112
+ (`models.haiku.longContext` in [Configuration](configuration.md)).
113
+
114
+ ## Turn it off or back to shadow
115
+
116
+ | Mode | What the router does |
117
+ | -------- | ------------------------------------------------------------------------------------------ |
118
+ | `on` | The default. Asks the activity and runs the override when the cell has one. |
119
+ | `shadow` | Asks the activity and shows what `on` would run. The base routes run. 1.6's default. |
120
+ | `off` | Does not ask the activity: the classifier is asked for the tier only. The base routes run. |
121
+
122
+ Pick one of:
123
+
124
+ - Run `/router activities shadow` or `/router activities off`. It is saved to `router.json` at once. **Undo** in the
125
+ pane reverts it.
126
+ - Open the pane with `/router`, press `2` for the **Routing** tab, set **Activity routing** at the top of
127
+ **ACTIVITIES**, and press **Save** (`s`).
128
+ - Write it in `router.json`:
129
+
130
+ ```json
131
+ { "activityRouting": "shadow" }
132
+ ```
133
+
134
+ Routing as a whole has its own on/off pair at the top of the pane. Turning routing off keeps Claude's model for every
135
+ turn, whatever the activity mode.
136
+
137
+ ## Change a cell
138
+
139
+ **In the pane.** Open `/router` and press `2`. **ACTIVITIES** shows the mode, then the route each cell runs, with `·`
140
+ for the base route, and counts the routes. Routes are abbreviated, such as `S·high` for Sonnet · high, and activities
141
+ with the same cells share a row. **OVERRIDES** lists each override with a model, an effort, and **remove**.
142
+ **add an override…** adds one for an activity and tier. Edits are a draft: the status bar lists the `router.json`
143
+ lines they change. **Save** (`s`) writes them, **Discard** (`d`) drops them, and **Undo** (`u`) reverts the last
144
+ write. A yellow note flags an override that has no effect, one stronger than the tier above, or the only cell or tier
145
+ on its (model, effort) pair, which adds a cache.
146
+
147
+ **In `router.json`.** `activities.<activity>.<tier>` takes `model`, `effort`, or both. A field you leave out keeps its
148
+ default. This runs `code` at `low` on Sonnet at `xhigh` and adds `max` effort for hard code:
149
+
150
+ ```json
151
+ {
152
+ "activities": {
153
+ "code": { "low": { "effort": "xhigh" }, "high": { "effort": "max" } }
154
+ }
155
+ }
156
+ ```
157
+
158
+ A cell cannot be `null`. To drop a built-in override, set the cell to the tier's base route, or press **remove** in
159
+ the pane, which writes that for you. The cell keeps that route if you later change the tier's route; remove it again
160
+ then:
161
+
162
+ ```json
163
+ { "activities": { "ops": { "medium": { "model": "opus", "effort": "medium" } } } }
164
+ ```
165
+
166
+ Two other directions, with what they trade:
167
+
168
+ - **Cheaper.** Put `ops`, `docs`, and `explore` at `medium` and `high` on Haiku · high. Haiku scored 39.2% on
169
+ Terminal-Bench 4.0 against 66.4% for Opus, and 50.1% on Humanity's Last Exam with tools against 63.0% for Opus at
170
+ `medium`.
171
+ - **Stronger.** Put `code`, `debug`, `plan`, and `review` at `low` on Opus · medium, and `ops` at `medium` back on
172
+ Opus · medium.
173
+
174
+ ```json
175
+ {
176
+ "activities": {
177
+ "code": { "low": { "model": "opus", "effort": "medium" } },
178
+ "debug": { "low": { "model": "opus", "effort": "medium" } },
179
+ "plan": { "low": { "model": "opus", "effort": "medium" } },
180
+ "review": { "low": { "model": "opus", "effort": "medium" } },
181
+ "ops": { "medium": { "model": "opus", "effort": "medium" } }
182
+ }
183
+ }
184
+ ```
185
+
186
+ **Activity threshold.** An activity applies only when the classifier gives it at least this probability. Below it, a
187
+ new task goes back to the base route if that move passes the usual checks, and a continuation of the running task
188
+ keeps its activity, or moves to the classifier's activity when that route is stronger. The default is 60% (`policy.activityMass: 0.6`). Change it on the Routing tab under **POLICY**,
189
+ **Activity threshold**, or in `router.json`. There is no data to tune it on yet: the probe results record whether the
190
+ label was right, not the classifier's probabilities.
191
+
192
+ [Configuration](configuration.md#activity-routing) has the full schema.
193
+
194
+ ## Upgrading from 1.6
195
+
196
+ 1.6 shipped activity routing in `shadow`. 1.7 turns it `on`, with the matrix above.
197
+
198
+ - A `router.json` that sets `activityRouting` keeps it. A file without it now runs `on`. To keep 1.6's behavior, run
199
+ `/router activities shadow`. Choosing `shadow` in 1.6 removed the key, because `shadow` was the default then. If you
200
+ chose `shadow` in 1.6, run `/router activities shadow` again after upgrading.
201
+ - A session started on Sonnet 5.5 used to start with routing off, because no tier route used Sonnet. Sonnet now runs
202
+ the `code` cell at `low`, so the session starts with routing on and the router may move it to Haiku or Opus. To
203
+ stay on Sonnet in this session, choose it with `/model` or run `/router off`. To make future Sonnet sessions start
204
+ with routing off, also run `/router activities shadow`.
205
+ - Overrides you saved stay as written. An override that sets only one field, such as `"effort"`, takes the other from
206
+ 1.7's built-in for that cell, or from the base route where 1.7 has none (`explore` and `docs` at `medium`, `docs` at
207
+ `low`). 1.6's overrides in those cells and in `ops` at `medium` were Sonnet · medium, so such a cell can now run
208
+ another model or effort. Write both `model` and `effort` to keep 1.6's route.
209
+ - If you removed a 1.6 built-in override that 1.7 no longer has, such as `docs` at `low`, the pane lists it with
210
+ "same as base: no effect". Press **remove** and **Save** to drop it.
211
+ - 1.6 reads the same keys. A file without `activityRouting` runs `shadow` under 1.6.
212
+
213
+ ## What the estimates mean
214
+
215
+ **In the pane.** The band, the Now tab and the Usage tab report Claude's own readings: cost, context, and cache. The
216
+ dollar figures next to them, such as the switch tax, the payback, and the shadow line on the Usage tab, are estimates
217
+ at the list prices in `router.json`. They are not your bill: a plan does not charge list prices. They are not measured
218
+ savings: the router does not know what another model would have answered, or how many requests it would have needed.
219
+
220
+ **The replay behind the defaults.** We replayed 10 days of one developer's Claude Code sessions at list prices, main
221
+ conversation only. Each request kept its recorded size and output. The tier came from the route that ran. The activity
222
+ came from the tools the turn used. In the 11 sessions with router markers, the default matrix came out between 2% below
223
+ and 1% above what ran, with 19 or 20 model changes where the sessions had 14. 1.6's matrix came out between 4% below
224
+ and 15% above. The ranges cover seven ways to run the replay.
225
+
226
+ Limits:
227
+
228
+ - One developer, 10 days, 11 router sessions. In a sample this small, a few percent is one or two cache writes.
229
+ - List prices, not a subscription bill.
230
+ - The replay keeps each request's output and the number of requests. A weaker model can need more requests, a
231
+ stronger one fewer. It does not measure answer quality.
232
+ - The tools a turn used show `code`, `ops`, `docs`, and reads. They cannot show `debug`, `plan`, or `review`.
233
+
234
+ ## What we do not know yet
235
+
236
+ - The answer quality of routed sessions.
237
+ - How well the classifier labels real turns. On 70 synthetic prompts, Jev and OpenAI labelled all 70 right; see
238
+ [Evaluation](evaluation.md#activity-probe-set). The Usage tab's **Agreement** line checks your own turns against the
239
+ tools they used.
240
+ - Whether an effort change on the same model keeps the cache. We found only 6 cases. The router counts each
241
+ (model, effort) pair as its own cache.
242
+ - How many requests a turn needs on each model.
243
+
244
+ ## Sources
245
+
246
+ - Claude Haiku 5.5 system card: Table 8.1.A; FrontierCode Main by effort (Figure 8.3.A); Terminal-Bench 4.0 (§8.4);
247
+ Humanity's Last Exam with tools by effort (Figure 8.8.1.A); OSWorld 2.1 (Figure 8.9.3.B); effort and PhysicianBench
248
+ (§8.11.3).
249
+ - Claude Sonnet 5.5 system card: Table 8.1.A; FrontierCode by effort (Figure 8.4.A); CursorBench 4.0 by effort
250
+ (Figure 8.8.A).
251
+ - Claude Opus 5.5 system card: Table 8.1.A; FrontierCode (§8.4); CursorBench 4.0 (§8.8); AA-Briefcase (§8.14.4).
252
+ - Anthropic prompting guides for Haiku 5.5 and Sonnet 5.5: effort starting points, Haiku at `xhigh` in multi-turn
253
+ chat.
254
+ - List prices: [`test/fixtures/list-prices.json`](../test/fixtures/list-prices.json).
@@ -90,7 +90,7 @@ The router decides on a *cell*: a tier and an activity. The route is `{ ...route
90
90
  2. **Activity.** Only in `on`; `off` and `shadow` use none for the route they apply, and ignore the activity a turn in `on` ran with before the mode changed. With no advice, or advice without an activity answer, the incumbent's activity stays. On a new prompt the classifier scores as a continuation of the task (advice `continuation` at or above `continuationMass`; Ollama gives none), the advice's activity applies only if its route at the incumbent tier is stronger than the running route, so a task can move from `explore` up to `code` but a weaker label never takes over. Tool continuations inside a turn do not reclassify: they keep the turn's route and activity. Otherwise the activity with probability at least `activityMass` applies; below that, or for `uncertain`, there is none and the tier's base route is used.
91
91
  3. **Tier.** The tier policy runs as before, with every candidate tier priced at its route for the activity and the incumbent at the route it runs. Repeated tool errors move to the lowest tier above whose route is stronger than the running one, or sends a request that cannot be ordered against it. With no activity that is one tier up, as in 1.5. If no tier above helps, nothing escalates and the failure signature is kept.
92
92
  4. **Lateral move.** If the tier stays and the route would change, `lateralMove` decides. Routes order by configured output price, then effort; a session effort counts as the effort Claude Code sends. Two routes that send the same request do not switch. A pair that cannot be ordered (an unpriced model, a numeric effort, two models at one price) counts as a move up, so the base route is always reachable. A stronger route needs the activity's probability to clear the upgrade bar for its switching tax (a base route with no activity counts as probability 1). A cheaper route needs its downgrade tax to be paid back within `downgradeHorizonTurns`, except before the first measured reply of a history, when there is no cache to protect. The cash gate applies to both. The result is `activity-up`, `activity-down`, `activity-pending` (stay on the running route and its activity), `cash-gate`, or `hold`. While an escalation hold lasts, only a stronger route may be taken. One vote is enough: an activity is a fact about the turn, not a noisy estimate. If the tier changes, the tier gates have already priced the new route, and no lateral rule applies.
93
- 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.
93
+ 5. **Fit.** Context fit and model availability resolve through `route(tier, activity)`. A fallback tries the last cell, the native model's cell, then each tier with the activity. The last and the native cell count only when they carry no activity or the turn's; otherwise, or when nothing fits, the native model runs at the session effort.
94
94
 
95
95
  `activityRouting: shadow` runs the decision twice. The applied one uses no activity, so it is the 1.5 decision. The second runs as `on` and is kept only as `decision.wouldRoute`, shown on the pane and counted in the stats. It never changes a route. The second run keeps its own cell and policy state in `loop.would`, so each would-route starts from the previous would-route, as `on` would, not from the route actually running. Its limit: the would-route never runs, so its cache is never observed; the switching estimates price it as any cache of unknown state. A tool continuation keeps the turn's route and activity.
96
96
 
@@ -100,7 +100,7 @@ At session start the incumbent is the session's model. `cellForModel` looks for
100
100
 
101
101
  `$.state` stores route decisions, response observations, and UI state for the active session. Version-checked writes reject stale turn results. A private in-memory view merges state writes during one dispatch because state reads are frozen for that dispatch.
102
102
 
103
- Clear, branch, rewind, and committed compaction clear cache evidence and votes. A turn in progress keeps its route, pin, and any engine fallback. `/clear` starts the new session with routing on. A fresh session on a model that a configured tier routes to starts with routing on. A fresh session on any other model starts with routing off, and the band names the reason. Session start sets the mode; the band and pane only read it, even when they draw first. Resume restores the selected session's saved mode. Hot reload retains valid `$.state`. Running `/model` turns routing off, including an explicit choice of the baseline. `/router auto` resumes routing. `/router off` also turns routing off. Pins apply to the next turn and its tool continuations. The prior route resumes afterward.
103
+ Clear, branch, rewind, and committed compaction clear cache evidence and votes. A turn in progress keeps its route, pin, and any engine fallback. `/clear` starts the new session with routing on. A fresh session on a model that a configured tier routes to, or with activity routing `on` a model an activity override uses, starts with routing on. A fresh session on any other model starts with routing off, and the band names the reason. Session start sets the mode; the band and pane only read it, even when they draw first. Resume restores the selected session's saved mode. Hot reload retains valid `$.state`. Running `/model` turns routing off, including an explicit choice of the baseline. `/router auto` resumes routing. `/router off` also turns routing off. Pins apply to the next turn and its tool continuations. The prior route resumes afterward.
104
104
 
105
105
  ### Observed activity and stats
106
106
 
@@ -109,10 +109,14 @@ When a turn completes, the Mod labels it from the tool calls the assistant made
109
109
  Two stores hold counts:
110
110
 
111
111
  - **Session**: `activityStats` in the view, reset when the session ends. It has turns, requests and tokens per activity, switches by tier and by activity, tool agreement, and the shadow readout. The label counted per activity is the one the turn used: the applied activity in `on`, the answer that cleared `activityMass` in `shadow`. Tool agreement always compares the answer that cleared `activityMass`, so it measures the classifier in both modes. The view also keeps an `activities` array aligned with the last 30 replies.
112
- - **Across sessions**: one `$.store` key, `activity:stats:v1`. It 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, and shadow turns, differences, and the summed next-request estimate of the differing turns with the count it covers. The key set is fixed, so the size is bounded. A 1.6.0 value without the estimate loads with zeros; a stored value with any other shape is read as empty. The view keeps the last value read or written as `activityStore`: read at session start and when the pane opens, replaced after each turn's write and after a reset. The open run is written when the session ends. **Reset activity stats** clears both stores.
112
+ - **Across sessions**: one `$.store` key, `activity:stats:v1`. It 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, and shadow turns, differences, and the summed next-request estimate of the differing turns with the count it covers. The key set is fixed, so the size is bounded. A 1.6.0 value without the estimate loads with zeros; a stored value with any other shape is read as empty. The view keeps the last value read or written as `activityStore`: read at session start and when the pane opens, replaced after each turn's write and after a reset. The open run is written when the session ends. **Reset stats** clears both stores, and the routing-vs-your-model totals below.
113
113
 
114
114
  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. A turn from a session that has since changed is dropped.
115
115
 
116
+ ### Routing vs your model
117
+
118
+ After each main reply, where the response is observed, `savings.mjs` prices the reply on the model that served it and the same tokens on "your model": the session's model and the effort Claude Code sent on the turn's first request. Your model keeps a simulated single cache in the loop as `yours` (`{ total, at, onYours, model, effort }`), which a history reset clears; after `/model` or an effort change the next reply finds it cold, since it was kept for another model or effort. The session's totals are `savings` in the view; at turn completion the turn's totals are added to the session's own `$.store` key `savings:v1:<session id>` (replies, five sums and `since`), under the same reset guard as the activity stats. Each key has one writer, and Claude Code 2.1.296 writes one key under a file lock (observed in its code; the `$.store` types do not promise it), so sessions that finish turns at the same moment do not overwrite each other. The view's `savingsStore` adds up two parts: every other session's key, read at session start and when the pane opens, and this session's record, which the router reads once, holds in memory, adds each finished turn to and then writes, so a pane opened during that write counts the turn once. **Reset stats** first writes the time in `savings:reset:v1`, then deletes every such key. A record whose first reply is older than that time reads as empty, and each session reads the time before it adds a turn, so a session that still holds its record from before a Reset in another session drops it instead of writing it back. The comparison is by milliseconds: a record whose first reply has the reset's millisecond, or one written while the clock had moved back, still counts. A stored value of any other shape reads as empty. A reply with routing off or after an engine fallback is not counted, but it still moves your model's cache. A reply whose cache lifetime cannot be read loses its prices only, and your model's cache still follows it; a usage without rate limits prices writes at five minutes. No failure here fails the turn. [Evaluation](evaluation.md#routing-vs-your-model) gives the method and its limits.
119
+
116
120
  Subagent events pass directly to Claude Code. They do not create classifier requests or change main-conversation metrics. This is the selected scope because Mods do not expose whether a subagent model was explicit or inherited.
117
121
 
118
122
  ## Classifier deadline and failure handling
@@ -129,6 +133,8 @@ Cache identity uses the exact response model ID and effective effort. The Haiku
129
133
 
130
134
  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.
131
135
 
136
+ Every estimate prices tokens through `ratesAt` in `cost.mjs`, which applies a model's `longContext` multiplier when the prompt (input, cache read and cache write) is over its threshold: Haiku 5.5 bills every rate at 5x above 100,000 tokens. Routing vs your model prices cache writes at the lifetime Claude Code gives the main conversation, since the usage it reports to a Mod has no 5m/1h split: `FORCE_PROMPT_CACHING_5M`, then `CLAUDE_CODE_PROMPT_CACHE_TTL`, then the `promptCacheTtl` setting, then `ENABLE_PROMPT_CACHING_1H`, then one hour when replies report plan rate limits, else five minutes.
137
+
132
138
  The switching policy prices the candidate at a conservative cache-write bound and the incumbent at its best supported input bound. The pane shows the configured-price range and a conditional payback estimate. These are estimates, not measured savings. Claude's native `/cost` ledger owns total API cost. Classifier spend is not included.
133
139
 
134
140
  ## Deployment
@@ -57,58 +57,70 @@ Default model settings:
57
57
  | `sonnet` | 2 / 10 / 0.2 | 1,000,000 | `plan` | `low`, `medium`, `high`, `xhigh`, `max` |
58
58
  | `haiku` | 0.1 / 0.5 / 0.01 | 1,000,000 | `plan` | `low`, `medium`, `high`, `xhigh`, `max` |
59
59
 
60
- Prices are configured list-price inputs for estimates. They are not a subscription bill or a claim of savings. Haiku 5.5 prices are for prompts up to 100,000 tokens; above that Anthropic charges more, so estimates run low there. A model with `"efforts": []` receives no effort field. A route in `router.json` without an `effort` takes the effort of that tier's default route. To keep the session effort, clamped to what the model supports, set `"effort": null`, for example `"routes": { "high": { "model": "opus", "effort": null } }`. A 1.3 file whose `low` route had no `effort` kept the session effort; in 1.4 it runs at `high` until you add `"effort": null`.
60
+ Prices are configured list-price inputs for estimates. They are not a subscription bill or a claim of savings. Haiku 5.5 lists these prices for prompts up to 100,000 tokens and five times each of them, cache reads and writes included, above that. Its default `longContext` is `{ "above": 100000, "multiplier": 5 }`: a request whose prompt, counting input, cache reads and cache writes, is over `above` tokens is priced at `multiplier` times every rate. Every estimate prices through it. Set `"longContext": null` to remove it, for example when you point the `haiku` alias at another model with `id`. A model with `"efforts": []` receives no effort field. A route in `router.json` without an `effort` takes the effort of that tier's default route. To keep the session effort, clamped to what the model supports, set `"effort": null`, for example `"routes": { "high": { "model": "opus", "effort": null } }`. A 1.3 file whose `low` route had no `effort` kept the session effort; in 1.4 it runs at `high` until you add `"effort": null`.
61
61
 
62
62
  ## Activity routing
63
63
 
64
- The classifier also names the activity of a turn: what the turn produces. `activityRouting` decides what the router does with it.
64
+ The classifier also names the activity of a turn: what the turn produces. `activityRouting` decides what the router does with it. [Activity routing](activity-routing.md) explains the defaults for end users.
65
65
 
66
- | `activityRouting` | Behavior |
67
- | ----------------- | ------------------------------------------------------------------------------------------------------------------ |
68
- | `off` | Asks nothing new. The classifier requests are the ones 1.5 sent, and routes are exactly the tier routes. |
69
- | `shadow` | The default. Asks, shows the activity, records stats, and computes what `on` would run. The tier routes still run. |
70
- | `on` | Applies the `activities` overrides below. |
66
+ | `activityRouting` | Behavior |
67
+ | ----------------- | ----------------------------------------------------------------------------------------------------- |
68
+ | `off` | Does not ask the activity: the classifier is asked for the tier only. The base routes run. |
69
+ | `shadow` | Asks, shows the activity, records stats, and computes what `on` would run. The base routes still run. |
70
+ | `on` | The default since 1.7. Applies the `activities` overrides below. |
71
71
 
72
- The seven activities are `code`, `debug`, `explore`, `plan`, `review`, `ops`, and `docs`. The classifier may also answer `uncertain`. In `on`, an activity applies only when its probability is at least `policy.activityMass`. Below that, or on `uncertain`, the turn goes back to its tier's route, if the move passes the cache checks. When the classifier gives no usable activity answer, the running activity stays and the tier answer still applies. When it gives no answer at all, the running route stays. In `off` and `shadow`, the tier route runs.
72
+ The seven activities are `code`, `debug`, `explore`, `plan`, `review`, `ops`, and `docs`. The classifier may also answer `uncertain`. In `on`, an activity applies only when its probability is at least `policy.activityMass`. Below that, or on `uncertain`, a new task goes back to its base route if the move passes the cache checks; a continuation of the running task keeps its activity, or moves to the classifier's activity when that route is stronger. When the classifier gives no usable activity answer, the running activity stays and the tier answer still applies. When it gives no answer at all, the running route stays. In `off` and `shadow`, the base route runs.
73
73
 
74
- `activities` maps an activity to a tier to a route override. An override may set `model`, `effort`, or both. A field it leaves out comes from the tier's route:
74
+ `activities` maps an activity to a tier to a route override. An override may set `model`, `effort`, or both. A field it leaves out comes from the built-in override for that cell, or from the tier's own route, the **base route**, where there is none:
75
75
 
76
76
  ```
77
77
  route(tier, activity) = { ...routes[tier], ...activities[activity][tier] }
78
78
  ```
79
79
 
80
- The built-in overrides ship with 1.6 and run only with `activityRouting: "on"`. Cells marked `·` have no override:
80
+ The built-in overrides run only with `activityRouting: "on"`. A `·` cell uses the base route:
81
81
 
82
- | Activity | `micro` | `low` | `medium` | `high` |
83
- | --------------------------------- | ------- | --------------- | --------------- | ------ |
84
- | `code`, `debug`, `plan`, `review` | `·` | Sonnet · medium | `·` | `·` |
85
- | `docs` | `·` | Sonnet · medium | Sonnet · medium | `·` |
86
- | `ops`, `explore` | `·` | `·` | Sonnet · medium | `·` |
82
+ | Activity | `micro` | `low` | `medium` | `high` |
83
+ | --------------------------------- | -------------- | ----------------- | ---------------- | ------------ |
84
+ | Base route | Haiku · medium | Haiku · high | Opus · medium | Opus · xhigh |
85
+ | `code`, `debug`, `plan`, `review` | · | **Sonnet · high** | · | · |
86
+ | `ops` | · | · | **Haiku · high** | · |
87
+ | `explore`, `docs` | · | · | · | · |
87
88
 
88
- At `low`, `ops` and `explore` keep Haiku at `high`: they are the cheap cases the `low` route is for. Coding is where Haiku 5.5 trails most (Terminal-Bench 4.0: Haiku 39.2%, Sonnet 70.6%). On knowledge and terminal tasks Sonnet 5.5 matched Opus 5.5 (GDPval-AA 1844 against 1846; Terminal-Bench 70.6% against 66.4%). These are vendor benchmarks at max or xhigh effort, not measurements of this router, and they are not a claim of equal quality. Every override uses Sonnet at `medium`, the one pair the four base routes do not use, so activity routing adds one cache.
89
+ - `code`, `debug`, `plan`, `review` at `low` run on Sonnet at `high`. Coding is where Haiku 5.5 trails most (Terminal-Bench 4.0: Haiku 39.2%, Sonnet 70.6%). Sonnet at `medium` scored below Haiku at `high` on FrontierCode Main (about 37% against 42%); at `high` it scored about 49%.
90
+ - `ops` at `medium` runs on Haiku at `high`. Command runs last long enough for Haiku to repay its cache write: about 4 requests from Opus at 350,000 tokens of context, against a median run of 6 to 11 requests in one developer's sessions. Haiku is weaker on multi-step tool work (OSWorld 2.1: about 61% against 79% for Opus at `medium`), so `ops` at `high` stays on Opus, and repeated tool errors move an `ops` turn to the `high` route.
91
+ - `explore` and `docs` keep the base routes: moving them saved nothing in that replay, and Haiku scores lower on research benchmarks (Humanity's Last Exam with tools: 50.1% against 63.0% for Opus at `medium`).
89
92
 
90
- A user file merges over these overrides one field at a time, as `routes` does. This sets only the effort of the built-in `code` override at `low`, so the cell runs Sonnet at `high`, and adds a new override at `high`:
93
+ These are vendor benchmarks and a list-price replay, not measurements of this router, and they are not a claim of equal quality. The overrides add one (model, effort) pair the base routes do not use, Sonnet at `high`. The router counts each pair as its own cache, so activity routing adds one. [Activity routing](activity-routing.md) has the evidence per cell and its limits.
94
+
95
+ A user file merges over these overrides one field at a time, as `routes` does. This sets only the effort of the built-in `code` override at `low`, so the cell runs Sonnet at `xhigh`, and adds a new override at `high`:
91
96
 
92
97
  ```json
93
98
  {
94
- "activityRouting": "on",
95
99
  "activities": {
96
- "code": { "low": { "effort": "high" }, "high": { "effort": "max" } }
100
+ "code": { "low": { "effort": "xhigh" }, "high": { "effort": "max" } }
97
101
  }
98
102
  }
99
103
  ```
100
104
 
105
+ An override for a cell with no built-in names both fields, or inherits the missing one from the base route. This runs `docs` at `medium` on Sonnet at the base route's `medium` effort:
106
+
107
+ ```json
108
+ { "activities": { "docs": { "medium": { "model": "sonnet" } } } }
109
+ ```
110
+
101
111
  - `effort: null` keeps the session effort, as in `routes`.
102
- - A cell cannot be `null`. To drop a built-in override, set it to the tier's route, for example `"ops": { "medium": { "model": "opus", "effort": "medium" } }`. The pane writes this for you when you remove an override.
112
+ - A cell cannot be `null`. To drop a built-in override, set it to the base route, for example `"ops": { "medium": { "model": "opus", "effort": "medium" } }`. The pane writes this for you when you remove an override. The cell keeps that route if you later change the tier's route; remove it again then.
103
113
  - An override applies to whatever the tier's route is. If you move `routes.low` to Opus, the built-in `code` override at `low` still runs Sonnet. Set it to match, or remove it.
104
114
  - Unknown activities and tiers, unknown model aliases, and invalid efforts make the file invalid, like any other invalid setting. The pane refuses to save one and names it, such as `activities.code.low.model is not in models`.
105
- - Each distinct (model, effort) pair is its own cache. The Routing tab counts them.
115
+ - The router counts each distinct (model, effort) pair as its own cache. The Routing tab counts them.
116
+
117
+ `policy.activityMass` (default `0.6`) is the lowest probability at which an activity applies. The Routing tab sets it as **Activity threshold** under POLICY, from 50% to 80%. It has not been tuned on any classifier, and the probe results do not record probabilities, so there is no data to tune it on yet.
106
118
 
107
- `policy.activityMass` (default `0.6`) is the lowest probability at which an activity applies. It has not been tuned on any classifier. Probabilities differ between classifiers, so recalibrate it from the [probe set](evaluation.md#activity-probe-set) if you change classifier.
119
+ Switch the mode with `/router activities off|shadow|on`, or with the **Activity routing** selector at the top of the Routing tab's ACTIVITIES section. The command writes `router.json` at once; the selector joins the Routing draft and writes on **Save**. Choosing `on`, the default, removes the key from the file.
108
120
 
109
- Switch the mode with `/router activities off|shadow|on`, or with the selector at the top of the Routing tab's OVERRIDES section. The command writes `router.json` at once; the selector joins the Routing draft and writes on **Save**. Choosing `shadow`, the default, removes the key from the file.
121
+ **Upgrade from 1.6.** 1.6 defaulted to `shadow` with Sonnet at `medium` in every override. A file without `activityRouting` now runs `on`; a file that sets it keeps its mode. Choosing `shadow` in 1.6 removed the key, because `shadow` was the default then: if you chose `shadow` in 1.6, run `/router activities shadow` again after upgrading. A session started on Sonnet 5.5 now starts with routing on, because Sonnet runs the `code` cell at `low`; to stay on Sonnet in that session, choose it with `/model` or run `/router off`, and run `/router activities shadow` to make future Sonnet sessions start with routing off. Cells you saved stay as written. A cell that sets one field takes the other from 1.7's built-in for that cell, or from the base route where 1.7 has none (`explore` and `docs` at `medium`, `docs` at `low`). 1.6's overrides in those cells and in `ops` at `medium` were Sonnet · medium, so such a cell can now run another model or effort; write both fields to keep 1.6's route. A 1.6 removal of a built-in that 1.7 no longer has, such as `docs` at `low`, stays in the file as the tier's route; the pane lists it as "same as base: no effect", and **remove** drops it.
110
122
 
111
- **Rollback.** Router 1.5 rejects unknown keys and makes routing unavailable. Before you install 1.5 again, remove `activities`, `activityRouting`, and `policy.activityMass` from `router.json`. The pane writes them when you set the mode to `off` or `on`, or edit or remove an override.
123
+ **Rollback.** To go back to 1.6 behavior without downgrading, set `"activityRouting": "shadow"`, or `off`. Router 1.6 reads the same keys; under 1.6 a file without `activityRouting` runs `shadow` with 1.6's overrides. Router 1.5 rejects unknown keys and makes routing unavailable. Before you install 1.5 again, remove `activities`, `activityRouting`, and `policy.activityMass` from `router.json`. The pane writes them when you set the mode to `off` or `shadow`, change the activity threshold, or edit or remove an override.
112
124
 
113
125
  ## Classifiers
114
126
 
@@ -176,9 +188,9 @@ The Mod validates the whole file. Unknown keys and invalid values make routing u
176
188
  | ------------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------- |
177
189
  | `baselineTier` | `micro`, `low`, `medium`, `high` | `low` |
178
190
  | `routes.<tier>` | `model`, optional `effort` (a level, or `null` for the session effort) | As in the route table above |
179
- | `activityRouting` | `off`, `shadow`, `on` | `shadow` |
191
+ | `activityRouting` | `off`, `shadow`, `on` | `on` |
180
192
  | `activities.<activity>.<tier>` | optional `model` and `effort`, as in `routes` | The overrides in [Activity routing](#activity-routing) |
181
- | `models.<alias>` | `id`, `input`, optional `output`, `cacheRead`, `contextWindow`, `billing`, `efforts` | Three defaults above |
193
+ | `models.<alias>` | `id`, `input`, optional `output`, `cacheRead`, optional `longContext` (`above`, `multiplier`, or `null`), `contextWindow`, `billing`, `efforts` | Three defaults above |
182
194
  | `cache` | `writeMultiplier`, `ttlMs`, `warmMarginMs` | `5m: 1.25`, `1h: 2`; `300000` / `3600000` ms; `30000` ms |
183
195
  | `policy` | Fields below | Values below |
184
196
  | `classifier` | An id in `classifiers` | `jev` |
@@ -187,24 +199,24 @@ The Mod validates the whole file. Unknown keys and invalid values make routing u
187
199
 
188
200
  Policy defaults:
189
201
 
190
- | Field | Default | Meaning |
191
- | ----------------------- | ------: | --------------------------------------------------------------------------------------------------------- |
192
- | `upgradeVotes` | `2` | Consecutive supporting votes before an upgrade; one before a history's first measured reply. |
193
- | `upgradeBase` | `0.75` | Minimum probability mass required for an upgrade. |
194
- | `upgradeSlope` | `0.15` | Maximum increase to the upgrade bar from estimated switching cost. |
195
- | `upgradePivotUsd` | `0.5` | Cost scale used by the upgrade bar. Must be positive. |
196
- | `jumpConfidence` | `0.95` | Support for a two-tier jump without waiting for votes. |
197
- | `downgradeVotes` | `2` | Consecutive supporting votes before a downgrade; one before a history's first measured reply. |
198
- | `downgradeMass` | `0.9` | Minimum probability mass required for a downgrade. |
199
- | `downgradeSlope` | `0.08` | Maximum increase to the downgrade bar from estimated switching cost. |
200
- | `downgradePivotUsd` | `0.5` | Cost scale used by the downgrade bar. Must be positive. |
201
- | `downgradeHorizonTurns` | `5` | Later turns included in a downgrade payback estimate. |
202
- | `continuationMass` | `0.7` | Advice probability that keeps the current route for a continuation. |
203
- | `escalationHoldTurns` | `2` | Turns held after a repeated tool error escalates the route. |
204
- | `cashCapUsd` | `2` | Maximum estimated cold cache write for a `credits` model. It does not cap output or session spend. |
205
- | `activityMass` | `0.6` | Minimum probability for the classifier's activity to apply. Not tuned on any classifier. Not in the pane. |
206
-
207
- The pane writes a subset of these settings. The **Routing** tab sets `routes`, `baselineTier`, `activities`, `activityRouting`, `policy.downgradeVotes`, `policy.downgradeHorizonTurns`, and `policy.cashCapUsd` in one save: it writes only values that differ from the defaults and removes the rest. `/router activities <mode>` writes `activityRouting` at once, with **Undo**. The **Classifier** tab sets `classifier` and the active classifier's `timeoutMs` at once. **Undo** reverts the settings the last pane write changed. Each save validates the whole file, keeps other keys, and applies from the next turn. A failed check names the setting and leaves the file unchanged. The pane refuses to write through a symlink. Model aliases and the other settings require a direct edit.
202
+ | Field | Default | Meaning |
203
+ | ----------------------- | ------: | -------------------------------------------------------------------------------------------------- |
204
+ | `upgradeVotes` | `2` | Consecutive supporting votes before an upgrade; one before a history's first measured reply. |
205
+ | `upgradeBase` | `0.75` | Minimum probability mass required for an upgrade. |
206
+ | `upgradeSlope` | `0.15` | Maximum increase to the upgrade bar from estimated switching cost. |
207
+ | `upgradePivotUsd` | `0.5` | Cost scale used by the upgrade bar. Must be positive. |
208
+ | `jumpConfidence` | `0.95` | Support for a two-tier jump without waiting for votes. |
209
+ | `downgradeVotes` | `2` | Consecutive supporting votes before a downgrade; one before a history's first measured reply. |
210
+ | `downgradeMass` | `0.9` | Minimum probability mass required for a downgrade. |
211
+ | `downgradeSlope` | `0.08` | Maximum increase to the downgrade bar from estimated switching cost. |
212
+ | `downgradePivotUsd` | `0.5` | Cost scale used by the downgrade bar. Must be positive. |
213
+ | `downgradeHorizonTurns` | `5` | Later turns included in a downgrade payback estimate. |
214
+ | `continuationMass` | `0.7` | Advice probability that keeps the current route for a continuation. |
215
+ | `escalationHoldTurns` | `2` | Turns held after a repeated tool error escalates the route. |
216
+ | `cashCapUsd` | `2` | Maximum estimated cold cache write for a `credits` model. It does not cap output or session spend. |
217
+ | `activityMass` | `0.6` | Minimum probability for the classifier's activity to apply. Not tuned on any classifier. |
218
+
219
+ The pane writes a subset of these settings. The **Routing** tab sets `routes`, `baselineTier`, `activities`, `activityRouting`, `policy.downgradeVotes`, `policy.downgradeHorizonTurns`, `policy.cashCapUsd`, and `policy.activityMass` in one save: it writes only values that differ from the defaults and removes the rest. `/router activities <mode>` writes `activityRouting` at once, with **Undo**. The **Classifier** tab sets `classifier` and the active classifier's `timeoutMs` at once. **Undo** reverts the settings the last pane write changed. Each save validates the whole file, keeps other keys, and applies from the next turn. A failed check names the setting and leaves the file unchanged. The pane refuses to write through a symlink. Model aliases and the other settings require a direct edit.
208
220
 
209
221
  Native cache freshness is unknown after 270 seconds or after a history reset. Claude usage does not report the cache TTL. The policy evaluates price bounds for five-minute and one-hour writes, but the one-hour case is not observed fact. See the [architecture](architecture.md#cache-and-cost) for the estimate rules.
210
222