Diff or roll back a behavioural version

behavioral diff and rollback.

Written By Dustin

Last updated 22 minutes ago

tovio behavioral listtovio behavioral diff <commit-a> <commit-b>tovio behavioral rollback <commit>

behavioral list takes no arguments: it walks your history and prints every commit that carries a snapshot, newest first. diff and rollback take commit addresses — either bare hex or the blake3: prefixed form.

Getting an address you can paste

The human output of list, log and status abbreviates every address to its first few characters followed by an ellipsis. Those are for reading, not for pasting — diff and rollback need the full address and will reject a truncated one.

tovio behavioral list --json

The JSON carries each snapshot's full commit and behavioral addresses. That is the reliable source for the arguments to the other two commands.

Diffing

behavioral diff names which of the six fields moved between two snapshots — model, prompts, tools, memory, retrieval, policy. This is the tool for "the agent started doing something different last Tuesday": compare a snapshot from before with one from after and the change is named rather than guessed at.

Because only hashes are stored, the answer is which fields changed, not what they changed to. That is usually enough to know where to look.

A side with no snapshot is reported as unrecorded rather than treated as an error. If neither side has one, it says so plainly.

The risk note

Every diff ends with an advisory risk level, derived deterministically from which fields moved:

Level	When
`none`	No recorded field changed.
`low`	Prompts only — review representative outputs.
`medium`	Tools, memory or retrieval — available actions or context changed; run targeted regression evaluation.
`high`	Model or policy changed — re-run safety and acceptance evaluations. Also `high` when either side has no snapshot at all, because missing data is not the same as no change.

It is a heuristic and it is advisory. It never blocks anything, and it is not a substitute for your own evaluation.

Rolling back

tovio behavioral rollback <commit>

Restores the behavioural surface of an earlier commit — the equivalent of reverting a deployment when a prompt change made things worse.

It works forward, not backward: it records a new snapshot carrying the old commit's descriptors and links it to your current commit. Your history is not rewound and your code is not touched — only the behavioural surface moves. The rollback itself is therefore visible in behavioral list, which is what you want in an audit.

If the commit you name has no snapshot to restore, the command fails cleanly with TVO-SEM-006 and changes nothing. Run behavioral list to find one that does.

If you snapshot the wrong thing

Both snapshot and rollback are recorded in the local operation log, so the ordinary undo puts your lane back where it was:

tovio undo

That is the fix for a mistyped descriptor path, which is silently hashed as a literal string rather than rejected.

Roll back, then investigate

The useful order is to restore known-good behaviour first and diagnose afterwards, rather than debugging a live system that is misbehaving.

Combine with provenance

tovio log --entity agent --why --task-id <id>

Behavioural snapshots say what the system was configured to do; provenance says what it actually did. Both together answer most questions about an agent's output.