Skip to content
WunderUI

Tool Permission Row

Pro

Whether 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.write

Create and edit files in the workspace

Pauses before each write and waits for a person

Installation

Tool Permission Row comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

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

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

Create 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.write

Create and edit files in the workspace

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

Read files in the workspace

files.write

Create and edit files in the workspace

web.search

Search the web and read the results

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

Run a command in the terminal

Pauses before each command and waits for a person

Keyboard interactions

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

TaborShiftTab
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.write

Create and edit files in the workspace

Covers apps/docs and packages/react. Files outside these folders, and everything in .git, stay read-only.
  • data-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.

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

  • Optional

    One line of 12 px secondary text under the id that says what the tool does.

  • A small segmented control with Allow, Ask and Deny, named Permission for plus the tool id. Ask is selected by default.

  • Optional

    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.

PropTypeDefaultDescription
tool requiredReactNode—The tool id, shown in monospace. Pass a string so the switch is named and the id.
descriptionReactNode—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.
scopeReactNode—A line that says what the setting covers. Any content, so an icon can lead the text. Hidden when not set.
scopeDetailReactNode—More detail that folds out under the scope line. It turns the scope line into a button. Ignored without .
disabledboolean—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.
classNamestring—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.

MCPget_component("tool-permission-row")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.