Keep agents out of your secrets

Path scope and secret clearance are separate. An agent can hold write access to a directory and still be unable to read the secret-marked content inside it.

The default is stronger than clearance alone

A default agent token does not merely lack clearance — it is structurally excluded from every policy-protected path. A request for one is rejected at the scope stage, before policy is even evaluated, so nothing about the policy leaks in the refusal. Clearance is the second line, not the first.

Where clearance is enforced

secret_clearance is never implied by path scope. It is granted deliberately, and checked in two places: before a protected read, and at seal time when committing.

The seal-time check exists for a specific failure. If a clearance-less token reaches a clearance-gated path and it is the only resolved recipient, the object would be sealed for nobody — readable by no one, including you. TOVIO fails closed with TVO-TOKEN-010 rather than produce it. In practice you only see this on a custom or narrowed token, because a default token is stopped at the scope stage first.

The default

Withhold it. Most agent tasks — refactoring, tests, documentation — need no access to credentials at all. If a task genuinely requires a secret, that is worth a moment's thought rather than a flag.

Checking

tovio agent show <token-id>tovio access check <path> --identity <path-to-identity.pub>

access check takes the path as its argument and a file path to the recipient's identity.pub; omit --identity to check this repository's own identity. Add --write to check the write policy instead.

Plugins too

A sandboxed plugin is denied protected plaintext at execution preflight unless its binding grants it — TVO-PLUGIN-011. An AI conflict resolver does not get your secrets merely because it is resolving a conflict near them.

Captured sessions are scanned

Agent session capture runs a mandatory secret scan, not a best-effort one, and refuse-rather-than-redact is the deliberate choice: a transcript that fails the scan is not stored.

What happens next depends on who asked for the capture. If TOVIO discovered the transcript on its own, the session is dropped with a warning and the commit still proceeds — failing a commit over an optional provenance record is how a safety feature gets switched off. If you named the transcript explicitly with --session-from, you asked and were denied, so the command fails with TVO-PROV-007. Either way the finding names the rule and shows a non-recoverable preview; the secret itself is never printed or stored.

If a finding is real, rotate the value. It is sitting in a plaintext transcript on that machine whether or not TOVIO stored it, so dropping the session changes nothing about the exposure.

If clearance was too broad

Revoke the token, rotate the secret, protect the path, and reissue. In that order — reissuing first just hands out the same reach again.