fence_prepare
Reserve a side-effecting tool call to prevent duplicate executions. Pass a stable intent; if the action already ran, replay its recorded result instead of rerunning it.
Instructions
Ask permission to run a side-effecting tool call. intent is a stable id for the logical action (e.g. charge:order-123) -- attempts sharing an intent are the SAME action and only one will ever execute. Returns {status:'fresh', prepared} when this attempt wins (run the tool, then call fence_commit or fence_abort with the ticket), or {status:'already_done', cert} when this exact action already ran (use the recorded result; do NOT run the tool). Errors mean do not run: another attempt is in flight, a previous attempt failed (reconcile first), a dependency changed (ReadSetStale), or a same-instant race was lost (DomainRace).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Arbitrary JSON arguments for the tool call being fenced. | |
| tool | Yes | Name of the tool/effect being fenced, e.g. `"charge_card"`. | |
| agent | Yes | Identifier of the calling agent. | |
| domain | Yes | The contention scope this effect will act on, e.g. `"order:123"`. | |
| intent | Yes | Stable identifier for the logical action, e.g. `"charge:order-123"`. Attempts sharing an intent are the SAME action: only one ever executes; later attempts get the recorded outcome replayed. Mint a new intent only for a genuinely new action. | |
| parent | No | Hex SHA-256 hash of the effect certificate this one causally follows. Omit for a genesis effect with no prior cause. | |
| read_set | No | Other domains this decision cross-checked, and the sequence observed for each. Do not include `domain` itself here — its own sequence is about to be advanced by the reservation, so an entry for it would go stale the instant that happens. Same-domain lineage belongs in `parent`. | |
| known_clock | No | The calling agent's current view of causal history. |