feat(llm-client): allow forwarding all Anthropic beta headers

[ting-hong-shieh]

What

When forward_auth = true, a caller can send beta-specific body fields while Switchyard drops their anthropic-beta values. Add forward_beta = "all" on an anthropic_messages client to forward the caller's beta header values unchanged, including repeated headers. Omitted or "oauth" settings keep the existing OAuth-only filtering.

[llm_clients.claude]
format = "anthropic_messages"
base_url = "https://api.anthropic.com"
forward_auth = true
forward_beta = "all"

Why

Claude Code may pair request fields with experimental beta values. Dropping those values can cause upstream HTTP 400 responses. Closes #938.

Notes for reviewers

The policy is applied in the shared HTTP request path for completion and token-counting calls. TOML permits the field only for Anthropic Messages clients with auth forwarding enabled. Static anthropic-beta values in extra_headers remain rejected in both forwarding modes.

The public Rust HttpBackendConfig struct gains forward_beta. Downstream struct literals need to add forward_beta: Default::default() or ForwardBeta::All. Existing TOML files need no edit. No body translation code changes.

Validation at 1df1dd7d: Rust workspace 927 passed, 1 ignored; prefill-router 70 passed; Python 187 passed, 2 deselected, 2 subtests passed. Formatting, workspace Clippy, prefill Clippy, Ruff, mypy, strict documentation build, and diff checks passed.

Tests use local mocks. Live Anthropic acceptance and a Claude subscription session were not tested.

Commands: cargo fmt --all --check; cargo clippy --workspace --all-targets --locked -- -D warnings; cargo test --workspace --locked; feature Clippy for switchyard-server and tests for switchyard-runner with --features prefill-router --locked; uv run --no-sync ruff check .; uv run --no-sync mypy switchyard; uv run --no-sync pytest tests/ -v -m "not integration"; make -C docs publish.

Summary by CodeRabbit

• New Features
  • Added configurable forwarding of Anthropic beta headers: the default forwards OAuth-related values, while "all" preserves all caller-supplied values, including repeated headers. This option requires Anthropic Messages format and authentication forwarding.
• Documentation
  • Updated configuration guidance and examples to explain the beta-header forwarding options and requirements.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository: NVIDIA-NeMo/Switchyard/.coderabbit.yaml
• Review profile: CHILL
• Plan: Enterprise
• Run ID: b9e306b2-febe-4efd-bba6-ac8e6f70cb19

📥 Commits

Reviewing files that changed from the base of the PR and between a3cdc51 and 1df1dd7.

📒 Files selected for processing (9)

• crates/libsy-llm-client/README.md
• crates/libsy-llm-client/src/backend.rs
• crates/libsy-llm-client/src/client.rs
• crates/libsy-llm-client/src/lib.rs
• crates/libsy-llm-client/src/run.rs
• crates/libsy-llm-client/tests/fallback_credit.rs
• crates/switchyard-runner/src/config.rs
• crates/switchyard-server/tests/server.rs
• docs/reference/toml_schema.md

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

---

Walkthrough

The client backend now supports OAuth-filtered or full forwarding of caller-supplied Anthropic beta headers. Runner configuration exposes the policy for Anthropic Messages clients with forwarded authentication. Tests and documentation cover the option and its request behavior.

Changes

Anthropic beta forwarding

Layer / File(s)	Summary
Backend policy and forwarding crates/libsy-llm-client/src/backend.rs, crates/libsy-llm-client/src/lib.rs, crates/libsy-llm-client/README.md	Adds the public ForwardBeta policy. The default forwards the filtered OAuth value; All forwards every caller-supplied beta value unchanged when auth forwarding is enabled.
Runner configuration and validation crates/switchyard-runner/src/config.rs, docs/reference/toml_schema.md	Adds the optional forward_beta setting. The runner validates that it is used with anthropic_messages and forward_auth = true, then passes the setting to the backend.
Request tests and fixtures crates/libsy-llm-client/src/client.rs, crates/libsy-llm-client/src/run.rs, crates/libsy-llm-client/tests/fallback_credit.rs, crates/switchyard-server/tests/server.rs	Tests completion and token-counting requests with repeated beta headers. Updates backend test configurations to set the new field’s default.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 1df1d

No actionable merge-blocking issue is identified; the change is mergeable after normal checks.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 68.42% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 19 functions across 7 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding support for forwarding all caller-supplied Anthropic beta headers.
Linked Issues check	✅ Passed	[#938] requests opt-in forwarding of caller anthropic-beta values for anthropic_messages clients with forward_auth = true, while retaining OAuth-only filtering by default. ForwardBeta::All for…
Out of Scope Changes check	✅ Passed	The code, configuration, tests, and documentation changes support [#938]. Updating HttpBackendConfig fixtures and exporting and documenting ForwardBeta are required to integrate the new option. No…

Full details: Docstring Coverage

Explanation

Docstring coverage is 68.42% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 19 functions across 7 files. (2 skipped: 2 unsupported.)

• Fix all pre-merge checks with AI

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{A rabbit checks the headers twice,
OAuth hops along, then All brings more.
Repeated beta values pass in line,
Completion and token counts arrive.
The config burrows into place.}

_{Comment @coderabbitai help to get the list of available commands.}