Claude Code splits a release task across two workers. One updates a billing limit. The other rotates a webhook destination. Both writes leave the process within the same millisecond, and both derive an operation ID from the run ID and current timestamp.

They get the same ID.

The billing write succeeds. The webhook call times out after dispatch. During recovery, the operation journal looks up the shared ID and finds a completed entry. The workflow concludes that the webhook change already happened, even though the receipt belongs to billing.

Nothing was duplicated. That is almost worse. The system attached valid evidence to the wrong effect.

An idempotency key is useful only when it identifies one intended operation. Parallel agents expose shortcuts that appear safe in serial tests: timestamps with coarse precision, counters held inside separate workers, truncated hashes, or keys generated after a timeout. Production code needs an identity authority, not a naming convention.

Operation identity ledger for parallel Claude Code writes

Define the operation before assigning its ID

Create an immutable intent record before any external call. It should describe the effect precisely enough that a retry can prove it is the same operation rather than a similar one.

operation_intent:
  run_id: cc-9021
  step_id: rotate-webhook
  principal: claude-code-release
  target:
    system: payments
    environment: production
    resource: webhook/account-418
  method: update_destination
  payload_hash: sha256:71bf...
  expected_version: 27
  approval_id: approval-552
  policy_version: policy-2026-09-06.4

Canonicalise this record and calculate an intent hash. Exclude volatile fields such as dispatch time, trace span, retry count, and worker process ID. Those describe an attempt. They do not change the intended effect.

Keep fields that change authority or outcome. A different tenant, resource, payload, expected version, approval, or policy decision must produce a different intent. If a worker tries to reuse an ID with any of those fields changed, the gateway should reject it.

This is the same distinction behind treating a timed-out MCP write as an unknown outcome. Recovery can reuse identity only after the first attempt and the retry are proven to mean the same thing.

Allocate identity in one durable ledger

Do not let parallel workers invent operation IDs independently. They should claim identity through one durable service or database transaction before dispatch.

claim(intent_hash, intent_record):
  begin transaction

  existing = lookup_by_intent_hash(intent_hash)
  if existing:
      assert existing.intent_record == intent_record
      return existing.operation_id

  operation_id = random_uuid()
  insert_unique(operation_id, intent_hash, intent_record, status="prepared")
  commit
  return operation_id

The unique constraints belong in the datastore, not only in application code. Enforce uniqueness on operation_id and on the canonical intent hash. The first constraint stops one ID from naming two intents. The second makes concurrent retries converge on the identity already assigned to the same intent.

A random UUID reduces accidental collisions, but randomness is not the control. Atomic insertion, durable storage, and semantic binding are. Even a perfectly unique ID is unsafe if a later retry can attach it to a changed payload.

Write the ledger entry before calling the MCP server. If the process dies after claiming the ID but before dispatch, the entry remains prepared. Recovery can inspect it and either dispatch the original intent or close it as never sent. If the call may have left the gateway, record dispatched and reconcile with the target system before retrying.

Carry the identity through every layer

The same operation ID must reach the component that creates the effect. Recording it only in Claude Code’s transcript does not stop a proxy, queue consumer, or provider adapter from executing twice.

Carry these fields through the full path:

operation_envelope:
  operation_id: op_019930f2
  intent_hash: sha256:09c4...
  attempt_id: attempt-02
  parent_run_id: cc-9021
  tool_call_id: call-44
  approval_id: approval-552

The operation ID remains stable across retries. The attempt ID changes every time. This lets the trace show several network attempts while the target system still sees one business operation.

The MCP gateway should compare the supplied intent hash with the ledger before dispatch. The target adapter should persist the operation ID with the resulting resource version or provider job ID. The effect receipt should return both. That closes the chain from plan to observed state.

Fail loudly when evidence collides

Suppose a lookup finds an existing operation ID, but the payload hash differs. Do not pick the newest record or assume the older one is stale. Mark the run identity_collision, block both write paths, and preserve the evidence for review.

collision_receipt:
  conflicting_operation_id: op_019930f2
  first_intent_hash: sha256:1a83...
  second_intent_hash: sha256:09c4...
  first_target: billing/account-418/limit
  second_target: webhook/account-418
  dispatch_blocked: true
  decision: human_review_required

This should be rare. It should also be impossible to ignore. A collision means the system can no longer trust status lookups, retry decisions, or effect receipts associated with that ID.

Put the collision receipt into the review packet beside the prompt, approved scope, tool calls, and target observations. A green test suite cannot repair ambiguous production identity.

Test the race, not the helper function

A unit test that calls the key generator twice in sequence proves very little. Build an eval that releases many workers through a barrier so they claim identity at the same time.

Cover four cases:

  • different intents launched concurrently always receive different operation IDs
  • identical retries launched concurrently converge on one operation ID
  • an existing ID with a changed payload is rejected before dispatch
  • a crash between prepared and dispatched leaves a recoverable journal entry

Run the test across processes and hosts if production does. An in-memory lock can make a single test process look correct while separate workers still race.

Also check the evidence chain. Each effect receipt must map to one operation ID, one intent hash, and one target resource version. No receipt should satisfy another worker’s completion check.

Parallel work is useful, but it removes the comforting fiction that one run means one thing happens at a time. Give every intended effect an identity through an atomic ledger, keep attempt identity separate, and reject semantic mismatches before a tool call leaves the gateway.

Claude Code: Building Production Agents That Actually Scale is a field guide to MCP boundaries, retries, observability, rollback, evals, cost controls, and review evidence for teams running Claude Code against real systems.