Tool Approval
Control what actions Claude takes during a session
Tool Approval
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
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
Review the tool name, risk level, and input to understand what Claude is about to do.
Click Approve to allow this single action. Claude executes the tool and continues.
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.
Or click Deny to reject the tool call. Claude receives a denial and chooses a different approach.
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.
If you deny a tool call, you can explain why in your next message or ask Claude to try a different approach.
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
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
When an approval card shows an Always Allow button, clicking it does two things:
- Approves the current tool call immediately
- 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 Shift+Enter.
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)
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.
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.
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
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
Your answers are injected into the tool's input. Claude continues with your selections incorporated into its reasoning.
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.
Bypass permissions mode disables all safety checks. Only use it in isolated environments where you trust the agent completely.
Auto mode
Auto mode is a research preview. It's available on newer Claude models only, and the experience may change as it evolves.
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
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
The Bash tool runs terminal commands. This is classified as high risk. Always review the command before approving.
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.
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
WebFetch and WebSearch calls access the internet and are classified as medium risk. Review the URLs or search queries before approving.
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.