Expose mediated tool preflight and external-tool pending hooks

[chubes4]

Problem

Data Machine is trying to migrate Extra-Chill/data-machine#2453 to the Agents API mediated conversation path. Normal server-side tool execution can use tool_executor + tool_declarations, but DM still has product behavior that currently happens before/around tool execution inside its caller-managed loop:

• duplicate tool-call rejection before execution
• runtime-rule rejection before execution
• external/client runtime tools that return a pending request instead of executing in PHP
• host metadata for pending runtime-tool requests and resume handoff
• completion nudge behavior after mediated tool results
• DM trace/inflight summary hooks around each executed tool

Automattic/agents-api#250 described the broader runtime-tool lifecycle, but the merged runtime policy work only added opt-in filtering. The mediated loop still has no host-neutral way for a product to intercept a tool call before execution, return a canonical pending external-tool status, or attach host diagnostics around mediated execution without forking the loop.

Desired contract

Agents API should expose host-neutral extension points in the mediated tool path so hosts can provide policy and lifecycle behavior while the loop remains the owner of sequencing and canonical envelopes.

A useful shape would include:

• a pre-tool-call hook/adapter that can allow, reject with a tool-result message, or return a canonical pending external-tool envelope
• a canonical pending external-tool status/result that stops the run without pretending the conversation completed
• enough context in the hook to include turn, tool name, parameters, declaration, request/run/session metadata, and prior messages
• a post-tool-result hook/adapter for host diagnostics such as traces, summaries, and product-specific metadata
• clear final result fields for pending external tools alongside existing approval_required, budget_exceeded, stalled, and interrupted

Acceptance criteria

• Data Machine can route normal PHP/server tools through WP_Agent_Conversation_Loop mediation without reimplementing the tool loop.
• Data Machine can preserve runtime/client tool pending behavior through a canonical Agents API pending external-tool envelope.
• Data Machine can preserve duplicate/runtime-rule rejections through a host preflight adapter, not a parallel local loop.
• Hosts can attach diagnostics/audit metadata around mediated tool execution without storing raw sensitive parameters.
• The default mediated path remains storage-neutral and does not add concrete storage/log tables.

Related

• DM migration blocker: Extra-Chill/data-machine#2453
• Previous runtime-tool lifecycle tracker: Automattic/agents-api#250
• Runtime tool policy opt-in: Automattic/agents-api#257

AI assistance

• AI assistance: Yes
• Tool(s): OpenCode (GPT-5.5)
• Used for: Auditing the Data Machine migration blocker and drafting this upstream contract issue.