pi-toolset-permissions

Toolsets, path scope, and bash sandboxes for pi, with patterns that you can edit during a session

Packages

Package details

extension

Install pi-toolset-permissions from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:pi-toolset-permissions
Package
pi-toolset-permissions
Version
0.2.4
Published
Nov 20, 2026
Downloads
791/mo · 791/wk
Author
00sapo
License
GPL-3.0-only
Types
extension
Size
679 KB
Dependencies
0 dependencies · 3 peers
Pi manifest JSON
{
  "image": "https://raw.githubusercontent.com/00sapo/pi-toolset-permissions/v0.2.4/docs/preview.png",
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-toolset-permissions

Do you find managing sandboxes and permissions complicated?

This extension adopts a different modular, on-the-fly approach: you can toggle sets of tools and sandboxes using a simple menu during the session.

You can even tell the AI what it should disable e.g. "forbid writing on that file", or "run in read-only mode now". The extension provides a tool to modify the list of allowed toolsets.

The AI can request state changes when the permissions toolset is on. Turn that toolset off to block these requests.

Main features

  • Five toolsets: read, write, execute, subagent, and permissions.
  • Compatibility with pi-subagent and herdr.
  • The LLM can ask you to change the permissions and set your preferred profile.
  • Third-party tools sandboxed automatically on Linux.
  • Custom toolsets for any additional tool.
  • The model asks you before every change.
  • In ask-mode, approval shows the exact input, and covers that one call.
  • Per-session state, inherited by subagents.
  • Allows global path exceptions but allows symlinks to build per-project exceptions.
  • Custom mounts: expose one host directory or file to the sandbox, read-only or read-write.
  • Make these settings default: the next session starts from them.

Install

pi install npm:pi-toolset-permissions

Try it for one session without saving it:

pi -e npm:pi-toolset-permissions

Then open the screen with /permissions.

Sandbox requirements

  • Linux: it wraps any tool and requires bubblewrap and unprivileged user namespaces.
  • macOS: it wraps bash only, through the built-in sandbox-exec.
  • Windows: no backend exists, and the screen says to start Pi inside WSL2.

Sandboxes automatically mount all the paths listed in your PATH env variable, your home's .gitconfig and your .profile. Other paths can be added through the UI or asking to the LLM.

Concept

A toolset is a group of tool names. Each toolset has one state: off, on, or ask.

A pattern is a regular expression. The extension tests each pattern against a tool name.

A sandbox is an operating-system boundary for shell commands.

A path scope is the set of directories that file tools can touch. PROJECT ONLY exposes only the project root. CUSTOM PATHS exposes the project root plus saved extra paths. EVERYWHERE removes the path limit.

PROJECT ONLY keeps saved extra paths but does not expose them. Scope also selects the roots for the filesystem sandbox.

A symlink is a path that points to another path. Project symlinks grant access to their existing file or directory targets outside the project. The filesystem sandbox exposes those targets with the selected read or read-write access. It follows links inside linked directories and prevents cycles. Broken links do not expose their parent directories. Links in custom roots do not add exceptions.

File tools must use the project link path, not the direct external path. Shell commands inside the sandbox can also use the exposed target path. Unrelated external paths stay outside the sandbox. Protected system paths remain unavailable as scope roots. If a project link targets a protected path, sandbox startup fails. Only use project links whose targets you trust.

The permissions toolset holds the permissions tool. Off blocks state changes through that tool, but still permits approval requests for ask tools. The /permissions command always works. Use that command to turn the toolset back on.

The permissions toolset has only the on and off states. It does not accept ask, because every change through the tool already asks you to confirm. set_toolset refuses mode: ask for this toolset, and a stored ask value loads as on.

Bash is one tool. Its patterns sit in the execute toolset. The sandbox is a second layer. It starts the whole call inside the boundary, and it does not read the command text.

The model changes the state with the permissions tool. The tool asks you to agree before each change. Without a dialog, the tool cannot change the state.

Use

Open the settings screen:

/permissions

The main screen groups toolsets, sandboxes, scope, and the defaults row. Custom Paths opens a path submenu inside Scope, and Custom mounts opens one inside Sandboxes.

Key Action
up/k, down/j move the selection
space cycle a toolset through off → on → ask → off, toggle a sandbox, or switch the scope
enter/l open toolset patterns, Unsandboxed tools, Custom mounts, or Custom Paths. On a sandbox or Modality, enter acts like space. On the defaults row, it saves the settings
s cycle PROJECT ONLY → EVERYWHERE → CUSTOM PATHS
a add a directory to the paths
d remove the selected extra path in Custom Paths
esc/h close the screen, or leave a submenu

Each change is saved at once.

License

GPL-3.0-only. Copyright (C) 2026 00sapo. The full text is in LICENSE.