# 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.

Web page: https://candor.themethodic.com/screens/permission-prompt

## Layouts

### Inline in the thread

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

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

Items:

- **Permission prompt** (`permission-prompt`, free; https://candor.themethodic.com/docs/permission-prompt.md): Why it asked, the run's permission mode, the input to edit before allowing, opt-in "always allow".
- **Tool call** (`tool-call`, free; https://candor.themethodic.com/docs/tool-call.md): The row above it, saying what the call is.
- **useCandorChat** (`use-candor-chat`, free; https://candor.themethodic.com/docs/use-candor-chat.md): approvals and respond(id, approved, reason) for the Vercel AI SDK; useClaudeAgent and useAgUi do the same.
- **Locked** (`locked`, free; https://candor.themethodic.com/docs/locked.md): Says why Allow can't be used, for example when the person lacks the role.

```bash
npx candor-ui add permission-prompt tool-call use-candor-chat locked
```

### Docked above the composer

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

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

Items:

- **Permission prompt** (`permission-prompt`, free; https://candor.themethodic.com/docs/permission-prompt.md): The same prompt, pinned.
- **Composer** (`composer`, free; https://candor.themethodic.com/docs/composer.md): Sits right under it; the person can still write.
- **Task tray** (`task-tray`, Pro; https://candor.themethodic.com/docs/task-tray.md): How many background runs are waiting on the person.

```bash
npx candor-ui add permission-prompt composer task-tray
```

### With a hold for a risky step

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

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

Items:

- **Permission prompt** (`permission-prompt`, free; https://candor.themethodic.com/docs/permission-prompt.md): Carries the question.
- **Blast radius** (`blast-radius`, Pro; https://candor.themethodic.com/docs/blast-radius.md): What the call can reach, or a plain statement that it couldn't be measured.
- **Hold to confirm** (`hold-to-confirm`, Pro; https://candor.themethodic.com/docs/hold-to-confirm.md): Held for its full time; letting go cancels, and the reason says what it does.
- **Undo window** (`undo-window`, Pro; https://candor.themethodic.com/docs/undo-window.md): After the step: Undo for exactly as long as the server allows.

```bash
npx candor-ui add permission-prompt blast-radius hold-to-confirm undo-window
```

## Rules that matter most here

- **Nothing is pre-selected in a decision** (https://candor.themethodic.com/principles#nothing-preselected): Allow and Deny both start unchosen, and "always allow" starts unticked.
- **A control that can't be used says why** (https://candor.themethodic.com/principles#locked-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** (https://candor.themethodic.com/principles#say-what-can-be-undone): A call that can't be undone says so before the person decides, not after.

## Patterns that cover part of it

- Human-in-the-loop approval UI for AI agents: https://candor.themethodic.com/patterns/ai-approval-ui.md
- Tool call UI for AI agents: https://candor.themethodic.com/patterns/tool-call-ui.md

## Brief for a coding agent

Paste this to the agent that builds the screen.

```text
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.
```