Chio/Docs

LearnAnatomy of a Governed Call

Guards

A guard checks a tool call before it proceeds; an evaluation error produces a deny verdict.

Capabilities and guards

A capability token is the mandate an agent acts under. At call time, the guard pipeline checks whether the request stays within that grant. See The Mediated Call for the full sequence guards sit inside.

The Guard Trait

Each guard in the catalog implements the same trait: a name and an evaluation function.

chio-kernel/src/kernel/mod.rs
pub trait Guard: Send + Sync {
    /// Short, kebab-case identifier (e.g., "forbidden-path").
    fn name(&self) -> &str;

    /// Evaluate the guard against one tool-call request.
    /// The kernel treats Err exactly like Deny: fail-closed is in
    /// the return type, not a convention layered on top of it.
    fn evaluate(&self, ctx: &GuardContext) -> Result<GuardDecision, KernelError>;
}

GuardDecision bundles a Verdict with guard evidence for the receipt. Verdict has exactly three variants: Allow, Deny, and PendingApproval. There is no Skip: a guard that does not apply to the current request simply returns Allow. The full struct fields, the constructors, and the narrower trait variant that runs unchanged on desktop, browser, and mobile are on the Kernel's Guard Trait page.

Guards and Hooks

The relevant distinction is when a guard runs. An input guard evaluates a request before the tool executes and gates the call: its verdict is Allow, Deny, or PendingApproval, and a deny or pending verdict means the tool never runs. A post-invocation hook evaluates the tool's response after it returns: it cannot undo the call, only decide what the caller is allowed to see, and its verdict is Allow, Redact, Block, or Escalate. See The Mediated Call for where each checkpoint sits in the seven-step sequence, and Human-in-the-Loop for the human side of PendingApproval.

Guard Pipeline Behavior

Guards do not run in isolation. A GuardPipeline is itself a Guard: it holds an ordered list of guards and folds their verdicts into one. The first Deny, or the first Err, short-circuits the whole pipeline: later guards never run and never appear in the receipt's evidence. A PendingApproval verdict is sticky rather than immediate: the pipeline keeps evaluating whatever is left, in case a later guard denies outright, and only surfaces once nothing else says Deny.

Guard order and latency

The fixed order runs cheap, stateless checks before expensive or session-aware ones. A request denied by the last guard receives the same deny verdict as one denied by the first guard, but evaluation can take longer. See Pipelines & Composition for the other pipeline shapes: advisory, post-invocation, and the external-adapter wrapper.

Advisory Guards and Promotion Policy

An advisory guard runs alongside the deterministic pipeline and records a severity-rated signal. Its advisory result does not itself return Deny. A PromotionPolicy matches a signal's guard name and severity against rules. A matching rule changes that call's verdict to Deny. A deployment can observe a pattern before enabling a promotion rule. See Advisory Guards for AdvisorySignal, the trait, and how the matching rule reads severity.

The Catalog, By Family

The catalog groups guards by what they inspect. Configuration, defaults, and scenarios are on each family's Kernel page.

Filesystem, Network, and Shell

The largest family covers where an agent can read or write, which domains it can reach, and which shell commands it can run: a forbidden-path denylist and an opt-in allowlist for the filesystem, a domain allowlist plus an SSRF-blocking guard for the network, and command, code-execution, and patch-integrity guards for shell and code. Which tools an agent may even name is its own tool_access allowlist. See Filesystem Guards, Network Guards, and Shell & Code Guards.

Rate Limiting and Behavioral Baselines

Rate limiting runs on token buckets: one guard throttles a single capability grant, and a second throttles a whole agent across every grant it holds in a session, both keyed in integer milli-tokens so no floating-point drift creeps in over a long-running session. Behavioral baselining watches the shape of a session instead of any one call: an ordered-tool-sequence check and a drift baseline over recent receipts flag an agent that remains below each individual rate ceiling but moves in a pattern absent from its recent history. See Rate Limit Guards and Session-Aware Guards.

Jailbreak and Prompt Injection

Two opt-in guards scan free-form text for adversarial framing rather than structured arguments: a jailbreak detector blending regex, statistical features, and a small linear model, and a lighter prompt-injection scan over the same canonicalized input. Neither is in the default pipeline; both exist for deployments that accept untrusted natural-language input as a tool argument. See Jailbreak & Injection Guards.

Response Sanitization

This family shows post-invocation hooks: content returned by a tool call is scanned for secrets, then redacted, blocked, or passed through, mostly after the tool has run. A related guard reviews outbound content before it leaves the kernel, when the destination itself is the sensitive part. See Response Sanitization.

Computer Use

Several guards cover computer use: a coarse allowlist on action types, a fine-grained input-injection gate, per-channel toggles for remote-desktop side channels, a browser-automation gate with credential detection, and an anomaly detector over action embeddings, composed conjunctively so a coarse allow never overrides a fine-grained deny underneath it. See Computer Use Agent Guards.

Approval and Human-in-the-Loop

A guard can also return PendingApproval, suspending a call for a human co-signature instead of resolving it immediately. This is where the pipeline hands off to an approval channel, a resume flow, and a signed approval token, described in full on Human-in-the-Loop. See Approval & HITL for the pipeline-side mechanics.

Memory Governance

Agents that persist context across calls write into a memory store; a governance guard caps what they can write, where, how long, and how much per session. See Memory Governance.

Data Layer

Several guards sit between the kernel and a database tool server: two pre-invocation gates check a SQL or vector-database query, another caps warehouse cost with a dry-run estimate, and a post-invocation hook reshapes the result set the agent actually sees. See Data-Layer Guards.

External Adapters

Some guards are not local checks: they call out to a third-party safety or threat-intel provider (a content-safety API, a malware scanner, a URL reputation service) through one generic async adapter with a circuit breaker, a cache, and a retry loop, bridging back to the same synchronous guard interface. See External Guard Adapters.

Advisory

The advisory family described above (anomaly detection, data-transfer signals, behavioral-profile drift) lives here as named guards. See Advisory Guards for the guards themselves and the thresholds a promotion rule matches.

Authoring Guards

The catalog above is not closed, and extending it does not require forking Chio. HushSpec, Chio's YAML policy format, compiles rule blocks like forbidden_paths or velocity down to the same native guards described here: writing a policy is authoring guards through a schema instead of a trait. Below YAML, a guard can be a Guard implementation compiled into the kernel binary, or a WebAssembly module the kernel loads at runtime, sandboxed and fuel-metered, with no fork or recompile required. WASM is the supported extension interface for most deployments; native Rust guards are for changes to Chio itself. See HushSpec Policy Format, Custom WASM Guards, and Custom Guards.

Next Steps

PreviousCapabilitiesNextHuman-in-the-Loop