## Description
Fix Claude Code server-side auto-mode compatibility when requests pass
through
Headroom’s native Anthropic Messages endpoint.
Previously, auto-mode capability headers, safeguard payloads, query
parameters,
unknown response fields, or opaque SSE frames could be rewritten or lost
while
proxying and handling CCR continuations. This could trigger Claude
Code’s
client-side classifier fallback and its associated warning.
This change adds a request-local Anthropic wire envelope, preserves
client-owned
capability data and opaque response attachments, prevents classifier
payloads
from entering Headroom-owned observations, and documents that
schema-translating
Bedrock, Vertex, and LiteLLM routes do not currently support the
server-side
auto-mode protocol.
Closes #
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)
## Changes Made
- Preserve native Anthropic request paths and raw query parameters.
- Preserve client-owned `anthropic-version`, `anthropic-beta`, and
safeguard data.
- Avoid sticky-beta, memory, or turn-hook rewrites on classifier-bearing
turns.
- Preserve unknown Anthropic response fields across CCR continuations.
- Preserve opaque SSE frames through request-local parse/render
envelopes.
- Reject unknown or malformed deltas during strict buffered
reconstruction.
- Redact safeguard payloads from diagnostics and pipeline observations.
- Consolidate Anthropic SSE parsing and rendering into the wire module.
- Document auto-mode limitations for Bedrock, Vertex, and LiteLLM
translation paths.
- Add request, response, streaming, CCR, malformed-byte, and passthrough
regression tests.
## Testing
<!-- Check what you actually ran, then paste the real command output
below. -->
- [ ] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [ ] Manual testing performed
### Test Output
```text
$ python -m pytest -p no:cacheprovider \
tests/test_anthropic_auto_mode_passthrough.py \
tests/test_anthropic_buffered_sse.py \
tests/test_ccr_response_handler_extra.py \
tests/test_ccr_buffered_stream_signed_thinking.py \
tests/test_proxy/test_anthropic_streaming_ccr_retrieve.py \
tests/test_buffered_ccr_salvage.py \
tests/test_buffered_ccr_accept_header.py \
tests/test_proxy/test_anthropic_copilot_upstream_auth.py \
tests/test_proxy_streaming_request_logger.py \
tests/test_proxy_streaming_resilience.py -q
125 passed, 1 warning in 13.70s
$ ruff check --no-cache .
All checks passed!
$ ruff format --check --no-cache .
1559 files already formatted
$ python -m mypy \
headroom/proxy/anthropic_wire.py \
headroom/ccr/response_handler.py \
headroom/proxy/handlers/anthropic.py \
headroom/proxy/handlers/streaming.py
Success: no issues found in 4 source files
$ npx --no-install commitlint \
--from origin/main --to HEAD \
--config .commitlintrc.json
Exited successfully.
```
## Real Behavior Proof
- Environment: Pending. Record OS, Python version, Claude Code version,
provider/model, and Headroom revision.
- Exact command / steps: Pending. Start Headroom with `headroom proxy
--port 8787`, then run Claude Code with
`ANTHROPIC_BASE_URL=http://127.0.0.1:8787` and exercise server-side auto
mode.
- Observed result: Pending. Attach redacted output or logs showing the
request completed through Headroom and whether Claude Code used its
client-side fallback.
- Not tested: Live Claude Code auto mode against Anthropic; Bedrock,
Vertex, and LiteLLM translation routes.
## Runtime Rollout Safety
- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A.
- Stable/default behavior changed: Native Anthropic safeguard-capable
requests.
- Kill switch / disable path: Set `CLAUDE_CODE_AUTO_MODE_SERVER=0` to
use Claude Code’s client-side fallback.
- Unsafe override required: No.
- Qualification impact: Live qualification is pending. Translation
routes remain documented as unsupported for server-side auto mode.
- Rollback path: Revert this PR or deploy the previous Headroom
revision.
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
## Checklist
- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code where needed
- [x] I have made corresponding documentation changes
- [x] No new warnings were observed in focused tests
- [x] I have added tests for the fix
- [ ] Full existing and new unit test suite passes locally
- [x] I did **not** edit `CHANGELOG.md`
## Screenshots (if applicable)
N/A. This change affects proxy wire behavior.
6.0 KiB
Claude Code + AWS Bedrock, with Headroom compression
Validated end-to-end on 2026-06-26 (Claude Code 2.1, Headroom 0.27.0, ap-southeast-2).
This is the working, tested way to run Claude Code against Claude models on AWS Bedrock with Headroom compressing the context in the middle.
TL;DR
Run Claude Code in normal Anthropic mode (NOT Bedrock mode) pointed at a local Headroom proxy, and let Headroom be the thing that talks to Bedrock:
Claude Code ──ANTHROPIC_BASE_URL──▶ Headroom proxy ──LiteLLM (bedrock)──▶ AWS Bedrock
(normal mode) (plain http) (compresses) (your AWS creds) (Claude)
One non-obvious requirement makes the difference between "works" and "silently bypasses the proxy":
CLAUDE_CODE_USE_BEDROCK=0— Without this, Claude Code sees theCLAUDE_CODE_USE_BEDROCK=1flag and calls Bedrock directly via the AWS SDK, completely bypassingANTHROPIC_BASE_URLand the proxy.
Why not "just set CLAUDE_CODE_USE_BEDROCK=1"?
That approach does not work with Headroom. When CLAUDE_CODE_USE_BEDROCK=1 is set,
Claude Code calls Bedrock directly using the AWS SDK — ANTHROPIC_BASE_URL is ignored
entirely and the proxy never receives a byte. Use the Anthropic-mode path below.
Prerequisites
- AWS credentials configured for your environment (env vars,
~/.aws/credentials, instance profile, or SSO viaaws sso login). Confirm direct access works before involving Headroom:aws bedrock-runtime invoke-model \ --region us-east-1 \ --model-id anthropic.claude-3-haiku-20240307-v1:0 \ --body '{"anthropic_version":"bedrock-2023-05-31","max_tokens":20,"messages":[{"role":"user","content":"hi"}]}' \ /tmp/out.json - boto3 in the proxy's Python environment (for dynamic inference profile discovery):
pip install boto3 - IAM permissions for the models you intend to use — at minimum
bedrock:InvokeModelandbedrock:InvokeModelWithResponseStream. For application inference profiles, scope to the specific profile ARN:{ "Effect": "Allow", "Action": ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream"], "Resource": ["arn:aws:bedrock:<region>:<account>:application-inference-profile/<id>"] }
Terminal 1 — start the Headroom proxy (Bedrock backend)
headroom proxy --port 8787 \
--backend bedrock \
--region us-east-1
With a named AWS SSO profile:
headroom proxy --port 8787 \
--backend bedrock \
--region us-east-1 \
--bedrock-profile my-sso-profile
On startup the proxy calls list_inference_profiles to build a model map. Confirm it
is routing correctly by checking the LiteLLM log lines — you should see:
LiteLLM completion() model= converse/arn:aws:... provider = bedrock
Terminal 2 — run Claude Code (normal Anthropic mode) against the proxy
export CLAUDE_CODE_USE_BEDROCK=0 # REQUIRED — prevents Claude Code bypassing the proxy
export ANTHROPIC_BASE_URL=http://127.0.0.1:8787
export ANTHROPIC_API_KEY=headroom # Claude Code needs *a* key to start; value is ignored
export ANTHROPIC_MODEL=claude-opus-4-6
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
claude
Or via ~/.claude/settings.json:
{
"env": {
"CLAUDE_CODE_USE_BEDROCK": "0",
"ANTHROPIC_BASE_URL": "http://127.0.0.1:8787",
"ANTHROPIC_API_KEY": "headroom",
"ANTHROPIC_MODEL": "claude-opus-4-6",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6",
"ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001"
}
}
Claude Code now talks plain Anthropic /v1/messages to Headroom; Headroom compresses
and forwards to Bedrock via LiteLLM, then translates the answer back.
This translating route is not currently compatible with Claude Code's server-side
auto-mode classifier protocol. Ordinary model traffic remains fail-open, but
classifier-bearing turns may use Claude Code's billable client-side fallback.
Use native Anthropic transport for server-side auto mode, or set
CLAUDE_CODE_AUTO_MODE_SERVER=0 when the fallback is intentional.
Application inference profiles (account-specific ARNs)
If your IAM policy only permits application inference profiles (account-specific
ARNs) rather than system-defined cross-region profiles, pass the ARN directly as the
model value in ANTHROPIC_DEFAULT_*_MODEL. The proxy detects arn:aws: prefixed model
IDs and routes them via bedrock/converse/<arn> automatically — no extra configuration
required.
Region prefix notes
| AWS region | Cross-region inference prefix |
|---|---|
us-* |
us. |
eu-* |
eu. |
ap-* (except ap-southeast-2) |
apac. |
ap-southeast-2 (Sydney) |
au. |
The proxy uses the correct prefix automatically when constructing fallback model IDs.
Verify compression is happening
- Dashboard: http://localhost:8787/dashboard — "tokens saved" climbs as you work.
curl -s localhost:8787/stats→tokens.savedandrequest_logs[].transforms_applied.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Proxy receives no requests | Claude Code is in Bedrock mode, bypassing proxy | Set CLAUDE_CODE_USE_BEDROCK=0 |
400 The provided model identifier is invalid |
Bedrock rejected the model name format | Use standard cross-region profile names (claude-sonnet-4-6) or a valid application inference profile ARN |
403 AccessDeniedException on system-defined profiles |
IAM policy only permits application profiles | Use --bedrock-profile with an authorized profile and pass application inference profile ARNs as model values |
400 … Try calling via converse route |
Old proxy version routing ARNs to invoke path | Upgrade to headroom ≥ 0.27.1 |
| Model map empty at startup | boto3 not installed or wrong AWS profile | pip install boto3; check --bedrock-profile / AWS_PROFILE |