Tool idempotency: preserve the effect identity across retries

Derive or allocate an effect identity from the intended business operation and store it durably before dispatch. Reuse it for attempts that mean the same operation, including recovery by another worker when that is the declared scope. A new user intent can require a new identity even if its arguments match an earlier request. Conversely, generating a fresh key for each retry defeats deduplication. Do not confuse a transport request ID, model tool-call ID, worker incarnation, and provider effect key unless the mapping is explicitly designed.

Bind the key to canonical arguments, target resource, tenant, and operation version as required by the provider protocol. Reusing one key for a changed payload should be rejected or handled under a documented rule rather than silently returning an unrelated old result. Concurrent first attempts need an atomic provider-side claim or equivalent mechanism; a client-side lookup followed by an unprotected write can race. The service that commits the effect must participate in the property, not only the runtime's local journal.

A provider may retain keys for a limited time, cache error results, reject mismatched parameters, or treat validation failures differently from executed requests. Stripe's idempotent-request documentation is one concrete API contract; its behavior must not be generalized to every tool. A workflow's recovery horizon can outlast the provider's deduplication record. After that window, repeating the same bytes and key may no longer suppress a new effect. Keep a longer-lived business ledger, reconcile resource identity, or stop for an explicit recovery decision as the application requires.

Idempotency does not guarantee the first operation succeeds, nor does it automatically authorize a retry after permissions change. An unknown result still needs an outcome lookup or a retry justified by the retained contract. Deduplication can return a prior receipt, report in-progress status, or reject a concurrent attempt under specific semantics. Record which occurred. A local unique constraint can prevent duplicate intent records while a remote write still executes twice if its own commit is outside the protected boundary.

Inject a lost response after provider commit, concurrent duplicate dispatches, changed arguments under one key, and a retry near or beyond key expiry. Inspect the provider's authoritative effect count as well as runtime results. Replay should preserve the key and payload digest. Verify that a new legitimate operation is not suppressed merely because it resembles an earlier one. Include authorization and budget treatment of duplicate transport attempts; a deduplicated external effect may still consume network, tool, or provider resources.

The cache lab only illustrates finite retained identities. Reset, set C=2 and s=4, predict zero hits among sixteen initial requests, then Play or Step. Separately Reset, set C=4 and s=4, predict twelve, then Play or Step. It uses LRU capacity rather than time-based key retention and has no provider commits. Use the lost working-set memory as a limited analogy, then test the actual retention clock and authoritative duplicate-effect behavior instead of equating cache hits with exactly-once execution.