[BUG] Bedrock Guardrails cannot be applied via ANTHROPIC_CUSTOM_HEADERS — need first-class SDK support

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report
• [x] I am using the latest version of Claude Code

What's Wrong?

When using Claude Code with AWS Bedrock, there is no supported way to apply Bedrock Guardrails to requests. Issue #1830 suggested using ANTHROPIC_CUSTOM_HEADERS to set X-Amzn-Bedrock-GuardrailIdentifier and X-Amzn-Bedrock-GuardrailVersion headers, but this approach is insufficient for IAM policy enforcement.

Root Cause

The @anthropic-ai/bedrock-sdk sends raw HTTP requests signed with SigV4. While the guardrail headers are sent and signed correctly, AWS IAM condition keys (bedrock:GuardrailIdentifier) evaluate against request context populated by the AWS service's API parameter layer. When using the official AWS SDK (boto3 / @aws-sdk/client-bedrock-runtime), API parameter serialization populates this context correctly. The Anthropic Bedrock SDK's raw HTTP approach may not populate the IAM request context the same way.

Additionally, the @anthropic-ai/bedrock-sdk has no first-class API for configuring guardrails — users must rely on undocumented header injection.

Comparison: boto3 vs Claude Code

| Aspect | boto3 (InvokeModel) | Claude Code (Bedrock SDK) |
|--------|----------------------|--------------------------|
| Guardrail config | guardrailIdentifier + guardrailVersion API params | No first-class support |
| IAM context | Populated by API layer | May not populate correctly |
| Header injection | Not needed | Required workaround via ANTHROPIC_CUSTOM_HEADERS |

What Should Happen?

Claude Code should support Bedrock Guardrails via dedicated environment variables:

• BEDROCK_GUARDRAIL_IDENTIFIER — Guardrail ID or full ARN
• BEDROCK_GUARDRAIL_VERSION — Version number (e.g., "1") or "DRAFT"

These should be passed to AnthropicBedrock({ guardrailIdentifier, guardrailVersion }) in the underlying SDK.

Steps to Reproduce

1. Create a Bedrock Guardrail in the AWS Console
2. Set an IAM policy requiring guardrail usage via condition keys
3. Configure Claude Code with CLAUDE_CODE_USE_BEDROCK=1
4. Set ANTHROPIC_CUSTOM_HEADERS="X-Amzn-Bedrock-GuardrailIdentifier:your-id,X-Amzn-Bedrock-GuardrailVersion:1"
5. Run Claude Code — requests may be denied by IAM despite headers being present

Proposed Fix

SDK side: Add guardrailIdentifier and guardrailVersion as first-class ClientOptions in @anthropic-ai/bedrock-sdk, with env var fallback to BEDROCK_GUARDRAIL_IDENTIFIER and BEDROCK_GUARDRAIL_VERSION. Headers are injected in buildRequest() before SigV4 signing.

Claude Code side: Read BEDROCK_GUARDRAIL_IDENTIFIER and BEDROCK_GUARDRAIL_VERSION env vars and pass them to the AnthropicBedrock constructor.

Related

• #1830 (closed) — original workaround via ANTHROPIC_CUSTOM_HEADERS

Environment

• Claude Code Version: 2.1.31
• Platform: AWS Bedrock
• Regression: No, this never worked
• OS: macOS (but applies to all platforms)
• Terminal: Any