Approval Flow Processing Architecture#
Internal architecture reference for the tool approval system in TanStack AI. Covers the full lifecycle from stream event to continuation, with emphasis on concurrency control and the chained approval mechanism.
Table of Contents#
- Overview
- Component Responsibilities
- Type System
- State Machine
- Single Approval Lifecycle
- Chained Approvals and Continuation Control
- Stream Event Protocol
- Key Source Files
Overview#
The approval flow allows tools marked with needsApproval: true to pause
execution until the user explicitly approves or denies the action. This
creates a human-in-the-loop checkpoint for sensitive operations (sending
emails, making purchases, deleting data).
The flow spans three layers:
flowchart TD
A[Server - TextEngine]
B[StreamProcessor]
C[ChatClient]
A -- "AG-UI stream · SSE / HTTP" --> B
B -- "events" --> C
| Layer | Responsibility |
|---|---|
| Server (TextEngine) | chat() detects needsApproval → emits CUSTOM approval-requested instead of executing the tool |
| StreamProcessor | Receives CUSTOM chunk → updateToolCallApproval() → fires onApprovalRequest callback |
| ChatClient | Exposes addToolApprovalResponse() → updates message state → triggers checkForContinuation() → sends new stream |
Framework hooks (useChat in React, Solid, Vue, Svelte) delegate to
ChatClient, which owns all concurrency and continuation logic.
Component Responsibilities#
TextEngine (server)#
- Runs the agent loop: calls the LLM adapter, accumulates tool calls, executes tools, and re-invokes the adapter with results.
- When a tool has
needsApproval: true, the engine emits aCUSTOM { name: "approval-requested" }event instead of executing the tool. - The stream ends with
RUN_FINISHED { finishReason: "tool_calls" }so the client knows tools are pending.
StreamProcessor (packages/typescript/ai/src/activities/chat/stream/processor.ts)#
- Single source of truth for
UIMessage[]state. - On
approval-requestedcustom event:- Calls
updateToolCallApproval()to set the tool-call part's state toapproval-requestedand attach approval metadata. - Fires
onApprovalRequestso the ChatClient can emit devtools events.
- Calls
- On
addToolApprovalResponse(approvalId, approved):- Calls
updateToolCallApprovalResponse()to set state toapproval-respondedand recordapproval.approved.
- Calls
- Provides
areAllToolsComplete()which the ChatClient uses to decide whether to auto-continue the conversation.
ChatClient (packages/typescript/ai-client/src/chat-client.ts)#
- Owns the streaming lifecycle (
streamResponse), post-stream action queue, and continuation control flags. - Exposes
addToolApprovalResponse()as the public API for responding to approval requests. - Manages two critical flags for continuation:
continuationPending— prevents concurrentstreamResponsecalls.continuationSkipped— detects when a queued continuation check was suppressed bycontinuationPendingand needs re-evaluation.
Framework Hooks (React useChat, Solid useChat, etc.)#
- Wrap
ChatClientmethods in framework-specific reactive primitives. - Expose
addToolApprovalResponsedirectly to the component. - No approval-specific logic beyond delegation.
Type System#
ToolCallState#
type ToolCallState =
| 'awaiting-input' // TOOL_CALL_START received, no arguments yet
| 'input-streaming' // Partial arguments being received
| 'input-complete' // All arguments received (TOOL_CALL_END)
| 'approval-requested' // Waiting for user approval
| 'approval-responded' // User has approved or denied
ToolCallPart (approval-relevant fields)#
interface ToolCallPart {
type: 'tool-call'
id: string // Unique tool call ID
name: string // Tool name
arguments: string // JSON string of arguments
state: ToolCallState
approval?: {
id: string // Unique approval ID (NOT the toolCallId)
needsApproval: boolean // Always true when present
approved?: boolean // undefined until user responds
}
output?: any // Set after execution (client tools)
}
Key distinction: approval ID vs tool call ID#
The approval.id is a separate identifier generated per approval request.
All user-facing APIs (addToolApprovalResponse) use the approval ID,
not the tool call ID. This allows the system to correlate approval responses
even when multiple tools share similar call IDs across different messages.
State Machine#
flowchart TD
S1[awaiting-input]
S2[input-streaming]
S3[input-complete]
S4[approval-requested]
S5([execute directly])
S6[approval-responded]
S7([execute tool])
S8([cancelled])
S1 -- "TOOL_CALL_START" --> S2
S2 -- "TOOL_CALL_ARGS" --> S3
S3 -- "TOOL_CALL_END · needsApproval: true" --> S4
S3 -- "TOOL_CALL_END · needsApproval: false" --> S5
S4 -- "addToolApprovalResponse()" --> S6
S6 -- "approved: true" --> S7
S6 -- "approved: false" --> S8
Terminal states for areAllToolsComplete()#
A tool call is considered complete (and eligible for auto-continuation) when any of the following is true:
state === 'approval-responded'— user approved or deniedoutput !== undefined && !approval— client tool finished (no approval flow)- A corresponding
tool-resultpart exists — server tool finished
Single Approval Lifecycle#
Step-by-step flow for a single tool requiring approval:
1. Server emits approval request during stream#
TOOL_CALL_START { toolCallId: "tc-1", toolName: "send_email" }
TOOL_CALL_ARGS { toolCallId: "tc-1", delta: '{"to":"..."}' }
TOOL_CALL_END { toolCallId: "tc-1" }
CUSTOM { name: "approval-requested", value: {
toolCallId: "tc-1",
toolName: "send_email",
input: { to: "..." },
approval: { id: "appr-1", needsApproval: true }
}}
RUN_FINISHED { finishReason: "tool_calls" }
2. StreamProcessor processes the CUSTOM chunk#
handleCustomEvent():
1. updateToolCallApproval(messages, messageId, "tc-1", "appr-1")
→ Sets part.state = "approval-requested"
→ Sets part.approval = { id: "appr-1", needsApproval: true }
2. emitMessagesChange()
3. fires onApprovalRequest({ toolCallId, toolName, input, approvalId })
3. Stream ends, ChatClient processes#
streamResponse() finally block:
1. setIsLoading(false)
2. drainPostStreamActions() → (nothing queued)
3. streamCompletedSuccessfully check:
lastPart is tool-call (not tool-result) → no auto-continue
→ Returns to caller (sendMessage resolves)
The conversation is now paused. The UI renders the approval prompt.
4. User approves#
addToolApprovalResponse({ id: "appr-1", approved: true }):
1. processor.addToolApprovalResponse("appr-1", true)
→ updateToolCallApprovalResponse():
part.approval.approved = true
part.state = "approval-responded"
2. isLoading is false → call checkForContinuation() directly
5. Continuation#
checkForContinuation():
1. continuationPending = false, isLoading = false → proceed
2. shouldAutoSend() → areAllToolsComplete():
part.state === "approval-responded" → true
3. continuationPending = true
4. streamResponse() → new stream to server with approval in messages
5. Server sees approval, executes tool, returns result + LLM response
6. continuationPending = false
Chained Approvals and Continuation Control#
The most complex scenario: a continuation stream produces another tool call that also needs approval, and the user responds to it while the stream is still active.
The Problem#
Timeline:
─────────────────────────────────────────────────────────────
1. User approves tool A
└─ checkForContinuation() sets continuationPending = true
└─ streamResponse() starts (stream 2)
2. Stream 2 produces tool B needing approval
└─ approval-requested chunk processed
└─ UI shows approval prompt for tool B
3. User approves tool B WHILE stream 2 is still active
└─ addToolApprovalResponse():
└─ processor state updated (approval-responded)
└─ isLoading is true → queues checkForContinuation
4. Stream 2 ends
└─ streamResponse() finally block:
└─ setIsLoading(false)
└─ drainPostStreamActions():
└─ Runs queued checkForContinuation()
└─ BUT continuationPending is STILL TRUE (from step 1)
└─ *** EARLY RETURN — approval swallowed ***
└─ Returns to step 1's checkForContinuation()
└─ continuationPending = false
5. Nobody re-checks → tool B's approval is lost
The Solution: continuationSkipped Flag#
Two flags work together to handle this:
continuationPending— prevents concurrentstreamResponse()calls. Set totruewhen enteringcheckForContinuation's streaming path, cleared in thefinallyblock.continuationSkipped— set totruewhenevercheckForContinuation()returns early due tocontinuationPendingorisLoadingbeing true. Checked aftercontinuationPendingis cleared to trigger a re-evaluation.
private async checkForContinuation(): Promise<void> {
if (this.continuationPending || this.isLoading) {
this.continuationSkipped = true // ← Mark that a check was suppressed
return
}
if (this.shouldAutoSend()) {
this.continuationPending = true
this.continuationSkipped = false // ← Reset before entering stream
try {
await this.streamResponse()
} finally {
this.continuationPending = false
}
// If a check was skipped during the stream, re-evaluate now
if (this.continuationSkipped) {
this.continuationSkipped = false
await this.checkForContinuation() // ← Recurse safely
}
}
}
Why the recursion is safe#
The recursion terminates because:
continuationSkippedis only set when a real check was suppressed. After the final stream (e.g., a text-only response), no new approvals arrive, socontinuationSkippedstaysfalseand the recursion stops.shouldAutoSend()returnsfalsewhen tools are still pending approval. If a new approval arrives that hasn't been responded to yet,areAllToolsComplete()returnsfalseand the method exits without streaming.Each recursion level sets
continuationPending = true, preventing any concurrent checks from entering the streaming path.
Corrected Timeline#
Timeline (with fix):
─────────────────────────────────────────────────────────────
1. User approves tool A
└─ checkForContinuation() [OUTER]
└─ continuationPending = true, continuationSkipped = false
└─ streamResponse() starts (stream 2)
2. Stream 2 produces tool B, user approves during stream
└─ Queues checkForContinuation as post-stream action
3. Stream 2 ends
└─ drainPostStreamActions():
└─ checkForContinuation(): continuationPending is true
└─ continuationSkipped = true ← MARKED
└─ returns early
└─ Back in OUTER: continuationPending = false
4. OUTER checks continuationSkipped → true
└─ continuationSkipped = false
└─ Recurses into checkForContinuation() [INNER]
└─ shouldAutoSend() → true (tool B is approval-responded)
└─ continuationPending = true
└─ streamResponse() → stream 3 (final text response)
└─ continuationPending = false
└─ continuationSkipped is false → no further recursion
5. Done. All three streams completed correctly.
Stream Event Protocol#
Approval-related AG-UI events#
These are CUSTOM events emitted by the TextEngine, not by adapters directly.
approval-requested#
Emitted when a tool with needsApproval: true has its arguments finalized.
{
type: 'CUSTOM',
name: 'approval-requested',
value: {
toolCallId: string, // ID of the tool call
toolName: string, // Name of the tool
input: any, // Parsed arguments
approval: {
id: string, // Unique approval ID
needsApproval: true
}
}
}
Processor handling: handleCustomEvent() → updateToolCallApproval() →
onApprovalRequest callback.
Relation to other tool events#
A complete approval tool call in the stream looks like:
TOOL_CALL_START → creates tool-call part (state: awaiting-input)
TOOL_CALL_ARGS* → accumulates arguments (state: input-streaming)
TOOL_CALL_END → finalizes arguments (state: input-complete)
CUSTOM → approval-requested (state: approval-requested)
RUN_FINISHED → finishReason: "tool_calls"
After the stream ends and the user responds, the ChatClient:
- Updates the tool-call part (state:
approval-responded) - Sends a new stream request with the full conversation (including approval)
- The server sees the approval and either executes or cancels the tool
Key Source Files#
| File | Role |
|---|---|
packages/typescript/ai/src/types.ts | ToolCallState, ToolCallPart, tool approval types |
packages/typescript/ai/src/activities/chat/stream/processor.ts | handleCustomEvent() (approval-requested), areAllToolsComplete(), addToolApprovalResponse() |
packages/typescript/ai/src/activities/chat/stream/message-updaters.ts | updateToolCallApproval(), updateToolCallApprovalResponse() |
packages/typescript/ai-client/src/chat-client.ts | addToolApprovalResponse(), checkForContinuation(), continuation flags |
packages/typescript/ai-react/src/use-chat.ts | React hook: exposes addToolApprovalResponse |
packages/typescript/ai-solid/src/use-chat.ts | Solid hook: exposes addToolApprovalResponse |
packages/typescript/ai-vue/src/use-chat.ts | Vue composable: exposes addToolApprovalResponse |
packages/typescript/ai-svelte/src/create-chat.svelte.ts | Svelte: exposes addToolApprovalResponse |
packages/typescript/ai-client/tests/chat-client.test.ts | Chained approval test (describe('chained tool approvals')) |
packages/typescript/ai/docs/chat-architecture.md | Internal stream processing architecture |