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

Web page: https://candor.themethodic.com/screens/tool-permissions

## Layouts

### Per agent, in its settings

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

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

Items:

- **Tool permissions** (`tool-permissions`, Pro; https://candor.themethodic.com/docs/tool-permissions.md): Per tool: always, ask first, or never.
- **Permission mode** (`permission-mode`, Pro; https://candor.themethodic.com/docs/permission-mode.md): The agent's mode, with what each mode lets it do written out.
- **Locked** (`locked`, free; https://candor.themethodic.com/docs/locked.md): A change this person can't make says why.

```bash
npx candor-ui add tool-permissions permission-mode locked
```

### Matrix of agents and tools

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

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

Items:

- **Role matrix** (`role-matrix`, Pro; https://candor.themethodic.com/docs/role-matrix.md): What each role can do, as a matrix; the same shape works for agents.
- **Tool permissions** (`tool-permissions`, Pro; https://candor.themethodic.com/docs/tool-permissions.md): The per-tool choice behind each cell.
- **Review ladder** (`review-ladder`, Pro; https://candor.themethodic.com/docs/review-ladder.md): How much a person reviews before agents act.

```bash
npx candor-ui add role-matrix tool-permissions review-ladder
```

### Changed from the prompt

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

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

Items:

- **Permission prompt** (`permission-prompt`, free; https://candor.themethodic.com/docs/permission-prompt.md): Opt-in "always allow", ticked by the person, never by default.
- **Tool permissions** (`tool-permissions`, Pro; https://candor.themethodic.com/docs/tool-permissions.md): Where the rules it creates are listed and removed.
- **Guardrail notice** (`guardrail-notice`, Pro; https://candor.themethodic.com/docs/guardrail-notice.md): One line when a guardrail stopped a call: what, and which rule.

```bash
npx candor-ui add permission-prompt tool-permissions guardrail-notice
```

## Rules that matter most here

- **A control that can't be used says why** (https://candor.themethodic.com/principles#locked-says-why): A tool this person can't change shows its setting and why it is fixed.
- **Nothing is pre-selected in a decision** (https://candor.themethodic.com/principles#nothing-preselected): A new tool starts as ask first, and "always allow" is never pre-ticked.
- **Say what can and can't be undone** (https://candor.themethodic.com/principles#say-what-can-be-undone): Setting "always" on a tool that can't be undone says so at that moment.

## Patterns that cover part of it

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

## Brief for a coding agent

Paste this to the agent that builds the screen.

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