Guardrails

Guardrails are policy checks that run at three points in an agent turn: before a user message reaches the worker, before the worker’s text reaches the user, and before a tool call is authorized. They are how you stop a worker from leaking a secret, echoing PII, or invoking a destructive tool, independent of the prompt, so a jailbroken or buggy worker still hits the same wall.

Each guardrail targets exactly one stage and returns a verdict. The gateway runs every enabled guardrail for a stage in parallel and acts on the first one that trips.

Stages

Stage	When it runs	What it inspects	On trip
`input`	User message to worker, before dispatch	The raw user message	Dispatch is skipped; the user gets `Message rejected: <reason>`
`output`	Worker text to user, per streaming delta	The worker’s output text	The stream is disposed, the partial buffer dropped, and `Message blocked by guardrail: <reason>` is posted
`pre-tool`	Tool call, before authorization	The tool name plus serialized arguments	The worker receives `isError: true` with `Tool call blocked by policy.`

The pre-tool block message is intentionally generic. The real reason is hidden from the worker because leaking why a tool was blocked is an evasion surface. The input and output reasons are surfaced to the user, who is trusted.

How the runner behaves

runGuardrails(registry, stage, enabled, ctx) races all enabled guardrails for the stage:

First trip wins. The runner short-circuits on the first guardrail that trips; the others keep running but their results are discarded.
Fail open. A guardrail that throws is logged and treated as a pass. Guardrails that need halt-on-error semantics must catch their own errors and return { tripped: true }. So an infrastructure failure (a judge API timeout, say) never wedges the turn; it weakens enforcement instead of blocking traffic.
No-op when empty. If no guardrails are enabled for a stage, the runner returns immediately.

Built-in guardrails

Three primitives ship from the gateway and are registered at boot. Reference them by name in lobu.config.ts.

Name	Stage(s)	Catches
`secret-scan`	`output`	Credential-shaped strings in worker output: OpenAI keys (`sk-…`), GitHub PATs (`ghp_…`), AWS access keys (`AKIA…`), and JWT-shaped tokens. Cheap enough to run per streaming delta.
`pii-scan`	`input`, `output`, `pre-tool`	Emails, US-shaped phone numbers, and Luhn-valid 13-19 digit card-shaped runs. On `pre-tool` it scans the serialized tool arguments.
`forbidden-tools`	`pre-tool`	A hardcoded deny list: `delete_repo`, `delete_branch`, `drop_table`.

secret-scan and forbidden-tools are stage-locked, so they only ever run at their natural stage. pii-scan is registered once per stage, so enabling pii-scan covers input, output, and pre-tool.

Enabling guardrails

List built-in (or globally-registered) guardrail names on the agent in lobu.config.ts:

import { defineAgent } from "@lobu/cli/config";

const assistant = defineAgent({
  id: "assistant",
  name: "assistant",
  dir: "./agents/assistant",
  guardrails: ["secret-scan", "pii-scan", "forbidden-tools"],
});

Names that don’t resolve to a guardrail registered in the gateway’s GuardrailRegistry at startup are logged and skipped. A typo silently disables protection rather than failing the boot, so check the startup logs after changing this list.

Inline LLM judges

When a regex won’t express the policy, attach an ad-hoc LLM-judge guardrail in the agent’s settings (via the /agents admin UI or the agent settings API). Each entry names a stage and a judge prompt; the gateway materializes it into a guardrail at resolve time.

Each inline judge has:

stage, one of input, output, pre-tool.
tools, which narrows a pre-tool judge to specific tool names (e.g. github.delete_repo); it is ignored for other stages.
judge, the policy text the LLM evaluates the stage context against (e.g. “Never mention competitor product names.”).

Inline judges run through a shared judge client with a verdict cache and a circuit breaker that fails closed after repeated failures (the same machinery as the egress judge). Each inline entry materializes into a guardrail named inline:<stage>:<hash8>, so operators can target it for disabling.

Skill-provided guardrails

A skill can declare its own pre-tool guardrails in its SKILL.md, either a built-in by name or an inline judge. These are added when the skill is enabled, so a skill that ships a destructive tool can also ship the policy that gates it. Skill-declared inline judges are named skill:<name>:inline:pre-tool:<hash8>.

Skills can only add pre-tool guardrails. They cannot weaken input/output policy.

Operator overrides

The full set for an agent is the union of enabled built-ins, skill-provided guardrails, and inline judges, deduplicated by name within each stage. The operator’s exclude list, set in the agent’s settings, is applied last and wins. For example, disabling a built-in like pii-scan and a skill’s judge like skill:github:inline:pre-tool:1a2b3c4d.

The disabled list matches against each guardrail’s resolved .name, including the synthesized inline:<stage>:<hash8> and skill:<name>:inline:pre-tool:<hash8> names. Because it is operator-only and applied last, it is the single override point: a skill cannot re-enable something an operator disabled.

The merge happens in resolveAgentGuardrails(); see packages/server/src/gateway/guardrails/aggregator.ts and judge-factory.ts for the resolution order, judge cache, and circuit breaker.

Auditing

Every trip, at any stage, built-in or judge, writes an event with semantic_type='guardrail-trip', so operators can review what fired and why without the worker or user seeing the internal reason. The trip is recorded even though the pre-tool reason is hidden from the worker.