Pi · 4 of 5
Extensions and permissions
Pi’s coding product is highly extensible and intentionally does not ship a complete permission sandbox. Hooks can block agent-level calls; operating-system confinement remains a separate deployment decision.
§1
The extension API reaches many product surfaces
A coding-agent extension can register tools, commands, event handlers, provider behavior, rendering, and resource contributions. Lifecycle events cover project trust, resource discovery, session start/shutdown, input, pre-agent prompt changes, model/tool events, and UI integration. Source · extension capabilities
Project-local extensions are loaded only after the project trust decision. Long-lived resources should begin at session lifecycle points and close through idempotent shutdown handling, rather than starting invisibly in the extension factory.
§2
Tool hooks are useful policy points, not a sandbox
The reusable agent core validates arguments before beforeToolCall. That hook can block the call and provide a structured result. afterToolCall can annotate or replace a result before final events. The coding extension system exposes corresponding lifecycle hooks and custom tools.
A hook runs inside the same process and depends on correct registration, ordering, and coverage. It can implement product policy, but it does not constrain an extension or process that can reach the filesystem, network, or credentials by another route.
§3
Pi states the permission boundary plainly
The pinned README says Pi has no built-in permission system restricting filesystem, process, network, or credential access. By default, it runs with the permissions of the user and process that launched it. Source · permissions
§4
The documented confinement patterns
| Pattern | Where Pi/auth runs | Where tools run | Tradeoff |
|---|---|---|---|
| Gondolin extension | Host | Built-in tools and shell commands routed into a local Linux micro-VM. | Host credentials remain available to Pi while selected effects move. |
| Plain Docker | Container | Container | Simple whole-process isolation; credentials/config must be supplied deliberately. |
| OpenShell | Policy-controlled sandbox | Same sandbox | Whole-process boundary with external policy. |
These are deployment patterns documented by the repository, not hidden built-in guards. Source · containerization
§5
Skills are discovered resources
Pi scans configured user, project, package, and explicit skill locations. The harness deterministically adds skill names and descriptions to the system prompt. The model may then use read to load a matching SKILL.md, but the documentation warns that models do not always do so. A user can force loading with /skill:name. Source · discovery Source · loading
The documentation warns that skills can direct arbitrary actions and may include executable code. Review and trust are content/deployment concerns, not properties conferred by the skill format.
§6
Subagents are an extension pattern here
The repository demonstrates a subagent custom tool as an example extension. It starts a separate Pi process per invocation, supplies an isolated context and delegated configuration, captures structured output, and propagates cancellation. Source · example contract
Keep the category boundary explicit: Pi makes the pattern implementable through extensions, but the minimal agentLoop() does not require it. The example can inherit the active model/thinking setting when unspecified, while tools and delegated prompt are explicit configuration.