Skip to content

Questions, approvals and sub-agents in the UI

An agent needs the person for two different reasons, and the stack gives each its own mechanism.

Questions versus approvals

A question or request An approval
What it is The agent needs input: an answer, a file, a data source A tool call waits for permission before it runs
Who decides it's needed The model, by calling a tool The workflow, by gating the tool
Mechanism A tool the browser runs; the run ends with the call in pendingToolCallIds A native interrupt; the run ends with an interrupt outcome
Server code None: an allow-list (client_tools) interrupt.tools, or a tool that asks itself
UI useAskUserTool, useRequestTool KabooInterruptHandler (built in)
Remembered No "Allow for this chat", "Always allow", with a grant store

Use a question when the model can't go on without the person's input. Use an approval when the model can, but shouldn't without consent: deleting, publishing, spending. An approval is enforced by the workflow, not requested by the model, so a model can't talk its way past it.

Both wait with no time limit, survive a restart (the paused run travels in the conversation's state), and are skipped when the person sends a message instead.

Who should ask

Questions are usually best from one voice. Compare the two placements with the lab's pair:

  • The orchestrator asks before it delegates, so every sub-agent works from the answer (ask-orchestrator).
  • A sub-agent asks mid-task, when only it knows what's ambiguous (ask-subagent). Its coordinator is told in plain words what was asked and answered, so it doesn't ask again.

yarn lab compare who-asks --live measures both on a real model. Allow ask_user where you want the questions to come from, and say in the prompt when to ask: "only when the question is ambiguous in a way that changes the answer".

Sub-agents in the UI

A delegate's work shows as a card at the call that started it, with its own tool calls inside, drawn by the same renderers as the chat. Two rules keep the transcript readable:

  • What needs the person is lifted into the main transcript. A sub-agent's question, request or approval shows in the chat, labelled with the agent, so nobody has to open a card to find out the run is waiting. Once answered, the Q&A stays in the agent's card.
  • Several at once go in order. One agent's questions are one card that steps through them; parallel agents' requests show one after another, the next under "Up next".

A sub-agent's approval shows at its real tool row, so the person sees exactly which call they're approving.

Lab scenarios: question-subagent, question-parallel, approval-subagent, approval-tool-requested.

Where to look next