fix(anthropic): forward safeguards and anthropic-beta unchanged on native /v1/messages

[devin-ai-integration]

TLDR

Problem this solves:

• Native /v1/messages dropped the safeguards request field
• Beta values LiteLLM did not recognise were stripped from anthropic-beta
• Claude Code auto mode then fell back to separately billed classifier calls

How it solves it:

• safeguards added to AnthropicMessagesRequestOptionalParams and the native supported list
• First-party anthropic route no longer filters anthropic-beta, other providers still do
• safeguards and safeguard_results typed as the arrays Claude Code 2.1.278 and api.anthropic.com actually exchange ([{"type": "dangerous_tool_use", ...}]), declared on the request, response and streaming chunk types (runtime already kept them)
• Adapter path to non-Anthropic models strips safeguards instead of leaking it

User Flow

Before: a Claude Code user on auto mode pays for classifier requests because the gateway strips the safeguards contract

1. Claude Code sends POST https://litellm-domain/v1/messages with "safeguards": {"auto_mode": {...}} and anthropic-beta: interleaved-thinking-2025-05-14,safeguards-2026-09-01
2. Anthropic receives a body with no safeguards key and an anthropic-beta header holding only interleaved-thinking-2025-05-14
3. The 200 response has no server-side safeguard_results, so Claude Code decides server review is unavailable and starts sending its own billed classifier requests

After: the same request reaches Anthropic unchanged and the response carries the server verdict

1. Claude Code sends the same POST https://litellm-domain/v1/messages with the same body and headers
2. Anthropic receives safeguards in the body and the full anthropic-beta value, anthropic-version untouched
3. The 200 response (and message_start / message_delta when streaming) carries safeguard_results, so the session qualifies for no-charge classifier requests
4. https://litellm-domain/ui/logs shows the request logged with the safeguards field and the full beta header, priced normally

Relevant issues

Affected release

Linear ticket

Resolves LIT-8232

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have added meaningful tests
• The handful of test files covering my change pass locally, e.g. uv run pytest tests/test_litellm/<your_test_file>.py -v. Leave the suites (make test-unit-*, make test-unit) to CI: it finishes in ~15 minutes where a laptop takes an hour or more
• My PR passes all required CI/CD checks (e.g., lint, schema.d.ts sync check, etc.)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

Screenshots / Proof of Fix

Root cause in one sentence: the native Anthropic Messages path builds its request allowlist from AnthropicMessagesRequestOptionalParams (no safeguards) and runs the cross-provider anthropic-beta filter even when the upstream is api.anthropic.com, so both the field and the unknown beta were dropped before the request left the proxy

Setup shared by both arms. Postgres plus the proxy on localhost:4000 started with PYTHONPATH=$PWD uv run --no-sync litellm --config proxy_config.yaml --port 4000. The fake-claude deployment is anthropic/claude-sonnet-4-5 with api_base: http://127.0.0.1:4123, a tiny HTTP server that records the exact headers and body it receives and answers a real Anthropic-shaped message (with safeguard_results) as JSON or SSE. real-claude is anthropic/claude-haiku-4-5 against api.anthropic.com with a real key. Payloads are byte-identical across arms

req.json:

{"model":"fake-claude","max_tokens":64,"safeguards":{"auto_mode":{"enabled":true,"version":"2026-09-01"}},"system":[{"type":"text","text":"You are Claude Code."},{"type":"text","text":"attribution block","cache_control":{"type":"ephemeral"}}],"messages":[{"role":"user","content":"hi"}]}

req_stream.json is the same with "stream":true. Headers on every call: anthropic-version: 2023-06-01 and anthropic-beta: interleaved-thinking-2025-05-14,safeguards-2026-09-01

Before (0f7d4dc)

Native /v1/messages, non-streaming

1. curl -s localhost:4000/v1/messages -H "Authorization: Bearer $KEY" -H "content-type: application/json" -H "anthropic-version: 2023-06-01" -H "anthropic-beta: interleaved-thinking-2025-05-14,safeguards-2026-09-01" -d @req.json
2. 200, control leg works, response includes "safeguard_results":{"verdict":"allow","checks":["shell_command"]} because the fake upstream always sends it
3. What the upstream actually received: {"anthropic-beta": "interleaved-thinking-2025-05-14", "anthropic-version": "2023-06-01", "has_safeguards": false, "safeguards": null, "body_keys": ["max_tokens", "messages", "model", "system"]}. The safeguards field is gone and safeguards-2026-09-01 was stripped from the beta header

Native /v1/messages, streaming

1. Same curl with -N and -d @req_stream.json
2. 200 SSE, message_start and message_delta reach the client with safeguard_results (the SSE bytes are forwarded raw)
3. Upstream capture identical to the non-streaming leg: has_safeguards: false, beta header reduced to interleaved-thinking-2025-05-14

After (b59028d; 1ac4d7a only retypes the fields as arrays and changes no runtime code, the filter matches on keys, not values)

Native /v1/messages, non-streaming

1. Same curl, same req.json
2. Output:

   {"id":"msg_fake_3e713f0b9fd6","type":"message","role":"assistant","model":"fake-claude","content":[{"type":"text","text":"ok from fake upstream"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":5},"safeguard_results":{"verdict":"allow","checks":["shell_command"]}}
   HTTP 200
   

3. Upstream received: {'anthropic-beta': 'interleaved-thinking-2025-05-14,safeguards-2026-09-01', 'anthropic-version': '2023-06-01', 'has_safeguards': True, 'safeguards': {'auto_mode': {'enabled': True, 'version': '2026-09-01'}}} and the body keys now include safeguards, with the system array and its attribution block in the original order

Native /v1/messages, streaming

1. Same curl with -N -d @req_stream.json
2. Output (filtered to the two events that carry the verdict):

   event: message_start
   data: {"type":"message_start","message":{"id":"msg_fake_2b1891a365b8",...,"safeguard_results":{"verdict":"allow","checks":["shell_command"]}}}
   event: message_delta
   data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null, "safeguard_results": {"verdict": "allow", "checks": ["shell_command"]}}, "usage": {"output_tokens": 5}}
   

3. Upstream capture identical to the non-streaming leg: has_safeguards: True, full beta header

Real api.anthropic.com (costs real money)

1. Control: curl -s localhost:4000/v1/messages ... -d '{"model":"real-claude","max_tokens":16,"messages":[{"role":"user","content":"Say ok"}]}' returns 200 with "content":[{"type":"text","text":"ok"}]
2. Same call plus -H "anthropic-beta: safeguards-2026-09-01" and "safeguards":{"auto_mode":{...}} in the body returns 400 from Anthropic: Unexpected value(s) safeguards-2026-09-01 for the anthropic-beta header. Without the header Anthropic answers safeguards: Extra inputs are not permitted. Both errors come from Anthropic, which proves the proxy now forwards the field and the beta verbatim. The account used here is not enrolled in the safeguards beta, so the positive verdict is shown with the recording upstream above

Admin UI, http://localhost:4000/ui/logs

1. Open the Logs page. The two fake-claude rows at 17:08 are the fixed non-streaming and streaming calls, logged as Success with cost $0.000105, so logging and cost tracking tolerate the new field
   
2. Click the row, switch Request & Response to JSON. The logged request shows safeguards.auto_mode and the forwarded anthropic-beta: interleaved-thinking-2025-05-14,safeguards-2026-09-01 plus anthropic-version: 2023-06-01
   
3. The real-claude failure row shows Anthropic's own safeguards: Extra inputs are not permitted message, i.e. the field left the proxy
   

Handler branches exercised

Both arms go through anthropic_messages -> BaseLLMHTTPHandler.anthropic_messages_handler with custom_llm_provider="anthropic", i.e. AnthropicMessagesConfig. The non-streaming leg takes the JSON response branch, the streaming leg takes the AnthropicMessagesStreamingResponse raw SSE forward. The raw pass-through route POST /anthropic/v1/messages was also exercised: it forwards the body and headers verbatim already (upstream capture showed has_safeguards: True and the full beta before the fix), so no change was needed there. Cross-provider configs (bedrock, vertex_ai) keep filtering betas because should_filter_anthropic_beta_headers only returns False when the resolved provider is anthropic

Mutation checks

Removing safeguards from AnthropicMessagesRequestOptionalParams fails both new tests (2 failed), restoring the line passes them (2 passed), restore verified with cmp -s. Removing the should_filter_anthropic_beta_headers override fails the non-streaming test on the beta assertion. Removing safeguards from ANTHROPIC_ONLY_REQUEST_KEYS fails the new adapter test (1 failed). Removing safeguards from get_supported_anthropic_messages_params alone survives: that list does not gate request fields on this path, it is kept so the native supported surface stays truthful

Taxonomy audit

F3/O4 (sibling surfaces): streaming and non-streaming both covered by tests and live runs, /anthropic/* pass-through audited and untouched, the adapter path (/v1/messages to an OpenAI-format model) now strips safeguards like output_config so those backends do not get a 400. W1 (caller dict mutation): no new mutation, the fix only adds a key to an allowlist and an override returning a bool. X1 (falsy handling): safeguards is only dropped when None, an empty dict is forwarded. V1: no key routing change. C1-C7: beta filtering on the first-party anthropic provider changes from allowlist to pass-through, called out in Caveats. H: no new comments in source, X | None used, ReadOnly on both TypedDict fields, no budget files touched. T1-T5: both tests fail on the unfixed tree

Type

🐛 Bug Fix

Caveats (if any)

Low

• First-party anthropic route now forwards every anthropic-beta value, so a typo reaches Anthropic and returns their 400 instead of being silently dropped
• Positive safeguard_results proof uses a recording upstream; the real account is not enrolled in the beta

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

Link to Devin session: https://app.devin.ai/sessions/b5a306df827d4047a1cf9d8d41c0aba8
Open in Devin Desktop: https://app.devin.ai/desktop/session/b5a306df827d4047a1cf9d8d41c0aba8?variant=devin
Requested by: @yassin-berriai

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[codspeed]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_claude_code_safeguards_passthrough (1ac4d7a) with main (f008c01)¹}

Footnotes

1. No successful run was found on main (32133a3) during the generation of this report, so f008c01 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge, with all previous findings resolved and no new actionable defects identified

Summary

This PR preserves Anthropic safeguard fields and unrecognized beta values on native Anthropic Messages requests while preventing Anthropic-only safeguards from leaking into adapter-backed providers

• Adds the array-shaped request and response fields to the relevant TypedDict contracts
• Preserves all anthropic-beta values for the resolved Anthropic provider
• Strips safeguards before translating requests for non-Anthropic targets
• Adds regression coverage for non-streaming, streaming, and adapter paths

_{Reviews (3) · Last reviewed commit: "fix(anthropic): type safeguards and safe..."}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[devin-ai-integration]

@greptileai please re-review b59028d: safeguards now stripped on the adapter path, streaming chunk types carry safeguard_results, test docstrings removed

[yassin-berriai]

@greptileai please review the current head 1ac4d7a, which retypes safeguards and safeguard_results as arrays and updates the test fixtures