Skip to main content
Version: v2.0

Control what an agent can do

Permissions decide which tool calls an agent makes on its own and which ones stop and wait for you. This page covers the two places you set them, which one wins, and what an approval request looks like mid-run. For the model behind them, see Permissions.

The two places permissions are set​

The agent's policy covers every tool at once. It lives in the Advanced dialog and it is the baseline.

A tool's own permission covers that one action and overrides the policy. It lives in the tool's detail dialog. Use it to carve out an exception: one action that always runs, or one action that is never allowed, while everything else follows the policy.

Set the agent's default policy​

  1. In the playground, set Playground mode to Build.
  2. In the Configuration column, click Advanced.
  3. Open the Permissions section.
  4. Pick a Policy, then click Save.
PolicyWhat it does
Allow readsReads run, writes ask. This is the default.
Allow allEvery tool runs without asking.
AskA human approves every tool call.
Deny allEvery tool call is refused.

Under Allow reads, a connected-app action counts as a read when it carries the READ-ONLY badge in the Add app tools dialog. Anything without that badge asks.

Override the permission for one tool​

  1. In the Configuration column, open Tools.
  2. Click the tool's row.
  3. In the TOOL DETAILS pane, set Permission, then click Save.
PermissionWhat it does
InheritFollows the agent's Policy. This is the default.
AllowThis tool runs without asking, whatever the policy says.
AskThis tool always waits for approval, whatever the policy says.
DenyThis tool is always refused.

Permission is on connected-app tools (listed under CONNECTED APPS) and on tools you write with Tool definition. Built-in tools have no per-tool permission: clicking one opens a read-only view with the subtitle Provider built-in tool, and the agent's Policy governs it instead.

Which setting wins​

When the agent calls a tool, the first of these that applies decides:

  1. The tool's own Permission, when it is anything other than Inherit.
  2. An entry in Auto-approve.
  3. The agent's Policy.

Take a built-in tool away entirely​

Permission is not the only lever on built-in tools. Below Policy, a pill names the agent's harness, and the fields under it belong to that harness. On Pi, Built-in tools lists the built-ins the agent has as multi-select tags: Read, Bash, Edit, Write. Remove a tag and the agent no longer has that tool at all, so there is nothing to approve or deny. Clearing the field leaves the agent with no built-ins.

Approve or deny a call while the agent runs​

When a gated tool comes up mid-run, the conversation shows a card titled Approval needed to continue, and the run pauses. The status above it reads Waiting for your input, and the tool's row reads Awaiting approval.

  • Expand Details to read the arguments the agent wants to pass, as JSON.
  • Click Approve and the run continues from where it paused. Click Deny and the action does not happen.
  • Anything you type while the card is open is queued until you answer.

Stop being asked about a tool you keep approving​

Turn on Always allow <Tool> for this agent on the approval card before you click Approve. That tool then runs without asking, on this run and on later ones, and it appears in the Auto-approve field in the Permissions section. Everything else still prompts.

Auto-approving from the card is a draft change like any other. Commit it if you want triggers to use it, since a schedule or an event trigger runs the committed version.

Limit what the sandbox can touch​

The Execution environment section of the Advanced dialog sets where tools and code run.

Sandbox has two options. With Local, that is the only field. With Daytona, three more appear:

FieldOptions
Network egressAllow all egress, Block all egress, Allowlist (CIDR ranges). The allowlist option reveals an Allowlist textarea for the ranges you permit, such as 10.0.0.0/8.
FilesystemRead / write, Read-only, No access.
EnforcementStrict (fail if unenforceable), Best effort.

Before the agent runs unattended​

warning

An automation has nobody in the chat to answer an approval request, so a run that hits one waits instead of finishing. Before you put an agent on a schedule or an event trigger, set every tool it needs to Allow (or set the policy to Allow all) and set anything it must never do to Deny.

Next​