Dry-run modes for agent actions: showing the plan before the change

Goal

Let an agent, and the person supervising it, see exactly what a state-changing action would do before it does it, using the same code path that will later apply the change.

Prerequisites

Tools that separate planning from applying, or can be wrapped so that they do. Established tools show the shapes: rsync --dry-run performs a trial run with no changes made; terraform plan without -out creates what the documentation calls a speculative plan, a description of the effect without any intent to apply it, while -out=FILE saves a plan that apply can execute later; kubectl apply --dry-run=client only prints the object that would be sent, and --dry-run=server submits the request without persisting the resource; the Kubernetes API documentation describes dry-run mode as evaluating a request through the usual stages (admission chain, validation, merge conflicts) up until persisting objects to storage, with a guarantee of no other side effects.

Steps

1. Add a dry_run parameter to every tool that writes, deletes, sends or publishes, and make it the documented default for the first call in a session. The tool description states that the result of a dry run is a plan, not an effect.
2. Return the plan in the same structure as the real result, plus a marker ("applied": false), with concrete objects: the file paths and hunks, the record IDs and the fields that would change, the recipients, the counts. "Would update some rows" is not a plan.
3. Prefer server-side dry runs where the target system offers them; a client-side plan cannot see permissions, quotas, validation rules or concurrent changes.
4. Require the plan before the change: the host refuses a real call whose arguments were not first submitted as a dry run in the same session, or routes the plan to a human gate for actions above a threshold.
5. Apply with the same arguments, then diff the real result against the plan and surface differences to the agent and the log; a mismatch means the state moved between plan and apply, or the plan logic is wrong.
6. Record plan and result together, so a review can see what was predicted and what happened.

Expected result

Every irreversible action is preceded by a concrete, reviewable statement of its effect, and drift between the two is detected rather than discovered later.

Limits and test basis

A dry run proves what the tool would do, not what other systems will do in response (webhooks, triggers, downstream jobs). It does not protect against a plan that is correct and unwanted; that is what approval gates and reversible actions are for. The step order is a proposal; no failure-rate reduction is claimed.

Preconditions on the apply, plans by threshold

A plan and an apply are two calls with a gap in which the state can move, so a mandatory dry run before every write proves nothing about the moment of application and doubles the calls for low-risk writes. Where the target supports it, require a precondition on the apply itself: If-Match with an ETag, Kubernetes' resourceVersion, a document version number, or a saved Terraform plan that apply rejects when the state has changed. The write then fails atomically when the world moved, and the after-the-fact diff becomes a check on the tool rather than the only defence. Reserve the mandatory plan for actions with no way back (send, publish, delete without a copy) and for bulk actions above a size threshold; for everything else the dry run stays available on request.