Tool Permissions

Pia asks before a tool changes anything. Reading, searching and listing are free; creating, changing and deleting always come with a card you have to answer.

This guide covers the four answers on that card, and the settings page that shows everything you’ve already agreed to.

Answering an Action Card

When Pia wants to do something, a card appears in the chat with the details — the file path and a colour-coded diff for a file write, the title and priority for a todo, the exact command for a git call. Then you choose:

Answer	How long it lasts
Decline	Nothing happens.
Allow once	This one call only. You’ll be asked again next time.
Allow this session	Until Pia closes. Nothing is saved to disk, and it doesn’t reach voice mode.
Always allow	Kept in your settings, until you revoke it.

Once a tool is covered, the card still appears — it just tells you why it went through: Auto-approved · you always allow create_todo.

Seeing exactly what Pia is about to do

Every action card carries a chevron on the right — Show or hide details. Expand it and you see the actual arguments of the call, not just the summary line:

New value — what Pia is about to write, in full.
Current value — for anything that changes something that already exists, what is there now, so you can see what is being replaced.

For a file write there is no chevron to open: the card shows a colour-coded diff permanently, green for added lines and red for removed ones, with the decision buttons underneath.

So yes — you can always read the exact arguments before you approve. If a card’s one-line summary isn’t enough to decide, open the chevron; that is what it is for. A card also has a Manage link that takes you straight to the tool-access settings page.

What “Always allow” actually covers

Always allow covers the named tool, with any arguments, from then on. Approving “Create Todo — Create medium priority todo: Winwright walkthrough test” grants create_todo — not that one todo, and not todos in general.

Concretely, after that grant:

Pia creates any todo without asking again, whatever the title or priority.
Pia still asks before it updates, completes, moves or deletes a todo — those are different tools with their own grants.
Nothing else from the Todo plugin is covered.

This is why the settings page warns that an approval here covers later calls whose arguments you never see: you’re agreeing to the capability, not to the specific text you were shown. For a tool that only ever adds something, that’s usually fine. For one that overwrites or deletes, prefer Allow once.

What happens when you Decline

Decline stops that one tool call. It does not end the turn — Pia carries on and replies to you.

What it does not do is quietly try the same thing again. Pia is instructed to treat a decline as final: it acknowledges that you said no and asks what you’d like to do differently, or whether you want to adjust the details. So a decline turns into a conversation rather than a retry loop, and you can approve a revised version if you want to.

If declining leaves Pia unable to do what you asked at all, it says so instead of pretending it succeeded.

Don’t leave an approval waiting

An approval card does not expire. Walk away and it will still be sitting there when you come back, and the chat stays in Waiting for your confirmation indefinitely.

The connection behind it does expire, though. The turn is holding an open request to your AI provider while it waits for you, and that request has its own timeout — 5 minutes by default, adjustable per provider in Settings → Providers. Answer the card after the provider has given up and the turn cannot resume: it ends with “Provider ‘…’ did not respond within 300 seconds.” and the chat flips to a red Error.

So an approval is a “answer me now” prompt, not something you can leave until tomorrow.

If a turn has already failed this way, nothing is lost except the reply — the tool never ran, and your message is still there. Use Regenerate on the failed turn to run it again, and answer the approval card promptly this time. If you routinely need longer to decide, raise the timeout on that provider.

Finding a chat that’s waiting for you

You don’t have to remember which chat is blocked. A chat waiting on an approval announces itself in three places:

Flow, the panel on the right edge of the window, gets a card reading Waiting for your confirmation with a link straight back to the chat. The Flow handle shows a badge with how many items are waiting, so it’s visible from any screen in Pia — you don’t have to be in the Assistant.
The chat list — both the chat title chip and the Chat history page show the waiting status on the chat’s row.
The chat itself, where the card is.

That answers the “do I get told, or only if I’m looking?” question: you get told. Flow is where the notice lands, it survives switching screens, and it survives restarting Pia — so a chat that got blocked while you were elsewhere is still flagged when you come back.

Why some tools ran without asking

Reading, searching and listing never ask — they don’t change anything, so there is nothing to approve. Only tools that create, change or delete something raise a card.

If a tool that does change something still ran without asking, one of these covered it, and the card says which:

You previously chose Allow this session or Always allow for that tool.
You ticked it in the All tools list on the settings page.
Agent autonomy is switched on and the tool is one of Pia’s own write tools.
It’s a routine running with tools you granted when you created the job.

To find out which tools are currently covered, open Settings → Assistant → Tool access — the sections below list exactly that, and let you take any of it back.

The Settings Page

Open Settings → Assistant → Tool access. The page is titled What runs without asking, and it has five parts.

Agent autonomy

One switch: Auto-approve Pia’s own write tools during agent runs and in voice mode. Off by default.

While it’s on, agent runs and voice mode stop asking for Pia’s own write tools — notes and memory, todos, reminders, routines, and files. It never covers deleting anything, git commands, or external (MCP) tools.

Screen capture while you are away

Windows a routine or background run may capture. A run nobody is watching can only capture a window on this list, and only when exactly one open window matches the entry. It can never capture a whole monitor. Each of those captures leaves a notice in Flow.

Add an entry by naming the program (for example outlook) and, optionally, text the window title must contain. Easier still, Choose from open windows… fills both in from a window that is open right now — and both stay editable, because a title you can shorten is one that still matches tomorrow. Nothing is captured while you pick.

The list starts empty: “No windows are allowed yet. Runs you are not watching cannot capture the screen until you add one.”

Capturing the screen at all needs the Pia Cloud provider. See File Attachments.

Allowed until Pia closes

Everything you answered Allow this session for. Nothing here is saved — it all disappears when Pia restarts. Click Forget to be asked again on the next call.

Session grants deliberately stop at the chat window: they don’t reach voice mode, where you couldn’t see what you were agreeing to.

Always-allowed tools

Your standing grants, each with the plugin it belongs to and when you granted it. Click Revoke to be prompted again next time.

If you haven’t granted any, it says so: No tools are always allowed. When you choose “Always allow” on a tool, it appears here.

All tools

The full catalogue, with two tick boxes per tool: Until Pia closes and Always. Ticking one here is exactly the same as choosing that answer on a card — you just don’t have to wait for the card.

Tools that deserve a second thought say so when you tick them:

this tool destroys data, and an approval here covers later calls whose arguments you never see
this tool can throw away uncommitted work
this tool grants permissions that later, unattended runs will use — approving it once lets Pia widen what it may do later

What Pia Can Ask For

Category	Examples
File	Write or delete a file in your assistant folder.
Git	Initialize, stage, commit, switch, restore, stash.
Memory	Save, update or forget something in your vault.
Todo	Create, update, complete, move or delete a task.
Reminder	Create, update or delete a reminder.
Routine	Create, update or delete a routine.
Screen	Capture a display or a window. See File Attachments.
External tool	Anything an MCP tool server provides — a server-delivered plugin or a local MCP server you added yourself.

Where Else Permissions Come From

Three other things can let a tool through, and the card always names which one it was:

A routine’s granted tools — ticked in its editor when you create it (Auto-approved · this run was granted write_file).
Agent autonomy — the switch above (Auto-approved · agent autonomy is on for this kind of tool).
A run’s own working notes — a write into the run’s .scratch/ folder, which is never published (Auto-approved · a working note in the scratch folder, which is never published). See Agent Runs.
A persona with tools switched off — the opposite case. A persona set to Tool Access: None can’t use any tool at all, whatever you’ve granted. See Personas.

Next Steps

Coding Tools & @Files — the folder Pia is allowed to work in
Agent Runs — where these grants matter most