The Kernel · Chio Docs

Where to start

If you are new to Chio, read this page top to bottom, then jump into Architecture for the crate map and The Guard Trait for the interface a single guard implements.

Mental Model

An agent issues a tool call. The kernel intercepts that call, walks a verified capability through a pipeline of guards, and produces a verdict. If every guard agrees, the kernel forwards the call to the tool server. The tool runs and returns a response. The kernel writes a signed receipt. Nothing reaches the tool unless the pipeline allowed it; nothing reaches the agent without a receipt.

The kernel mediates calls between an untrusted agent and a tool server. It validates the capability, evaluates guards, and signs a receipt for each outcome.

The diagram above is the spatial view: where each component sits and what role it plays. The sequence below is the temporal view: the steps a single call walks through from request to response.

rendering…

Agent issues a request, the kernel evaluates the guard pipeline, the tool runs, and a receipt is written.

Three properties hold for every call through the kernel:

Synchronous evaluation. The guard pipeline runs to completion before the tool is invoked. There is no probabilistic admission and no asynchronous deferral on the critical path.
Fail-closed. Any guard that returns Verdict::Deny or anErr stops the call. See Fail-Closed Semantics.
Receipts always. Allowed calls, denied calls, and human-pending calls all produce a signed receipt. The receipt is the audit boundary.

Glossary

These terms recur throughout the Kernel docs. The definitions here are the ones the source code uses.

Term	Meaning
`Guard`	A type that implements the sync `Guard` trait. One `name()` and one `evaluate()` method. `evaluate()` returns `Ok(GuardDecision)`, a `Verdict` plus the evidence the guard recorded, or an `Err` the kernel treats as a deny.
`Pipeline`	An ordered collection of guards, itself wrapped as a single `Guard`. Evaluates in registration order. Three flavors: `GuardPipeline`, `AdvisoryPipeline`, `PostInvocationPipeline`.
`Verdict`	The three-valued outcome of guard evaluation: `Allow`, `Deny`, or `PendingApproval`. `Copy + Clone`, no payload. The full kernel can also produce `PendingApproval`; the portable core never does.
`Evidence`	Structured findings a guard records on the receipt. Examples: redaction summaries from the sanitizer, provider decision identifiers from external guards, advisory signals.
`Capability`	A signed token that names what an agent can invoke. The kernel verifies the signature, expiry, and subject binding before guards run. See Capabilities.
`Receipt`	The signed record of one evaluation. Carries the verdict, the guard evidence, advisory signals, and the policy hash used. See Receipts.
`Advisory`	A non-blocking signal. Recorded as evidence, never a denial, unless promoted by a `PromotionPolicy`.

Guard Categories

Every guard falls into one of five categories, distinguished by the state it reads and the phase it runs in. This is the vocabulary the rest of the Kernel docs use. The protection-area tour below groups the same catalog differently.

Category	State	Phase	Blocking
Stateless deterministic	None	Pre-invocation	Yes
Session-aware deterministic	Session journal	Pre-invocation	Yes
Post-invocation hooks	Tool response	Post-invocation	Yes
Advisory signals	Session journal (optional)	Pre-invocation	No, unless promoted
WASM custom guards	Sandboxed runtime	Pre-invocation	Configurable

Capability Tour

The table groups guards by the area they protect. Each row links to a page in this section.

Surface	What it protects	Page
Filesystem	Path allowlists, forbidden patterns, normalization, session-scoped roots.	Filesystem
Network	Egress allowlists, internal-network checks, URL validation.	Network
Shell & Code	Forbidden shell patterns, code-execution gates, patch integrity.	Shell & Code
Rate & Velocity	Per-window invocation and spend caps: per-grant and cross-capability token buckets.	Rate Limit
Session-aware	Guards that read the session journal: data flow and behavioral sequence.	Session-aware Guards
Jailbreak & Prompt Injection	Pattern and ML detection of jailbreak prompts and indirect injection.	Jailbreak Detection
Sanitization	Output sanitizer hook redacting secrets, PII, high-entropy tokens.	Sanitization
Computer Use (CUA)	Browser automation, remote desktop, computer-use mediation.	Computer Use
Approval (HITL)	Human-in-the-loop checkpoints producing `PendingApproval`.	Approval
Memory Governance	Reads and writes to agent memory stores.	Memory
Data Layer	DB query review, structured-data redaction.	Data Layer
External Adapters	Cloud guardrails (Bedrock, Azure, Vertex) and threat-intel (Safe Browsing, VirusTotal, Snyk).	External Adapters
Advisory	Non-blocking signals with severity, optional promotion to denial.	Advisory Signals
WASM Custom	Custom guards loaded as sandboxed WASM modules.	WASM Guards

How Policy Fits In

A guard implementation performs enforcement. A policy supplies its configuration. Operators write a HushSpec YAML file, the policy compiler converts it into a configured pipeline, and the kernel runs that pipeline against every request. The same guard binary serves every deployment; the policy file is what differs.

HushSpec authoring lives in HushSpec and Write a Policy.
Runtime configuration knobs (caches, breakers, rate limits) live in Configuration.

Trust Boundary

The kernel is the trusted component. The agent is untrusted. Tool servers are cooperating. Guards run inside the kernel process, so their evaluation cannot be tampered with by the agent. The receipt signature binds the verdict to the kernel's signing key, which is verifiable offline.

Errors are denials

A guard that returns Err from evaluate is treated as if it returned Deny. This is the fail-closed invariant. When in doubt, the pipeline blocks.

Where to Go Next

Architecture · the crate map and trust boundaries
The Guard Trait · the contract every guard implements
Pipelines & Composition · how guards combine into a pipeline
Fail-Closed Semantics · what happens when something goes wrong
Default Pipeline · what runs out of the box