Tool Permission Row
ProWhether an agent may call a tool: Allow runs it without asking, Ask pauses for a person and Deny blocks it, with a line that says what the setting covers.
Playground
files.writeCreate and edit files in the workspace
files.writeCreate and edit files in the workspace
Pauses before each write and waits for a person
files.writeCreate and edit files in the workspace
Installation
Tool Permission Row comes with WunderUI Core and Pro, in the package from your plan. See the plans.
Then import what you need:
import { ToolPermissionRow } from "@wunderui/react"Then use it:
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 for
- Scope List for the access one request asks for, with a countdown until it lapses
- Approval Card for one pending action that a person approves or rejects
- Segment for any other choice between a few options that is not a permission
Level
Allow runs the tool without asking, Ask pauses for a person and Deny blocks it; Ask is the default. Write what each level means for this tool in the scope line.
files.writeCreate and edit files in the workspace
Pauses before each write and waits for a person
Content
The tool id is set in monospace and breaks at any character, so a long id wraps instead of pushing the switch out. The description is optional.
files.writeCreate and edit files in the workspace
files.writeworkspace.files.write_and_overwrite_existing_files_in_nested_foldersCreate new files and overwrite existing ones anywhere under the workspace folders the person has opened in this run
Grouping
The row has no frame of its own. Put the rows in a box with one divider between them, and add a headed group per area when the list is long.
Group
files.readRead files in the workspace
files.writeCreate and edit files in the workspace
web.searchSearch the web and read the results
Files
files.readRead files in the workspace
files.writeCreate and edit files in the workspace
Web
web.searchSearch the web and read the results
Messages
email.sendSend an email from info@wunderui.com
Locked by policy
A locked row disables the three options, takes them out of the tab order and keeps showing the level you pass. Put the reason in the scope line, where it stays visible.
Policy
shell.runRun a command in the terminal
Pauses before each command and waits for a person
shell.runRun a command in the terminal
Blocked by your workspace policy
Keyboard interactions
The switch is a segmented control with one tab stop. The scope line is a native button when it has a detail.
- TaborShift+Tab
- Moves focus into the switch, onto the selected option, and on to the scope button when there is one. Locked options are skipped.
- ArrowRightorArrowLeft
- Moves focus to the next or previous option, from Deny back to Allow and the other way round. Nothing is chosen yet.
- HomeorEnd
- Moves focus to Allow or Deny. Nothing is chosen yet.
- EnterorSpace
- On a focused option, chooses it and calls 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 and motion
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
The figure marks a row with a scope detail. The folded-out detail belongs to the scope line and has no number of its own.
files.writeCreate and edit files in the workspace
- 1data-slot="tool-permission-row"
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.
- 2
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.
- 3Optional
One line of 12 px secondary text under the id that says what the tool does.
- 4
A small segmented control with Allow, Ask and Deny, named Permission for plus the tool id. Ask is selected by default.
- 5Optional
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
- 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.
- Do
Leave the default at Ask. A tool that runs without asking is a decision the person has to make on purpose.
- Do
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.
- Do
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.
- Do
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.
- Do
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
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 is a plain component, not a wrapper of a primitive, so this table lists every prop. It passes no other props on to its element.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| tool required | ReactNode | — | The tool id, shown in monospace. Pass a string so the switch is named and the id. |
| description | ReactNode | — | One line under the id that says what the tool does. |
| value | "ask" | "allow" | "deny" | — | The level of a controlled row: , or . Pair it with , or the row cannot change. |
| defaultValue | "ask" | "allow" | "deny" | "ask" | The starting level of an uncontrolled row. Default . |
| onValueChange | (value) => 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 | ReactNode | — | A line that says what the setting covers. Any content, so an icon can lead the text. Hidden when not set. |
| scopeDetail | ReactNode | — | More detail that folds out under the scope line. It turns the scope line into a button. Ignored without . |
| 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. |
| className | string | — | Extra classes for the row. It is on the card background by default. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("tool-permission-row")The full library index for assistants is at /llms.txt.
Related components
Requested access
Expires in- Read the docs appapps/docs · 412 files
- Edit component filespackages/react/src/components · 198 files
- Open a pull requestwunder-ui/wunderui · branch tokens-sync
AI & Agents5 stylesProScope ListWhat an agent asks to access, one scope per row, with a countdown until the request lapses.Send 14 payment reminders
Medium riskEmails the contact on every invoice more than 30 days overdue. Sent emails cannot be recalled.
2 min agoPOST /email/bulk to: 14 recipients template: invoice-overdue-30 dry_run: false
AI & Agents5 stylesProApproval CardThe human-in-the-loop gate: what the agent wants to do, how risky it is, approve or reject.- Done420 tok$0.01640ms
Input
status: overdue, age: 30+ daysOutput
14 invoices, $42,860 in total - Done3,420 tok$0.042.1s
Input
14 invoice idsOutput
14 contacts, all with an email address - Running2,310 tok
Input
template: invoice-overdue-30 - Pending
Input
to: 14 recipients - PendingLog the result
AI & Agents5 stylesProRun TimelineEvery step of a run in order, with duration, tokens and expandable input/output.