Control & safety

An AI agent editing your codebase is fast, and fast is exactly what makes it risky: by the time you notice it touched something it should not have, it has already moved on. The Operon Harness is the layer that keeps the agent inside the lines — it defines what the agent may touch, pauses it at the moments that matter, and makes every intervention recoverable. This page covers the five pieces: scope boundaries, checkpoint gates, the intent monitor, the governance policy, and rollback.

Scope boundaries

A scope boundary is a set of file globs that say which files a session’s agent is allowed to change. You set it per session when you create it, using two lists: allowed patterns (the files the agent may edit) and blocked patterns (files it must never touch, which always win). Patterns are ordinary globs, one per line — for example src/auth/** to fence the agent into the auth code, or .env to keep it away from secrets.

Every scope has a mode that decides what happens when the agent writes outside the boundary:

In enforce mode, the sequence is deliberate and safe. The moment a file watcher sees an out-of-scope write, Operon pauses the agent first, snapshots the file’s current contents into a quarantine folder, and only then reverts the file to its prior state. Because the pre-revert content is quarantined, the revert is never destructive — you can always get the change back.

Set a file scope

You configure a scope when you start a session, in the New Session dialog.

1. 1

   Open the Scope Boundary section

   In the New Session dialog, expand the Scope Boundary section. It is collapsed by default.

2. 2

   Choose a mode

   Pick enforce, warn, or off. Start with warn if you want to see what the agent touches before committing to hard enforcement.

3. 3

   Add allowed patterns

   List the globs the agent is allowed to edit, one per line — for example src/features/checkout/** and src/lib/pricing.ts. An empty allowed list means "allow everything except what is blocked".

4. 4

   Add blocked patterns

   List globs the agent must never touch, one per line — for example .env, secrets/**, or infra/**. Blocked patterns always take priority over allowed ones.

5. 5

   Use a quick preset (optional)

   Presets like Frontend, Backend, Tests, and Auth fill in a sensible starting scope you can then edit.

Checkpoint gates

When a session is driven by a plan (a sequence of steps the agent works through), checkpoint gates let you review the work between steps instead of only at the end. With gates enabled, each time the agent finishes a plan step, Operon records a checkpoint — a git snapshot of exactly what changed — pauses the agent, and shows you a review panel before the next step begins.

The review panel shows the step title, the diff of what changed in that step, and a confidence score derived from signals like how many files were touched and whether errors occurred. From there you have three choices:

• Approve — accept the step. Operon tags the checkpoint and lets the agent continue to the next step.
• Reject — roll back to the last approved checkpoint, undoing the step’s changes, and let the agent try again.
• Rollback — return the working tree to any earlier checkpoint you have taken in the session.

Intent monitor

Scope boundaries catch out-of-bounds file writes; the intent monitor catches a subtler failure — the agent drifting away from the goal you actually gave it. It watches the run in real time and raises a goal-drift alert when the work stops matching the mission.

It looks for signals such as: most of the edits landing outside the scope you set; the agent editing files that share nothing with your goal (when no scope is set); touching far more files than a task of this size should; or a run of consecutive tool errors. When it fires, you get a drift alert so you can steer the agent back — or stop it — before it burns time going the wrong way.

Governance and policy

Scope and intent are per-session. A governance policy is the standing rulebook for a project — a declarative .operon/policy.json checked into the repository that applies to every session automatically. It is hard-enforced and every action it takes is written to an audit feed you can review later.

A policy can declare:

• Protected paths — globs the agent may never modify. A write here is reverted and the session is paused, just like a scope violation, but the rule lives with the project instead of the session.
• Forbidden commands — commands the agent is not allowed to run. A match pauses the session and is recorded.
• Budgets — a spending ceiling per session (or per project per day). When it is reached, the policy pauses (or warns, depending on the configured action) so a runaway agent cannot quietly rack up cost.
• A required test gate — a test command that must pass before the session can create a PR or merge to base. Until it passes, those actions are blocked.
• Checkpoints — whether approval is required between plan steps, so an organization can mandate checkpoint gates.

Policies compose from two layers: an organization baseline and a project’s own .operon/policy.json. A project may only tighten the org baseline — union the protected paths and forbidden commands, take the lower budget, and it cannot remove a test gate the org requires. Everything the policy stops — a reverted write, a blocked command, a budget pause, a failing test gate — appears in the project’s Governance audit feed with the rule, the detail, and when it happened.

Rollback

When you want to explore an alternative — or a session went down the wrong path — rollback lets you branch from a past decision instead of starting over. Operon records a timeline of decision points across a session (commits, decisions, and plan steps), and you can branch from any of them to explore a different approach in a new child session while the original stays intact. It is the "undo" that operates on the shape of the work, not just individual files.

How the pieces fit together

Each guardrail covers a different kind of risk, and they layer: scope keeps the agent in the right files, checkpoint gates give you a look between plan steps, the intent monitor catches goal drift, the governance policy enforces the standing rules a whole team agrees on, and rollback makes any of it reversible. Turn on as much or as little as the task warrants — a quick throwaway session might use none, a change to production auth code might use all five.

Related