The agent namespace

An agent's token is scoped to agent/<name>/**, and a token cannot write to a lane outside that scope. This is structural, not a convention.

The scope covers both the plain agent/<name> lane and anything under it, so agent/refactor-bot and agent/refactor-bot/experiment are both in bounds. TOVIO allows multi-component lane names precisely so agent tokens have room to work.

One naming note: TOVIO calls this a lane — the concept Git calls a branch — but the token field is branch_scope and agent abandon takes a <BRANCH> argument. Same thing, two spellings, because tovio branch is kept as a git-compatible alias.

What it gets you

• Nothing lands in your work by surprise. Agent output sits in its own namespace until you promote it.
• Review before integration is the default, because there is a boundary to cross.
• Isolation between agents. Several agents working at once do not interleave commits on one lane.
• Discarding is easy — tombstone the lane.

Promoting good work

tovio agent promote <name> --onto main

Takes the agent name and resolves its single live lane, or a full lane path if you would rather be explicit. --onto defaults to main.

Discarding a bad run

tovio agent abandon agent/<name>

Takes the lane path, not the agent name. It refuses anything outside agent/ and points you at tovio branch <name> --delete for an ordinary lane, and it refuses to abandon the lane you are currently on — which would leave you standing on a dead ref.

Reviewing first

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

semantic diff is worth running on agent work specifically — it flags breaking interface changes rather than textual ones, which is exactly the failure mode of a confident model.

Do not use the namespace yourself

Keep agent/ for agents so the distinction stays meaningful, and so scope reasoning stays simple.