Keep Claude custom request headers scoped to launch

[andy-xu-db]

🥞 Stacked PR

Use this link to review incremental changes.

• andy/custom-request-headers [Files changed]
  • andy/custom-request-headers-claude [Files changed] ← this PR

---

ug claude --header "Name: value" adds repeatable headers through a launch-only Claude settings override, preserving required headers without writing custom values into shared settings. The global ug --header ... claude form uses the same implementation. Direct, smart-routing, and relayed launches compose this override with existing launch settings.

Claude launches reject --header when OS-managed settings define env.ANTHROPIC_CUSTOM_HEADERS, including an empty value. That policy takes precedence over launch settings, so silently accepting the flag would not deliver the requested header. Existing private/admin header-name collisions are also rejected.

Headers reach model discovery before Claude starts. Scoped model lists and defaults stay in the launch context. The obsolete global-header journal, cleanup, and recovery tests are removed; focused launch/policy/discovery tests cover the replacement behavior. Shared invocation handling, cache isolation, usage, and routing propagation come from #610.

Merged the updated #610, including main at 7deeaf7a.

Validation (2026-10-07):

• 3,486 passed, 6 skipped: uv run --frozen pytest -q --ignore=tests/test_e2e.py --ignore=tests/test_e2e_user_agent.py.
• 656 focused HTTP/cache, Claude launch, and routing tests passed after the final cache-test strengthening and redundant-edit cleanup.
• Ruff lint/format, Ty, and git diff --check passed.

Native-agent capture validation remains unverified: four Claude/Codex capture checks failed because no request reached the local capture server. Live LiteSwap validation was not completed. Component tests verify request construction and launch configuration; they do not establish a live agent or gateway pass.

[andy-xu-db]

Live LiteSwap + Actual TUI Validation (2026-09-21)

Validated the combined #610/#687 stack at 635dad951b3050351913a00dcdcac23ebc669741 using real Claude Code 2.1.278 and Codex 0.154.0 TUIs, driven through a PTY with the repository's terminal helpers. No mocked clients or responses, headless substitutes, sandbox overrides, or manually seeded onboarding state.

Deployed a harmless AI Gateway marker change to staging-aws-us-east-1-0 and used eng-ml-inference-staging. Both launches passed repeated --header options for x-databricks-traffic-id: testenv://liteswap/andy-ug-headers-0921 and a client-specific probe.

Actual TUI run	Assistant answer	Result
ug claude --header ... --header ...	1739 + 2846 = 4585	Swap logged /ai-gateway/anthropic/v1/messages?beta=true with both exact headers and Claude User-Agent
ug codex --header ... --header ...	1927 + 3648 = 5575	Swap logged /ai-gateway/codex/v1/responses with both exact headers and Codex User-Agent
Header-free ug claude	1839 + 2846 = 4685	No new swap markers; both temporary headers and their state entry removed
Header-free ug codex	2027 + 3648 = 5675	No new swap markers; headers never persisted in user/managed config

All four TUIs exited normally with code 0. Server marker evidence was collected at 22:18:49 UTC (Claude, request 73c97621-fea1-4a8a-8b25-04b9a208dd5c) and 22:19:12 UTC (Codex, request f093e6ee-61fe-41d9-b0f5-0f30f0c477b6). Marker logs before and after header-free controls were byte-identical.

Scope limitation: staging smart-router selection returned HTTP 400 both with and without custom headers. The TUIs fell back successfully to their current models. This verifies actual inference header propagation through that fallback path, not a successful live smart-router model switch. MCP tool execution was not exercised.

No additional header-code fix was needed. The temporary container/token were removed and LiteSwap teardown succeeded. The marker change was not added to these PRs.