# Tool Permission Row

Whether an agent may call a tool: Allow, Ask or Deny, with the scope it covers.

- Category: AI & Agents
- Page: https://wunderui.com/components/tool-permission-row
- Tier: Core and Pro

## Install

Tool Permission Row ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { ToolPermissionRow } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import { ToolPermissionRow } from "@wunderui/react"

export function WritePermission() {
  const [value, setValue] = useState<"allow" | "ask" | "deny">("ask")
  return (
    <ToolPermissionRow
      tool="files.write"
      description="Create and edit files in the workspace"
      value={value}
      onValueChange={setValue}
      scope="Pauses before each write and waits for a person"
    />
  )
}
```

Expected result: The tool id in monospace with its description, a switch with Allow, Ask and Deny with Ask selected, and the scope line under them. Pressing Deny or an arrow key moves the selection.

## When to use

### Use Tool Permission Row for

- A settings list of the tools an agent may call, one row per tool
- A default for a tool that applies to every run, with the scope it covers
- Showing that a tool is locked by a workspace policy

### Use something else

- [Scope List](https://wunderui.com/components/scope-list) for the access one request asks for, with a countdown until it lapses
- [Approval Card](https://wunderui.com/components/approval-card) for one pending action that a person approves or rejects
- [Segment](https://wunderui.com/components/segment) for any other choice between a few options that is not a permission

## Keyboard

The switch is a segmented control with one tab stop. The scope line is a native button when it has a detail.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into the switch, onto the selected option, and on to the scope button when there is one. Locked options are skipped. |
| `ArrowRight` or `ArrowLeft` | Moves focus to the next or previous option, from Deny back to Allow and the other way round. Nothing is chosen yet. |
| `Home` or `End` | Moves focus to Allow or Deny. Nothing is chosen yet. |
| `Enter` or `Space` | On a focused option, chooses it and calls `onValueChange` once. On the scope button, folds the detail out or in. |

Arrow keys only move focus. Enter or Space chooses the focused option, so one key press can never flip Deny to Allow.

## Behavior

How the row holds its level, what the keys do and what it leaves to the page around it.

- **Controlled or not:** Without a value the row keeps its own level, starting at Ask. With a value it shows that value and only reports changes to your handler, so without one it can't change.
- **Keyboard chooses on purpose:** Arrow keys, Home and End only move focus between Allow, Ask and Deny, and arrows wrap. Enter or Space chooses once, so one key press can't flip Deny to Allow, the riskiest change.
- **Semantics:** The switch is a tab list with three tabs, not radio buttons. It is named Permission for plus the tool id when the tool is a string, and just Permission otherwise.
- **Scope:** The scope is text you write. Without a detail it is a plain line, and with one a button folds the detail out, which stays in the DOM but inert while folded.
- **Consequences:** The row doesn't say what a level means. Write that in the scope, let it follow the level, and say it in a status line when it changes.
- **Locking:** Disabled turns the three options off, dims them to 40 % and removes them from the tab order. The level you pass is shown and nothing changes it, and a row in a disabled fieldset is locked too.
- **Layout:** The tool column is at least 240 px wide and the switch keeps its size. When the row is narrower than both, the switch wraps below the text.
- **Motion:** The chevron of a scope detail turns a quarter turn quickly, and the detail folds out a little slower. The switch doesn't slide.
- **Reduced motion:** With reduced motion the chevron turns at once and the detail appears at once. The level, text and focus order stay the same.

## Anatomy

- `ToolPermissionRow`: A row on the card background with 16 px side padding and 12 px top and bottom padding. It has no border or radius, so it sits in a box you provide.
- `Tool id`: The tool id in 12 px medium monospace. It breaks at any character so a long id wraps, and the text column is at least 240 px wide with the switch moving below it on a narrow row.
- `Description`: One line of 12 px secondary text under the id that says what the tool does.
- `Permission switch`: A small segmented control with Allow, Ask and Deny, named Permission for plus the tool id. Ask is selected by default.
- `Scope line`: 12 px tertiary text that says what the setting covers. With a detail it becomes a button with a chevron that folds the detail out below in 12 px secondary text.

## Best practices

### When to use

- Use it in a list of tools to set what an agent may do on its own. For the access one request asks for, use Scope List, and for a decision on one pending action, use Approval Card.

### Do

- Write the consequence of each level in the scope and let it follow the level: Writes without asking for Allow, Pauses before each write for Ask. The row writes no text of its own.
- Leave the default at Ask. A tool that runs without asking is a decision the person has to make on purpose.
- Pass the tool as a string. The switch is then named Permission for files.write, while with a node it is only named Permission, the same for every row on the page.
- Say what changed in a status line, such as files.write set to deny. The switch announces the option, not the consequence, and a changed scope line isn't a live region.
- Lock a row with disabled and put the reason in the scope line, such as Blocked by your workspace policy. A locked row can't take focus, so a tooltip would never be reached.
- Save each change as it comes. Arrow keys only move focus and Enter or Space chooses, so the change handler fires once per choice, but confirm Allow if the tool writes, deletes, sends or spends.

### Don't

- Don't set Allow as the default for tools that write, delete, send or spend. Reserve it for read-only tools the person has already seen.
- Don't pass a value without a change handler. A controlled row shows exactly the value it is given and does nothing when a person presses an option.

## API reference

### ToolPermissionRow

| Prop | Type | Default | Description |
|---|---|---|---|
| tool* | React.ReactNode |  | The tool id, shown in monospace. Pass a string so the switch is named `Permission for` and the id. |
| className | string |  | Extra classes for the row. It is `w-full` on the card background by default. |
| defaultValue | "ask" \| "allow" \| "deny" | "ask" | The starting level of an uncontrolled row. Default `ask`. |
| description | React.ReactNode |  | One line under the id that says what the tool does. |
| disabled | boolean |  | Locks the row: the three options are disabled and leave the tab order, and the level you pass stays shown. Default false. Say why in the scope line. |
| onValueChange | (value: ToolPermission) => void |  | Called with the new level when a person presses an option or chooses the focused one with Enter or Space. The arrow, Home and End keys only move focus and never call it. |
| scope | React.ReactNode |  | A line that says what the setting covers. Any content, so an icon can lead the text. Hidden when not set. |
| scopeDetail | React.ReactNode |  | More detail that folds out under the scope line. It turns the scope line into a button. Ignored without `scope`. |
| value | "ask" \| "allow" \| "deny" |  | The level of a controlled row: `allow`, `ask` or `deny`. Pair it with `onValueChange`, or the row cannot change. |

## Examples

### Level: allow, ask or deny

### Content: with and without a description, and long text

### Group: one list or rows under headings

### Policy: editable or locked

## In context

### Permissions panel: tools by area, a summary and a reset

Every row is controlled, so the scope line follows the level and the summary counts them. On a focused row the arrow keys move between levels and Enter or Space chooses.

### Workspace policy: one tool is locked

An admin policy blocks shell.run. The row shows Deny, its switch is disabled, and the reason sits in the scope line; the person can ask for access.

### Widening asks first: Allow needs a yes

Moving a tool to Allow does not apply at once: the row keeps its level while a panel says what Allow means and waits. Moving to Ask or Deny applies immediately.

## For AI agents

`get_component("tool-permission-row")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
