Capabilities

Agents share the kernel and hold distinct grants

Each agent presents its own grant, and one kernel admits every call against the grant that agent holds.

Applications share Chio’s rules for authority, delegation, and execution admission while choosing their own models and workflows, and adapters connect those rules to the protocols and resources they use. A capability makes an agent’s authority available for the kernel to check: who granted it, who may exercise it, which operations it covers, and when it expires. The application can change a worker’s assignment or replace its planning logic, and those permissions stay explicit.

The host establishes isolation and supplies the configured storage and worker lifecycle. For a protected resource, the host must make kernel admission mandatory by preventing access through other credentials or handles.

Read more in Architecture.

A grant is signed for one subject

A grant describes the work an agent may perform. For the reviewer, that means reading /workspace without changing it. In the Quickstart project, you fork the project and grant the fixer agent the workspace, your model route, and two dollars for twenty minutes.

import { Computer, USD } from "@chio-protocol/sdk";

const project = await Computer.open("quickstart");
const fixer = await project.agent("fixer");
const fork = await project.fork();
const authority = fork.grant({
  to: fixer,
  resources: { "/workspace": ["read", "write"], "/models/default": ["invoke"] },
  budget: USD(2),
  expiresIn: "20m",
});
console.log(authority.describe());

grant      cap-01a8…31f2, signed by your kernel
to         fixer, did:chio:z6MkrT2…8wd
on         quickstart, fork 51c07ae
allows     /workspace         read, write
           /models/default    invoke
budget     USD 2.00, charged at your door
expires    in 20 minutes

from chio import Computer, USD

project = Computer.open("quickstart")
fixer = project.agent("fixer")
fork = project.fork()
authority = fork.grant(
    to=fixer,
    resources={"/workspace": ["read", "write"], "/models/default": ["invoke"]},
    budget=USD(2),
    expires_in="20m",
)
print(authority.describe())

grant      cap-01a8…31f2, signed by your kernel
to         fixer, did:chio:z6MkrT2…8wd
on         quickstart, fork 51c07ae
allows     /workspace         read, write
           /models/default    invoke
budget     USD 2.00, charged at your door
expires    in 20 minutes

use chio::{Computer, Grant, USD};

let project = Computer::open("quickstart").await?;
let fixer = project.agent("fixer").await?;
let fork = project.fork().await?;
let authority = fork.grant(
    Grant::to(&fixer)
        .resource("/workspace", ["read", "write"])
        .resource("/models/default", ["invoke"])
        .budget(USD(2))
        .expires_in("20m"),
)?;
println!("{}", authority.describe());

grant      cap-01a8…31f2, signed by your kernel
to         fixer, did:chio:z6MkrT2…8wd
on         quickstart, fork 51c07ae
allows     /workspace         read, write
           /models/default    invoke
budget     USD 2.00, charged at your door
expires    in 20 minutes

The issuer creates the permission by signing a token that contains the scope, the caller’s public key, and its validity period. The kernel checks that the issuer is trusted and that the token has not changed. In the output, your kernel is the issuer, the fixer is the subject who may exercise the grant, and the allows lines are the scope of permitted calls.

Knowing a tool’s name or a token’s identifier, or copying the grant code, does not provide that authority. Editing the grant code changes a future grant; it does not rewrite a token already signed.

Read more about grant fields and their constraints in the capability reference.

The kernel checks the token before the call

A valid signature establishes that the token has not changed since its issuer signed it. The kernel still has to decide whether that token authorizes this caller, at this time, to make this call, and its capability checks answer that before guards or tools run.

A failure stops the call. A request that passes still goes on to policy evaluation. When a grant requires proof of possession, the kernel also verifies a fresh proof signed with the caller’s key. In the Quickstart project, the fixer tried to read /secrets/.env, which its grant does not cover.

const [refusal] = await project.history.receipts({ outcome: "deny" });
console.log(refusal.describe());

receipt    rcpt-01a8…9c04
request    fixer read /secrets/.env
verdict    deny: outside the grant
grant      cap-01a8…31f2
policy     sha256 3c7b…8010
signed     your kernel 4f1c…a2e9, signature verifies

refusal = project.history.receipts(outcome="deny")[0]
print(refusal.describe())

receipt    rcpt-01a8…9c04
request    fixer read /secrets/.env
verdict    deny: outside the grant
grant      cap-01a8…31f2
policy     sha256 3c7b…8010
signed     your kernel 4f1c…a2e9, signature verifies

let refusal = project.history().receipts().outcome("deny").first().await?;
println!("{}", refusal.describe());

receipt    rcpt-01a8…9c04
request    fixer read /secrets/.env
verdict    deny: outside the grant
grant      cap-01a8…31f2
policy     sha256 3c7b…8010
signed     your kernel 4f1c…a2e9, signature verifies

The refusal comes from the grant itself, at the scope check, before a guard needs to inspect the call. The receipt records the decision and identifies the capability that was checked. That identifier connects the decision to a token; it does not contain the grant or establish that a tool executed.

Read more in Receipts.

Share a parent’s capacity

Adding specialists means dividing shared capacity as well as assigning operations. Several workers can each pass the scope check and still request more of a shared budget than their parent holds, so the application accounts for the family of admitted children together.

The budget_share_bps field expresses a delegated share in basis points: 10,000 represents a full share. In this example the parent holds 10,000 bps, and two admitted children hold 4,000 and 3,500. A third child can request at most the remaining 2,500.

A request for 3,500 bps is within the token field’s 10,000 bps limit on its own. Adding it to the existing children would allocate 11,000 bps, so the registry rejects that proposal and leaves the admitted siblings unchanged. A request for 1,500 bps fits and would leave 1,000 bps available.

This check requires an enforcing budget registry that knows the parent and its admitted children. The registry supplies the shared accounting; a signed budget_share_bps field by itself does not. Scope, validity, and the other admission checks still apply to each child.

Expiry and revocation end a grant

Set a token’s lifetime to fit the work it authorizes. Its validity period is fixed when it is signed, and once it expires the caller needs another token. Changing the lifetime in the grant code does not extend a token already issued.

Revocation ends authority sooner. It is state maintained by the kernel, separate from the signed token, and the kernel checks both the presented token and every link in its delegation chain against that state. A delegated child’s admission therefore still depends on its ancestors, so an application must preserve the chain and make revocation state available wherever calls are checked. Where revocation records live, and how fresh they are, depend on the deployment.

Read more in Delegation and chain validation.

Size each grant to its task

Authority can follow the work as the coordinator divides it. The reviewer’s grant covers the whole workspace, so for the tester assigned the tests directory it can issue a grant for that assignment alone: one operation, one path prefix, a few calls, and a lifetime measured in minutes. An instruction injected into pull request #421 then reaches only what the current assignment holds.

The Authority application narrows a parent read grant on src/ to src/review/ for its reviewer and src/audit/ for its auditor:

let mut scope = parent.scope.clone();
scope.grants[0].operations = vec![Operation::Invoke];
scope.grants[0]
    .constraints
    .push(Constraint::PathPrefix(prefix.into()));
scope.grants[0].max_invocations = Some(2);
let expires_at = now.saturating_add(1800).min(parent.expires_at);

The three edits after the clone each narrow one dimension of the first grant, grants[0]; any other grant in the parent’s scope passes to the child unchanged. Keeping only Operation::Invoke removes onward delegation. Constraint::PathPrefix appends the child’s directory to the parent’s src/ constraint. Every constraint on a grant must hold and a prefix matches whole path segments, so the child’s directory must sit inside the parent’s: a tests/ prefix under src/ would admit nothing. max_invocations allows two calls. The expiry is thirty minutes after issue, clamped to the parent’s expires_at, so the child cannot outlive its parent.

The prefix bounds the requests the kernel admits; the tool server and its confinement bound what the process can open. Task-Scoped Authority extends the pattern to a family of workers, where an aggregate invocation budget caps their combined calls and revoking the root grant closes the subtree.

Policy narrows the calls a grant permits

A grant for read_file lets the reviewer invoke that tool within the grant’s limits. It does not establish that a particular read serves the review, that the answer is correct, or that the task succeeded.

Capability checks sit within a larger call path. Guards can apply additional policy to a call the token permits, and they cannot enlarge the token’s scope. In the Quickstart project, the tests-are-evidence rule refuses the fixer’s write to /workspace/tests/ even though its grant covers writes to /workspace.