@alexeiled/claude-router 0.5.1 → 0.6.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "router",
   "displayName": "jev-router",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "Auto-picks the right Claude model for each turn — small models for quick edits, mid-tier for code, frontier for hard problems. Uses Jev to classify each request.",
   "author": { "name": "Alexei Ledenev", "url": "https://github.com/alexei-led" },
   "repository": "https://github.com/alexei-led/claude-router",

package/README.md

@@ -7,11 +7,17 @@
 
 A Claude Code plugin that auto-picks the right model and effort for each turn.
 
-A local gateway on `127.0.0.1` receives each request from Claude Code. For a
-new user turn, the gateway asks Jev (TypeSafe) which tier the turn needs. Then
-the gateway rewrites `model`, `effort` and `thinking` in the request and sends
-it to Anthropic. All other data goes through unchanged. The gateway has no
-runtime dependencies and needs Node 22 or later.
+**Status: experimental.** I built this to dogfood Jev, TypeSafe's routing
+model, inside Claude Code. It works for me; I don't know yet if it holds up
+outside my setup. Try it and open an issue with what you find.
+
+## Why
+
+One model for every turn is a compromise: strong enough for the hard turns
+and it burns your limits on "rename this variable"; cheap enough for the easy
+turns and it struggles on the hard ones. Switching models by hand works, but
+it is friction you pay on every message. This plugin asks a small router
+model which tier a turn needs and switches for you, automatically.
 
 ## How it works
 
@@ -26,19 +32,23 @@ only requests for `jev-router`:        ├─ facts.mjs    prompt, continuation,
    responses go through unchanged; the gateway reads `usage` (context size, cache TTL)
 ```
 
+A local gateway on `127.0.0.1` receives each request from Claude Code. For a
+new user turn, the gateway asks Jev which tier the turn needs, then rewrites
+`model`, `effort` and `thinking` and sends the request to Anthropic. All other
+data goes through unchanged. No runtime dependencies; Node 22 or later.
+
 The tiers are `micro` (Haiku), `low` (Sonnet, the baseline), `medium` (Opus at
 high effort) and `high` (Opus at xhigh effort). The exact model IDs are in
 `~/.claude/router.json` and default to the current generation of each family.
 
 A tool continuation keeps the route of its turn — the gateway does not ask Jev.
-Side requests, for example session titles, get the baseline tier. A request for
-any other model goes through unchanged. This is how `/router:<tier>` pins and
+Side requests, for example session titles, get the baseline tier. A subagent
+that inherits the model gets routing with its own memory. A request for any
+other model goes through unchanged; this is how `/router:<tier>` pins and
 subagents with their own `model` work.
 
-Module dependencies point in one direction: `gateway.mjs` (HTTP) →
-`router.mjs` (orchestration) → `facts`, `jev`, `policy` → `cost`, `rewrite`,
-`store`. The modules `facts`, `cost`, `rewrite`, `sse` and `policy` are pure.
-Only `store` writes files. The Jev transport is injected.
+See [Architecture](docs/architecture.md) for the module map, the switching
+policy, and a real-usage evaluation.
 
 ## Install
 
@@ -78,14 +88,11 @@ plugin never replaces a newer gateway. The Jev API key stays in the macOS
 Keychain. Run `/router:setup` once after an update: the status line command
 path contains the plugin version.
 
-Updating from 0.3.0 or earlier: these gateways cannot hand over, so stop the
-old one once with `pkill -f scripts/gateway.mjs`.
-
 ## Documentation
 
 - [User guide](docs/user-guide.md): daily use, pins, decision log, troubleshooting.
 - [Configuration](docs/configuration.md): each key, and where the API key and the configuration file are.
-- [Design](docs/design.md): decisions, the switching policy, test results.
+- [Architecture](docs/architecture.md): how the gateway works, the switching policy, a real-usage evaluation.
 
 ## Develop
 
@@ -101,4 +108,4 @@ claude --plugin-dir . --model jev-router   # with ANTHROPIC_BASE_URL and TYPESAF
 Releases: push a signed tag `v<version>` that matches `package.json`. The
 release workflow publishes `@alexeiled/claude-router` to npm with trusted
 publishing and creates the GitHub release. See
-[docs/design.md](docs/design.md#release).
+[docs/architecture.md](docs/architecture.md#release).

package/docs/{design.md → architecture.md}

@@ -1,4 +1,4 @@
-# Design record
+# Architecture
 
 Each decision has the date when the owner took it.
 
@@ -21,12 +21,17 @@ get the context size, the cache reads and the cache TTL.
 For a model without thinking (Haiku), the gateway also removes the
 `clear_thinking_*` edits from `context_management`, because the API rejects
 them without thinking. The gateway never changes `system`, `tools` or
-`messages`. Thus preserved
-thinking and prompt caching work as if Claude Code talked to Anthropic. Claude
-Code documents this gateway mode, including the OAuth value for a claude.ai
-login. See [llm-gateway](https://code.claude.com/docs/en/llm-gateway) and
+`messages`. Thinking and prompt caching work as if Claude Code talked to
+Anthropic directly. Claude Code documents this gateway mode, including the
+OAuth value for a claude.ai login. See
+[llm-gateway](https://code.claude.com/docs/en/llm-gateway) and
 [protocol](https://code.claude.com/docs/en/llm-gateway-protocol).
 
+Module dependencies point in one direction: `gateway.mjs` (HTTP) →
+`router.mjs` (orchestration) → `facts`, `jev`, `policy` → `cost`, `rewrite`,
+`store`. The modules `facts`, `cost`, `rewrite`, `sse` and `policy` are pure.
+Only `store` writes files. The Jev transport is injected.
+
 The `SessionStart` hook of the plugin starts the gateway when the port does not
 answer. `/router:setup` writes `model`, `ANTHROPIC_BASE_URL` and the picker row to
 the user settings once. A plugin cannot set them by itself.
@@ -38,22 +43,14 @@ is the only place where the real model of the turn is visible.
 
 ### Why not the native skill path
 
-The first design used a `UserPromptSubmit` hook. The hook asked Claude to call
-a tier skill. The frontmatter `model:` and `effort:` of the skill were to serve
-the rest of the turn.
-
-The test on Claude Code 2.1.278 gave this result. A skill that the user types
-(`/router:medium …`) changes the model for the turn. The same skill,
-called by Claude through the Skill tool, does not change the model. The
-transcript records `attributionSkill`, but the session model answers. The test
-ran in three sessions, in auto mode and in `acceptEdits` mode, with Opus and
-Fable targets. The documentation says "when this skill is active". The
-behavior is user invocation only. A feedback report is filed. The skills stay
-as manual pins.
-
-This result also removed the "Sonnet session model" argument from the peer
-review. The gateway has no bootstrap request and no cache drop for a turn that
-keeps its route. The baseline is a configuration value.
+The first design used a `UserPromptSubmit` hook that asked Claude to call a
+tier skill, relying on the skill's frontmatter `model:` and `effort:` to serve
+the rest of the turn. On Claude Code 2.1.278 that only works for a skill the
+user types (`/router:medium …`); the same skill called by Claude through the
+Skill tool does not change the model — the transcript records
+`attributionSkill`, but the session model answers. So `/router:<tier>` skills
+stay as manual pins, and the gateway is the only path that routes turns Claude
+calls on its own.
 
 ## Tiers
 
@@ -64,19 +61,20 @@ keeps its route. The baseline is a configuration value.
 | low    | sonnet | as sent | claude-sonnet-5      |
 | micro  | haiku  | none    | claude-haiku-4-5     |
 
-The gateway lowers the effort to a level that the model family accepts. Sonnet
-4.6 has no `xhigh`. Haiku gets no effort and no adaptive thinking. The ids are
-configuration. `sonnet` is 4.6 because the alias resolved to 4.6 on the test
-account.
+The gateway lowers the effort to a level the model's `efforts` list accepts
+(see [configuration](configuration.md#models)); Haiku accepts none, so it gets
+no effort and no adaptive thinking. The ids are configuration.
 
 ## Request classes
 
 - New user turn (the last message has no `tool_result`): Jev and the policy.
 - Tool continuation: the route of the turn, without a Jev call.
-- Every request class other than `main`, from the header
+- The classes `auxiliary` and `compaction` from the header
   `x-claude-code-request-class`: `auxiliaryTier`, and the memory stays
-  unchanged. Without the header, a body with `thinking: disabled` and a
-  `format` is a side request.
+  unchanged. `main`, `subagent` and `workflow` get routing. Without the header,
+  a body with `thinking: disabled` and a `format` is a side request.
+- A subagent (header `x-claude-code-agent-id`): routing with its own memory,
+  under the key `<session>.<agent id>`. The main conversation keeps its route.
 - Any other `model`: unchanged. This covers `/router:<tier>` pins,
   `/model` changes and subagents with their own model.
 - A resent request (the same history length and the same last message): the
@@ -84,6 +82,10 @@ account.
   429, a 529 or a dropped connection.
 - A side endpoint with the alias, such as `/v1/messages/count_tokens`: the
   model of the session's last route. Only `POST /v1/messages` is a turn.
+- A history break: a main request with fewer messages than the last one (a
+  compaction or a rewind), or the header `x-claude-code-context-compacted`.
+  The gateway drops the cached prefixes, the votes and the escalation hold,
+  then routes the request as usual. The route stays until the next decision.
 
 ## Failure handling
 
@@ -101,7 +103,7 @@ request must not reach the others.
   logged. The routing decision stands.
 - Jev: one retry on a network error or a transient status, after
   `Retry-After` when it fits the 1.5 s budget. After three failures in a row,
-  new turns skip Jev for a minute, then try once.
+  new turns skip Jev for a minute, then try once per pause.
 - The daemon logs a stray exception instead of exiting. On `SIGTERM` it
   releases the port at once and finishes open streams for up to 10 minutes.
   A second daemon on a busy port exits quietly.
@@ -125,18 +127,20 @@ request must not reach the others.
 All inputs come from the traffic of the gateway. The gateway does not read
 transcripts.
 
-| Input                                            | Source                                                                                                                          |
-| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
-| Context of the last request, cache reads, output | `usage` in the response (`message_start` and `message_delta`)                                                                   |
-| Granted TTL                                      | `usage.cache_creation.ephemeral_1h_input_tokens` or the `5m` field                                                              |
-| Cache warmth of a model                          | The time of the last response of that model, plus the TTL, minus 30 s                                                           |
-| Reusable prefix of a model                       | The context plus the output at the last response of that model. Cleared when the context shrinks by more than 20% (compaction). |
-| Failure signal                                   | Two `tool_result` blocks with `is_error` and the same signature, with an edit tool call between them                            |
-| Continuation                                     | The last message contains a `tool_result`. For a new prompt, a Jev Noul answers "does this prompt continue the task".           |
-
-Prices are a list-price table in the configuration. `modelPricing` is a
-managed setting and is not readable. The switching tax for a candidate `c`
-against the current route `i` is:
+| Input                                            | Source                                                                                                                                                                   |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Context of the last request, cache reads, output | `usage` in the response (`message_start` and `message_delta`)                                                                                                            |
+| Granted TTL                                      | `usage.cache_creation.ephemeral_1h_input_tokens` or the `5m` field                                                                                                       |
+| Cache identity                                   | The model id and the effort the gateway sent (`claude-opus-5-5@xhigh`). An effort change rewrites the messages cache, so each effort is its own cache.                  |
+| Cache warmth                                     | The time of the last response for that cache, plus the TTL, minus 30 s. `unknown` when no response since the session started or the history broke.                      |
+| Reusable prefix                                  | The context plus the output at the last response for that cache. Cleared by a history break, or when the context shrinks by more than 20% (context editing).             |
+| Failure signal                                   | Two `tool_result` blocks with `is_error` and the same signature, with an edit tool call between them                                                                     |
+| Continuation                                     | The last message contains a `tool_result`. For a new prompt, a Jev Noul answers "does this prompt continue the task".                                                    |
+
+Prices are a list-price table in the configuration (see
+[configuration](configuration.md#models)). `modelPricing` is a managed setting
+and is not readable. The switching tax for a candidate `c` against the current
+route `i` is:
 
 ```
 input_cost(m) = P_read(m) * W_m + P_write(m) * (N - W_m)
@@ -146,11 +150,13 @@ tax = max(0, input_cost(c) - input_cost(i))
 The subscription economics are not symmetric. Every default model uses the plan
 limits, and dollars give the order between them. A model with `billing:
 "credits"` bills cash, on the 5m TTL, and behind the gateway without the
-consent prompt of Claude Code. `policy.cashCapUsd` ($2 by default) caps the
-cold cache write that the gateway will pay for an automatic route to such a
-model. A Claude Code turn starts at about 100k tokens (system prompt and 159
-tool definitions), so the gate binds on the first switch, not later. No default
-model bills credits; the gate stays for configurations that add one.
+consent prompt of Claude Code. `policy.cashCapUsd` is a cold-write guard: it
+caps the estimated first cache write of an automatic route to such a model
+when its cache is not warm. It is not a budget: a warm cache passes, and
+output is not counted. A Claude Code turn starts at about 100k tokens (system
+prompt and tool definitions), so the guard binds on the first switch, not
+later. No default model bills credits; the guard stays for configurations that
+add one.
 
 ## Switching policy v0
 
@@ -169,8 +175,9 @@ Agreed with Codex on 2026-09-22. The thresholds are start values.
    `U >= 0.75 + 0.15 * tax / (tax + 0.5)`. A jump of two tiers with
    `U >= 0.95` skips the delay. A downgrade needs `D >= 0.90` and two
    consecutive votes.
-5. Cash gate. An automatic route to a `credits` model needs a warm cache, or a
-   cold write below the cap. Otherwise the strongest `plan` tier serves.
+5. Cold-write guard (reason `cash-gate`). An automatic route to a `credits`
+   model needs a warm cache, or a cold write below the cap. Otherwise the
+   strongest `plan` tier serves.
 6. No cooldown on upgrades. Plan, then execute, then hard again is sometimes
    the correct routing. The log separates reversals from real changes in the
    required capability.
@@ -178,19 +185,64 @@ Agreed with Codex on 2026-09-22. The thresholds are start values.
    and cache reads of each routed response. The memory changes only from
    responses that the gateway sent.
 
-## Test results (2026-09-22, Max plan, Claude Code 2.1.278)
-
-- Easy prompt: Jev gave `micro` at confidence 1. It was the first vote, so
-  `low` served (`claude-sonnet-5`, 103,799 context tokens on the first
-  request).
-- Hard prompt: Jev gave `high` at 0.66. A cold Fable write cost $1.30 against
-  the cap of $0.50 at that time, so `medium` served (`claude-opus-5`). Four
-  tool continuations kept the route, with cache reads within 1% of the
-  context.
-- Claude Code accepted `message_start.model` with the real model. The status
-  line showed the alias at all times.
-- Cold start: the `SessionStart` hook started the gateway before the first
-  request.
+## Cache identity, history breaks and shadow economics (2026-09-23)
+
+From a design review with the architect of pi-model-router, the Pi router
+that uses the same Jev tiers.
+
+- Cache identity is the model and the effort. A top-level effort change
+  invalidates the messages cache; the cache-preserving per-message effort is
+  not available on Opus 5.5. Before 0.6.1 the key was the model alone, so
+  `medium` ↔ `high` (Opus at `high` and `xhigh`) looked like a free switch
+  between warm caches.
+- A history break (fewer messages, or the compaction header) drops the cached
+  prefixes, the votes and the escalation hold: they were about turns that are
+  gone. Context editing shrinks the context but keeps the messages; it drops
+  only the prefixes. The gateway has no branch id, so it does not restore state
+  from before a rewind; `unknown` is the honest cache state after one.
+- `/router:status` and the status line show the reason; the report adds the
+  estimate. The dollars are list prices, a list-price equivalent for plan
+  models.
+- Shadow economics in `decisions.jsonl`, not read by the policy: for a turn
+  where Jev's choice differs from the current route, the extra cost of the
+  next turn, the difference for each later turn (input and output), and the
+  turns until a cheaper route repays its cache write. The owner's first
+  request (2026-09-22) was to stay while the model works on a warm cache and
+  to step down once the thinking is done. Rule 2 covers the first half; the
+  shadow estimate measures the second before any rule acts on it.
+- The default prices match `test/fixtures/list-prices.json`, which names its
+  source and date. A test pins how a tenfold cache-read error changes one
+  decision: the bar moves within `upgradeBase` and `upgradeBase +
+  upgradeSlope`, and a confident jump ignores it. That error happened once
+  (a838f7c).
+
+Not taken: the agent type as a routing signal; a payback check on downgrades
+before shadow data; removing the switching tax from the upgrade bar before a
+replay of the logs. The Pi router rejects the tax-to-confidence formula
+because it mixes dollars with an uncalibrated probability; the replay decides.
+
+## Real-world evaluation (2026-09-23)
+
+A day of dogfooding this repository on the installed plugin: 31 Claude Code
+sessions, 1,578 routed requests, one machine. `decisions.jsonl` holds the
+tier, the reason and the token counts for every request — no prompt text.
+
+![Share of requests by tier, and the input-token cost of the same traffic repriced at Opus's rates](tier-share.svg)
+
+82% of turns never needed more than Sonnet, 10% stayed on Haiku, and 8% needed
+Opus. `medium` (Opus at `high` effort) fired once: a confident vote jumps two
+tiers straight to `high` instead of stopping at `medium` (switching policy,
+rule 4).
+
+Repricing that same traffic — same tokens, same observed cache reads — at
+Opus's rates puts the input-token bill 18.8% above what the router actually
+spent. That number covers input tokens only: the price table has no output
+price (see [Cache and cost inputs](#cache-and-cost-inputs)), so it cannot say
+how much of the real saving is left out — likely more, since Haiku and Sonnet
+also bill less per output token than Opus. Answer quality isn't measured
+here either.
+
+One developer, one day: a dogfood snapshot, not a benchmark.
 
 ## Layout
 
@@ -207,7 +259,7 @@ Agreed with Codex on 2026-09-22. The thresholds are start values.
   lib/config.mjs               defaults, user file, validation
   lib/facts.mjs                request body and memory -> facts (pure)
   lib/jev.mjs                  request, injected transport, parse
-  lib/cost.mjs                 warmth, input cost, switching tax
+  lib/cost.mjs                 cache key, warmth, input cost, switching tax, shadow economics
   lib/policy.mjs               switching policy v0
   lib/rewrite.mjs              model, effort, thinking per model family
   lib/sse.mjs                  usage reader for SSE and JSON bodies
@@ -229,8 +281,17 @@ Agreed with Codex on 2026-09-22. The thresholds are start values.
   `decisions.jsonl` are the input for the tuning.
 - The gateway reads the configuration once. A reload without a restart is not
   implemented.
-- Without `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1`, subagents with `model: inherit`
-  get routing like the main conversation.
+- Without `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1`, the gateway guesses side
+  requests from the body; the guesses miss some. A missed side request with
+  a short history also counts as a history break.
+- `x-claude-code-agent-type` is logged, not used: no policy rule reads it yet.
+- Does a downgrade that the shadow estimate says never repays deserve a rule,
+  and does the switching tax belong in the upgrade bar? A replay of
+  `decisions.jsonl` against the `shadow` and `observed` lines decides.
+- Effort changes how much a model writes. The shadow estimate uses the last
+  output size for both routes.
+- Whether tools and system survive an effort change is model-specific; the
+  gateway counts the whole prefix as lost, an upper bound.
 
 ## Release
 

package/docs/configuration.md

@@ -23,7 +23,8 @@ starts it again.
   "model": "jev-router[1m]",
   "env": {
     "ANTHROPIC_BASE_URL": "http://127.0.0.1:43170",
-    "ENABLE_TOOL_SEARCH": "true"
+    "ENABLE_TOOL_SEARCH": "true",
+    "CLAUDE_CODE_GATEWAY_HINT_HEADERS": "1"
   },
   "modelPicker": {
     "options": [
@@ -76,18 +77,31 @@ If you agree, it also wraps the status line command:
 ```
 
 The wrapper runs the command after it, then adds one line for a routed
-session, for example `jev-router ▸ opus-5-5 · xhigh`. Without a command
+session, for example `jev-router ▸ opus-5-5 · xhigh · upgrade`. Without a command
 after it, it prints only that line. The path contains the plugin version, so
 run `/router:setup` again after a plugin update.
 
-One optional key in `env`:
+`CLAUDE_CODE_GATEWAY_HINT_HEADERS: "1"` makes Claude Code send the gateway
+hint headers:
 
-- `CLAUDE_CODE_GATEWAY_HINT_HEADERS: "1"`. Claude Code then tells the gateway
-  the class of each request. Requests of the class `main` get routing. All
-  other classes (`auxiliary`, `subagent`, `workflow`, `compaction`) get
-  `gateway.auxiliaryTier`. A subagent with `model: inherit` runs on that tier.
-  Without the header, the gateway identifies side requests by their shape, and
-  subagents get routing like the main conversation.
+- `x-claude-code-request-class`. The classes `main`, `subagent` and `workflow`
+  get routing. `auxiliary` and `compaction` are side requests and get
+  `gateway.auxiliaryTier`.
+- `x-claude-code-context-compacted` on the first request after a compaction.
+  The gateway then drops the cached prefixes of every model, the pending
+  votes and the escalation hold.
+- `x-claude-code-agent-type`, for example `Explore` or `Plan`. It goes to
+  `decisions.jsonl` only.
+
+Without the headers, the gateway identifies side requests by their shape. A
+main request with fewer messages than the last one is a compaction or a
+rewind, with or without the headers: the gateway drops the same state. A
+context that shrank by more than 20% with no fewer messages is context
+editing; it drops only the cached prefixes.
+
+A subagent with `model: inherit` sends `x-claude-code-agent-id` even without
+the hint headers. Each subagent keeps its own routing memory, so its turns do
+not change the route of the main conversation.
 
 ## Configuration file
 
@@ -113,6 +127,7 @@ path. Nested objects merge.
     "sonnet": {
       "id": "claude-sonnet-5",
       "input": 2,
+      "output": 10,
       "cacheRead": 0.2,
       "contextWindow": 1000000,
       "billing": "plan",
@@ -146,14 +161,18 @@ frontmatter of `skills/<tier>/SKILL.md`. A test makes sure that they agree.
 
 ### models
 
-| Alias    | ID                 | Input | Cache Read | Window | Max output | Billing | Efforts       |
-| -------- | ------------------ | ----- | ---------- | ------ | ---------- | ------- | ------------- |
-| `opus`   | `claude-opus-5-5`  | $4    | $0.2       | 1M     | as sent    | plan    | all           |
-| `sonnet` | `claude-sonnet-5`  | $2    | $0.2       | 1M     | as sent    | plan    | low–xhigh–max |
-| `haiku`  | `claude-haiku-4-5` | $1    | $0.1       | 200k   | 64k        | plan    | none          |
-
-`id` is the model id that the gateway sends to Anthropic. `input` and
-`cacheRead` are list prices in USD per million tokens. `contextWindow` is the
+| Alias    | ID                 | Input | Output | Cache Read | Window | Max output | Billing | Efforts       |
+| -------- | ------------------ | ----- | ------ | ---------- | ------ | ---------- | ------- | ------------- |
+| `opus`   | `claude-opus-5-5`  | $4    | $20    | $0.2       | 1M     | as sent    | plan    | all           |
+| `sonnet` | `claude-sonnet-5`  | $2    | $10    | $0.2       | 1M     | as sent    | plan    | low–xhigh–max |
+| `haiku`  | `claude-haiku-4-5` | $1    | $5     | $0.1       | 200k   | 64k        | plan    | none          |
+
+`id` is the model id that the gateway sends to Anthropic. `input`, `output`
+and `cacheRead` are list prices in USD per million tokens. `output` is
+optional and feeds only the `shadow` estimate in `decisions.jsonl`; the policy
+does not read it. The defaults match `test/fixtures/list-prices.json`, which
+names its source and the date it was checked; a test fails when the two
+differ. `contextWindow` is the
 size of the context window in tokens. `maxOutput`, when set, caps the
 `max_tokens` that Claude Code sends; the API rejects a request above the
 model's output limit. `billing` is `plan` for models that use
@@ -170,12 +189,12 @@ effort and thinking from the request.
 | `gateway.auxiliaryTier`                          | The tier for side requests, for example session titles.                                                                                      |
 | `gateway.idleShutdownMs`                         | The gateway exits after this long without requests, when no turn waits for a tool result. Two hours by default; `0` keeps it running.        |
 | `upgradeVotes`                                   | The number of consecutive votes above the current tier before an upgrade of one tier.                                                        |
-| `upgradeBase`, `upgradeSlope`, `upgradePivotUsd` | The required probability mass: `base + slope * tax / (tax + pivot)`. The `tax` is the extra input cost to read the context on the new model. |
+| `upgradeBase`, `upgradeSlope`, `upgradePivotUsd` | The required probability mass: `base + slope * tax / (tax + pivot)`. The `tax` is the extra input cost to read the context on the new route; the cache is per model and effort. |
 | `jumpConfidence`                                 | The mass that lets a jump of two tiers skip the vote delay.                                                                                  |
 | `downgradeVotes`, `downgradeMass`                | The number of consecutive votes, and the mass at or below the candidate, for a downgrade.                                                    |
 | `continuationMass`                               | The Jev probability for "this prompt continues the task" that keeps the current route.                                                       |
 | `escalationHoldTurns`                            | The number of turns to hold one tier up after two failed repairs of the same error.                                                          |
-| `cashCapUsd`                                     | The cold cache-write cost above which the gateway refuses an automatic route to a `credits` model.                                           |
+| `cashCapUsd`                                     | The cold-write guard: the estimated first cache write above which the gateway refuses an automatic route to a `credits` model whose cache is not warm. Not a budget for the turn: output is not counted. |
 
 ## Environment variables
 

package/docs/tier-share.svg

@@ -0,0 +1,44 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 500" font-family="system-ui, -apple-system, 'Segoe UI', sans-serif">
+  <rect width="720" height="500" fill="#fcfcfb"/>
+  <text x="24" y="34" font-size="18" font-weight="700" fill="#0b0b0b">Where the router sent the calls</text>
+  <text x="24" y="56" font-size="13" fill="#898781">one developer, 31 sessions, one day of dogfooding (2026-09-23) — 1578 routed requests</text>
+
+  <text x="24" y="74" font-size="12" font-weight="600" fill="#52514e">SHARE OF REQUESTS BY TIER</text>
+
+  <text x="196" y="111" text-anchor="end" font-size="13" fill="#52514e">micro · Haiku</text>
+  <rect x="210" y="96" width="50.07299270072993" height="22" rx="4" fill="#86b6ef"/>
+  <text x="268.0729927007299" y="111"
+        text-anchor="start" font-size="13" font-weight="600"
+        fill="#0b0b0b">9.8%</text>
+
+  <text x="196" y="157" text-anchor="end" font-size="13" fill="#52514e">low · Sonnet</text>
+  <rect x="210" y="142" width="420" height="22" rx="4" fill="#3987e5"/>
+  <text x="620" y="157"
+        text-anchor="end" font-size="13" font-weight="600"
+        fill="#ffffff">82.2%</text>
+
+  <text x="196" y="203" text-anchor="end" font-size="13" fill="#52514e">medium · Opus (high)</text>
+  <rect x="210" y="188" width="3" height="22" rx="4" fill="#1c5cab"/>
+  <text x="221" y="203"
+        text-anchor="start" font-size="13" font-weight="600"
+        fill="#0b0b0b">0.1%</text>
+
+  <text x="196" y="249" text-anchor="end" font-size="13" fill="#52514e">high · Opus (xhigh)</text>
+  <rect x="210" y="234" width="40.87591240875912" height="22" rx="4" fill="#0d366b"/>
+  <text x="258.8759124087591" y="249"
+        text-anchor="start" font-size="13" font-weight="600"
+        fill="#0b0b0b">8%</text>
+
+  <line x1="24" y1="300" x2="696" y2="300" stroke="#e1e0d9" stroke-width="1"/>
+  <text x="24" y="320" font-size="12" font-weight="600" fill="#52514e">INPUT-TOKEN COST, LIST PRICE — SAME TRAFFIC, REPRICED AT OPUS RATES</text>
+
+  <text x="196" y="355" text-anchor="end" font-size="13" fill="#52514e">router (actual)</text>
+  <rect x="210" y="340" width="341.043219076006" height="22" rx="4" fill="#2a78d6"/>
+  <text x="559.0432190760059" y="355" font-size="13" font-weight="600" fill="#0b0b0b">$114.42</text>
+
+  <text x="196" y="401" text-anchor="end" font-size="13" fill="#52514e">same traffic, Opus prices</text>
+  <rect x="210" y="386" width="420" height="22" rx="4" fill="#c3c2b7"/>
+  <text x="638" y="401" font-size="13" font-weight="600" fill="#0b0b0b">$140.91</text>
+  <text x="24" y="448" font-size="12" fill="#898781">−18.8% on input tokens alone. Output-token price isn't in the model, so real savings are likely larger, not smaller.</text>
+  <text x="24" y="468" font-size="12" fill="#898781">Not measured: answer quality. One machine, one day — a dogfood snapshot, not a benchmark.</text>
+</svg>

package/docs/user-guide.md

@@ -29,13 +29,20 @@ ANTHROPIC_BASE_URL=http://127.0.0.1:43170 claude --plugin-dir . --model jev-rout
   route stays there for two turns. A repair is an edit between the two errors.
 - An upgrade needs two consecutive votes for a higher tier. A jump of two
   tiers with high confidence happens at once. The required confidence goes up
-  with the cost to read the context again on the new model.
+  with the cost to read the context again on the new model. Opus at `high` and
+  Opus at `xhigh` are two caches: a change of effort rewrites the cached
+  conversation, so `medium` to `high` is not free.
 - A downgrade needs two consecutive confident votes.
-- A cold switch to a model that bills usage credits is refused when the cache
-  write costs more than `policy.cashCapUsd`. Then the strongest plan tier
-  serves the turn. Behind the gateway, Claude Code does not show its consent
-  prompt for these credits, so the cap is the only guard. No default model
-  bills credits; this applies once you add one in `router.json`.
+- When the conversation gets shorter, after a compaction or a rewind, the
+  gateway forgets the cached prefixes, the pending votes and the escalation
+  hold. They were about turns that are no longer in the conversation.
+- The cold-write guard: an automatic switch to a model that bills usage
+  credits is refused when that model's cache is not warm and the first cache
+  write would cost more than `policy.cashCapUsd`. Then the strongest plan tier
+  serves the turn. The guard limits that one estimated write, not the cost of
+  the turn: output is not counted. Behind the gateway, Claude Code does not
+  show its consent prompt for these credits. No default model bills credits;
+  this applies once you add one in `router.json`.
 - When Jev fails or times out, or when there is no key, the baseline tier
   serves the turn. After three failures in a row, new turns skip Jev for one
   minute and then try it once, so an outage costs one slow turn a minute, not
@@ -64,12 +71,19 @@ The gateway sends the real model id unchanged.
 ## See the current route
 
 `/router:status` shows the gateway, the routes, and the model, effort and
-reason of the last turn in this session.
+reason of the last turn in this session. It also says why in words, and for
+a vote it shows the estimate: the probability mass, the bar it had to reach,
+the switching tax and whether each cache was `warm`, `expired` or `unknown`.
+`unknown` means no response for that cache since the session started or the
+conversation got shorter. The dollars are list prices. For plan models they
+are a list-price equivalent, not a charge.
 
 The status line wrapper from `/router:setup` adds one line to your status line
 while the session uses the router:
 
-- `jev-router ▸ opus-5-5 · xhigh`: the model and the effort of the last turn.
+- `jev-router ▸ opus-5-5 · xhigh · upgrade`: the model, the effort and the
+  reason of the last turn. `upgrade-pending` means that Jev asked for a higher
+  tier and the policy held the route back.
 - `router: no turn yet`: the session has no routed turn.
 - `router: gateway off, the next prompt starts it`: the gateway stopped after
   idle time, or it crashed. Either way the next prompt starts it.
@@ -84,7 +98,7 @@ the plugin data directory. The directory is
 by hand, the directory is `$TMPDIR/router/`.
 
 ```sh
-tail -n 20 ~/.claude/plugins/data/router-*/decisions.jsonl | jq -c '{tier, reason, estimate, observed}'
+tail -n 20 ~/.claude/plugins/data/router-*/decisions.jsonl | jq -c '{tier, reason, estimate, shadow, observed}'
 ```
 
 `tier` is the selected tier. `reason` is the rule that decided. The `observed`
@@ -92,6 +106,12 @@ lines carry the model that answered, the context tokens and the cache reads
 from the response. Compare the estimated and the observed cache reads to tune
 the thresholds.
 
+`shadow` is what following Jev's choice instead of the current route would
+cost, at list prices: the next turn, each later turn, and the number of turns
+until a cheaper route repays its cache write. The policy does not read it.
+`historyBreak` lines mark a compaction or a rewind; `cacheReset` lines mark a
+context that shrank by more than a fifth.
+
 `scripts/transcript-models.sh <transcript.jsonl>` shows the model for each
 assistant message in a Claude Code transcript.
 
@@ -115,3 +135,6 @@ assistant message in a Claude Code transcript.
 - Rate limits and overload errors from Anthropic (429, 529) reach Claude Code
   unchanged. Claude Code waits and retries; the gateway does not add a second
   layer of retries.
+- Updating from 0.3.0 or earlier: those gateways cannot hand over to a newer
+  one. Stop the old one once with `pkill -f scripts/gateway.mjs`; the next
+  prompt starts the new version.

package/lib/config.mjs

@@ -20,12 +20,14 @@ export const DEFAULTS = {
     micro: { model: 'haiku' },
   },
   // `id` is sent upstream verbatim. List prices in USD per million tokens; `cacheRead` is absolute,
-  // not a multiplier (Opus 5.5 reads at 0.05x input, the rest at the standard 0.1x — verify when prices move).
+  // not a multiplier (Opus 5.5 reads at 0.05x input, the rest at the standard 0.1x). A price change must also change
+  // test/fixtures/list-prices.json, with its source and date. `output` feeds only the shadow estimate in the log.
   // `efforts` lists what the model accepts; an empty list means no effort field and no adaptive thinking.
   models: {
     opus: {
       id: 'claude-opus-5-5',
       input: 4,
+      output: 20,
       cacheRead: 0.2,
       contextWindow: 1_000_000,
       billing: 'plan',
@@ -34,6 +36,7 @@ export const DEFAULTS = {
     sonnet: {
       id: 'claude-sonnet-5',
       input: 2,
+      output: 10,
       cacheRead: 0.2,
       contextWindow: 1_000_000,
       billing: 'plan',
@@ -43,6 +46,7 @@ export const DEFAULTS = {
     haiku: {
       id: 'claude-haiku-4-5',
       input: 1,
+      output: 5,
       cacheRead: 0.1,
       contextWindow: 200_000,
       maxOutput: 64_000,
@@ -116,6 +120,8 @@ function validate(config) {
       if (!Number.isFinite(model[field]) || model[field] < 0)
         throw new Error(`models.${alias}.${field} must be a non-negative number`);
     }
+    if (model.output !== undefined && !(Number.isFinite(model.output) && model.output >= 0))
+      throw new Error(`models.${alias}.output must be a non-negative number`);
     if (typeof model.id !== 'string' || !model.id) throw new Error(`models.${alias}.id is required`);
     if (model.maxOutput !== undefined && !(Number.isInteger(model.maxOutput) && model.maxOutput > 0))
       throw new Error(`models.${alias}.maxOutput must be a positive integer`);

package/lib/cost.mjs

@@ -1,22 +1,46 @@
-// Cache-aware input cost of the next request. Pure arithmetic over configured prices and the gateway's memory.
+// Cache-aware cost of the next request. Pure arithmetic over configured prices and the gateway's memory.
+import { clampEffort } from './rewrite.mjs';
+
+// The prompt cache belongs to a model, and its messages part to the effort too: a top-level effort change rewrites
+// the messages cache. Opus at `high` and Opus at `xhigh` are two caches, not one.
+export function cacheKey(modelId, effort) {
+  return effort ? `${modelId}@${effort}` : modelId;
+}
+
+// The cache a request routed to `tier` uses. `sentEffort` is what Claude Code sent, for a route that keeps it.
+export function routeCacheKey(config, tier, sentEffort) {
+  const model = modelOf(config, tier);
+  return cacheKey(model.id, clampEffort(config.routes[tier].effort ?? sentEffort, model.efforts));
+}
 
 export function isWarm(modelState, now, cache) {
   if (!modelState) return false;
   return now < modelState.lastAt + cache.ttlMs[modelState.ttl] - cache.warmMarginMs;
 }
 
+// For the logs: `unknown` means no response for this cache since the session started or its history broke. The cost
+// arithmetic treats `unknown` and `expired` alike, as a full write.
+export function cacheState(modelState, now, cache) {
+  if (!modelState) return 'unknown';
+  return isWarm(modelState, now, cache) ? 'warm' : 'expired';
+}
+
+function modelOf(config, tier) {
+  return config.models[config.routes[tier].model];
+}
+
 function ttlFor(config, alias, facts) {
   if (config.models[alias].billing === 'credits') return '5m';
   return facts.lastRequest?.ttl ?? '5m';
 }
 
-// USD for the input side of one request on `alias` with `tokens` of context.
-export function inputCostUsd(config, alias, tokens, facts, now) {
+// USD for the input side of one request routed to `tier` with `tokens` of context.
+export function inputCostUsd(config, tier, tokens, facts, now) {
+  const alias = config.routes[tier].model;
   const model = config.models[alias];
-  const state = facts.models[model.id];
+  const state = facts.models[routeCacheKey(config, tier, facts.effort)];
   const reusable = isWarm(state, now, config.cache) ? Math.min(state.prefixTokens, tokens) : 0;
-  const ttl = ttlFor(config, alias, facts);
-  const write = model.input * config.cache.writeMultiplier[ttl];
+  const write = model.input * config.cache.writeMultiplier[ttlFor(config, alias, facts)];
   return (model.cacheRead * reusable + write * (tokens - reusable)) / 1e6;
 }
 
@@ -31,9 +55,30 @@ export function nextContextTokens(facts) {
   return last ? last.tokens + last.outputTokens : 0;
 }
 
-export function switchingTaxUsd(config, candidateAlias, incumbentAlias, facts, now) {
+export function switchingTaxUsd(config, candidateTier, incumbentTier, facts, now) {
   const tokens = nextContextTokens(facts);
   return (
-    inputCostUsd(config, candidateAlias, tokens, facts, now) - inputCostUsd(config, incumbentAlias, tokens, facts, now)
+    inputCostUsd(config, candidateTier, tokens, facts, now) - inputCostUsd(config, incumbentTier, tokens, facts, now)
   );
 }
+
+// Shadow estimate for the decision log; the policy does not read it. At list prices, so for `plan` models it is a
+// list-price equivalent, not a charge. Output uses the last observed output size for both routes, although effort
+// changes how much a model writes.
+// - nextTurnUsd: candidate minus incumbent for the next request, input at the current cache state plus output.
+// - laterTurnUsd: the same difference for each later turn, once both caches are warm.
+// - paybackTurns: 0 when the switch is cheaper at once, n when later turns repay it after n turns, null when never.
+export function shadowEconomics(config, candidateTier, incumbentTier, facts, now) {
+  const candidate = modelOf(config, candidateTier);
+  const incumbent = modelOf(config, incumbentTier);
+  if (candidate.output === undefined || incumbent.output === undefined) return null;
+  const tokens = nextContextTokens(facts);
+  const outputTokens = facts.lastRequest?.outputTokens ?? 0;
+  const outputUsd = ((candidate.output - incumbent.output) * outputTokens) / 1e6;
+  const nextTurnUsd = switchingTaxUsd(config, candidateTier, incumbentTier, facts, now) + outputUsd;
+  const laterTurnUsd = ((candidate.cacheRead - incumbent.cacheRead) * tokens) / 1e6 + outputUsd;
+  let paybackTurns = null;
+  if (nextTurnUsd <= 0 && laterTurnUsd <= 0) paybackTurns = 0;
+  else if (nextTurnUsd > 0 && laterTurnUsd < 0) paybackTurns = Math.ceil(nextTurnUsd / -laterTurnUsd);
+  return { nextTurnUsd, laterTurnUsd, paybackTurns, outputTokens };
+}

package/lib/facts.mjs

@@ -32,6 +32,8 @@ export function factsFromRequest(body, memory, { recentTurns, maxTextChars }) {
     // The same history length and the same last message: Claude Code resent the request (429, 529, a dropped stream).
     turnKey: last?.role === 'user' ? `${messages.length}:${hash(JSON.stringify(last.content))}` : null,
     failure: repeatedFailure(errors, edits, messages.length - 1),
+    // The effort Claude Code sent: a route without its own effort keeps it, and it is part of the cache key.
+    effort: body.output_config?.effort ?? null,
     lastRoute: memory.lastRoute,
     lastRequest: memory.lastRequest,
     models: memory.models,

package/lib/gateway.mjs

@@ -63,10 +63,7 @@ export function createGateway({
         if (parsed && router.isRouted(parsed)) {
           if (turn) {
             try {
-              routed = await router.route(parsed, {
-                sessionId: session,
-                requestClass: req.headers['x-claude-code-request-class'] ?? null,
-              });
+              routed = await router.route(parsed, { sessionId: session, ...routingHints(req) });
             } catch (error) {
               onError(error);
               routed = router.fallback(parsed); // never forward the alias upstream
@@ -116,7 +113,7 @@ export function createGateway({
       if (reader.stopReason === 'tool_use') activity.turnPaused(session);
       if (!routed || routed.auxiliary) return;
       try {
-        router.recordResponse(session, routed.tier, usage);
+        router.recordResponse(session, routed.tier, usage, routed.effort);
       } catch (recordError) {
         onError(recordError);
       }
@@ -130,8 +127,15 @@ export function createGateway({
   }
 }
 
-// Claude Code sends its session id as a header; the metadata field is the fallback.
+// Claude Code sends its session id as a header; the metadata field is the fallback. A subagent's requests carry
+// its agent id too: it gets its own routing memory, so its turns do not mix with the main conversation's.
 export function sessionKey(req, body) {
+  const agent = req.headers['x-claude-code-agent-id'];
+  const session = sessionOf(req, body);
+  return agent ? `${session}.${agent}` : session;
+}
+
+function sessionOf(req, body) {
   const header = req.headers['x-claude-code-session-id'];
   if (header) return String(header);
   try {
@@ -141,6 +145,15 @@ export function sessionKey(req, body) {
   }
 }
 
+// Gateway hint headers, sent when CLAUDE_CODE_GATEWAY_HINT_HEADERS=1. Without them the router falls back to the body.
+function routingHints(req) {
+  return {
+    requestClass: req.headers['x-claude-code-request-class'] ?? null,
+    agentType: req.headers['x-claude-code-agent-type'] ?? null,
+    contextCompacted: req.headers['x-claude-code-context-compacted'] ?? null,
+  };
+}
+
 // A web page can reach a loopback port too: by DNS rebinding (a foreign Host) or by a cross-site request (a foreign
 // Origin). Claude Code sends a loopback Host and no Origin.
 function isLocalClient(req) {

package/lib/policy.mjs

@@ -1,6 +1,6 @@
-// Switching policy v0 (docs/design.md): stickiness, escalation floor, cost-gated votes.
+// Switching policy v0 (docs/architecture.md): stickiness, escalation floor, cost-gated votes.
 import { rank, TIERS } from './config.mjs';
-import { coldWriteUsd, isWarm, nextContextTokens, switchingTaxUsd } from './cost.mjs';
+import { cacheState, coldWriteUsd, isWarm, nextContextTokens, routeCacheKey, switchingTaxUsd } from './cost.mjs';
 
 export function initialState() {
   return { turn: 0, votes: [], holdUntilTurn: 0, escalatedSignature: null };
@@ -34,15 +34,13 @@ export function decide({ config, facts, advice, state, baseline, now }) {
       if (rank(gated.fallback) <= rank(incumbent)) return stay('cash-gate', gated.estimate);
       return result(gated.fallback, 'cash-gate', next, gated.estimate);
     }
-    const tax = Math.max(
-      0,
-      switchingTaxUsd(config, config.routes[choice].model, config.routes[incumbent].model, facts, now),
-    );
+    const tax = Math.max(0, switchingTaxUsd(config, choice, incumbent, facts, now));
     const threshold =
       config.policy.upgradeBase + config.policy.upgradeSlope * (tax / (tax + config.policy.upgradePivotUsd));
     const jump = rank(choice) - rank(incumbent) >= 2 && upgrade >= config.policy.jumpConfidence;
     const streak = trailing(next.votes, (v) => rank(v.tier) > rank(incumbent));
-    const estimate = { taxUsd: tax, threshold, upgradeMass: upgrade, streak };
+    const cache = { candidate: cacheOf(config, choice, facts, now), incumbent: cacheOf(config, incumbent, facts, now) };
+    const estimate = { taxUsd: tax, threshold, upgradeMass: upgrade, streak, cache };
     if (jump || (streak >= config.policy.upgradeVotes && upgrade >= threshold))
       return result(choice, jump ? 'jump' : 'upgrade', next, estimate);
     return stay('upgrade-pending', estimate);
@@ -73,16 +71,22 @@ export function fitTier(config, tier, tokens) {
   );
 }
 
-// Automatic routing to a credits-billed model must fit the cash cap unless its cache is warm.
+// Cold-write guard: an automatic route to a credits-billed model whose cache is not warm must not start with a cache
+// write above `cashCapUsd`. It bounds that one estimated write, not the spend of the turn: a warm cache passes, and
+// output is not counted.
 function cashGate(config, tier, facts, now) {
   const alias = config.routes[tier].model;
-  const model = config.models[alias];
-  if (model.billing !== 'credits') return { blocked: false };
-  if (isWarm(facts.models[model.id], now, config.cache)) return { blocked: false };
+  if (config.models[alias].billing !== 'credits') return { blocked: false };
+  if (isWarm(facts.models[routeCacheKey(config, tier, facts.effort)], now, config.cache)) return { blocked: false };
   const cold = coldWriteUsd(config, alias, nextContextTokens(facts), facts);
   if (cold <= config.policy.cashCapUsd) return { blocked: false };
   const fallback = [...TIERS].reverse().find((t) => config.models[config.routes[t].model].billing === 'plan');
-  return { blocked: true, fallback, estimate: { coldUsd: cold, cap: config.policy.cashCapUsd } };
+  const estimate = { coldUsd: cold, cap: config.policy.cashCapUsd, cache: cacheOf(config, tier, facts, now) };
+  return { blocked: true, fallback, estimate };
+}
+
+function cacheOf(config, tier, facts, now) {
+  return cacheState(facts.models[routeCacheKey(config, tier, facts.effort)], now, config.cache);
 }
 
 function trailing(votes, predicate) {

package/lib/router.mjs

@@ -1,6 +1,6 @@
 // Per-request orchestration: facts -> advice -> policy -> rewritten body. Knows nothing about HTTP.
-import { LEGACY_ALIAS } from './config.mjs';
-import { nextContextTokens } from './cost.mjs';
+import { LEGACY_ALIAS, TIERS } from './config.mjs';
+import { cacheKey, nextContextTokens, shadowEconomics } from './cost.mjs';
 import { factsFromRequest } from './facts.mjs';
 import { askJev } from './jev.mjs';
 import { decide, fitTier, initialState } from './policy.mjs';
@@ -13,19 +13,30 @@ export const JEV_FAILURES_TO_PAUSE = 3;
 export const JEV_PAUSE_MS = 60_000;
 // Reasons that reuse the route of the turn and must not replace the reason that chose it.
 const REUSED_ROUTE = new Set(['tool-continuation', 'retry']);
+// `x-claude-code-request-class` values that are side requests. `main`, `subagent` and `workflow` carry a conversation.
+const SIDE_REQUEST_CLASSES = new Set(['auxiliary', 'compaction']);
 
 export function emptyMemory() {
   return {
     lastRoute: null,
     lastReason: null,
+    lastEstimate: null,
     lastEffort: null,
     lastRequest: null,
     lastTurnKey: null,
+    lastMessageCount: null,
     models: {},
     state: null,
   };
 }
 
+// The history the gateway saw is gone: a compaction or a rewind. The cached prefixes are unknown, and the votes and
+// the escalation hold were about turns that are no longer in it. The route stays until the next decision.
+function restartHistory(memory) {
+  memory.models = {};
+  if (memory.state) memory.state = { ...memory.state, votes: [], holdUntilTurn: 0, escalatedSignature: null };
+}
+
 export class Router {
   constructor({ config, fetchFn, dataDir, now = Date.now, onError = () => {} }) {
     this.config = config;
@@ -44,10 +55,19 @@ export class Router {
 
   // Returns { body, tier, reason, auxiliary }. The caller forwards `body` and records the response
   // usage only when `auxiliary` is false: side requests carry their own context sizes.
-  async route(body, { sessionId, requestClass }) {
+  // The hints come from Claude Code's gateway headers (CLAUDE_CODE_GATEWAY_HINT_HEADERS=1); each may be missing.
+  async route(body, { sessionId, requestClass = null, agentType = null, contextCompacted = null }) {
     const memory = this.memory(sessionId);
+    const auxiliary = requestClass ? SIDE_REQUEST_CLASSES.has(requestClass) : isAuxiliaryShape(body);
+    // Messages only grow within one history. Fewer than the last main request: Claude Code compacted the conversation
+    // or the user rewound it. Context editing clears tool results but keeps the messages, so it is not a break.
+    const messageCount = Array.isArray(body.messages) ? body.messages.length : 0;
+    const rewound = !auxiliary && memory.lastMessageCount !== null && messageCount < memory.lastMessageCount;
+    if (contextCompacted || rewound) {
+      restartHistory(memory);
+      this.log({ session: sessionId, historyBreak: contextCompacted ? 'compaction' : 'shorter-history' });
+    }
     const facts = factsFromRequest(body, memory, this.config.context);
-    const auxiliary = requestClass ? requestClass !== 'main' : isAuxiliaryShape(body);
     let decision;
     if (auxiliary) decision = { tier: this.config.gateway.auxiliaryTier, reason: 'auxiliary', state: memory.state };
     else if (facts.continuation && memory.lastRoute)
@@ -61,20 +81,27 @@ export class Router {
       if (tier !== decision.tier) decision = { ...decision, tier, reason: 'context-fit' };
     }
     const rewritten = rewriteRequest(body, decision.tier, this.config);
+    const effort = rewritten.output_config?.effort ?? null;
     if (!auxiliary) {
       memory.lastRoute = decision.tier;
-      memory.lastEffort = rewritten.output_config?.effort ?? null;
+      memory.lastEffort = effort;
       memory.lastTurnKey = facts.turnKey;
-      if (!REUSED_ROUTE.has(decision.reason)) memory.lastReason = decision.reason;
+      memory.lastMessageCount = messageCount;
+      if (!REUSED_ROUTE.has(decision.reason)) {
+        memory.lastReason = decision.reason;
+        memory.lastEstimate = decision.estimate ?? null;
+      }
       memory.state = decision.state;
       this.persist(sessionId, memory);
     }
     this.log({
       session: sessionId,
       requestClass,
+      agentType,
       tier: decision.tier,
       reason: decision.reason,
       estimate: decision.estimate ?? null,
+      shadow: decision.shadow ?? null,
       advice: decision.advice ?? null,
       adviceError: decision.adviceError ?? null,
       contextTokens: memory.lastRequest?.tokens ?? 0,
@@ -82,6 +109,7 @@ export class Router {
     return {
       body: rewritten,
       tier: decision.tier,
+      effort,
       reason: decision.reason,
       auxiliary,
     };
@@ -124,15 +152,15 @@ export class Router {
         }
       }
     }
-    const decision = decide({
-      config: this.config,
-      facts,
-      advice,
-      state,
-      baseline: gateway.baselineTier,
-      now: this.now(),
-    });
-    return { ...decision, advice, adviceError };
+    const now = this.now();
+    const decision = decide({ config: this.config, facts, advice, state, baseline: gateway.baselineTier, now });
+    // Shadow only: what following Jev's choice instead of staying would cost at list prices. The policy ignores it.
+    const incumbent = TIERS.includes(facts.lastRoute) ? facts.lastRoute : gateway.baselineTier;
+    const shadow =
+      TIERS.includes(advice?.choice) && advice.choice !== incumbent
+        ? shadowEconomics(this.config, advice.choice, incumbent, facts, now)
+        : null;
+    return { ...decision, advice, adviceError, shadow };
   }
 
   jevSucceeded() {
@@ -154,14 +182,19 @@ export class Router {
       );
   }
 
-  // Called with the usage the gateway read from a forwarded main-conversation response.
-  recordResponse(sessionId, tier, usage) {
+  // Called with the usage the gateway read from a forwarded main-conversation response, and the effort the gateway
+  // sent with that request: the cache is keyed by both.
+  recordResponse(sessionId, tier, usage, effort = null) {
     if (!usage) return;
     const memory = this.memory(sessionId);
     const modelId = usage.model ?? this.config.models[this.config.routes[tier].model].id;
     const at = this.now();
-    // A context that shrank is a compaction: every model's cached prefix is gone.
-    if (memory.lastRequest && usage.tokens < memory.lastRequest.tokens * COMPACTION_SHRINK) memory.models = {};
+    // A context that shrank by more than a fifth: a compaction, or context editing that cleared old tool results.
+    // Either way the cached prefixes no longer match. The votes stay: a shorter history in messages resets them.
+    if (memory.lastRequest && usage.tokens < memory.lastRequest.tokens * COMPACTION_SHRINK) {
+      memory.models = {};
+      this.log({ session: sessionId, cacheReset: 'context-shrink' });
+    }
     memory.lastRequest = {
       model: modelId,
       tokens: usage.tokens,
@@ -170,7 +203,11 @@ export class Router {
       ttl: usage.ttl,
       at,
     };
-    memory.models[modelId] = { lastAt: at, prefixTokens: usage.tokens + usage.outputTokens, ttl: usage.ttl };
+    memory.models[cacheKey(modelId, effort)] = {
+      lastAt: at,
+      prefixTokens: usage.tokens + usage.outputTokens,
+      ttl: usage.ttl,
+    };
     this.persist(sessionId, memory);
     this.log({ session: sessionId, observed: { ...usage, model: modelId, tier } });
   }

package/lib/status.mjs

@@ -34,6 +34,7 @@ export function statusSnapshot(config, memory) {
       ? {
           tier: memory.lastRoute,
           reason: memory.lastReason ?? null,
+          estimate: memory.lastEstimate ?? null,
           effort: memory.lastEffort ?? null,
           model: memory.lastRequest?.model ?? null,
           tokens: memory.lastRequest?.tokens ?? null,
@@ -51,14 +52,32 @@ function routeRow(config, tier) {
   return { tier, model: model.id, effort };
 }
 
-// One status-line segment, e.g. "router ▸ opus-5-5 · xhigh".
+// Why the route of the last turn is what it is, for /router:status.
+const REASONS = {
+  upgrade: 'Jev voted above the current tier often enough, with enough mass for the switching tax',
+  jump: 'Jev was confident enough to skip a tier and the vote delay',
+  downgrade: 'Jev voted for a lower tier often enough, with enough mass',
+  'upgrade-pending': 'Jev asked for a higher tier; the route stays until the votes and the mass are enough',
+  'downgrade-pending': 'Jev asked for a lower tier; the route stays until the votes and the mass are enough',
+  'same-tier': 'Jev agreed with the current tier',
+  continuation: 'the prompt continues the task, so the route stays',
+  uncertain: 'Jev abstained, so the route stays',
+  'no-advice': 'no Jev answer (no key, a failure or a pause), so the route stays',
+  escalation: 'the same error came back after an edit: one tier up',
+  hold: 'the tier stays up for a few turns after an escalation',
+  'cash-gate':
+    'cold-write guard: the first cache write on a credits model would cost more than policy.cashCapUsd, so the strongest plan tier served',
+  'context-fit': "the chosen model's window does not hold the context",
+  forced: 'ROUTER_FORCE_TIER is set',
+};
+
+// One status-line segment, e.g. "router ▸ opus-5-5 · xhigh · upgrade".
 export function statusSegment(status) {
   if (!status) return 'router: gateway off, the next prompt starts it';
   const last = status.session;
   if (!last) return `${status.alias}: no turn yet`;
   const model = shortModel(last.model ?? status.routes.find((r) => r.tier === last.tier)?.model);
-  const effort = last.effort ? ` · ${last.effort}` : '';
-  return `${status.alias} ▸ ${model}${effort}`;
+  return [`${status.alias} ▸ ${model}`, last.effort, last.reason].filter(Boolean).join(' · ');
 }
 
 // Markdown for /router:status.
@@ -82,10 +101,32 @@ export function statusReport(status) {
     const effort = last.effort ? ` at ${last.effort}` : '';
     const context = last.tokens ? `, context ${last.tokens} tokens, cache reads ${last.cacheReadTokens}` : '';
     lines.push(`Last turn: ${last.tier} → ${model}${effort}, reason ${last.reason ?? 'unknown'}${context}.`);
+    if (REASONS[last.reason]) lines.push(`Why: ${REASONS[last.reason]}.`);
+    const estimate = describeEstimate(last.estimate);
+    if (estimate) lines.push(`Estimate: ${estimate}.`);
   }
   return lines.join('\n');
 }
 
+// Dollars are list prices: for `plan` models a list-price equivalent, not a charge. `unknown` cache: no response for
+// that cache since the session started or its history broke.
+function describeEstimate(e) {
+  if (!e) return null;
+  const usd = (n) => `$${n.toFixed(2)}`;
+  const parts = [];
+  if (e.upgradeMass !== undefined)
+    parts.push(
+      `upgrade mass ${e.upgradeMass.toFixed(2)} against a bar of ${e.threshold.toFixed(2)}`,
+      `switching tax ${usd(e.taxUsd)} at list prices`,
+    );
+  if (e.downgradeMass !== undefined) parts.push(`downgrade mass ${e.downgradeMass.toFixed(2)}`);
+  if (e.coldUsd !== undefined) parts.push(`cold write ${usd(e.coldUsd)} against the cap of ${usd(e.cap)}`);
+  if (e.streak !== undefined) parts.push(`${e.streak} vote(s) in a row`);
+  if (e.cache?.candidate) parts.push(`cache: candidate ${e.cache.candidate}, current ${e.cache.incumbent}`);
+  else if (typeof e.cache === 'string') parts.push(`cache ${e.cache}`);
+  return parts.join(', ');
+}
+
 // null when the gateway does not answer in time.
 export async function fetchStatus(port, sessionId) {
   const query = sessionId ? `?session=${encodeURIComponent(sessionId)}` : '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexeiled/claude-router",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "Claude Code plugin: auto-picks the right model and effort for each turn using Jev routing.",
   "license": "MIT",
   "author": "Alexei Ledenev",

package/skills/setup/SKILL.md

@@ -13,6 +13,7 @@ Configure Claude Code for the router gateway. This session does not use the gate
    - `model`: `"jev-router[1m]"`. Claude Code does not know the model `jev-router` and assumes a 200K window; the `[1m]` suffix declares 1M. Claude Code strips the suffix before it sends the request. If `router.json` routes no model with a 1M `contextWindow`, use `"jev-router"`.
    - `env.ANTHROPIC_BASE_URL`: `"http://127.0.0.1:43170"`. If `router.json` sets `gateway.port`, use that port.
    - `env.ENABLE_TOOL_SEARCH`: `"true"`. With a custom `ANTHROPIC_BASE_URL`, Claude Code turns tool search off and loads every MCP tool schema into each request (about 50K tokens with the claude.ai connectors). This key keeps the schemas deferred, as with the Anthropic API.
+   - `env.CLAUDE_CODE_GATEWAY_HINT_HEADERS`: `"1"`. Claude Code then tells the gateway the class of each request (main turn, subagent, side request, compaction) instead of the gateway guessing it from the body.
    - Remove `env.CLAUDE_CODE_MAX_CONTEXT_TOKENS`. Older versions of this setup wrote it; Claude Code ignores it for `jev-router`. The gateway sends a turn only to a model whose window holds the context, and drops the 1M beta header for a model with a smaller window.
    - The `/model` picker row. In `modelPicker.options`, replace the row whose `model` is `"jev-router[1m]"`, `"jev-router"` or `"router"` (the name before 0.4.2), or append it if there is none:
      `{ "model": "jev-router[1m]", "label": "Jev Router (auto)", "description": "Auto-selects the model and effort for each turn", "behavesAs": "claude-opus-5-5" }`.
@@ -24,7 +25,7 @@ Configure Claude Code for the router gateway. This session does not use the gate
    - Restart Claude Code now. Until the restart, this session can show "There's an issue with the selected model (jev-router[1m])", because it still sends requests to Anthropic and not to the gateway.
    - After the restart, the router serves each turn, and `/router:status` shows the routes and the last turn.
    - The status line path contains the plugin version. After a plugin update, run `/router:setup` again.
-   - To stop the routing, remove `model`, `env.ANTHROPIC_BASE_URL`, `env.ENABLE_TOOL_SEARCH` and the `jev-router[1m]` row of `modelPicker.options`, and restore the status line command.
+   - To stop the routing, remove `model`, `env.ANTHROPIC_BASE_URL`, `env.ENABLE_TOOL_SEARCH`, `env.CLAUDE_CODE_GATEWAY_HINT_HEADERS` and the `jev-router[1m]` row of `modelPicker.options`, and restore the status line command.
 5. Write the whole object to `~/.claude/settings.json` with one Write call. Do not use a sequence of edits. Do nothing after this step.
 
 Do not change any other file.