Human-in-the-Loop Tool Approval#

Human-in-the-Loop (HITL) tool approval is the mechanism by which the agent chat pauses a run when a tool requires browser-side fulfillment or explicit user consent, collects the required response, and then resumes the run. It consolidates two distinct interaction paths — approval-gated server tools (approve/deny before the runner executes) and client tools (browser fulfills the tool directly, e.g., OAuth, form input) — through a shared resume predicate.

The full system spans:

• Resume predicate — decides when a paused run should continue
• Queue gating — prevents user messages from injecting into the transcript while a tool is pending
• Render hint infrastructure — routes tool calls to the correct browser widget
• Approval metadata guard — distinguishes client-tool results from server-tool approvals

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

Resume Predicate and Approval Metadata Guard#

agentApprovalResume.ts is the single module that decides when agentShouldResumeAfterApproval fires. It recognizes three distinct settled states 1 2:

The approval metadata guard (checking approval == null) is load-bearing: an approval-gated tool that was approved and subsequently ran server-side also lands in output-available with providerExecuted falsy. Without the guard, the predicate would fire a second spurious resume. 1

Two classification helpers support the predicate 3:

• isClientTool(part, renderMap) — returns true when renderKindFor() resolves a known render.kind or the tool name is in CLIENT_TOOL_NAMES (v1 backward-compatibility)
• isClientToolResult(part, renderMap) — returns true for a settled client-tool part; triggers auto-resume

Queue Gating#

agentMessageQueue.ts holds the outbound user-message queue via canReleaseQueuedMessage() for as long as any pending client-tool interaction exists. 3 Without this gate, a queued user message could inject itself into the conversation transcript before the widget has settled, producing an incoherent run. 2

The gate is released automatically when the resume predicate fires — that is, when the widget calls settle(...), which chains through:

1. Widget → settle(...) via the onClientToolOutput callback
2. addToolOutput in AgentChatPanel matches the parked part by toolCallId
3. agentShouldResumeAfterApproval detects the settled result → queue released

Cross-turn isolation (runner side): A companion fix in responder.ts scopes the client-tool output store to the current turn only. currentTurnToolResultBlocks yields tool_result blocks at or after the latest user-role message, so a second identical request_input call in a new turn re-pauses and shows a fresh interaction rather than silently reusing the prior turn's answer. Approval grants remain full-history (idempotent). 2

Render Hint Infrastructure#

Because AI SDK v6 tool chunks are strict objects that drop inline fields, render.kind cannot be embedded directly in the tool-call part. Instead it travels as a sibling data-render stream part containing { toolCallId, render: { kind, ... } }. 3

renderMap.ts provides two utilities 3 2:

• buildRenderMap(parts) — filters data-render parts from a message and returns a Map<toolCallId, RenderHintLike>. This is the single source of truth for render hints within a turn.
• renderKindFor(part, renderMap) — checks the inline render.kind field first (forward compatibility), then falls back to the map.

Both registry.tsx (widget dispatch) and agentApprovalResume.ts (resume predicate) consume the same render map, ensuring consistent tool classification.

AI SDK v6 stream
  ├─ tool-call part { toolCallId, toolName, args }
  └─ data-render part { toolCallId, render: { kind: "elicitation" } }
          │
          ▼
    buildRenderMap()
          ├──▶ registry.tsx → widget lookup
          └──▶ agentApprovalResume.ts → resume predicate

Client-Tool Registry and Dispatch#

registry.tsx resolves the widget for a tool part using three-tier precedence 3 2:

render.kind is the primary axis for all new interaction kinds. toolName-based dispatch is legacy — request_connection predates the render-hint guarantee. 1

meta.ts derives the renderKind and toolName properties a registry lookup needs, from a ToolUIPart and the message-scoped render map. 3

Graceful degradation — UnhandledClientTool auto-settles any unrecognized tool so the run continues. ElicitationWidget handles malformed payloads by auto-settling with an errorText prefix; a degradedEarlierInTurn flag prevents the settle → resume → re-emit loop from repeating more than once per turn. 3 2

Key Files Reference#