Two-Phase Writes From the Agent's Side: Dry Run, Then Commit

Treat the dry run response as a contract with four fields that must survive intact until the commit, or until the agent abandons the plan.

• The plan token. An opaque value the server uses to look up the stored plan. The agent never parses it, never regenerates it, and never guesses at its structure.
• The plan ID. A log-friendly identifier, separate from the token, that appears in logs and user-facing confirmation. If a human approves the write, this is what they approve.
• The expiration. An absolute UTC timestamp, converted once at receipt. Once the clock passes it, the plan is dead and no commit should be attempted.
• The exact inputs and their fingerprint. The canonical serialized form the agent sent, plus the fingerprint the server computed over it. The commit presents that fingerprint so the server can confirm nothing moved.

{
  "plan_id": "plan_8f21c",
  "plan_token": "pt_9c0e...opaque...",
  "expires_at": "2026-03-14T09:41:12Z",
  "input_fingerprint": "sha256:6b1f...",
  "actions": [
    {"op": "update", "target": "invoice/4412", "field": "status", "to": "paid"}
  ]
}

Store this object verbatim in task-scoped state. Do not re-derive the fingerprint locally; the server's value is authoritative, and a disagreement is a bug to surface, not to paper over.

This is the failure server-side tests never catch. An agent runs a dry run for a refund and gets a fingerprint over the current invoice state. Before committing, it fetches a support ticket, which is read-only and harmless. Then it notices a stale customer address and issues an address update, which is a write. Then it commits the refund with the original token.

The token is valid. The plan is not. If the commit carries the fingerprint captured at dry run time, the server sees the mismatch and returns a conflict. If the agent is expected to recompute the fingerprint before committing, a sloppy implementation recomputes over the new state, and the server applies an old plan to a new world.

The decision rule is blunt and belongs in your tool descriptions and your code: once a dry run returns, the inputs it covered are frozen until the commit resolves or the plan is abandoned. Reads are fine. Writes that invalidate the plan are not, unless followed by a fresh dry run.

If a needed write does occur, discard the token, run the dry run again against the new state, and present the new plan. The second plan may be identical, costing one round trip, or it may differ, in which case you avoided applying a stale intent.

This is the same discipline schema systems enforce: a producer should not assume its consumer is at the same version, and the safe move is to add and drain rather than mutate in place (Conduktor). The agent is the producer of a write intent, and the plan is the version it asks the server to honor.

Three choices make staleness detectable instead of silent.

The commit takes the token and the fingerprint, and nothing else that matters. If the agent can send fresh inputs alongside the token, the server must decide which wins, and the approved plan stops being the thing that executes. Keep the plan payload server-side.

The conflict is specific. A 409 whose body names the changed field and the plan's creation time is far more useful to an agent than a generic error. It can then re-plan automatically or escalate. A bare 409 teaches it nothing.

Expiry is enforced, not advisory. A token past expiry is refused even when inputs are unchanged. The window exists because the world is only known to be as the plan assumed for so long.

Idempotency belongs on the commit, not the dry run. The commit should accept a client-generated key so a timeout and retry produce one applied plan. The standard contract: the server stores the key with its result, returns the stored result on repeat, and rejects the same key with a different payload (Basis Theory). The key must be generated before the first attempt, not during a retry (Zuplo).

The timeout rows matter most. An agent that treats silence as failure and starts a new plan will sometimes apply the write twice.

A support agent refunds 480.00 USD against invoice 4412 using refund.dry_run and refund.commit.

1. It calls the dry run with {"invoice_id": "4412", "amount_cents": 48000}. The server returns a plan valid for ten minutes, fingerprint sha256:6b1f..., and a token.
2. It stores the plan and checks expiry against UTC. Eight minutes remain.
3. It calls shipping.lookup, a read, and logs the delivery exception as evidence.
4. It commits with the token, the fingerprint, and idempotency key idem_7a12.
5. Suppose another process already applied a partial 200.00 USD refund. The fingerprint no longer matches, and the server returns 409 naming the changed field.
6. The agent does not retry. It re-runs the dry run, gets a plan for the remaining 280.00 USD, and presents that to the reviewer.

The interesting number is the gap between steps 5 and 6. A naive implementation retries twice, gives up, and reports "refund failed" while the invoice sits in a state nobody described. The correct implementation produces a truthful description of what remains.

If step 4 times out after the server applied the plan, the agent retries with idem_7a12, receives the stored result, and reports success once. If it times out before applying, the retry applies it. The agent cannot tell these apart, and does not need to.

Server tests prove the commit refuses bad requests. Agent tests prove the agent never sends them.

The last row is where agent frameworks go wrong. If the plan lives in a conversation transcript rather than explicit task state, a later turn can pick up an old token and commit it.

The tool schema should make misuse hard. If the commit marks both token and fingerprint as required, a missing field fails before the request leaves the process. JSON Schema's dependentRequired expresses the constraint that a token without a plan ID is invalid (JSON Schema reference, Stack Overflow).

def commit_plan(task, plan, idem_key):
    if plan.expires_at <= utcnow():
        return {"status": "expired", "action": "re-run dry run"}
    if task.inputs_dirty_since(plan.created_at):
        return {"status": "stale", "action": "re-run dry run"}
    resp = post("/refund/commit", json={
        "plan_token": plan.token,
        "input_fingerprint": plan.input_fingerprint,
    }, headers={"Idempotency-Key": idem_key}, timeout=30)
    if resp.status == 409:
        return {"status": "conflict", "detail": resp.json()["changed"]}
    return {"status": "ok", "result": resp.json()}

The dirty flag is the agent's own cheap defense, set by any mutating tool call touching the plan's target.

Expired before commit. An agent that pauses for human approval longer than the window hits this routinely. The fix is not a longer window; approval should happen immediately before the commit, not before a queue.

Inputs changed. A 409 is information, not an error to retry. Re-plan.

Status unknown. Retry with the same idempotency key, then read the plan's state by plan ID. Generating a new key and re-planning is how double writes happen. The contract requires one key per logical operation, not per attempt (the idempotency token pattern).

Abandonment. Define it: task end, changed user intent, or expiry. Drop the token and record it as abandoned. "Planned and did not do it" is a distinct audit event from "never planned." In-flight plans need an owner and a lifespan, much as in-flight approval documents need an explicit treatment when rules change under them (approval workflow versioning).

Teams running many agents against shared internal APIs often standardize the tool-calling loop and plan-state rules in one layer. Quanta Inference exposes one API for text, image and embedding models, so the guard lives in one place rather than in every prompt.

1. Call the dry run with deterministically serialized inputs so the fingerprint is meaningful.
2. Store token, plan ID, absolute UTC expiry, and fingerprint in task-scoped state, never in a revisitable transcript.
3. Present the plan if a human is in the loop, and commit right after approval.
4. Before committing, check expiry and the dirty flag. If either fires, re-plan and stop.
5. Commit with token, fingerprint, and one idempotency key per logical operation.
6. Map every response: success and stored result are done; conflict and expiry re-plan; unknown retries with the same key.
7. On task end, clear the token and record abandonment.

The insight worth keeping: a two-phase write is one call plus a promise that the world has not moved. The server can keep that promise only if the caller sends the fingerprint and refuses to commit a plan it knows is stale. Write that promise into the tool schema and the task state, and the rest follows.