Support temporary global custom request headers for Claude Code

[andy-xu-db]

🥞 Stacked PR

Use this link to review incremental changes.

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

---

Summary

• add repeatable ug claude --header "Name: value" support
• reuse the existing private and OS-managed settings reconciliation required by Claude precedence
• reject protected headers and collisions with existing user or admin headers
• record exact temporary values in the existing global state and remove only those values on the next header-free launch or configuration
• document that the setting applies globally to active Claude sessions until it is cleared

Stack

Stacked on #610, which contains the shared parser and launch plumbing. Merge #610 first.

Rebase Validation (2026-09-21)

Rebased the stack onto aa55bba from main. Preserved the current Codex provider-header cleanup and protected Databricks-Smart-Router-Recipe from custom-header overrides, with case-insensitive regression coverage.

• Codex PR: 584 focused tests passed.
• Combined stack: 2,542 passed, 41 skipped with uv run --frozen pytest -q --ignore=tests/test_e2e_user_agent.py before the final integration-test-only main update.
• After including that main update: all 89 integration contract, model discovery, and provider catalog unit tests passed.
• Ruff lint, formatting, and git diff --check passed on the final stack.
• Live integration was not run locally. The user-agent e2e exclusion follows the existing limitation below.

Previous Testing

• uv run pytest -q tests/test_state.py tests/test_agent_claude.py tests/test_cli.py tests/test_agent_codex.py tests/test_codex_smart_routing_v2.py (734 passed)
• full suite passes with tests/test_e2e_user_agent.py excluded; its installed Claude 2.1.273 rejects the synthetic test model before making a request
• uv run ruff check src tests
• uv run ruff format --check src tests
• git diff --check

[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.