Let an agent commit

tovio commit --token <token-id> -m "extract parser module" --prompt "the instruction given"

Commits under a capability token.

Scope is checked before any seal

This ordering is the guarantee. The token's validity, the paths it may write, the lane it may write to and the operation it is performing are all settled before a tree is built or an envelope sealed. A commit that violates any of them produces a refusal, not a partially-written state to clean up.

An --amend is checked as the amend operation rather than commit; a token granted one and not the other is enforced on exactly that distinction.

What --prompt records

--prompt records the BLAKE3 hash of the instruction into provenance — not the instruction text. That is enough to prove later that a given instruction is the one this commit was made under, without putting the prompt itself into the repository. It requires --token; there is no bare --prompt.

Reading under a token

tovio cat <path> --token <token-id>

Path scope and secret clearance are both checked before any decryption. An out-of-scope read fails with TVO-TOKEN-001; a read of a clearance-gated path by a token without clearance fails with TVO-PERM-001. Without --token, cat is an ordinary human read under this repository's identity.

Where it lands

On a lane inside the agent's own agent/<name>/** scope. It does not reach your lane until you promote it.

Reviewing what it did

tovio log --entity agenttovio change show <chg-id> --diff

Common refusals

• TVO-TOKEN-001 — a written path is outside the token's scope.
• TVO-TOKEN-002 / TVO-TOKEN-003 — the token expired, or was revoked.
• TVO-TOKEN-004 — the operation is not in the token's allowed set.
• TVO-TOKEN-008 — the repository has no identity yet, so there is nobody to authorize an agent. Run tovio identity init first.
• TVO-PERM-* where the underlying policy denies it regardless of the token.

Why an agent operation was refused explains what each stage means and which knob to turn.

The denial is recorded

An out-of-scope write is appended to the per-actor signed audit chain before the error is returned. The write plane leaves the same evidence the read plane does — so you can ask later what an agent tried to do, not only what it managed.