Control what an agent's transcript records

Observed capture is on by default. Here is what that means and how to change it.

Written By Dustin

Last updated About 3 hours ago

Provenance capture is not something you switch on. When a command writes a commit — commit, and also resolve and land — TOVIO looks for an agent transcript belonging to this repository and records it. This surprises people, so it is worth understanding before it surprises you.

What gets captured

An observed session record: the originating prompt and the ordered turns, taken from a runtime transcript. It is explicitly unattested — nothing binds it to a capability token, and it never enters the signed audit entry. The link to the commit is proven by the field it hangs from; the contents are self-reported.

Adapters ship for Claude Code and Codex. There is also a published neutral format, open-transcript: any runtime or wrapper that writes it into ~/.tovio/transcripts/*.jsonl is captured with no bespoke adapter.

Turning it down

tovio commit -m "…" --no-session

The per-commit opt-out. For the durable setting:

tovio config set provenance.observed_capture off

tovio config set provenance.observed_capture prompt

tovio config set provenance.observed_capture full

Value	Keeps
`off`	Nothing. An explicit capture request is refused (`TVO-PROV-008`) rather than silently skipped — if you asked and were denied, you are told. This also disables `agent backfill`.
`prompt`	The originating prompt only, no turns.
`full`	The prompt and the full ordered run record. The unpinned default.

A repository owner can pin the value in the policy manifest, and a present-but-unparseable value fails safe to off.

Naming a source explicitly

tovio commit -m "…" --session-from claude-code

tovio commit -m "…" --session-from ./run.jsonl

Use a runtime id (claude-code, codex, open-transcript) or a file path when discovery would pick the wrong thing. An explicit request surfaces its failures rather than falling back to silence: an unreadable transcript is TVO-PROV-009, and a transcript belonging to a different project is refused outright. A discovered transcript that turns out to belong elsewhere is an ordinary outcome, treated the same as finding nothing — directory slugs collide, and an agent may simply have run next door.

The secret scan is mandatory

Every capture is scanned before it is stored, and refuse-rather-than-redact is the deliberate design: a transcript that fails the scan is not stored.

What happens to your command depends on who asked for the capture:

How the transcript was found	On a secret finding
Discovered automatically	A warning on stderr, the session is dropped, and the commit proceeds. Failing a commit over an optional provenance record is how a safety feature gets switched off.
Named with `--session-from`	`TVO-PROV-007` and the command fails. You asked, and you are told you were denied.

Either way, rotate the value if the finding is real. It is sitting in a plaintext transcript on that machine regardless of what TOVIO did, so dropping the session changes nothing about the exposure. The message names the rule and shows a non-recoverable preview; the secret itself is never printed or stored.

What does not capture

A commit carries one run record. A second is refused (TVO-PROV-011) rather than layered on top.
A land's record binds to the integration commit the lander authored, never to the changes being landed — and a fast-forward or rebase land captures nothing at all.
agent promote captures nothing. Accepting an agent's work is not the same as authoring it, and the record that belongs on such a change is the attested one the agent's own write path produced — not whatever transcript happens to be sitting on the promoting operator's machine.

Reading it back

tovio log --session <chg-id>

tovio blame <file> --session

Both label the tier, so an observed record never reads as an attested one.