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

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:

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. Two different reasons apply:

Read-only tools cannot change anything: Read, Grep, Glob, LS, NotebookRead, WebSearch, WebFetch

DorkOS agent tools are auto-approved because they are checked by their own rules instead, not because they are read-only: messaging other chats (chat_send, chat_read, chat_stop), Relay (relay_notify_user, relay_list_endpoints), 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).

Some of these do change things. chat_send starts work in another chat, and chat_stop stops it. They are auto-approved anyway because agents message each other's chats as a matter of course: a card on every message would arrive dozens of times an hour, and a person who learns to click through those cards stops reading every other card too. What protects you instead is that every message lands in a chat you can open, DorkOS marks who sent it so no agent can pass as another, and every stop is recorded in the audit trail. Two cases still ask you:

• You asked to be asked. Set the Messages permission to Ask on the agent's Permissions page, and you get a card before each message or stop.
• The work came from outside. When another agent's message or someone outside your team started the agent's current turn, stopping a chat, or cutting into a chat's running turn, waits for your yes. Sending a message that waits its turn, and reading a chat, still go straight through.

Otherwise these tools never produce an approval card. That list is short and hand-picked, not a rule about DorkOS tools in general: everything else an agent can ask DorkOS for prompts like any other tool, and the things an agent cannot take back stop and ask you no matter which permission mode the session is in. See Action approvals.

Always Allow

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

1. Approves the current tool call immediately
2. Tells Claude Code to stop asking about similar tool calls

How far that reaches depends on what Claude Code suggests, and the button names it: this session, this project, or all your Claude sessions. The last two are saved in Claude Code's own settings files, so they last beyond this conversation.

Not every approval card shows this button: it only appears when Claude Code offers a suggestion for the tool.

This is different from Always allow on a DorkOS request card, which remembers your yes for one agent and one DorkOS action. See Permissions. 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 DorkOS does.

Keyboard Shortcuts

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.

The Trust Dial

Each session has a trust setting — one dial with three stops — that decides how much Claude may do before it checks with you. You can change it at any time from the session's permission picker:

• Ask first: Claude prompts before it edits a file or runs a command. Read-only and agent tools are still auto-approved. This is where every session starts.
• Act: Claude edits files and runs routine commands on its own, and only stops to ask about the risky ones.
• Full autonomy: every tool approval prompt inside the session is skipped. The session stops pausing for your approval on each tool call — though the agent still asks when something genuinely needs your call, and still follows anything you have told it to check with you about.

Plan mode is a separate toggle next to the composer, not a stop on the dial: it puts the session in read-only planning — Claude can investigate and propose a plan but cannot execute tools — and you switch it on for a stretch of work rather than leaving a session parked at it.

Where a new conversation starts

This dial is what an agent's Files & commands setting decides for a new conversation before you touch it. DorkOS works out the starting stop in order: a session, task, or room turn you set yourself always wins; failing that, the agent's own Files & commands setting on its Permissions page; failing that, the setting for its runtime in Settings → Runtimes, if you set one; and otherwise the setting everyone has. Moving the dial here only ever changes this one conversation — to change where this agent's next conversation starts, set its Files & commands row on its Permissions page. See Permissions.

A chat an agent starts with the session_start tool runs at the same setting as the chat that started it, or a lower one if the agent asks for that. It can never be higher, and the new chat's first lines say which it got. Full autonomy is the one setting an agent has to ask for by name, so you see it on the approval card.

Never ask

Never ask is a switch inside the Ask first stop, for Claude Code chats. With it on, the agent runs only the tools your Claude Code settings already allow (the allow rules in the project's .claude/settings.json and .claude/settings.local.json, and in your own Claude Code user settings), and refuses everything else. It never stops to ask you, and it never gets to do more than Ask first lets it.

Use it for an agent that answers people on its own, where nobody is there to approve anything. A refused tool shows up in the chat as a blocked step. DorkOS's own tools count too: in this mode even the ones Ask first approves on its own are refused unless your settings allow them.

Only you can turn it on: no DorkOS tool lets an agent switch a chat to Never ask, and a chat in Never ask can only start chats that cannot ask you either. Codex and OpenCode chats don't offer it.

Auto mode

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. It's a toggle that lives inside the Act stop, not a fourth stop of its own — turning it off returns the session to plain Act.

Availability is model-gated. The Auto toggle only appears when the model you've selected supports it. If you switch to a model that doesn't, the session falls back to Ask first 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 runs in auto mode: no approval prompt for the routine steps, but it still checks with you before risky actions like deleting files or running unfamiliar commands. 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.

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 so similar calls stop asking. Check how far it reaches, named on the button, before you press it.
• 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