Skip to content

Agents & capabilities

AI agents are first-class actors in TOVIO, and they are bounded ones. When you point Cursor, Claude Code, or a custom bot at your repository, you don't hand it your credentials and hope. You issue it a capability — a signed, expiring token that says exactly which paths it may touch and whether it may read protected files — and everything it does is stamped with provenance.

This page explains the model: agent identities, how a capability scopes what an agent can do, what secret_clearance means, and what provenance records.

Phase note

Phase 2's functional plane is implemented across the CLI, Node bindings/SDK, and MCP server: token issuance, expiry and revocation, monotonically-narrower sub-token minting, operation/path/lane scope, secret_clearance, agent lanes, intent/promote/abandon, signed full-chain provenance, and canonical tool-manifest binding. Delegated sessions reconstruct and revalidate the whole authorization chain (including ancestor revocation) and commit the complete chain and tool-manifest hash. The MCP edge runs over stdio or loopback-default Streamable HTTP and exposes the effective scope. What remains is Phase 5 productization — publishing the Node SDK, MCP server, and N-API packages — tracked on the roadmap.

An agent is an identity, too

Every agent is a cryptographic identity, the same kind of keypair a human gets. That's the foundation everything else rests on: because an agent has its own identity, its actions are attributable, its access is governed by the same permission system as a person's, and — crucially — it can only decrypt what its key can decrypt. There is no "service account that can read everything." An agent's reach is exactly the reach of its key plus its token.

A capability is a scoped, expiring token

A capability token answers, precisely, "what is this agent allowed to do, and until when?" The pieces that matter conceptually:

Field What it bounds
path_scope The glob set the token may read and write within, e.g. src/integrations/cgm/**.
denied_path_scope Globs excluded from the scope — exclusion always wins, so you can say "everything except these paths."
secret_clearance Whether the token can obtain keys for clearance-gated objects at all (see below).
operations Which verbs are allowed: read, commit, branch:create, conflict:resolve, and so on.
expiry A short TTL; clients renew proactively before it lapses.

The enforcement order is the important part. Path scope is checked before policy. A read or write to a path outside path_scope (or inside denied_path_scope) is rejected at the scope stage — before any policy is even consulted, so nothing about the protected content leaks in the rejection. Scope is the outer fence; policy is the inner lock.

Mental model

A fine-grained personal access token: scoped to specific paths, tied to a specific agent identity, and short-lived — so a leaked token is both narrow and quickly stale.

secret_clearance: the line an agent can't cross

This is the field that makes the whole model trustworthy, so it's worth dwelling on.

When secret_clearance is false, the token cannot obtain a content key for any object whose read policy references clearance. Read that carefully: the agent isn't told no by a rule that it might find a way around. It is structurally unable to get the key. The denial is enforced at the key-availability step, by the same cryptography that protects the file from anyone else without clearance.

Why this is stronger than a rule

A permission rule says "you may not read this." A capability without clearance says "you cannot obtain this through the TOVIO authorization edge" — the edge will not unwrap a protected object for an agent identity whose scope, clearance, capability chain, and recipient key do not satisfy policy. This does not control plaintext an authorized user, tool, runner, or model endpoint deliberately discloses through another channel; those endpoints remain separate trust boundaries.

This is the answer to the obvious anxiety about giving an AI agent access to a repository that contains secrets: you give it a capability that excludes the secret paths from its scope and withholds clearance, and the secrets are doubly out of reach — outside its fence and behind a lock it has no key for.

Delegation: tokens that issue narrower tokens

For multi-agent orchestration, a token can issue sub-tokens — child capabilities with equal-or-narrower scope. This is monotonic restriction: a child can drop a path, add an exclusion, or surrender clearance, but it can never widen beyond its parent. An orchestrator agent holding a broad token can hand a worker agent a tightly-scoped slice of it, and the worker physically cannot exceed that slice. The delegation chain is recorded so you can always see which token authorized which token.

Provenance: every agent commit carries its story

Everything an agent commits carries provenance — structured metadata recorded on the commit itself. It answers "who, with what, and to what end":

  • the model (and its hash) that powered the agent,
  • the task ID and description it was working on,
  • the prompt and tool-manifest hashes,
  • the authorizing identity and the capability token ID (and, for delegated work, the full token chain).

Because provenance is part of the commit, it travels with history and can't be detached after the fact. You can look at any change an agent made and know exactly which model, under which task, with which tools and which authorizing token, produced it. That's the difference between "an AI touched our code somewhere" and a complete, auditable record of every autonomous action.

Mental model

A commit's Author and Committer lines, expanded for the machine age: not just who, but which model, which prompt, which task, which token — verifiable and permanent.

How this connects to the rest of the model

Capabilities only make sense on top of the other concepts:

  • They're issued against an agent identity.
  • secret_clearance is enforced by the permission system — the same crypto that protects files from people.
  • An agent's commits land through the same change model and are reviewed and audited on the Forge, where provenance becomes a dashboard you can watch.

Where to go next

Last reviewed September 9, 2026

Suggest an improvement to this page Not for security reports — see disclosure