Screens / Talking to the agent

Permission prompt in chat

Let the person allow or deny one tool call before it runs.

For: The person who is chatting with the agent.

Markdown

3 ways to lay it out

1. Inline in the thread

Pick it when: The default: the question sits where the agent stopped, so the person sees what led to it.

A thread with a prompt card between the agent's tool row and the composer, holding Deny and Allow buttons.

Permission promptFreeWhy it asked, the run's permission mode, the input to edit before allowing, opt-in "always allow".
Tool callFreeThe row above it, saying what the call is.
useCandorChatFreeapprovals and respond(id, approved, reason) for the Vercel AI SDK; useClaudeAgent and useAgUi do the same.
LockedFreeSays why Allow can't be used, for example when the person lacks the role.

Install inline in the thread

2. Docked above the composer

Pick it when: Long threads, where an inline prompt would scroll out of sight while the agent waits.

The message column with a prompt card fixed between it and the composer.

Permission promptFreeThe same prompt, pinned.
ComposerFreeSits right under it; the person can still write.
Task trayProHow many background runs are waiting on the person.

Install docked above the composer

Pro and Premium items need a licence key; free ones install as they are.

3. With a hold for a risky step

Pick it when: The call can't be undone, or reaches many things.

A prompt card with a scope list and a wide hold-to-confirm button along its bottom edge.

Permission promptFreeCarries the question.
Blast radiusProWhat the call can reach, or a plain statement that it couldn't be measured.
Hold to confirmProHeld for its full time; letting go cancels, and the reason says what it does.
Undo windowProAfter the step: Undo for exactly as long as the server allows.

Install with a hold for a risky step

Pro and Premium items need a licence key; free ones install as they are.

Rules that matter most here

Nothing is pre-selected in a decision
Allow and Deny both start unchosen, and "always allow" starts unticked.
A control that can't be used says why
If this person can't decide, the button stays and says why instead of disappearing or going grey.
Say what can and can't be undone
A call that can't be undone says so before the person decides, not after.

Already covered elsewhere

Pattern: Human-in-the-loop approval UI for AI agents
Pattern: Tool call UI for AI agents

Brief for a coding agent

Paste this into the agent that builds the screen. The docs MCP server returns the same text from get_screen.

Build a permission prompt in the chat with Candor UI: when the agent's tool call needs a go-ahead, show a PermissionPrompt in the thread where the agent stopped.
Read the waiting calls from `approvals` on useCandorChat (or useClaudeAgent, useAgUi) and answer with respond(id, approved, reason).
The prompt says why the agent asked, the run's permission mode and the input the person can edit before allowing; "don't ask again" rules start unticked.
Allow and Deny both start unchosen. If the person can't decide, wrap the control in Locked so it says why.
For a call that can't be undone, add BlastRadius and a HoldToConfirm, and say what can and can't be undone before the person decides; afterwards offer UndoWindow only for as long as the server allows.
The decision is shown only once the server has recorded it; never show an approval the server doesn't have.
Follow the ai-approval-ui pattern for the wording and the Allow / Deny layout.

Start from the "Inline in the thread" layout: A thread with a prompt card between the agent's tool row and the composer, holding Deny and Allow buttons.
Candor items: permission-prompt (https://candor.themethodic.com/docs/permission-prompt.md), tool-call (https://candor.themethodic.com/docs/tool-call.md), use-candor-chat (https://candor.themethodic.com/docs/use-candor-chat.md), locked (https://candor.themethodic.com/docs/locked.md).
Install: npx candor-ui add permission-prompt tool-call use-candor-chat locked
Read each item's docs before using it and take its props from there; don't guess them. Pro and Premium items need the person's licence key, which they add with `npx candor-ui key <key>`; don't ask for it.