coderouter-cli 2.17.0__py3-none-any.whl → 2.19.0__py3-none-any.whl

coderouter/adapters/anthropic_native.py

@@ -46,6 +46,7 @@ from coderouter.adapters.base import (
     StreamChunk,
     StreamTruncatedError,
 )
+from coderouter.adapters.slot_affinity import apply_slot_affinity
 from coderouter.credentials import resolve_provider_credential
 from coderouter.logging import (
     get_logger,
@@ -243,6 +244,9 @@ class AnthropicAdapter(BaseAdapter):
         body.update(dumped)
         body["model"] = self.config.model
         body["stream"] = stream
+        apply_slot_affinity(
+            body, slots=self.config.slot_affinity_slots, key=req.session_key
+        )
         return body
 
     # ------------------------------------------------------------------

coderouter/adapters/base.py

@@ -65,6 +65,9 @@ class ChatRequest(BaseModel):
 
     # CodeRouter-specific extension (not sent upstream)
     profile: str | None = Field(default=None, exclude=True)
+    # v2.18.0: conversation key for KV-slot affinity (see
+    # ``ProviderConfig.slot_affinity_slots``). Never serialized.
+    session_key: str | None = Field(default=None, exclude=True)
 
 
 class ChatResponse(BaseModel):

coderouter/adapters/openai_compat.py

@@ -30,6 +30,7 @@ from coderouter.adapters.base import (
     StreamChunk,
     StreamTruncatedError,
 )
+from coderouter.adapters.slot_affinity import apply_slot_affinity
 from coderouter.credentials import resolve_provider_credential
 from coderouter.logging import (
     get_logger,
@@ -182,6 +183,11 @@ class OpenAICompatAdapter(BaseAdapter):
             value = getattr(request, field, None)
             if value is not None:
                 body[field] = value
+        apply_slot_affinity(
+            body,
+            slots=self.config.slot_affinity_slots,
+            key=getattr(request, "session_key", None),
+        )
         if stream:
             # Request a terminal usage chunk. Providers that honor this
             # (OpenAI, OpenRouter, Ollama >=0.x) will send one extra chunk

coderouter/adapters/slot_affinity.py

@@ -0,0 +1,54 @@
+"""v2.18.0: KV-slot affinity for llama-server (``id_slot``).
+
+llama-server started with ``--parallel N`` serves N slots, each holding its
+own prompt cache. Without a hint it picks a free slot, so consecutive turns
+of one conversation can land on different slots and re-prefill the whole
+prompt. Sending ``id_slot`` pins a conversation to one slot.
+
+The slot is ``sha256(key) % N`` — stable across processes and restarts
+(Python's ``hash`` is salted per process).
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Mapping
+from typing import Any
+
+# Request classes whose prompt shares the main conversation's prefix: they
+# belong on the main conversation's slot. Everything else (sub-agents,
+# auxiliary calls such as the auto-mode classifier or titles, workflows) has
+# its own prompt and gets its own key, so it neither waits on the main slot
+# nor evicts its cache.
+_MAIN_CLASSES = frozenset({"", "main", "compaction"})
+
+
+def affinity_key(hints: Mapping[str, str]) -> str | None:
+    """Conversation key for slot affinity, from Claude Code's hint headers.
+
+    ``None`` when there is no session id. ``main`` / ``compaction`` (and a
+    missing class) share ``<session>``; other classes get
+    ``<session>:<class>:<agent_type>``.
+    """
+    session = hints.get("session_id")
+    if not session:
+        return None
+    request_class = hints.get("request_class", "").lower()
+    if request_class in _MAIN_CLASSES:
+        return session
+    return f"{session}:{request_class}:{hints.get('agent_type', '').lower()}"
+
+
+def slot_for(key: str, slots: int) -> int:
+    digest = hashlib.sha256(key.encode("utf-8")).digest()
+    return int.from_bytes(digest[:8], "big") % slots
+
+
+def apply_slot_affinity(body: dict[str, Any], *, slots: int | None, key: str | None) -> None:
+    """Set ``body["id_slot"]`` when affinity is configured and a key exists.
+
+    An ``id_slot`` already present (e.g. from ``extra_body``) wins.
+    """
+    if not slots or not key or "id_slot" in body:
+        return
+    body["id_slot"] = slot_for(key, slots)

coderouter/cli.py

@@ -483,7 +483,8 @@ def _build_parser() -> argparse.ArgumentParser:
         help=(
             "v2.16.0: do not write the Claude Code gateway settings "
             "(ENABLE_TOOL_SEARCH=false, CLAUDE_CODE_AUTO_MODE_SERVER=0, "
-            "and --max-context-tokens). Use when the chain is "
+            "CLAUDE_CODE_GATEWAY_HINT_HEADERS=1 and --max-context-tokens). "
+            "Use when the chain is "
             "api.anthropic.com only."
         ),
     )

coderouter/config/schemas.py

@@ -562,6 +562,23 @@ class ProviderConfig(BaseModel):
     # withholds those opening events from the client. ``None`` (default)
     # disables it. Typical use: a local llama-server still loading a model
     # or chewing through a long prompt while a cloud fallback could answer.
+    # v2.18.0: KV-slot affinity for llama-server started with
+    # ``--parallel N``. When set to N and the request carries a conversation
+    # key (Claude Code's ``x-claude-code-session-id`` hint header), the body
+    # gets ``id_slot = stable_hash(key) % N`` so every turn of a conversation
+    # lands on the same slot and reuses its prompt cache instead of
+    # re-prefilling on whichever slot is free. llama.cpp only (other servers
+    # ignore or reject ``id_slot``); ``None`` (default) sends nothing.
+    slot_affinity_slots: int | None = Field(
+        default=None,
+        ge=1,
+        le=256,
+        description=(
+            "v2.18.0: llama-server --parallel N. Pins each conversation to "
+            "slot hash(session) % N via id_slot so its KV cache is reused. "
+            "llama.cpp only. None disables."
+        ),
+    )
     ttft_timeout_s: float | None = Field(
         default=None,
         gt=0.0,
@@ -1639,6 +1656,21 @@ class RuleMatcher(BaseModel):
     # declares any tools); ``False`` is rejected by ``_exactly_one``
     # since a "no-tools" rule would shadow the default fall-through.
     has_tools: bool | None = None
+    # v2.18.0: Claude Code gateway hint headers. Claude Code 2.1.273+ sends
+    # these to a custom ANTHROPIC_BASE_URL when
+    # ``CLAUDE_CODE_GATEWAY_HINT_HEADERS=1`` is set (``coderouter
+    # vscode-init`` sets it). They say what a request *is* — something the
+    # body heuristics above can only guess:
+    #   * ``request_class`` — ``x-claude-code-request-class``: ``main`` /
+    #     ``subagent`` / ``workflow`` / ``compaction`` / ``auxiliary``
+    #     (auto-mode classifier, titles, …). Case-insensitive exact match.
+    #   * ``agent_type`` — ``x-claude-code-agent-type`` (e.g. ``Explore``),
+    #     case-insensitive exact match.
+    #   * ``compaction: True`` — ``x-claude-code-compaction`` is truthy.
+    # Without the headers these matchers simply never match.
+    request_class: str | None = None
+    agent_type: str | None = None
+    compaction: bool | None = None
 
     _MATCHER_FIELDS: tuple[str, ...] = (
         "has_image",
@@ -1649,12 +1681,15 @@ class RuleMatcher(BaseModel):
         "content_token_count_min",
         "has_tools",
         "cjk_ratio_min",
+        "request_class",
+        "agent_type",
+        "compaction",
     )
 
     # Boolean matcher fields carry meaning only at ``True`` — the runtime
     # evaluator uses ``is True`` — so a ``False`` value is a dead rule that
     # never matches. ``_exactly_one`` rejects it explicitly (see below).
-    _BOOL_MATCHER_FIELDS: tuple[str, ...] = ("has_image", "has_tools")
+    _BOOL_MATCHER_FIELDS: tuple[str, ...] = ("has_image", "has_tools", "compaction")
 
     @model_validator(mode="after")
     def _exactly_one(self) -> Self:

coderouter/doctor_claude_code.py

@@ -125,6 +125,18 @@ def check(version: Version | None, env: Mapping[str, str]) -> list[ClaudeCodeFin
             )
         )
 
+    if env.get("CLAUDE_CODE_GATEWAY_HINT_HEADERS", "").lower() in ("1", "true"):
+        out.append(ClaudeCodeFinding("ok", "CLAUDE_CODE_GATEWAY_HINT_HEADERS=1"))
+    else:
+        out.append(
+            ClaudeCodeFinding(
+                "info",
+                "CLAUDE_CODE_GATEWAY_HINT_HEADERS is not set: auto_router rules "
+                "on request_class / agent_type / compaction (v2.18.0) never "
+                "match without it.",
+            )
+        )
+
     if env.get("CLAUDE_CODE_AUTO_MODE_SERVER") == "0":
         out.append(ClaudeCodeFinding("ok", "CLAUDE_CODE_AUTO_MODE_SERVER=0"))
     else:

coderouter/ingress/anthropic_routes.py

@@ -31,6 +31,7 @@ from fastapi import APIRouter, Header, HTTPException, Request
 from fastapi.responses import JSONResponse, Response, StreamingResponse
 
 from coderouter.adapters.base import StreamTruncatedError
+from coderouter.adapters.slot_affinity import affinity_key
 from coderouter.guards.context_budget import ContextBudgetRejectError
 from coderouter.guards.tool_loop import ToolCountExceededError, ToolLoopBreakError
 from coderouter.ingress.anthropic_errors import (
@@ -49,7 +50,7 @@ from coderouter.routing import (
     MidStreamError,
     NoProvidersAvailableError,
 )
-from coderouter.routing.auto_router import RESERVED_PROFILE_NAME, classify
+from coderouter.routing.auto_router import RESERVED_PROFILE_NAME, classify, extract_gateway_hints
 from coderouter.routing.fallback_trace import (
     SSE_FALLBACK_EVENT,
     current_fallback_trace,
@@ -226,6 +227,11 @@ async def messages(
     if anthropic_beta:
         anth_req.anthropic_beta = anthropic_beta
 
+    # v2.18.0: Claude Code gateway hint headers — routing matchers below,
+    # and the conversation key for llama-server KV-slot affinity.
+    gateway_hints = extract_gateway_hints(request.headers)
+    anth_req.session_key = affinity_key(gateway_hints)
+
     # Profile selection — body field wins over header (same policy as OpenAI route).
     if anth_req.profile is None and x_coderouter_profile:
         anth_req.profile = x_coderouter_profile
@@ -253,7 +259,7 @@ async def messages(
     # AnthropicRequest), so both OpenAI and Anthropic ingress use the same
     # classifier without a shared request shim.
     if anth_req.profile is None and config.default_profile == RESERVED_PROFILE_NAME:
-        anth_req.profile = classify(payload, config)
+        anth_req.profile = classify(payload, config, gateway_hints)
 
     if anth_req.profile is not None:
         try:

coderouter/ingress/app.py

@@ -19,6 +19,7 @@ from coderouter.ingress.dashboard_routes import router as dashboard_router
 from coderouter.ingress.launcher_routes import router as launcher_router
 from coderouter.ingress.metrics_routes import router as metrics_router
 from coderouter.ingress.openai_routes import router as openai_router
+from coderouter.ingress.responses_routes import router as responses_router
 from coderouter.logging import configure_logging, get_logger
 from coderouter.metrics import install_collector
 from coderouter.plugins import discover_and_load
@@ -491,6 +492,8 @@ def create_app(config_path: str | None = None) -> FastAPI:
 
     app.include_router(openai_router, prefix="/v1", tags=["openai-compat"])
     app.include_router(anthropic_router, prefix="/v1", tags=["anthropic-compat"])
+    # v2.19.0: OpenAI Responses API (Codex CLI).
+    app.include_router(responses_router, prefix="/v1", tags=["openai-responses"])
     # v1.5-A: /metrics.json sits at the root (no /v1 prefix) — metrics are not
     # part of the OpenAI / Anthropic API surface, and Prometheus-style
     # endpoints conventionally live at the root in v1.5-B.

coderouter/ingress/openai_routes.py

@@ -32,9 +32,10 @@ from fastapi import APIRouter, Header, HTTPException, Request
 from fastapi.responses import JSONResponse, StreamingResponse
 
 from coderouter.adapters.base import ChatRequest
+from coderouter.adapters.slot_affinity import affinity_key
 from coderouter.logging import get_logger
 from coderouter.routing import FallbackEngine, NoProvidersAvailableError
-from coderouter.routing.auto_router import RESERVED_PROFILE_NAME, classify
+from coderouter.routing.auto_router import RESERVED_PROFILE_NAME, classify, extract_gateway_hints
 from coderouter.routing.fallback_trace import current_fallback_trace
 
 router = APIRouter()
@@ -199,6 +200,10 @@ async def chat_completions(
     except Exception as exc:  # pydantic.ValidationError, etc.
         raise HTTPException(status_code=422, detail=str(exc)) from exc
 
+    # v2.18.0: gateway hint headers (routing matchers + KV-slot affinity key).
+    gateway_hints = extract_gateway_hints(request.headers)
+    chat_req.session_key = affinity_key(gateway_hints)
+
     # Header-based override (body wins if both are set — see module docstring)
     if chat_req.profile is None and x_coderouter_profile:
         chat_req.profile = x_coderouter_profile
@@ -226,7 +231,7 @@ async def chat_completions(
     # When inactive, the engine still falls through to
     # ``config.default_profile`` on its own — same semantics as pre-v1.6.
     if chat_req.profile is None and config.default_profile == RESERVED_PROFILE_NAME:
-        chat_req.profile = classify(payload, config)
+        chat_req.profile = classify(payload, config, gateway_hints)
 
     # Validate profile exists before we kick off any upstream call
     if chat_req.profile is not None:

coderouter/ingress/responses_routes.py

@@ -0,0 +1,269 @@
+"""OpenAI Responses API route: ``POST /v1/responses`` (v2.19.0).
+
+Lets the OpenAI Codex CLI (Responses-only since 2026-02) use CodeRouter as a
+custom provider::
+
+    [model_providers.coderouter]
+    name = "CodeRouter"
+    base_url = "http://127.0.0.1:8088/v1"
+    wire_api = "responses"
+
+The request is translated to an Anthropic Messages request
+(:mod:`coderouter.translation.responses`) and run through the same fallback
+engine as ``/v1/messages`` — tool-call repair, guards, fallback and the
+v2.16.0 error mapping all apply. Profile selection mirrors the other
+routes: body ``profile`` > ``X-CodeRouter-Profile`` > ``X-CodeRouter-Mode``
+> auto router > default.
+
+Failures are reported the way Codex reads them:
+
+- before the response commits: an OpenAI-style error body with a real
+  HTTP status (400 non-retryable / 429 with ``Retry-After`` / 502);
+- a context overflow on a streaming request: ``response.failed`` with code
+  ``context_length_exceeded`` — the only overflow signal Codex recognizes
+  (an HTTP 400 is treated as a plain invalid request);
+- after the stream started: ``response.failed`` (``server_error``), then end
+  of stream, which Codex retries.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+from collections.abc import AsyncIterator
+
+from fastapi import APIRouter, Header, Request
+from fastapi.responses import JSONResponse, Response, StreamingResponse
+
+from coderouter.adapters.slot_affinity import affinity_key
+from coderouter.guards.context_budget import ContextBudgetRejectError
+from coderouter.guards.tool_loop import ToolCountExceededError, ToolLoopBreakError
+from coderouter.ingress.anthropic_errors import (
+    PROMPT_TOO_LONG_PREFIX,
+    AnthropicErrorResponse,
+    map_no_providers_error,
+)
+from coderouter.ingress.anthropic_routes import (
+    _DisconnectWatcher,
+    _resolve_stream_timeout_s,
+)
+from coderouter.logging import get_logger
+from coderouter.routing import FallbackEngine, MidStreamError, NoProvidersAvailableError
+from coderouter.routing.auto_router import (
+    RESERVED_PROFILE_NAME,
+    classify,
+    extract_gateway_hints,
+)
+from coderouter.translation import AnthropicStreamEvent
+from coderouter.translation.responses import (
+    ResponsesStreamTranslator,
+    anthropic_response_to_responses,
+    format_sse,
+    responses_to_anthropic,
+)
+
+router = APIRouter()
+logger = get_logger(__name__)
+
+_PROFILE_HEADER = "x-coderouter-profile"
+_MODE_HEADER = "x-coderouter-mode"
+
+_OPENAI_TYPE = {
+    "invalid_request_error": "invalid_request_error",
+    "request_too_large": "invalid_request_error",
+    "rate_limit_error": "rate_limit_error",
+    "timeout_error": "server_error",
+    "api_error": "server_error",
+}
+
+
+def _openai_error(
+    status: int,
+    message: str,
+    *,
+    etype: str,
+    code: str | None = None,
+    headers: dict[str, str] | None = None,
+) -> JSONResponse:
+    return JSONResponse(
+        status_code=status,
+        content={"error": {"message": message, "type": etype, "param": None, "code": code}},
+        headers=headers or None,
+    )
+
+
+def _is_overflow(mapped: AnthropicErrorResponse) -> bool:
+    return mapped.status_code == 400 and mapped.message.lower().startswith(PROMPT_TOO_LONG_PREFIX)
+
+
+def _mapped_to_http(mapped: AnthropicErrorResponse) -> JSONResponse:
+    code = None
+    if _is_overflow(mapped):
+        code = "context_length_exceeded"
+    elif mapped.status_code == 429:
+        code = "rate_limit_exceeded"
+    return _openai_error(
+        mapped.status_code,
+        mapped.message,
+        etype=_OPENAI_TYPE.get(mapped.error_type, "server_error"),
+        code=code,
+        headers=dict(mapped.headers),
+    )
+
+
+def _failed_stream(translator: ResponsesStreamTranslator, code: str, message: str) -> StreamingResponse:
+    async def gen() -> AsyncIterator[str]:
+        for ev in translator.start():
+            yield format_sse(ev)
+        for ev in translator.failed(code, message):
+            yield format_sse(ev)
+
+    return StreamingResponse(gen(), media_type="text/event-stream", headers={"Cache-Control": "no-cache"})
+
+
+@router.post("/responses", response_model=None)
+async def responses(
+    request: Request,
+    x_coderouter_profile: str | None = Header(default=None, alias=_PROFILE_HEADER),
+    x_coderouter_mode: str | None = Header(default=None, alias=_MODE_HEADER),
+) -> Response:
+    """OpenAI Responses API endpoint (streaming and non-streaming)."""
+    engine: FallbackEngine = request.app.state.engine
+    config = request.app.state.config
+
+    try:
+        body = await request.json()
+    except (json.JSONDecodeError, ValueError):
+        return _openai_error(400, "request body must be JSON", etype="invalid_request_error")
+    if not isinstance(body, dict):
+        return _openai_error(400, "request body must be a JSON object", etype="invalid_request_error")
+
+    try:
+        anth_req, tool_map = responses_to_anthropic(body)
+    except Exception as exc:  # pydantic ValidationError and shape errors
+        return _openai_error(400, f"could not translate request: {exc}", etype="invalid_request_error")
+
+    model = body.get("model") if isinstance(body.get("model"), str) else "coderouter"
+
+    # Conversation key for llama-server slot affinity: Claude-style hint
+    # headers when present, else Codex's own ``session-id`` header.
+    hints = extract_gateway_hints(request.headers)
+    anth_req.session_key = affinity_key(hints) or request.headers.get("session-id") or None
+
+    if anth_req.profile is None and x_coderouter_profile:
+        anth_req.profile = x_coderouter_profile
+    if anth_req.profile is None and x_coderouter_mode:
+        try:
+            anth_req.profile = config.resolve_mode(x_coderouter_mode)
+        except KeyError:
+            return _openai_error(
+                400, f"unknown mode {x_coderouter_mode!r}", etype="invalid_request_error"
+            )
+    if anth_req.profile is None and config.default_profile == RESERVED_PROFILE_NAME:
+        anth_req.profile = classify(anth_req.model_dump(), config, hints)
+    if anth_req.profile is not None:
+        try:
+            config.profile_by_name(anth_req.profile)
+        except KeyError:
+            return _openai_error(
+                400, f"unknown profile {anth_req.profile!r}", etype="invalid_request_error"
+            )
+
+    translator = ResponsesStreamTranslator(tool_map, model=model)
+
+    try:
+        anth_req, _ctx = engine.apply_context_budget(anth_req)
+    except ContextBudgetRejectError as exc:
+        if anth_req.stream:
+            return _failed_stream(translator, "context_length_exceeded", str(exc))
+        return _openai_error(400, str(exc), etype="invalid_request_error", code="context_length_exceeded")
+
+    if not anth_req.stream:
+        try:
+            resp = await engine.generate_anthropic(anth_req)
+        except NoProvidersAvailableError as exc:
+            return _mapped_to_http(map_no_providers_error(exc))
+        except ContextBudgetRejectError as exc:
+            return _openai_error(400, str(exc), etype="invalid_request_error", code="context_length_exceeded")
+        except (ToolLoopBreakError, ToolCountExceededError) as exc:
+            return _openai_error(400, str(exc), etype="invalid_request_error")
+        return JSONResponse(
+            anthropic_response_to_responses(resp.model_dump(exclude_none=True), tool_map, model=model)
+        )
+
+    # Streaming: pull the first engine event before committing, like
+    # /v1/messages (v2.16.0), so pre-content failures get a real status.
+    timeout_s = _resolve_stream_timeout_s(engine, anth_req.profile)
+    deadline = asyncio.get_running_loop().time() + timeout_s
+    source = engine.stream_anthropic(anth_req)
+    first: AnthropicStreamEvent | None = None
+    watcher = _DisconnectWatcher(request)
+    watcher.start()
+
+    async def _close() -> None:
+        with contextlib.suppress(Exception):
+            await source.aclose()  # type: ignore[attr-defined]
+
+    try:
+        async with asyncio.timeout_at(deadline) as scope:
+            first = await anext(source)
+    except StopAsyncIteration:
+        first = None
+    except NoProvidersAvailableError as exc:
+        await _close()
+        mapped = map_no_providers_error(exc)
+        if _is_overflow(mapped):
+            return _failed_stream(translator, "context_length_exceeded", mapped.message)
+        return _mapped_to_http(mapped)
+    except ContextBudgetRejectError as exc:
+        await _close()
+        return _failed_stream(translator, "context_length_exceeded", str(exc))
+    except (ToolLoopBreakError, ToolCountExceededError) as exc:
+        await _close()
+        return _openai_error(400, str(exc), etype="invalid_request_error")
+    except MidStreamError as exc:
+        await _close()
+        return _failed_stream(translator, "server_error", str(exc))
+    except TimeoutError:
+        await _close()
+        if not scope.expired():
+            raise
+        return _openai_error(504, f"no upstream event within {timeout_s:.0f}s", etype="server_error")
+    except asyncio.CancelledError:
+        await _close()
+        if watcher.fired:
+            watcher.uncancel()
+            return Response(status_code=499)
+        raise
+    except BaseException:
+        await _close()
+        raise
+    finally:
+        await watcher.stop()
+
+    async def gen() -> AsyncIterator[str]:
+        try:
+            async with asyncio.timeout_at(deadline):
+                for ev in translator.start():
+                    yield format_sse(ev)
+                if first is not None:
+                    for out in translator.feed(first):
+                        yield format_sse(out)
+                async for ev in source:
+                    for out in translator.feed(ev):
+                        yield format_sse(out)
+            for out in translator.finish():
+                yield format_sse(out)
+        except TimeoutError:
+            logger.warning("responses-stream-timeout", extra={"timeout_s": timeout_s})
+            for out in translator.failed("server_error", f"stream exceeded {timeout_s:.0f}s ceiling"):
+                yield format_sse(out)
+        except (MidStreamError, NoProvidersAvailableError) as exc:
+            logger.warning("responses-stream-failed", extra={"error": str(exc)[:300]})
+            for out in translator.failed("server_error", str(exc)):
+                yield format_sse(out)
+        finally:
+            await _close()
+
+    return StreamingResponse(gen(), media_type="text/event-stream", headers={"Cache-Control": "no-cache"})

coderouter/routing/auto_router.py

@@ -36,6 +36,7 @@ from __future__ import annotations
 
 import logging
 import re
+from collections.abc import Mapping
 from typing import TYPE_CHECKING, Any
 
 from coderouter.config.schemas import AutoRouterConfig, AutoRouteRule, RuleMatcher
@@ -169,6 +170,32 @@ def _has_tools_in_body(body: dict[str, Any]) -> bool:
     return isinstance(functions, list) and len(functions) > 0
 
 
+# v2.18.0: Claude Code gateway hint headers → hint keys.
+_HINT_HEADERS: dict[str, str] = {
+    "x-claude-code-request-class": "request_class",
+    "x-claude-code-agent-type": "agent_type",
+    "x-claude-code-compaction": "compaction",
+    "x-claude-code-session-id": "session_id",
+    "x-claude-code-prompt-id": "prompt_id",
+}
+_TRUTHY = frozenset({"1", "true", "yes", "on"})
+
+
+def extract_gateway_hints(headers: Mapping[str, str]) -> dict[str, str]:
+    """Pull Claude Code's gateway hint headers out of a request.
+
+    Returns only the hints that are present (lower-cased keys from
+    :data:`_HINT_HEADERS`). Header lookup is case-insensitive whenever the
+    mapping is (Starlette's ``Headers`` is).
+    """
+    out: dict[str, str] = {}
+    for header, key in _HINT_HEADERS.items():
+        value = headers.get(header)
+        if value:
+            out[key] = value.strip()
+    return out
+
+
 def _match_rule(
     rule: AutoRouteRule,
     message: dict[str, Any] | None,
@@ -176,8 +203,17 @@ def _match_rule(
     model: str | None,
     estimated_tokens: int,
     has_tools: bool,
+    hints: Mapping[str, str] | None = None,
 ) -> bool:
     m = rule.match
+    if m.request_class is not None:
+        value = (hints or {}).get("request_class")
+        return value is not None and value.lower() == m.request_class.lower()
+    if m.agent_type is not None:
+        value = (hints or {}).get("agent_type")
+        return value is not None and value.lower() == m.agent_type.lower()
+    if m.compaction is True:
+        return (hints or {}).get("compaction", "").lower() in _TRUTHY
     if m.has_image is True:
         return message is not None and _has_image(message)
     if m.code_fence_ratio_min is not None:
@@ -237,7 +273,11 @@ def _extract_model(body: dict[str, Any]) -> str | None:
     return None
 
 
-def classify(body: dict[str, Any], config: CodeRouterConfig) -> str:
+def classify(
+    body: dict[str, Any],
+    config: CodeRouterConfig,
+    hints: Mapping[str, str] | None = None,
+) -> str:
     """Resolve an incoming request body to a profile name.
 
     Rule order (first match wins) is determined by:
@@ -252,6 +292,10 @@ def classify(body: dict[str, Any], config: CodeRouterConfig) -> str:
 
     Emits one of two log events: ``auto-router-resolved`` on match, or
     ``auto-router-fallthrough`` on default-rule fall.
+
+    v2.18.0: ``hints`` carries Claude Code's gateway hint headers (see
+    :func:`extract_gateway_hints`) for the ``request_class`` /
+    ``agent_type`` / ``compaction`` matchers.
     """
     user_msg = _latest_user_message(body)
     text = _extract_text(user_msg) if user_msg is not None else ""
@@ -294,7 +338,7 @@ def classify(body: dict[str, Any], config: CodeRouterConfig) -> str:
     # present — they short out via ``_match_rule``'s message-None
     # handling.
     for rule in rules:
-        if _match_rule(rule, user_msg, text, model, estimated_tokens, has_tools):
+        if _match_rule(rule, user_msg, text, model, estimated_tokens, has_tools, hints):
             _emit_resolved(rule, user_msg, text, model, estimated_tokens, has_tools)
             return rule.profile
 

coderouter/routing/capability.py

@@ -194,12 +194,13 @@ def strip_thinking(request: AnthropicRequest) -> AnthropicRequest:
 
     # model_dump() serializes extras; roundtripping via validate rebuilds a
     # clean instance without the dropped key. exclude=True fields (profile,
-    # anthropic_beta) are omitted by model_dump, so we reassign them.
+    # anthropic_beta, session_key) are omitted by model_dump, so we reassign them.
     dumped = request.model_dump()
     dumped.pop("thinking", None)
     stripped = AnthropicRequest.model_validate(dumped)
     stripped.profile = request.profile
     stripped.anthropic_beta = request.anthropic_beta
+    stripped.session_key = request.session_key
     return stripped
 
 
@@ -450,6 +451,7 @@ def emulate_tool_choice(request: AnthropicRequest) -> AnthropicRequest:
     emulated = AnthropicRequest.model_validate(dumped)
     emulated.profile = request.profile
     emulated.anthropic_beta = request.anthropic_beta
+    emulated.session_key = request.session_key
     return emulated
 
 
@@ -522,6 +524,7 @@ def strip_cache_control(request: AnthropicRequest) -> tuple[AnthropicRequest, in
     stripped = AnthropicRequest.model_validate(dumped)
     stripped.profile = request.profile
     stripped.anthropic_beta = request.anthropic_beta
+    stripped.session_key = request.session_key
     return stripped, removed