Screens / Approving and controlling

Tool permissions

Say, per tool, what an agent may do without asking, what needs a go-ahead, and what it may never do.

For: Admins and the people who own an agent.

Markdown

3 ways to lay it out

1. Per agent, in its settings

Pick it when: One agent's page: its tools in one list with always, ask first or never.

A settings page with a list of tools, each with a three-way choice, under the agent's permission mode.

Tool permissionsProPer tool: always, ask first, or never.
Permission modeProThe agent's mode, with what each mode lets it do written out.
LockedFreeA change this person can't make says why.

Install per agent, in its settings

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

2. Matrix of agents and tools

Pick it when: A team of agents where the question is who may do what.

A grid with agents down the side and tools across the top, each cell a choice.

Role matrixProWhat each role can do, as a matrix; the same shape works for agents.
Tool permissionsProThe per-tool choice behind each cell.
Review ladderProHow much a person reviews before agents act.

Install matrix of agents and tools

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

3. Changed from the prompt

Pick it when: People learn what to allow while using the agent: "always allow" on the prompt writes a rule.

A thread with a permission prompt whose "always allow" box, unticked, links to the rules list.

Permission promptFreeOpt-in "always allow", ticked by the person, never by default.
Tool permissionsProWhere the rules it creates are listed and removed.
Guardrail noticeProOne line when a guardrail stopped a call: what, and which rule.

Install changed from the prompt

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

Rules that matter most here

A control that can't be used says why
A tool this person can't change shows its setting and why it is fixed.
Nothing is pre-selected in a decision
A new tool starts as ask first, and "always allow" is never pre-ticked.
Say what can and can't be undone
Setting "always" on a tool that can't be undone says so at that moment.

Already covered elsewhere

Pattern: Human-in-the-loop approval 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 tool permissions screen with Candor UI: per tool, always, ask first, or never.
Use ToolPermissions for the list and PermissionMode for the agent's mode; each mode is written out in words, not just named.
A new tool starts as ask first. "Always" is a choice the person makes, never a default.
Wrap a setting this person can't change in Locked so it shows its value and says why.
When the person sets "always" on a tool that changes or deletes things, say what can and can't be undone.
Rules created from a PermissionPrompt ("don't ask again") appear in the same list and can be removed there.
Enforce the setting on your server: the screen shows a permission, it doesn't grant one.
See the ai-approval-ui pattern.

Start from the "Per agent, in its settings" layout: A settings page with a list of tools, each with a three-way choice, under the agent's permission mode.
Candor items: tool-permissions (https://candor.themethodic.com/docs/tool-permissions.md), permission-mode (https://candor.themethodic.com/docs/permission-mode.md), locked (https://candor.themethodic.com/docs/locked.md).
Install: npx candor-ui add tool-permissions permission-mode 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.