Guardrails

---
context: fork
name: guardrails
description: "Input/output and per-tool guardrails with tripwire semantics. Auto-activates when: an agent processes untrusted input, calls a sensitive tool, or must short-circuit on a policy violation. Triggers: guardrail, input validation, tripwire, tool guardrail, policy check, refusal, agent safety."
lang: [en]
level: 2
triggers: ["guardrail", "input validation", "tripwire", "tool guardrail", "policy check", "refusal", "agent safety"]
agents: ["security-reviewer", "backend-developer", "architect"]
tokens: "~2K"
category: "safety"
platforms: [claude-code, gemini-cli, codex-cli, cursor]
whenNotToUse:
  - "Trivial single-call utilities with no untrusted input"
  - "Pure-function tools whose output is already type-checked at the call site"
  - "Operations where blocking is unsafe (logging, telemetry stubs)"
source_hash: 3406edd4
---

# Guardrails: Input, Output, and Tool-Level Policy Enforcement

## Overview

Guardrails are async checks that run alongside agent input/output and per-tool invocations. A "tripwire" result short-circuits the run with either a refusal message or a thrown `GuardrailTripped` error. The Artibot implementation lives in `lib/orchestration/guardrails.js` (top-level) and `lib/orchestration/tool-guardrails.js` (per-tool registry).

## When to Use

- The agent receives free-form user input that could contain prompt injection, PII, or jailbreak content
- A tool exposes a sensitive surface (file write, network egress, shell exec) that needs an extra gate
- Output policy must enforce a structured shape before returning to the user
- Multiple concurrent checks must run in parallel and any single trip should halt the run

## When NOT to Use

- A single-file utility with type-checked inputs and no user-facing surface
- A pre-existing static validator (Zod/Pydantic) already covers the contract
- The check is performance-critical hot-path (guardrails add async overhead)
- The intent is to log only — use the `on_llm_end` hook instead

## Process

| Step | Action |
|---|---|
| 1 | Identify the smallest input/output boundary (per-agent vs per-tool) |
| 2 | Write a `Guardrail` (or `registerToolGuardrail`) returning `{ tripwireTriggered, info, refusal? }` |
| 3 | For per-tool, decide behavior: `reject_content` (continue with refusal) vs `raise_exception` (throw) |
| 4 | Run via `runAll(guardrails, ctx, input)` or `evaluateToolInput(toolName, params)` |
| 5 | Test the tripwire fires for a known-bad input and stays silent on a clean input |

## Common Rationalizations

| Excuse | Rebuttal |
|---|---|
| "the LLM will refuse it anyway" | LLM refusal is probabilistic; guardrails are deterministic |
| "we already have Zod schemas" | Zod validates shape; guardrails validate intent and policy |
| "it slows down every call" | Run in parallel via `Promise.all`; cost is the slowest check, not the sum |
| "we will catch it in the post-hoc review" | Post-hoc means production already saw the bad output |

## Red Flags

- A guardrail that returns `tripwireTriggered: false` for every input it has ever seen
- A single guardrail that mutates the input in place (guardrails must be pure)
- Behavior `raise_exception` used on a customer-facing tool without a global error handler
- Per-tool guardrails registered globally at module import (use explicit registration in the run setup)

## Verification

- `tests/lib/orchestration/guardrails.test.js` — runAll parallelism + tripwire propagation
- Manual: register a known-bad guardrail, call `evaluateToolInput`, confirm refusal payload
- DATA POLICY: guardrails MUST NOT call out to external HTTP services for decisions