# Tool Approval
Source: https://dorkos.ai/docs/guides/tool-approval

Control what actions Claude takes during a session





# Tool Approval [#tool-approval]

<ProductShot id="tool-approval" alt="A tool approval card in the DorkOS chat showing the tool name, a risk indicator, the command to run, and Approve, Always Allow, and Deny buttons" />

DorkOS gives you control over what Claude does during a session. When tool approval is active, Claude pauses before running operations and waits for your decision.

## How It Works [#how-it-works]

When Claude wants to use a tool (writing a file, running a command, editing code), a tool approval card appears in the chat. The card shows:

* **Tool name**: a display name for the operation Claude wants to perform
* **Risk indicator**: a color-coded shield icon showing the risk level (red for high, amber for medium, gray for low)
* **Context details**: SDK-provided description, the decision reason, and the blocked file path (when applicable)
* **Tool input**: parameters for the tool (file paths, command arguments, search terms)
* **Action buttons**: Approve, Always Allow (when available), and Deny

<Steps>
  <Step>
    **Review** the tool name, risk level, and input to understand what Claude is about to do.
  </Step>

  <Step>
    **Click Approve** to allow this single action. Claude executes the tool and continues.
  </Step>

  <Step>
    **Click Always Allow** (when available) to approve this action and grant a standing permission
    so similar tool calls won't require approval for the rest of the session.
  </Step>

  <Step>
    **Or click Deny** to reject the tool call. Claude receives a denial and chooses a different
    approach.
  </Step>
</Steps>

<Callout type="info">
  Tool approvals have a **10-minute timeout**. If you don't respond, the tool call is automatically
  denied and Claude continues with a different approach. The countdown timer is synchronized with
  the server clock, so switching tabs or briefly losing connection won't cause drift.
</Callout>

If you deny a tool call, you can explain why in your next message or ask Claude to try a different approach.

## Risk Levels [#risk-levels]

Each tool approval card shows a shield icon whose color reflects the risk level of the requested operation:

| Risk   | Color | Tools                                                      |
| ------ | ----- | ---------------------------------------------------------- |
| High   | Red   | `Bash`, `Write`, `Edit`, `NotebookEdit`                    |
| Medium | Amber | `WebFetch`, `WebSearch`, unknown MCP tools (`mcp__*`)      |
| Low    | Gray  | All other tools (read-only operations, DorkOS agent tools) |

High-risk tools can modify the filesystem or execute shell commands. Medium-risk tools have external side effects or come from third-party MCP servers. Low-risk tools are read-only.

## Auto-Approved Tools [#auto-approved-tools]

Certain tools are always auto-approved regardless of permission mode because they cannot modify state:

**Read-only tools:** `Read`, `Grep`, `Glob`, `LS`, `NotebookRead`, `WebSearch`, `WebFetch`

**DorkOS agent tools:** Relay messaging (`relay_send`, `relay_inbox`, `relay_list_endpoints`, `relay_register_endpoint`), Mesh discovery (`mesh_list`, `mesh_inspect`, `mesh_discover`, `mesh_register`, `mesh_status`, `mesh_query_topology`, `get_agent`), and UI control tools (`control_ui`, `get_ui_state`).

These tools never produce an approval card. Relay access control (`relay/access-rules.json`) handles authorization for agent communication tools separately.

## Always Allow [#always-allow]

When an approval card shows an **Always Allow** button, clicking it does two things:

1. Approves the current tool call immediately
2. Sends SDK permission updates back to Claude so that similar tool calls are auto-approved for the rest of the session

Not every approval card shows this button: it only appears when the SDK provides permission suggestions for the tool. The keyboard shortcut is <kbd>Shift+Enter</kbd>.

## Batch Approvals [#batch-approvals]

When Claude fires multiple tool calls concurrently, a **batch approval bar** appears above the active approval card. It shows the count of pending approvals and provides:

* **Approve All**: approve every queued tool call at once
* **Deny All**: deny every queued tool call at once

This is useful during parallel operations (e.g., Claude editing several files at the same time).

## Approvals in Chat (Telegram and Slack) [#approvals-in-chat-telegram-and-slack]

When an agent is connected to a Telegram chat or Slack channel through Relay, approval prompts appear there too, as Approve/Deny buttons under the message. Tapping a button resolves the tool call the same way clicking in the cockpit does.

<Callout type="warn">
  **In group chats, anyone can respond.** Approval buttons are not restricted to the person who
  started the conversation: any member of the bound group chat or channel can approve or deny a tool
  execution. If that matters to you, bind agents with approval-gated permissions to private chats or
  DMs instead of shared channels.
</Callout>

## Keyboard Shortcuts [#keyboard-shortcuts]

| Action             | Shortcut                            | Context         |
| ------------------ | ----------------------------------- | --------------- |
| Approve            | `Enter`                             | Approval card   |
| Always Allow       | `Shift+Enter`                       | Approval card   |
| Deny               | `Escape`                            | Approval card   |
| Toggle option      | `1`-`9` or `Space`                  | Question prompt |
| Navigate options   | `Arrow Up` / `Down`                 | Question prompt |
| Navigate questions | `Arrow Left` / `Right` or `[` / `]` | Question prompt |
| Submit answers     | `Enter`                             | Question prompt |

Shortcuts are active whenever a pending tool approval or question prompt is visible. They are disabled when a text input field is focused (except `Enter` to submit and arrows to navigate).

## Question Prompts [#question-prompts]

Some tools need more than a yes/no: they need answers. When Claude uses the `AskUserQuestion` tool, you'll see an interactive question prompt instead of an approval card.

Question prompts support three response types:

* **Single-select**: choose one option from a list
* **Multi-select**: choose multiple options
* **Free-text ("Other")**: type a custom answer when none of the options fit

<Steps>
  <Step>
    Read the question.
  </Step>

  <Step>
    Select one or more options, or type a custom answer in the "Other" field.
  </Step>

  <Step>
    Click 

    **Submit**

     to send your answers back to Claude.
  </Step>
</Steps>

Your answers are injected into the tool's input. Claude continues with your selections incorporated into its reasoning.

## Permission Modes [#permission-modes]

Each session has a permission mode that sets how Claude handles tool approvals. You can change it at any time from the session's permission picker:

* **Default**: Claude prompts on tool use and respects your project's permission settings. Read-only and agent tools are still auto-approved.
* **Accept edits**: file edits are auto-accepted; Claude still prompts for other tools.
* **Plan**: read-only planning mode. Claude can investigate and propose a plan but cannot execute tools.
* **Bypass permissions**: all approval prompts are skipped. A persistent red warning banner appears at the top of the UI while this mode is active.
* **Auto**: a safety classifier decides each tool call for you, approving routine work and pausing only for risky actions.

<Callout type="warn">
  Bypass permissions mode disables all safety checks. Only use it in isolated environments where you
  trust the agent completely.
</Callout>

### Auto mode [#auto-mode]

<Callout type="info">
  Auto mode is a **research preview**. It's available on newer Claude models only, and the
  experience may change as it evolves.
</Callout>

Auto mode trades constant approvals for autonomy on long-running work. Instead of pausing on every tool call, a safety classifier evaluates each one, auto-approving routine actions and stopping only for risky ones, like deleting files or running unfamiliar commands. It's designed for autonomous runs where approving each step yourself would slow Claude down.

**Availability is model-gated.** Auto mode only appears in the permission picker when the model you've selected supports it. If you switch to a model that doesn't, the session falls back to Default automatically. Claude never enters auto mode on a model that can't run it.

**A one-time confirmation.** The first time you turn on auto mode in a session, DorkOS asks you to confirm:

> The agent runs on its own and only checks with you before risky actions, like deleting files or running unfamiliar commands. You can switch back anytime.

After you confirm, the rest of that session switches to auto mode without asking again. You can leave auto mode whenever you want.

**Denials are visible.** When the classifier blocks a tool call, a read-only "blocked" chip appears in the chat showing what was denied and why. It's a record, not a prompt: there's no action to take and no re-approval path. This keeps auto mode honest: Claude never silently swallows a denied action.

## Common Scenarios [#common-scenarios]

### File Operations [#file-operations]

`Write` and `Edit` tool calls appear when Claude modifies your files. These are classified as **high risk** and always require approval in default mode. Check the file paths carefully. Claude should be working in the right location.

### Command Execution [#command-execution]

The `Bash` tool runs terminal commands. This is classified as **high risk**. Always review the command before approving.

<Callout type="warn">
  Review `Bash` tool calls carefully. Terminal commands can modify files, install packages, or make
  network requests. When in doubt, deny and ask Claude to explain its intent.
</Callout>

### MCP Tool Calls [#mcp-tool-calls]

Tools from MCP servers (prefixed with `mcp__`) are classified as **medium risk** by default. The approval card shows the server name as a badge for identification.

### Web Access [#web-access]

`WebFetch` and `WebSearch` calls access the internet and are classified as **medium risk**. Review the URLs or search queries before approving.

## Tips [#tips]

* **Read the full input.** Tool inputs can be long. Understanding the parameters before approving is worth the extra few seconds.
* **Use Always Allow for repetitive approvals.** If Claude is performing many similar operations (e.g., editing multiple files), use Always Allow to grant a standing permission.
* **Use batch actions for parallel operations.** When the batch bar appears, you can approve or deny all pending tools at once instead of handling them one by one.
* **Deny when uncertain.** If you're not sure why Claude wants a tool, deny it and ask. Claude will explain.
* **Check context first.** Claude often explains what it's about to do before requesting a tool. Read the assistant message before reviewing the approval card.
* **"Other" is always available.** In question prompts, you can always provide a free-text answer if the pre-defined options don't fit.

## Next Steps [#next-steps]

<Cards>
  <Card title="Keyboard Shortcuts" href="/docs/guides/keyboard-shortcuts">
    Full keyboard shortcut reference including tool approval bindings.
  </Card>

  <Card title="Slash Commands" href="/docs/guides/slash-commands">
    Create custom commands that guide Claude through common tasks.
  </Card>

  <Card title="Sessions" href="/docs/concepts/sessions">
    How DorkOS stores and manages conversation sessions.
  </Card>
</Cards>