Support invocation-scoped custom request headers for UG and Codex

[andy-xu-db]

🥞 Stacked PR

Use this link to review incremental changes.

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

---

ug --header "Name: value" usage applies repeatable custom headers to the invocation, including its recommendModel request. Agent launches accept the global option or the existing ug codex --header ... form. Headers reach UG's prelaunch discovery and managed-config reads, Codex requests, and smart-routing helpers.

Codex receives launch-only environment-backed header configuration. Header-specific catalogs are temporary; ordinary model/config caches and saved discovery values remain separate. Scoped managed-config reads fail rather than falling back to the ordinary cache. Protected credential/transport headers and administrator-header collisions are rejected, and UG requests carrying custom headers reject cross-origin redirects. Use non-secret header values.

Merged main at 7deeaf7a.

Validation on the full stack (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.