[FEATURE] RFC: Contextual Usage Policy Error Reporting

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

RFC: Contextual Usage Policy Error Reporting

Author: Dimitri Geelen
Date: 2026-04-20
Status: Draft
Related: RFC #45427 "Deterministic tool gate: hooks are necessary but insufficient for governance enforcement"

Triggering Error Example

API Error: Claude Code is unable to respond to this request, which appears to violate our Usage Policy 
(https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new 
session for Claude Code to assist with a different task. If you are seeing this refusal repeatedly, try 
running /model claude-sonnet-4-20250514 to switch models.

Problem Statement

The current usage policy enforcement system is fundamentally broken for professional use cases and violates basic principles of enterprise control.

Claude's black-box usage policy enforcement creates a governance failure cascade that actively undermines both user productivity and regulatory compliance requirements. Organizations investing in AI tooling are being systematically blocked from legitimate infrastructure work, security research, and system administration tasks without any mechanism to understand, audit, or override violations within their own compliance frameworks.

The Enterprise Control Gap

Organizations cannot fulfill their regulatory obligations when AI systems operate as black boxes. Modern regulatory frameworks (SOX, GDPR, SOC2, FedRAMP, ISO 27001) require organizations to demonstrate control over their technology stack — meaning documented, auditable, and configurable governance mechanisms.

Anthropic is implementing safeguards at the CLI layer (as acknowledged in our related RFC #45427 on deterministic tool gates), but this misses the fundamental enterprise requirement: organizations need the ability to define their own control policies, not merely accept vendor-dictated restrictions they cannot see, understand, audit, or modify.

This isn't about bypassing safety — it's about regulatory compliance and organizational sovereignty, Enterprises need:

• Auditable control frameworks that document what policies are enforced and why
• Configurable policy boundaries that align with their specific compliance requirements
• Override mechanisms for legitimate business use cases within their risk tolerance
• Audit trails that demonstrate due diligence to regulators and auditors

The Security Paradox, this Dysfunction is Systemic

Black-box enforcement actively weakens security posture and violates "control" requirements. Organizations cannot:

• Audit their AI usage for compliance violations they can't see
• Train their teams on policy boundaries they can't understand
• Implement preventive measures for violations they can't predict
• Document their compliance efforts when the system provides no violation records
• Demonstrate control to auditors when policies are vendor-imposed and opaque

This isn't user-unfriendly — it's user-hostile and compliance-toxic.

Real-World Regulatory Impact, the Control Framework Imperative

"Control" is not a nice-to-have — it's a regulatory requirement. Organizations subject to compliance frameworks cannot delegate control decisions to black-box vendor systems. Anthropic's current approach forces organizations to operate in violation of their own control frameworks.**

This is blocking regulated organizations from AI adoption entirely. Organizations are forced to choose between AI tooling and regulatory compliance.**

The Trust and Learning Deficit

We appreciate that Anthropic is learning and evolving their approach to AI safety. The CLI-layer safeguards show recognition that governance needs improvement. **However, we need Anthropic to acknowledge this enterprise control gap and maintain an open ear to organizational requirements.

Opaque enforcement without organizational override capabilities erodes trust and creates adversarial relationships.Users experiencing repeated blocks without explanation begin to:

• Work around the system rather than with it
• Avoid legitimate but "risky" topics that might trigger unknown violations
• Develop negative sentiment toward AI safety and governance efforts
• Seek alternative tools that provide the control frameworks their compliance requires

This undermines Anthropic's broader mission of beneficial AI adoption in enterprise contexts.

Technical Context

Affected Model: Claude Opus 4.7 (1M context)
Model ID: claude-opus-4-7[1m]
Platform: Claude Code CLI
Enforcement Behavior: Binary block with session termination
System Recommendation: Switch to claude-sonnet-4-20250514

Policy enforcement appears to be model-specific, with claude-opus-4-7[1m] showing particularly restrictive behavior around:

• Hexadecimal strings ≥64 characters (interpreted as cryptographic keys)
• Network configuration documentation (IP addresses, VPN configs)
• Infrastructure topology content
• Inter-agent authentication protocols

Critical observation: The error message recommends model switching rather than content modification, indicating:
Policy enforcement varies by model rather than being consistent across the platform

Context: Error triggered during legitimate agentic engineering work involving:

• Inter-agent communication protocols
• VPN configuration management
• Cryptographic key exchange for agent authentication
• Infrastructure topology documentation

Suspected trigger: Hexadecimal string 79f4c6b468e42c8ff4e49534c415c8ab1df6cad95e28b0c315ae9749dc62b925 in agent-to-agent authentication handshake.

User impact: Complete session halt, no identification of problematic content, no path to resolution.

Proposed Solution

Proposed Solution: Contextual Error Classification

1. Violation Type Taxonomy

Replace generic blocking with specific violation categories:

CREDENTIAL_DETECTION: Potential private key, token, or secret detected
NETWORK_SECURITY: Network configuration or access pattern flagged  
COORDINATION_CONCERN: Multi-agent or automated system coordination
CONTENT_POLICY: Content violates acceptable use guidelines
SAFETY_CONCERN: Potential harm or misuse scenario identified

2. Contextual Error Response Format

{
  "error": "USAGE_POLICY_VIOLATION",
  "violation_type": "CREDENTIAL_DETECTION", 
  "trigger_pattern": "64-character hexadecimal string",
  "suggested_resolution": "Replace with placeholder (e.g., [HEX_KEY_REDACTED])",
  "policy_reference": "https://anthropic.com/legal/aup#credentials",
  "allow_retry": true,
  "organizational_override": "contact_admin"
}

3. Graduated Response System

Instead of binary block/allow:

Level 1 - Warning + Guidance:

⚠️  Potential credential detected in your message. If this is a real key, 
    consider using a placeholder. Continue anyway? [Y/N]

Level 2 - Soft Block + Alternatives:

🚫 Content appears to contain private credentials. Suggested approaches:
   • Use placeholder tokens ([API_KEY], [SECRET])  
   • Reference credential types without actual values
   • Use environment variable references ($SECRET_KEY)
   • Request organizational override from admin
   [Edit Message] [Learn More] [Request Override] [Contact Support]

Level 3 - Hard Block (current behavior):
Reserved for clear policy violations with no legitimate use case.

Implementation Requirements

For API/Web Interfaces

1. Structured error responses with violation type and guidance
2. Edit-in-place functionality allowing users to modify flagged content
3. Policy documentation links specific to violation type
4. Escalation path for disputed violations
5. Organizational override mechanisms for enterprise accounts

For Claude Code CLI

1. Inline violation markers showing specific problematic content
2. Auto-suggestion engine proposing compliant alternatives
3. Whitelist/exception mechanism for trusted organizational patterns
4. Audit logging of policy triggers for compliance review
5. Admin override capabilities for organizational control

For Organizations

1. Policy configuration dashboard for org-specific exceptions and overrides
2. Violation analytics showing patterns across team usage
3. Training integration linking violations to educational resources
4. Compliance reporting for security/legal review
5. Control framework integration with existing governance systems

Benefits

For Users:

• Clear understanding of what triggered violations
• Actionable steps to achieve compliance
• Reduced session disruption and frustration
• Learning opportunities about policy boundaries

For Organizations:

• Regulatory compliance through auditable control frameworks
• Policy sovereignty with configurable organizational boundaries
• Audit trail generation for compliance documentation
• Risk management within organizational tolerance levels

For Anthropic:

• Higher enterprise adoption and satisfaction
• Better policy compliance through organizational alignment
• Reduced false positive escalations and support burden
• Partnership approach rather than adversarial vendor relationship

Success Metrics

• Violation resolution rate: % of users who successfully modify content after guidance
• False positive reduction: Decrease in disputed/overturned violations
• Enterprise satisfaction: NPS improvement for organizational control experience
• Compliance documentation: % of organizations able to generate required audit trails
• Support ticket reduction: Fewer escalations about blocked content

Open Questions

1. Performance impact: How much latency does violation classification add?
2. Privacy concerns: What violation details can be safely surfaced?
3. Enterprise integration: How do org-specific policies interact with base policy?
4. Override governance: What controls prevent override abuse while enabling legitimate use?
5. Regulatory alignment: How do organizational policies map to different compliance frameworks?

---

Next Steps:

1. Technical feasibility assessment with safety/policy teams
2. Enterprise stakeholder consultation on control framework requirements
3. Regulatory compliance review of organizational override mechanisms
4. User research on preferred error experience patterns
5. Prototype implementation for common violation types
6. Beta testing with infrastructure/security practitioner cohorts

This RFC addresses the enterprise control gap in AI governance systems — organizations need configurable, auditable, and transparent policy enforcement to maintain regulatory compliance while enabling legitimate AI adoption.

We appreciate Anthropic's continued learning in this space and hope for acknowledgment of these enterprise requirements and an ongoing dialogue about organizational control frameworks.

Alternative Solutions

_No response_

Priority

Critical - Blocking my work

Feature Category

API and model interactions

Use Case Example

Use Case Examples

Here are concrete scenarios where contextual error reporting transforms blocked workflows into productive ones:

Use Case 1: Infrastructure Documentation

Scenario: DevOps engineer documenting VPN configuration for compliance audit

Current experience:

User: "Here's our WireGuard config for the production environment:

[Interface]
PrivateKey = yAnz4TF+lXXWRTuPiwo2gHaFQafztkHjP8Ny5sVo= 
Address = 10.0.0.1/24

[Peer]  
PublicKey = xTIBA5rboUvnvEUr4EyIbhyoOGQO9XlYTXPgABWsRt4=
Endpoint = vpn.company.com:51820"

Claude: API Error: violates Usage Policy [session terminated]

Result: Engineer can't document infrastructure, audit fails, compliance gap.

Proposed experience:

Claude: ⚠️ Potential private keys detected. For documentation, consider:
• Use placeholder: PrivateKey = [REDACTED_PRIVATE_KEY]
• Reference key types: "WireGuard private/public key pair" 
• Use environment variables: PrivateKey = $VPN_PRIVATE_KEY

Continue with actual keys? [Admin Override Required] [Edit Message] [Learn More]

Result: Engineer understands issue, documents properly, audit succeeds.

Use Case 2: Security Research

Scenario: Security team analyzing threat patterns for board presentation

Current experience:

User: "The attack used these compromised API keys we found in logs:
sk_live_4f5e6d7c8b9a0e1f2g3h4i5j6k7l8m9n
ak_prod_9n8m7l6k5j4i3h2g1f0e9d8c7b6a5f4"

Claude: API Error: violates Usage Policy [session terminated]

Result: Security analysis blocked, threat intelligence incomplete, board uninformed.

Proposed experience:

Claude: 🔍 API credential patterns detected. For security analysis:
• Anonymize: sk_live_[REDACTED_32_CHARS]  
• Categorize: "Stripe live API key, AWS access key"
• Hash reference: "Keys SHA256: a1b2c3d4..."

Organizational policy: Security team authorized for credential analysis
[Continue with Override] [Sanitize and Continue] [Contact Admin]

Result: Analysis proceeds with appropriate safeguards, threat intelligence complete.

Use Case 3: Agent Development

Scenario: AI engineer building multi-agent authentication system

Current experience:

User: "Agent handshake protocol needs secure key exchange:

def exchange_keys(self, peer_agent):
    my_secret = '79f4c6b468e42c8ff4e49534c415c8ab1df6cad95e28b0c315ae9749dc62b925'
    return hmac.new(my_secret.encode(), peer_agent.identity, hashlib.sha256)"

Claude: API Error: violates Usage Policy [session terminated]

Result: Agent development stalled, authentication system incomplete.

Proposed experience:

Claude: 🔐 Hardcoded secret detected in agent code. Secure alternatives:
• Environment variable: my_secret = os.getenv('AGENT_SECRET')
• Key derivation: my_secret = derive_key(agent_id, master_secret)  
• Hardware security: my_secret = hsm.get_key(key_id)

For development/testing with mock keys?
[Continue with Mock Data] [Show Secure Patterns] [Edit Code]

Result: Engineer learns secure patterns, develops robust authentication.

Use Case 4: Compliance Documentation

Scenario: Legal team documenting data processing controls for GDPR audit

Current experience:

User: "Our API authentication uses these rotation patterns:
- Production: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
- Staging: Basic YWRtaW46cGFzc3dvcmQ=  
Document these for the GDPR processor agreement."

Claude: API Error: violates Usage Policy [session terminated]

Result: Legal documentation incomplete, GDPR compliance at risk.

Proposed experience:

Claude: ⚖️ Authentication credentials in compliance document. Best practices:
• Token format: "Bearer [JWT_TOKEN]" (without actual values)
• Encoding type: "Basic [BASE64_ENCODED_CREDENTIALS]"  
• Rotation policy: "Tokens rotate every 90 days per security policy"

Generate compliant documentation template?
[Create Template] [Anonymize Current] [Compliance Guidelines]

Result: Legal gets compliant documentation, GDPR audit succeeds.

Additional Context

_No response_