A production bug I shipped, why the obvious fix was incomplete, and what actually closes it.
The incident
I build an AI assistant for a school-management platform. Teachers and school admins ask it questions in natural language, and it can also perform write operations: create an exam room, correct attendance, and so on. The stack is a LangGraph agent in Python calling an MCP server written in Go. The MCP server exposes 26 tools. Twelve of them write.
A few months after launch we found duplicate rows. Two exam rooms where the user had created one. Two attendance corrections where the user had made one.
Nothing in the logs looked wrong. Both writes were authenticated. Both were authorized. Both contained exactly what the user had asked for. There were just two of them.
The cause was mundane. Sometimes the user clicked again because the response felt slow. Sometimes the model called the same tool twice inside one turn. The user approved one action. The system performed two.
The first fix
I split every write tool into two phases.
The first call does not write anything. It returns a preview of what will happen, plus a confirmation token. The second call replays that token, and only then does the write happen.
The token is an HMAC. It is bound to the user ID, the tool name, and a hash of the parameters. It expires after five minutes. The nonce inside it is burned the moment it is used.
# phase 1 - preview only
token = hmac(secret, f"{user_id}|{tool}|{sha256(params)}|{nonce}|{exp}")
return {"preview": render(params), "confirm_token": token}
# phase 2 - execute
assert verify_hmac(token)
assert burn_nonce(token.nonce) # fails if already used
write(params)
The parameter hash matters. Without it, the model could show the user one thing and execute another. With it, what the user approved is exactly what runs.
I also strip the token out of the SSE stream before it reaches the browser. The model never sees it. The user never sees it.
This worked. The duplicate writes stopped. I considered the problem solved for a long time.
What I missed
The nonce protects the token. It does not protect the action.
Burning a nonce means one specific token cannot be used twice. But the agent does not need the old token. The agent re-plans.
It calls phase one again, for the same action. It receives a new token. A completely valid one. Then it replays that token, and the write happens a second time.
Walk through the checks with me. HMAC signature: valid, it is a fresh token. Nonce: unused, it is a fresh nonce. Expiry: fine, it was issued a second ago. Parameter hash: matches, because it is the same action with the same parameters.
Every check passes. That is the uncomfortable part. The parameter hash matching is the strongest evidence available that this is a duplicate, and my design treated it as proof of correctness instead.
The root cause is that my state was keyed by the token, not by the action. The issuer remembered which tokens had been spent. It remembered nothing about which actions had been performed.
Recent work has a name for this: semantic replay. Xu et al. define it as "exceeding the execution budget of a token-independent authorization instance rather than merely reusing an old token identifier" (Beyond Single-Use Tokens, arXiv:2608.01710). Their phrase for the failure mode is precise: identifier-local tokens permit fresh semantic reissuance.
That is exactly what my design did. It made reissuance cheap and invisible.
Why more token hardening does not help
The instinct is to tighten the token. It does not work.
A shorter expiry does not help, because the second token is brand new. A stronger nonce does not help, because no nonce is reused. Signing more fields does not help, because every field is legitimately identical.
Asking the user to confirm again feels like a fix, and it is the worst one. In a chat interface, the second confirmation prompt looks exactly like the first. The user clicks yes. That is not oversight. That is a rubber stamp with an audit log attached.
Every fix at the token layer protects the token. The problem is not at the token layer.
What actually closes it
Key the state to the action.
action_key = sha256(user_id | tool_name | canonical(params) | turn_id)
canonical(params) is not optional. Sort the keys, normalise the types. Otherwise {"a":1,"b":2} and {"b":2,"a":1} produce different keys and the mechanism does nothing.
Then keep a durable record per action key, and let the state move in one direction only.
- No record: create one in
ISSUEDstate, return a new token. - Already
ISSUED, not committed: return the same token again. Issuing is idempotent. You do not hand out a second authorization for an action that already has one. - Already
COMMITTED: refuse, and return the result of the first execution.
That third case is the one people forget. A duplicate request should not fail loudly. It should return what happened the first time.
Commit is a transaction. Flipping ISSUED to COMMITTED and performing the write happen together, or neither happens.
In my case the write goes out over HTTP, to the same REST endpoints the browser uses, so a shared database transaction is not available. The answer there is to derive an idempotency key from the action key and pass it to that endpoint.
Two layers, doing two different jobs. The ledger prevents duplicate admission. The idempotency key prevents duplicate effects. You need both, because the ledger can commit and the HTTP call underneath it can still be retried.
If this shape feels familiar, it should. It is at-least-once delivery with idempotent consumers. Agent frameworks are rediscovering a problem that message queues solved twenty years ago.
The cost
There is a trade-off here, and I would rather state it than hide it.
Including turn_id in the action key means a user can genuinely create two identical exam rooms in two different turns. That is correct behaviour. It is also a gap.
Removing turn_id closes the gap and breaks legitimate repetition.
There is no universally correct answer. There is only an explicit one. The choice I favour: keep turn_id, and when two action keys differ only by the turn while the parameters are identical inside a short window, surface a warning to the user instead of silently proceeding.
The takeaway
The risk in agent systems sits in the authorization layer and in the side effects, not in the model.
Human-in-the-loop tells you that an action was approved. It does not tell you that the action happened once. Those are different guarantees, and they are constantly confused.
So ask your stack one question. If the model re-plans, can it obtain a second valid approval for the same action? If you do not know the answer, it can.
