Approvals & Safety

Approve tool calls before they touch your files

Tools that read your files ask permission first, and an unanswered request always defaults to deny.

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant.",
)
# When this agent calls a file tool in the Desktop app,
# an approval card appears before the tool runs.
agent.start("Read notes.txt and summarize it")

Quick Start

1. Pick an approval mode

   Open Settings → Safety → Tool approval and choose ask, smart, or never.

2. Answer the card

   When a tool call arrives, an approval card offers Allow, Always allow, or Deny.

3. Let silence deny

   If you do nothing, the request is declined after the timeout — the default is 300 seconds.

---

How It Works

Each approval carries a call_id, so a decision is bound to the specific tool call rather than to whichever prompt happens to be pending.

The event carries name (the tool name) and args (the tool arguments) so the approval card can show what is about to run, not just that something is.

What smart mode waives

smart mode waives the approval card for a small allowlist of low-risk read tools and still prompts for everything else. Any tool that isn’t on the low-risk list — including new tools added in a future release — is treated as high-risk and shows the card.

Tool	Under smart	Notes
read_file	✅ No card	Reads a file on disk
list_directory	✅ No card	Lists a directory’s entries
current_time	✅ No card	Returns the current clock time
web_search	✅ No card	Runs a web search query
fetch_url	⚠️ Card shown	Network fetch — still gated (redirects are re-gated too)
any other builtin	⚠️ Card shown	Unknown tools default to high-risk

smart is fail-closed: only the four tools above skip the card. Anything unlisted — including a tool a future release adds — is treated as high-risk and still prompts, so the app never silently trusts a new tool.

An approval binds to one URL

fetch_url treats the approved URL as the URL — nothing else. A page that redirects stops at the redirect and returns an error rather than silently following it. To follow the new URL, ask for it again and get a fresh approval card for it.

Situation	What happens
Approved URL returns 200	Body is returned (up to ~400 KB, UTF-8, replacement chars on decode errors).
Approved URL returns 3xx	The fetch stops. The tool returns Fetch failed: HTTPError: redirect to <url> was not approved.
Non-http(s) URL	Rejected before the gate: Only http and https URLs are supported.
Any other error	Returned as Fetch failed: <ExceptionType>: <message>.

If the model needs the redirected URL, it should ask again with the new URL. That triggers a new approval card, so you decide whether the second hop is allowed — the first card doesn’t cover it.

Setting	Values	Default
approval_mode	ask | smart | never	ask
approval_timeout	seconds (10–3600)	300
confirm_delete	true | false	true

A malformed approval body defaults to deny, and an unanswered request defaults to deny at the timeout. Silence is never treated as consent. An approval card names one URL — the fetch cannot follow a redirect to another one under that card. A new URL needs a new card.

The three buttons:

Button	Effect
Allow	Runs this one call
Always allow	Persists for that tool name for the rest of the session
Deny	Declines this call

Setting approval_mode to never prompts a confirmation first: “Tools will read your files without asking. Continue?”

---

Choosing a Mode

Mode	Behaviour	Best for
ask	Prompts on every file tool call	Maximum control
smart	Waives an allowlist of low-risk reads (read_file, list_directory, current_time, web_search) and prompts on everything else	Balanced
never	Runs file tools without asking	You fully trust the agent

See What smart mode waives for the full per-tool table and the fail-closed default.

---

Best Practices

Start with ask

The default ask mode surfaces every file read. Loosen to smart or never only once you trust the agent’s behaviour.

Use Always allow sparingly

Always allow persists for the whole session per tool name. Use it for tools you re-run constantly, not one-offs.

Keep the timeout short if unattended

The timeout declines unanswered requests. A shorter approval_timeout frees a stuck turn faster when you step away.

Re-approve a redirected URL by name

If fetch_url reports redirect to <url> was not approved, that’s the gate refusing to hand the new URL your approval. Ask the agent to fetch that URL directly if you want the content — you’ll get a fresh approval card for it, and you decide whether the second hop is allowed.

---

Related

Settings Reference

Every Safety field and its default

Chat & Streaming

Where approval cards appear in a turn