permission-control

A small permission extension for Pi built around three concepts:

Zone × Profile × Elevation

Model

Paths are canonicalized and classified into:

• workspace — normal project work
• external — paths outside the workspace
• sensitive — credentials and permission-control paths that always require user approval

Profiles return one of:

• allow — execute without approval
• elevate — use an existing grant, bounded LLM judge, or user approval
• deny — hard denial when a custom profile uses it

Default mapping:

Zone	Profile	Read	Write
workspace	full	allow	allow
external	guarded-read	elevate	elevate
sensitive	confirm	elevate	elevate

When sensitive access is configured as elevate, it always goes to the user. It offers only Allow once, Deny, or Abort turn; sensitive session grants are not created. A trusted mode may explicitly map the sensitive zone to full, in which case it is allowed like every other full-profile zone.

Every non-sensitive external read or write is reviewed by the automatic judge before the user is asked. The judge may silently approve the exact operation once when it directly serves the current user task and has an appropriate scope and impact. Rejected, uncertain, failed, or low-confidence judgments fall back to user approval. Sensitive paths never go through the judge.

Enforcement

• read, grep, find, ls, write, edit, and apply_patch are checked directly.
• AI bash is wrapped with @landstrip/landstrip.
• Bash can write workspace roots and temporary scratch paths.
• Home-directory reads outside the workspace are denied by the OS sandbox until a matching Bash grant is issued.
• Sensitive paths remain denied inside the sandbox until an exact user-approved one-shot Bash grant is supplied.
• Outbound network is enabled by default; local binding and Unix sockets are not.
• User-entered !/!! commands are treated as trusted user actions and are not intercepted by this extension.
• Custom extension and MCP tools are not automatically rewritten; they need their own permission integration if they access local resources.

Elevation

The request_permission tool requests:

{
  "capability": "read",
  "resource": "~/Developer/upstream-repo",
  "justification": "Compare the upstream implementation",
  "command": "git -C ~/Developer/upstream-repo diff"
}

command is optional for direct file tools and required for a judge-reviewed one-shot Bash grant. All non-sensitive external read and write requests go to the judge first; only requests it does not approve are shown to the user.

User approval choices:

• Allow once
• Allow for session
• Deny
• Abort turn

Subagent requests are forwarded to the main Pi TUI through the existing subagents message channel. If no channel or UI is available, the request fails closed.

Configuration

Global configuration:

~/.pi/agent/permission-control.json

Named modes make it easy to switch the profile used by every zone:

{
  "activeMode": "standard",
  "modes": {
    "standard": {
      "workspace": "full",
      "external": "guarded-read",
      "sensitive": "confirm"
    },
    "trusted": {
      "workspace": "full",
      "external": "full",
      "sensitive": "full"
    }
  }
}

Mode changes are persisted and take effect immediately. Both commands open interactive selectors:

/perm-mode
/perm-zone

/perm-mode selects a named mode. /perm-zone first selects a zone, then the profile to assign to that zone in the currently active mode.

The committed default is in agent/permission-control.json.

Commands

• /perm — status, active profiles, roots, judge, grants, and Landstrip backend
• /perm-mode — interactively switch named permission modes
• /perm-zone — interactively update one zone in the active mode
• /perm-grants — list grants
• /perm-grants clear — clear grants
• /perm-log — recent audit decisions

Audit records are stored in:

~/.pi/agent/permission-control-audit.jsonl

Install

Install the extension from npm:

pi install npm:pi-permission-control

Reload Pi after changes:

/reload