Guardrail

@kindgi/specs/guardrail.schema.json, schema version 1.1.0.

An assertion about agent behavior. Enforced at runtime (halt / retry / escalate / log-only / compensate per guardrail) AND in CI (blocks builds). Same definition, two enforcement paths — no drift between what tests check and what prod enforces. Zero-LLM checks are default (fast, deterministic); LLM-judge scorers are an opt-in class with explicit cost declaration. Schema-version 1.1.0 matches the Guardrail type: check is required, a retry action needs maxAttempts, kind and on-violation accept any non-empty string (the built-ins are listed as examples), and sandbox / limits / network / needsSpec are allowed.

• id (string, required): Unique guardrail identifier.
• name (string): Human-readable name.
• description (string): What this guardrail guarantees, and what happens if violated.
• kind (string, required): How the guardrail is checked. Open string: the engine dispatches it to the execution strategy registered for that kind, and defineGuardrail requires a registered check of the same kind. Built-in kinds: 'zero-llm' = pure function over run trace (default, fast, deterministic). 'llm-judge' = uses a model to score (opt-in, costs money). 'external' = evaluated outside the engine by a caller-registered strategy (the built-in 'external' strategy returns an error). Adapters can register strategies for their own kinds.
• check (string, required): Id of the check in the CheckRegistry. For zero-llm: a built-in check ('must-cite', 'never-call-tool', 'max-tool-calls', 'output-matches', 'tool-order', 'required-substring', 'forbidden-substring') or a custom check id. For llm-judge: the id of a registered check of kind 'llm-judge' (the judge is configured by config and judgeCapabilities). For external and adapter kinds: an id the kind's strategy understands. Required since schema-version 1.1.0 (defineGuardrail already failed without a registered check).
• config (map of any): Check-specific configuration. Interpreted by the check implementation.
• action (Action, required)
• severity ("info" | "warn" | "error" | "critical")
• scope (Scope): When this guardrail applies: 'always' (every run), 'ci-only' (blocks CI, not runtime), 'runtime-only' (runtime enforcement, not CI), or a per-agent/per-flow selector.
• budget (object): For llm-judge guardrails: cost budget per invocation. Declarative — not enforced by the runtime.
  • maxCostUsd (number)
  • maxLatencyMs (integer)
• sandbox ("none" | "context-isolated" | "strict"): Isolation posture the runtime enforces around the check's handler. Same values as a tool's sandbox. Added in schema-version 1.1.0.
• limits (object): Sandbox-enforced resource caps while the check runs. Same shape as a tool's limits. Added in schema-version 1.1.0.
  • memMB (integer, required)
  • cpuMs (integer, required)
• network (object or object): Network egress policy the sandbox honors while the check runs. Discriminated on kind; same shape as a tool's network. Added in schema-version 1.1.0.
• needsSpec (object): Typed discriminated needs of the check (env / secrets / config / capabilities / bindings). Same shape as a tool's needsSpec. Added in schema-version 1.1.0.
  • env (map of object)
  • secrets (map of object)
  • config (map of object)
  • capabilities (array of string)
  • bindings (array of string)
• codeArtifactRef (object or object): Handler-artifact pointer for the guardrail's check implementation. Discriminated on kind: oci is the deploy-pipeline shape (image + module path + artifactVersion); filesystem is the local-development shape — absolute host path at the check module. Production servers SHOULD reject filesystem.
• judgeCapabilities (map of any): For llm-judge guardrails: capability declaration for the judge model. Routed through @kindgi/capabilities over the providers bound for evaluation; when the caller passes a tenant policy (an agent turn passes its own), the judge is routed under it. BYO judges supported.

Definitions

Action

• on-violation (string, required): What happens when the guardrail fires. Open string: any non-empty name is accepted here, and an action handler registered under that name applies it; when the caller evaluates with an action-handler registry, a name with no handler fails with unknown-action. Built-in actions: 'halt' = fail the run. 'retry' = re-execute the step (needs retry.maxAttempts). 'escalate' = route to HITL review. 'log-only' = record but don't block. 'compensate' = invoke a compensation action.
• retry (object): For on-violation = 'retry'.
  • maxAttempts (integer, required)
• escalateTo (string): For on-violation = 'escalate': reviewer role or queue id.
• compensateWith (string): For on-violation = 'compensate': tool id to invoke as compensation.

Scope

• when ("always" | "ci-only" | "runtime-only")
• agents (array of string): Agent ids this guardrail applies to. Empty = all agents.
• flows (array of string): Flow ids this guardrail applies to. Empty = all flows.
• tenants (array of string): Tenant ids this guardrail applies to. Empty = all tenants.