@alexeiled/claude-router 0.5.0 → 0.6.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "router",
   "displayName": "jev-router",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "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

@@ -31,7 +31,8 @@ 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
+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.
 

package/docs/configuration.md

@@ -22,7 +22,9 @@ starts it again.
 {
   "model": "jev-router[1m]",
   "env": {
-    "ANTHROPIC_BASE_URL": "http://127.0.0.1:43170"
+    "ANTHROPIC_BASE_URL": "http://127.0.0.1:43170",
+    "ENABLE_TOOL_SEARCH": "true",
+    "CLAUDE_CODE_GATEWAY_HINT_HEADERS": "1"
   },
   "modelPicker": {
     "options": [
@@ -37,6 +39,11 @@ starts it again.
 }
 ```
 
+With a custom `ANTHROPIC_BASE_URL`, Claude Code turns tool search off: every
+MCP tool schema goes into each request, about 50K tokens with the claude.ai
+connectors. `ENABLE_TOOL_SEARCH` keeps the schemas deferred, as with the
+Anthropic API; `/context` lists them as "MCP tools (deferred)".
+
 The `modelPicker` row adds `Jev Router (auto)` to the `/model` picker, next to the
 built-in rows. `behavesAs` maps `jev-router` to a model that Claude Code knows.
 Without it, Claude Code rejects `jev-router` because the model is not in its
@@ -74,14 +81,23 @@ session, for example `jev-router ▸ opus-5-5 · xhigh`. 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:
+
+- `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.
+- `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 and
+a compaction by a context that shrank by more than 20%.
 
-- `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.
+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
 

package/docs/design.md

@@ -73,10 +73,12 @@ account.
 
 - 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
@@ -130,7 +132,7 @@ transcripts.
 | 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). |
+| Reusable prefix of a model                       | The context plus the output at the last response of that model. Cleared by `x-claude-code-context-compacted`, or 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".           |
 
@@ -229,8 +231,9 @@ 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 and compactions from the body; the guesses miss some.
+- `x-claude-code-agent-type` is logged, not used: no policy rule reads it yet.
 
 ## Release
 

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
@@ -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/router.mjs

@@ -13,6 +13,8 @@ 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 {
@@ -44,10 +46,13 @@ 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);
+    // The compaction rewrote the conversation: no model has its prefix cached any more.
+    if (contextCompacted) memory.models = {};
     const facts = factsFromRequest(body, memory, this.config.context);
-    const auxiliary = requestClass ? requestClass !== 'main' : isAuxiliaryShape(body);
+    const auxiliary = requestClass ? SIDE_REQUEST_CLASSES.has(requestClass) : isAuxiliaryShape(body);
     let decision;
     if (auxiliary) decision = { tier: this.config.gateway.auxiliaryTier, reason: 'auxiliary', state: memory.state };
     else if (facts.continuation && memory.lastRoute)
@@ -72,6 +77,7 @@ export class Router {
     this.log({
       session: sessionId,
       requestClass,
+      agentType,
       tier: decision.tier,
       reason: decision.reason,
       estimate: decision.estimate ?? null,
@@ -160,7 +166,8 @@ export class Router {
     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.
+    // A context that shrank is a compaction: every model's cached prefix is gone. Without the hint headers this is
+    // the only sign of a compaction.
     if (memory.lastRequest && usage.tokens < memory.lastRequest.tokens * COMPACTION_SHRINK) memory.models = {};
     memory.lastRequest = {
       model: modelId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexeiled/claude-router",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "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

@@ -1,6 +1,6 @@
 ---
 name: setup
-description: Point Claude Code at the router gateway. Adds `model` with the 1M window, `ANTHROPIC_BASE_URL` and the `/model` picker row to the user settings, and offers the status line.
+description: Point Claude Code at the router gateway. Adds `model` with the 1M window, `ANTHROPIC_BASE_URL`, tool search and the `/model` picker row to the user settings, and offers the status line.
 disable-model-invocation: true
 allowed-tools: Read, Edit, Write
 ---
@@ -12,6 +12,8 @@ Configure Claude Code for the router gateway. This session does not use the gate
 3. Prepare the new settings object in memory:
    - `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" }`.
@@ -23,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` 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.