2026-03-26-guardrail-transparency

Guardrail Transparency

Date: 2026-03-26 Phase: 087-guardrail-transparency Systems: guardrails, completions, security

What

When guardrails modify a response (PII redaction, tool blocking, content filtering), new headers surface exactly what changed: positions, types, and reasons.

Headers

Header	When	Example
X-BR-Guardrail-Summary	Every response	clean, modified:pii=2,tool=1, blocked:content_policy
X-BR-Guardrail-Actions	Only when modifications occur	URL-encoded JSON array of action objects

Action Types

• pii_redacted — entity type, position, replacement string
• tool_blocked — tool name, reason (deny list, policy)
• content_filtered — category, action (warn/blocked), reason
• response_truncated — original/truncated lengths, reason

Implementation

• src/api/middleware/guardrail-transparency.ts — GuardrailActionCollector class with typed action methods, summary builder, header serialization with 4KB cap, streaming payload support
• Header size capped at 4KB with truncation indicator
• CORS: already handled (Access-Control-Expose-Headers: *)

Lockstep Checklist

• [x] API: New guardrail transparency module
• [x] Tests: 13 tests — collection, summary, header encoding, truncation, streaming
• [x] Docs: This ship log
• [x] SDK-TS: N/A (headers automatic)
• [x] SDK-PY: N/A
• [x] MCP: N/A
• [x] CLI: N/A
• [x] GTM: N/A
• [x] Dashboard: N/A