feat(azure-foundry): turnkey Claude Code + Azure AI Foundry compression

[ravensorb]

Description

Adds first-class support for running Claude Code on Azure AI Foundry through the Headroom proxy, following the same pattern as the recently merged Vertex AI support (#1113) and the in-progress Bedrock support (#1104).

Azure AI Foundry is Microsoft's hosted Claude endpoint (surfaced via CLAUDE_CODE_USE_FOUNDRY=1 + ANTHROPIC_FOUNDRY_RESOURCE). When this mode is active, Claude Code routes requests to an Azure-hosted endpoint rather than api.anthropic.com, and ANTHROPIC_BASE_URL is ignored — making the standard proxy intercept path inoperative. As a result, all Headroom compression is silently bypassed for any Claude Code installation running on Azure AI Foundry.

This is the same class of problem that was fixed for Vertex AI in #1113, where ANTHROPIC_VERTEX_BASE_URL had to be set instead of ANTHROPIC_BASE_URL.

Use Case

Enterprise and Azure-hosted deployments of Claude Code commonly use Azure AI Foundry rather than the direct Anthropic API. This includes:

• Avanade / Anthropic partner deployments provisioned through Azure Marketplace
• Any shop using CLAUDE_CODE_USE_FOUNDRY=1 (the apiKeyHelper-based auth path Claude Code exposes for Azure)
• CI/CD agents and self-hosted runners that authenticate via Entra managed identity rather than a personal Anthropic API key

These installations today receive zero Headroom compression benefit even after a correct proxy setup, with no error or warning to explain why.

Technical Details

When CLAUDE_CODE_USE_FOUNDRY=1 is set, Claude Code derives its endpoint from ANTHROPIC_FOUNDRY_RESOURCE and routes to:

https://{resource}.openai.azure.com/openai/deployments/{deployment}/chat/completions?api-version=...

or (newer Foundry endpoint):

https://{resource}.services.ai.azure.com/models/...

Authentication is either an api-key header or an Entra Bearer token — not an Anthropic API key. The proxy needs to:

1. Detect CLAUDE_CODE_USE_FOUNDRY=1 in wrap claude, analogous to CLAUDE_CODE_USE_VERTEX=1 detection in feat(vertex): turnkey Claude Code + Vertex compression (+ fixes from the Vertex review) #1113
2. Set ANTHROPIC_FOUNDRY_BASE_URL (or the equivalent env var Claude Code accepts in Foundry mode) to point at the local proxy, so Claude Code sends its Azure-format requests through Headroom
3. Forward auth headers (api-key or Authorization: Bearer) from the client to the Azure upstream — Headroom holds no credentials, same as the Vertex ADC passthrough pattern
4. Register an azure-foundry provider in providers/registry.py (or reuse the existing azure litellm provider with Foundry-specific host derivation)
5. Derive the upstream host per-request from ANTHROPIC_FOUNDRY_RESOURCE, handling both the .openai.azure.com and .services.ai.azure.com endpoint shapes

Prior Art in This Repo

Cloud	PR/Issue	Status	Pattern
Vertex AI	#1113	Merged	CLAUDE_CODE_USE_VERTEX → set ANTHROPIC_VERTEX_BASE_URL
Bedrock	#1104	Open	--bedrock-client-hook for pluggable credentials
Azure OpenAI (via Portkey)	#1123	Open bug	Proxy crashes on non-Anthropic upstreams

The Vertex PR is the closest model — the same wrap claude detection pattern and per-request host derivation apply directly.

Environment Variables (reference)

Var	Purpose
CLAUDE_CODE_USE_FOUNDRY	Set to 1 by Claude Code when Azure AI Foundry is active
ANTHROPIC_FOUNDRY_RESOURCE	Azure resource name (e.g. my-org-claude)
ANTHROPIC_FOUNDRY_BASE_URL	Override endpoint — this is what wrap claude should set to http://127.0.0.1:8787

Suggested Approach

Modelled on feat(vertex) in #1113:

• cli/wrap.py: detect CLAUDE_CODE_USE_FOUNDRY=1 and set ANTHROPIC_FOUNDRY_BASE_URL to the proxy address
• providers/registry.py: add azure-foundry alias mapping to the litellm azure provider with Foundry host derivation
• providers/proxy_routes.py: derive Azure upstream URL per-request from ANTHROPIC_FOUNDRY_RESOURCE, handling both endpoint shapes and forwarding client auth headers unchanged
• docs/: new claude-code-azure-foundry.mdx guide (parity with claude-code-vertex.mdx)
• tests/: new test_azure_foundry_claude_compression.py (parity with test_vertex_claude_compression.py)