Skip to content
Agentic Control Plane

Pi permission system and permission modes, explained

Pi has no built-in permission system. Its four tools (read, write, edit, bash) run without prompts until an extension on the tool_call event adds allow, ask and deny. The closest thing Pi has to permission modes is its run mode. It tells an extension through ctx.hasUI whether a human can answer an ask: yes in the interactive TUI and RPC, no in print (-p) and JSON, where a permission check should block.

pi, from Mario Zechner and Armin Ronacher, MIT, ships less than Claude Code or Cursor on purpose and leaves the rest to you. This page explains what Pi ships, where controls attach, and how the ask/approve loop works in each mode. For the key-by-key reference to the pi-permission-system extension and its pi-permissions.jsonc file, see pi-permission-system and Pi permissions: the reference.

This page covers pi’s own model. For adding ACP to pi, see the install guide. For the cross-harness picture, see the controls comparison. ACP’s model-judged approvals can clear routine reads without a prompt when pi has a UI.

What pi ships natively

pi’s security documentation doesn’t claim a boundary it doesn’t have:

  • No permission prompts. The four built-in tools (read, write, edit, bash) run with the permissions of the user who launched pi.
  • No allowlist, denylist, or rules file. There is no settings.json of permission patterns, because there is no permission system to configure.
  • No sandbox built in. pi runs in your process, with your access to the filesystem, network, and credentials.

Instead, pi points at containment as the boundary and documents three patterns. Gondolin is an extension that keeps pi and your provider auth on the host and routes the built-in tools and ! commands into a local Linux micro-VM. The other two are plain Docker and OpenShell. The split is sensible: a container bounds where the agent can act, and an extension decides which actions run. What pi doesn’t ship is the second half, the deciding and the record.

Two typed events

pi is a good place to attach controls even though it ships none, because of its extension model. pi dispatches every tool through a typed event pipeline, and extensions are TypeScript modules that subscribe to it. Two events matter:

Event Fires An extension can
tool_call before the tool runs return { block: true, reason, terminate? } to deny; mutate event.input in place to rewrite arguments (no re-validation after)
tool_result after the tool runs return { content, isError, details, usage } to rewrite or redact what the model reads

That gives you deny, input rewrite, and output rewrite, the same set as dsh and Claude Code. opencode can’t rewrite output, because its post-hook only observes. Coverage is complete because pi has no MCP layer and no second tool path. bash, read, write, edit, and any custom or extension-registered tool all flow through these two events.

tool_call handlers chain, so later handlers see earlier mutations. tool_result handlers chain like middleware, and each sees the previous one’s patch. Load order is how they compose.

Whether a human is watching

pi tells extensions something most harnesses leave implicit: whether a human is watching. ctx.hasUI is true in the interactive TUI (and RPC mode) and false in print (-p) and JSON modes. ctx.mode names the exact mode. pi’s shipped permission-gate.ts example uses it correctly: it prompts via ctx.ui.select or confirm when there is a UI, and blocks by default when there isn’t:

In non-interactive mode, block by default.

Mode by mode, the ask/approve loop looks like this:

ctx.mode ctx.hasUI What an ask can do
tui (interactive) true prompt with ctx.ui.confirm or ctx.ui.select, then block or allow
rpc true prompt, same calls as the TUI
print (pi -p) false nobody to answer: block
json false nobody to answer: block

Rule-based extensions layer allow, ask and deny on top of this. pi-permission-system also has a yoloMode setting that turns every ask into an approval. The reference documents its file and precedence.

This is the empty-chair posture built in: an approval with nobody to answer it is a deny, and pi tells you which case you are in, so you don’t infer it from a timeout. Correct unattended behavior is a one-line check.

Loading and trust

Extensions load from:

Path Scope Trust
~/.pi/agent/extensions/*.ts global (all projects) loads immediately
.pi/extensions/*.ts project-local loads only after you trust the project
pi -e ./x.ts one run for testing

pi loads TypeScript directly, with no build step (like dsh’s plain ESM). A control extension belongs in the global path, so control is active before any repository is opened. Project-local extensions are gated behind pi’s project_trust flow, which is itself extensible. pi requires Node 22+, and Node 20 fails at startup with an unhelpful error.

What pi’s model doesn’t include

pi ships the mechanism and not the policy, so these gaps are by design:

  • No policy. Nothing decides allow or deny until an extension does. Out of the box, everything runs.
  • No record beyond the session tree. pi keeps a branchable session tree, which is good for editing your own history and not an audit trail. It is the run’s own account, on the run’s own machine, and it doesn’t record what was evaluated, against which policy, or on whose authority.
  • No identity. Tool calls aren’t attributed to a user or a delegation chain.
  • Nothing shared across machines. Extensions and their config live per machine. Two developers share nothing unless they build the sharing.

What the extension adds

The ACP extension for pi is one TypeScript file with no dependencies (it imports only a pi type), dropped into ~/.pi/agent/extensions/. It subscribes to the same two events and turns interception into enforcement:

  • tool_call checks workspace policy before the call runs. On deny it returns { block: true, reason }, and on allow it lets the call through. An ask decision shows a prompt when ctx.hasUI is true and denies by default when it’s false, matching pi’s own posture.
  • tool_result scans output for policy violations (secrets, PII patterns) and can redact or rewrite before the model reads it. It also writes the decision and latency to an off-machine ledger, whether the call was allowed or denied.

If the gateway is unreachable, an attended session proceeds with a loud [ACP] UNGOVERNED warning and a ~/.acp/lapse.log line. Print and JSON runs are blocked.

Configuration is environment variables, set once in the shell that launches pi:

  • ACP_BEARER_TOKEN is the workspace key (gsk_...).
  • ACP_GOVERN_BASE is the gateway URL, and defaults to the hosted one.
  • ACP_AGENT_TIER labels the session interactive, subagent, background, or api for policy purposes.
  • ACP_SHADOW set to off hides the advisory [ACP shadow] notices the gateway sends while a workspace is still in audit mode. It does not change enforcement. To run record-only, leave the workspace in audit mode.

That covers tool-call policy and audit. The extension never sees a model call, so it adds no cost data. Cost is a separate, optional install: a provider entry in ~/.pi/agent/models.json pointing baseUrl at the ACP proxy, launched with pi --model acp/<model-id>. The two pieces install independently and report to the same console. See pi cost tracking for the setup.

Where ACP fits

pi puts control in extensions, so that is where it has to go. The ACP extension for pi is an ordinary extension on tool_call and tool_result. Workspace policy decides allow, ask, or deny before the call. Output scanning redacts or blocks after. ctx.hasUI drives the attended/unattended split, and every decision lands in a ledger off the machine. The same policy applies on pi, Claude Code, dsh, and the other harnesses we cover, with one place to see what happened and why. It is a single file that imports only a pi type, so it adds only the half pi left out.

Frequently asked questions

pi permission modes: what modes does Pi have?

Pi has no permission modes of its own. It has run modes, and an extension reads them through ctx.mode and ctx.hasUI: the interactive TUI and RPC have a UI, so an ask can be answered; print (-p) and JSON do not, so a permission check should block. Allow, ask and deny come from an extension such as Pi’s permission-gate.ts example or the community pi-permission-system package.

pi permission system explained: how does an ask reach me?

An extension subscribes to tool_call, which fires before every tool runs. For an ask it calls ctx.ui.confirm or ctx.ui.select when ctx.hasUI is true, then returns { block: true, reason } on a no or lets the call run on a yes. With no UI it should block rather than wait or approve.

pi agent permissions: what runs without asking on a fresh install?

Everything. Pi’s README says it does not include a built-in permission system and runs with the permissions of the user who launched it, so read, write, edit and bash all run without a prompt until you add an extension or run Pi in a container or micro-VM.

Does pi have a permission system?

No, by design. pi (earendil-works/pi, from Mario Zechner and Armin Ronacher) ships four tools (read, write, edit, bash) and no built-in approval prompts, allowlists, or sandbox. Its own docs say so and point you at containment instead (the Gondolin micro-VM extension, Docker, or OpenShell). Control in pi is an extension, not a setting, which fits its minimal-core, extend-everything approach.

Can a pi extension block or approve tool calls?

Yes. pi dispatches every tool through two typed events: tool_call (fires before execution, can return { block: true, reason } to deny, or mutate event.input in place to rewrite arguments) and tool_result (fires after, can return replacement content to redact or rewrite what the model reads). An extension on both events sees and controls every tool the agent runs. There is no second dispatch path and no MCP layer to miss.

What does a pi extension do when no human is present?

It can tell: ctx.hasUI is true in the interactive TUI and false in print (-p) and JSON modes. That is the attended/unattended signal. An extension prompts for approval when hasUI is true and denies (rather than hangs or auto-approves) when it’s false, so it doesn’t have to guess at timeouts.

How do you add real controls to pi?

Drop an extension in ~/.pi/agent/extensions/ (global, no trust prompt) or .pi/extensions/ (project-local, loads after you trust the project). It’s TypeScript, loaded directly with no build step. A policy extension on tool_call/tool_result turns pi’s interception points into allow/ask/deny enforcement plus an audit record, which is what the ACP extension does.

Running pi? One command adds a hook. Each tool call it sees is recorded, and a force-push, destructive SQL or curl | sh is blocked until you approve it on the console or from the email.

macOS · Linux · WSL
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
Windows · PowerShell
irm https://agenticcontrolplane.com/install.ps1 | iex

What the installer writes  ·  pi guide  ·  free up to 5 agents