<!-- llms-explorer concept facts · https://llms-explorer.com/tree/claude-code-gateway-hint-headers-for-local-route/ · pack 2026-10-05 · ~1282 tokens -->

# Claude Code gateway hint headers for local routers

> `x-claude-code-request-class` is sent on every request and has five values: `main` (a turn of the main conversation), `subagent`, `workflow` (an agent inside a workflow), `compaction`, and `auxiliary` (side requests such as session titles, classifiers and summaries).

Parent: [Mac local LLMs: Agent clients, context and compaction](https://llms-explorer.com/tree/mac-local-llms-agent-clients-context-and-compaction/) · 1 facets · 17 facts · page: https://llms-explorer.com/tree/claude-code-gateway-hint-headers-for-local-route/

## Facts

- `x-claude-code-request-class` is sent on every request and has five values: `main` (a turn of the main conversation), `subagent`, `workflow` (an agent inside a workflow), `compaction`, and `auxiliary` (side requests such as session titles, classifiers and summaries). — [source](https://code.claude.com/docs/en/llm-gateway-protocol)
- `x-claude-code-agent-type` is present only on a subagent's own turns, and carries a built-in type name such as `Explore`, `Plan` or `general-purpose`, or `custom` for a user-defined agent, `teammate` for an agent-team member in the lead's process, or `fork` for a fork. — [source](https://code.claude.com/docs/en/llm-gateway-protocol)
- A user-chosen agent name is never sent in `x-claude-code-agent-type`. — [source](https://code.claude.com/docs/en/llm-gateway-protocol)
- `x-claude-code-context-compacted` carries the same values (`auto`, `manual`, `reactive`) as `x-claude-code-compaction`, and appears once, on the first main-conversation request after the compaction. — [source](https://code.claude.com/docs/en/llm-gateway-protocol)
- `x-claude-code-prev-tool-durations` has the form `<name>=<ms>;<name>=<ms>` (for example `Bash=742;Read=9`) and is sent on the next request of the same conversation after a batch of tool calls, from the main session or a subagent. — [source](https://code.claude.com/docs/en/llm-gateway-protocol)
- `x-claude-code-prev-tool-durations` is capped at 32 entries and 4 KB (first entries kept), percent-encodes tool names (covering `%`, `;`, `=`, comma, space and non-printable-ASCII), and is never sent on compaction calls, side requests or the first request of a new prompt. — [source](https://code.claude.com/docs/en/llm-gateway-protocol)
- The tool durations exclude permission prompts and hooks, and parallel tool calls each report their own time, so entries do not add up to the gap between requests. — [source](https://code.claude.com/docs/en/llm-gateway-protocol)
- `x-claude-code-prompt-id` is a random UUID shared by every request serving one user prompt, including turns of subagents that prompt started; requests not attributed to a prompt omit it. — [source](https://code.claude.com/docs/en/llm-gateway-protocol)
- The hint headers carry only fixed vocabularies, tool names, durations and a random prompt identifier, never prompt text or file contents, and every value is printable ASCII. — [source](https://code.claude.com/docs/en/llm-gateway-protocol)
- On a direct connection to the Anthropic API the hints are sent by default; on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry and Claude Platform on AWS they are sent only when `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1`. — [source](https://code.claude.com/docs/en/llm-gateway-protocol)
- `x-claude-code-session-id` (all requests in a session), `x-claude-code-agent-id` (subagent requests only) and `x-claude-code-parent-agent-id` (nested agents only) are listed as ordinary request headers, apart from the hint set, and a gateway may use them for routing, attribution and tracing without forwarding them. — [source](https://code.claude.com/docs/en/llm-gateway-protocol)
- Subagent IDs are fresh for each spawn, while agent-team teammates reuse a stable name-based ID across reconnections, so the agent ID identifies an agent and not a person or device. — [source](https://code.claude.com/docs/en/llm-gateway-protocol)
- A gateway should forward `anthropic-version` and `anthropic-beta` unchanged and pass `anthropic-*` request headers and body fields through to an Anthropic-format upstream without an allowlist. — [source](https://code.claude.com/docs/en/llm-gateway-protocol)
- Claude Code reads response headers and error bodies from the gateway for retry decisions, so a gateway should forward error bodies unmodified. — [source](https://code.claude.com/docs/en/llm-gateway-protocol)
- Compaction invalidates the conversation layer of the prompt cache by design, while Claude Code reuses the system-prompt layer unless a resumed session switched to a changed system prompt. — [source](https://code.claude.com/docs/en/prompt-caching)
- Inferred: a local router can treat `x-claude-code-request-class: main` and `subagent` as the only classes worth pinning to a warm KV slot, and treat `compaction` as a one-shot long prompt whose old prefix will not recur. — source: `asserted`
- Inferred: because `auxiliary` requests have a different prompt from the main conversation, routing them to the same slot would evict the main prefix on a single-slot hybrid server. — source: `asserted`
