mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 18:41:07 +08:00
## Why
`headroom wrap claude` silently bypassed Headroom for every Claude Code
user on Bedrock.
With `CLAUDE_CODE_USE_BEDROCK=1`, Claude Code ignores
`ANTHROPIC_BASE_URL` and calls AWS itself. wrap only sets
`ANTHROPIC_BASE_URL`, so it started a proxy that saw no traffic: no
error, no savings.
The flag usually lives in `~/.claude/settings.json`, which Claude Code
obeys over the shell, so exporting `CLAUDE_CODE_USE_BEDROCK=0` didn't
help either. A customer hit exactly this and needed a call to find it.
## What
When Bedrock mode is on, wrap routes it through Headroom using the path
that already works with the proxy's Bedrock backend:
- **Read the flag the way Claude Code does:** shell → user → project →
project-local settings → managed settings.
- **Proxy:** started with `--backend bedrock`, in the region Claude Code
would use, with the AWS settings it would read. Settings-file values are
copied in, and keys a settings file clears are cleared.
- **Claude Code:** launched in Anthropic mode against the proxy, with
`--settings '{"env":{"CLAUDE_CODE_USE_BEDROCK":"0"}}'`, which outranks
the settings files. A placeholder credential is added only if none is
configured. The proxy calls Bedrock with the user's AWS credentials.
- **Bedrock wins over Vertex and Foundry,** as it does in Claude Code
(checked: with both flags set, Claude Code calls the Bedrock endpoint).
- **Project-local settings aren't written in Bedrock mode,** since
daemon workers read them without the override.
Where routing isn't safe, wrap leaves the session alone and **says
Headroom is bypassed, and why**:
- the flag is in managed settings (they outrank `--settings`);
- a Bedrock gateway (`ANTHROPIC_BEDROCK_BASE_URL` /
`CLAUDE_CODE_SKIP_BEDROCK_AUTH`);
- `--no-proxy`;
- a non-Bedrock `--backend` / `HEADROOM_BACKEND`;
- the user's own `--settings`.
Also:
- **Managed settings are read tolerantly.** An unreadable file is
reported and skipped instead of stopping every `wrap claude`.
- **The env overlay moves to `providers/claude/runtime.py`**
(`claude_effective_env`) and is shared with the auth-conflict check.
That check now uses the same shell-first order, so settings files
outrank the shell as they do in Claude Code.
## Testing
- **Verified against Claude Code 2.1.304** with a loopback recorder:
- `settings.json` `env` beats the shell;
- `--settings` beats `settings.json`;
- Bedrock beats Vertex.
- **Unit:** 44 tests in `test_wrap_claude_vertex_proxy_env.py`, one per
case above, including the bypass reasons, the unreadable managed file,
region precedence, and the AWS profile reaching the proxy. A conftest
fixture keeps the host's managed-settings file out of CLI tests.
- **Wider suites:** `tests/test_cli`, the Claude provider and doctor
suites pass, except 5 tests that already fail on `main` on macOS:
- 4 in `test_wrap_persistent.py`: the fake `_Manifest` lacks
`runtime_kind`, which the darwin-only branch reads;
- `test_mcp_reconcile::test_ordinary_install_does_not_adopt_serena`,
which depends on whether `headroom` is on PATH.
- **Live, real Bedrock** (Sonnet 4.6, us-east-1), with this change on
core 0.41.0. Customer setup: `CLAUDE_CODE_USE_BEDROCK=1` only in
`~/.claude/settings.json`, plain `headroom wrap claude`:
- routed through Headroom: 13 requests, 0 failed;
- first request 18,312 tokens vs 22,648 sent straight to Bedrock (−19%,
with the tool-search and skill-search plugins).
## Related
- **#1220** routes Bedrock differently: it points
`ANTHROPIC_BEDROCK_BASE_URL` at the proxy and re-signs requests with
SigV4. In a live test it compressed nothing (Bedrock-mode bodies reach a
handler that runs no compression or hooks), and one stream hung for over
5 minutes. This PR uses the Anthropic-mode path the Bedrock backend
already serves.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- devin-review-badge-begin -->
---
<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4316"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->
## Maintainer post-merge qualification
Published `f1f11da91d481e48e57526a784187810f762c209` incorporates
upstream main `e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`. 44 existing
handoff tests pass; both existing effective-client probes fail:
competing Vertex flag remains enabled and user-settings remote base URL
wins over launched proxy URL. Ruff/format/diff pass; clean main sync, no
routing rewrite. Existing Changes Requested decision remains applicable;
unchanged findings are not reposted. Scoped Windows probes use the real
CLI configuration harness or actual metrics object, not live
cloud-provider traffic. Contributor correctness logic was not rewritten;
hosted checks are handled by maintainers. Nothing merged.
### Maintainer current-main requalification
Exact head `79b861ef2351bd321900b221f6cf99ad5cbedf27`, upstream main
`ecbaf86d78cf52d185fbffa306157b9a4cc1b906`.
Mechanically updated from upstream/main
ecbaf86d78 with a clean merge and no
contributor routing-policy rewrite. Reviewed existing discussion and
integration delta. All 54 existing Bedrock handoff/Gemini tests pass;
Ruff0.17.3 lint/format and whitespace checks pass.
Both prior effective-client probes still fail on this combined tree:
user-settings Bedrock plus shell Vertex leaves effective
CLAUDE_CODE_USE_VERTEX=1; user-settings Bedrock plus remote
ANTHROPIC_BASE_URL retains https://example.invalid instead of the
launched http://127.0.0.1:8787 proxy. These probes combine the real CLI
harness's captured launch environment and settings overlay; child/proxy
processes are stubbed and no live-provider request is claimed. Retain
the existing requested complete session overrides for competing provider
flags and proxy base URL while respecting managed-policy precedence,
with assertions on effective launched-client configuration. This is not
an inherited-main CI hold. Maintainers handle hosted checks; nothing
merged.
Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.
### Maintainer current-main requalification
Exact head `4187711078787567dff800087f4e68e814c0aaa9`, upstream main
`8d3e9e5ca7cd645eb73084b848edbea5fc796e1a`.
Clean mechanical sync with upstream
main8d3e9e5ca7cd645eb73084b848edbea5fc796e1a, with no contributor
routing policy rewrite. Existing discussion/source
re-reviewed.54existing Bedrock handoff/Gemini tests pass;5changed Python
files Ruff0.17.3check/format and whitespace pass.
Both prior effective-client probes freshly fail on this combined tree:
user-settings Bedrock plus shell Vertex leaves effective
CLAUDE_CODE_USE_VERTEX=1; user-settings Bedrock plus remote
ANTHROPIC_BASE_URL retains https://example.invalid rather than launched
loopback proxy. Probes combine the real CLI harness launch environment
and settings overlay with stubbed child/proxy, not a live provider.
Supply complete session overrides for competing provider flags and proxy
base URL while preserving managed-policy precedence; assert effective
launched configuration. This is not inherited-main CI. Maintainers
handle hosted checks; copied extension is not fresh-native-build proof.
Nothing merged.
Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.
### Maintainer current-main requalification
Exact head `2c94a2f3dacaeba93c2ff846b3c7ea9614f8165d`, upstream main
`2d3ee51846435ef5b320eea4806af14e602b0d8c`.
Clean integration with upstream/main
2d3ee51846. Re-reviewed current discussion
and the composed tree. Exact comparison of CLI launch and Claude
provider implementation plus the Bedrock handoff test file against prior
reviewed 418771107 shows no changes. All 131 Bedrock
handoff/release/version/MCP/memory/Gemini tests pass; whitespace passes.
Prior changed-file lint/format applies to identical contributor inputs.
The existing effective-client configuration finding remains:
user-settings Bedrock combined with shell Vertex or settings
ANTHROPIC_BASE_URL can preserve the competing provider flag or remote
URL. Earlier harness probes remain evidence for the unchanged launch
paths; they were not rerun or claimed as live-provider proof after these
unrelated main merges. Preserve the requested complete per-session
overrides and launched-configuration regressions while respecting
managed policy precedence. No routing-policy winner selected between
overlapping PRs. No contributor correctness logic rewritten, no fresh
native build claimed. Maintainers handle checks; nothing merged.
Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.
### Maintainer current-main requalification
Exact head `26ad500eadcd958cbea4d433333958e0e36a766c`, upstream main
`c01cf07d943d816cfd9d97e6838ed4e38f1ff9a4`.
Clean integration with upstream/main
c01cf07d94 after the
release/runtime/dependency merges. Resolved the test-fixture-only
conflict by retaining both the author's proxy environment capture and
main's actual-port override; original UTF-8 banner assertions and
contributor production logic are preserved.107 Bedrock
handoff/region/Hermes tests pass with actual Click8.5.0 and the fresh
native binding; changed-source Ruff and whitespace pass.
The two existing effective-client routing blockers freshly reproduce on
this composed tree. With Bedrock selected in user settings and Vertex
enabled in the shell, the launched effective configuration still has
CLAUDE_CODE_USE_VERTEX=1. With user-settings
ANTHROPIC_BASE_URL=https://example.invalid, the launched settings retain
that gateway while the shell points to the proxy. The proxy backend is
Bedrock in both cases, so the client route disagrees with the announced
route. Please provide complete per-session overrides, or explicitly
refuse incompatible effective configurations, with
launched-configuration regressions while respecting managed-policy
precedence. Current author discussion and Devin findings considered; no
policy winner or new unsupported cloud-runtime claim introduced. No real
AWS call was made. Maintainers handle exact-head hosted checks; nothing
merged.
Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.
### Maintainer current-main requalification
Exact head `3fa44885c12e14e95ac55e8352d30542328a90d2`, upstream main
`da6d9736cd82074988c7d0a2360b49d9d8b6c0a0`.
Current-main requalification against
da6d9736cd. All69 integration patches
exactly match c01cf07-to-current-main delta after diff-location
normalization; contributor handoff/ownership policy unchanged.107
Bedrock handoff/region/Hermes tests pass.31 changed Python files pass
Ruff lint/format; offline lock and whitespace pass. Existing pr3982
native DLL verified complete native input hashes/artifact checksum; no
fresh build claimed. Author and Devin discussions considered. Both
effective-client routing blockers freshly reproduce with captured launch
configuration: user-settings Bedrock plus shell CLAUDE_CODE_USE_VERTEX=1
leaves Vertex enabled; user-settings
ANTHROPIC_BASE_URL=https://example.invalid survives while shell proxy
base URL points locally. Announced Bedrock backend and effective client
route disagree. Provide complete per-session overrides or explicitly
reject incompatible effective configuration, respecting managed-policy
precedence, with launched-configuration regressions. No real AWS request
or live cloud claim. Maintainers handle hosted checks; no contributor
semantics rewritten or merge.
Exact-head hosted checks are being handled by maintainers. Existing
correctness/qualification holds remain; nothing merged.
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
29 lines
1.0 KiB
Python
29 lines
1.0 KiB
Python
"""Shared fixtures for the CLI test suite.
|
|
|
|
``headroom wrap`` may fetch helper binaries (e.g. tokensave) over the network
|
|
via ``headroom.binaries``. Force offline across CLI tests so a missing binary
|
|
resolves locally instead of reaching out to GitHub releases. Tests that
|
|
exercise a binary-present path patch the relevant resolver directly and are
|
|
unaffected by this guard.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import pytest
|
|
|
|
|
|
@pytest.fixture(autouse=True)
|
|
def _tokensave_offline(monkeypatch: pytest.MonkeyPatch) -> None:
|
|
monkeypatch.setenv("HEADROOM_BINARIES_OFFLINE", "1")
|
|
|
|
|
|
@pytest.fixture(autouse=True)
|
|
def _no_host_claude_managed_settings(
|
|
monkeypatch: pytest.MonkeyPatch, tmp_path_factory: pytest.TempPathFactory
|
|
) -> None:
|
|
"""Keep the machine's own Claude managed-settings file out of wrap tests."""
|
|
from headroom.cli import wrap as wrap_mod
|
|
|
|
missing = tmp_path_factory.mktemp("managed") / "managed-settings.json"
|
|
monkeypatch.setattr(wrap_mod, "_claude_managed_settings_path", lambda: missing)
|