Tool Result Handling and Resume Flow#

When the agent runner emits a client-tool call (e.g., request_input for elicitation or request_connection for OAuth), the frontend parks the call, shows a widget, collects the user's response, then resumes the run by replaying the conversation with the tool result injected. This article covers the three distinct phases of that lifecycle: settlement timing, message array composition, and cross-turn scoping.

Introduced in PR #4934 1 and extended with schema-driven elicitation in PR #5155 2.

Settlement Timing: settle() → addToolOutput → Resume#

The settlement chain runs entirely on the frontend 1 2:

1. Widget calls settle(...) — ConnectToolWidget (line 186–188) or ElicitationWidget (line 151) call settle on user action (confirm/accept/cancel).
2. ClientToolPart dispatcher (lines 40–51) wraps the settlement into { toolName, toolCallId, output | errorText } and calls the onClientToolOutput callback.
3. handleClientToolOutput in AgentChatPanel.tsx (lines 264–289) calls the AI SDK's addToolOutput with { tool: toolName, toolCallId, output } (success) or { state: "output-error", tool: toolName, toolCallId, errorText } (failure) 1.
4. agentShouldResumeAfterApproval in agentApprovalResume.ts fires when it detects a settled client-tool part (lines 113–151) — the AI SDK's sendAutomaticallyWhen hook then re-sends the conversation as the resume HTTP request 2.

widget.settle()
  └─▶ ClientToolPart dispatcher (40–51)
        └─▶ handleClientToolOutput / addToolOutput (264–289)
              └─▶ agentShouldResumeAfterApproval fires (113–151)
                    └─▶ HTTP resume POST → runner

Resume Predicate and Approval Metadata Guard#

agentApprovalResume.ts contains the three-state logic that triggers resume 3 1:

The approval == null guard is load-bearing: an approval-gated server tool that was approved and ran also lands in output-available with providerExecuted falsy. Without this guard, resume fires twice 1.

Two helpers classify parts: isClientTool(part, renderMap) (checks render.kind or falls back to CLIENT_TOOL_NAMES for v1 compat) and isClientToolResult(part, renderMap) (triggers auto-resume on settled state) 4.

Message Array Composition for Resume#

The resume HTTP body is assembled by the AI SDK from the current message array. The message array contains 2 4:

• tool-call parts: { toolCallId, toolName, args } — the original AI request
• data-render sibling parts: { toolCallId, render: { kind: "elicitation" | "connect" } } — render hints that traveled as separate stream parts because AI SDK v6 strict objects drop inline fields
• tool_result blocks: injected by addToolOutput — the settled widget output (output: Record<string, unknown> for success; errorText: string for error)

buildRenderMap(parts) reconstructs a Map<toolCallId, RenderHintLike> from the data-render parts at resume time. Both the registry dispatcher and the resume predicate consume this same map 4.

Cross-Turn Scoping of Tool Result Blocks#

On the runner side, responder.ts gates which tool_result blocks satisfy a pending client-tool call 2:

• currentTurnStartIndex(request) — finds the latest user-role message boundary (returns 0 if none exists).
• currentTurnToolResultBlocks(request) — yields only tool_result blocks at or after that boundary.

extractClientToolOutputs() was updated to use currentTurnToolResultBlocks (was previously full-history) so a second identical request_input call in turn 2 cannot reuse turn 1's answer — it parks and shows a fresh form 2. Approval grants remain full-history; they are idempotent.

Queue Gating#

agentMessageQueue.ts holds queued user messages via canReleaseQueuedMessage() (lines 47–56) while any pending client-tool interaction exists 4. The gate releases automatically when the resume predicate fires — preventing a user's next message from injecting into the transcript before the widget settles 2.

Graceful Degradation#

• Unknown tools — UnhandledClientTool.tsx auto-settles unrecognized tools so the run never hangs silently 1.
• Invalid payloads — ElicitationWidget.tsx auto-settles malformed payloads with "elicitation: unsupported payload — ...". A degradedEarlierInTurn flag caps the settle→resume→re-emit loop at one retry per turn 2.

Key Files#