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)"
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
By