Add structured pending-action confirmations for destructive tool calls

[lezama]

Problem

A downstream app can safely resolve a destructive operation to exact tool arguments, show the exact summary to the user, and ask for confirmation. The next user turn is usually just something like "Yes" or "Sí, borrar".

Today that confirmation goes back through the model as free text. The model has to infer that it should continue the previous pending operation and reuse the exact IDs/arguments it just listed. In practice this can loop: the model repeats the lookup/listing and asks for the same confirmation again instead of executing the already-confirmed action.

Concrete downstream case: wp-carpeta asks Menta to delete all paddocks whose name starts with Padrón. The agent lists 13 paddocks with exact IDs and asks "¿Borro estos 13 potreros?". When the user taps "Sí, borrar", the model repeats the list instead of calling carpeta/delete-potreros(ids=[...], confirm=true).

This is distinct from a generic external runtime-tool pending request. The tool, arguments, effect, and user-facing summary are already known. What is pending is the user's decision to execute exactly that action.

Desired contract

Agents API should support a structured pending-action confirmation state for tool calls, especially destructive/write/external effects.

A possible shape:

• loop/tool policy can return or register a pending_action with:
  • action id / nonce
  • agent/session/run id
  • tool/ability name
  • exact arguments to execute
  • resolved effect (write, destructive, external, etc.)
  • user-facing summary/prompt
  • expiry / single-use decision state
• a later user decision can resolve the pending action as allow/deny without asking the model to reconstruct arguments from transcript text;
• on allow, the loop executes the original tool call arguments and appends canonical tool-call/tool-result messages/events;
• on deny, the loop appends a canonical denied tool result so the model can respond normally;
• ambiguous free-text confirmations can still go through the model, but structured UI/channel decisions should not require transcript reconstruction.

Acceptance criteria

• A destructive tool call can be paused for confirmation and later resumed with the exact original arguments.
• The user-visible confirmation label can remain short (for example "Sí, borrar") while the runtime keeps the pending action id/args out of the visible message.
• Deny/cancel resolves the pending action without executing the tool.
• Expired or already-resolved pending actions cannot execute.
• Canonical transcript/events make replay/debug clear: pending action created, user decision received, tool executed or denied.
• Hosts can implement this without product-specific hidden-context hacks.

Related

• Automattic/agents-api#259 covers mediated tool preflight and external-tool pending hooks, but not the common "known tool args awaiting human confirmation" case.
• Automattic/agents-api#260 and #261 cover mediation and continuation/nudge behavior.
• lezama/openclawp#40 implemented an app-level confirmation gate; this asks for a product-neutral Agents API contract.

AI assistance

• AI assistance: yes
• Tool(s): Codex
• Used for: analyzing a downstream confirmation loop in wp-carpeta and drafting this upstream tracker.