Claude Code gateway hint headers for local routers

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]
• `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]
• A user-chosen agent name is never sent in `x-claude-code-agent-type`. [source]
• `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]
• `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]
• `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]
• 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]
• `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]
• 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]
• 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]
• `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]
• 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]
• 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]
• Claude Code reads response headers and error bodies from the gateway for retry decisions, so a gateway should forward error bodies unmodified. [source]
• 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]
• 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]
• 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]