pi-permission

Native permission and sandbox extension for pi.

What it implements

• Sandbox modes: read-only, workspace-write, danger-full-access.
• Approval policies: untrusted, on-failure, on-request, never.
• Approval reviewers: user, auto_review.
• Bash tool escalation fields:
  • sandbox_permissions: "require_escalated"
  • escalation_reason (optional, <=80 chars; use only for a very short why)
  • justification (backward-compatible alias)
  • prefix_rule
• Native sandbox backend implemented by this plugin (Linux bubblewrap; macOS sandbox-exec/Seatbelt when available; unsupported platforms fail closed unless danger-full-access).
• Path gating for pi write/edit matching sandbox mode.
• /permission, /permissions, and /permissions-rules commands.
• Audit log at .pi/permissions-audit.jsonl by default.

Install

pi install npm:@fadouse/pi-permission

Usage

pi -e ./src/index.js --sandbox workspace-write --ask-for-approval on-request
pi -e . --sandbox read-only --ask-for-approval never
pi -e . --dangerously-bypass-approvals-and-sandbox
pi -e . --auto-review
pi -e . --sandbox workspace-write --ask-for-approval on-request --approvals-reviewer auto_review

--add-dir accepts comma/colon-separated writable roots for workspace-write.

Config

Global: ~/.pi/agent/permissions.json Project: .pi/permissions.json

{
  "sandbox_mode": "workspace-write",
  "approval_policy": "on-request",
  "approvals_reviewer": "auto_review",
  "auto_review_model": "openai/gpt-4.1-mini",
  "auto_review_timeout_ms": 45000,
  "add_dir": ["../shared"],
  "network_access": false,
  "allow_tmp_write": true,
  "status_line": false,
  "bubblewrap_command": "bwrap",
  "approved_prefixes": [
    { "rule": ["cargo", "test"], "scope": "project" }
  ]
}

Project config overrides global config; CLI flags override both. Use /permission (or /permissions) to persist project settings without editing JSON manually:

/permission                         # show current settings
/permission auto-review             # persist workspace-write + on-request + auto_review
/permission auto-review openai/gpt-4.1-mini
/permission user                    # persist interactive user approvals
/permission sandbox read-only
/permission approval never
/permission model clear             # use current session model for auto_review
/permission add-dir ../shared
/permission set network=false auto_review_timeout_ms=45000
/permission set status_line=true      # opt in to footer status display

Auto Review Mode

auto_review uses workspace-write, on-request, restricted network, and a model reviewer for approval requests. Low-risk requests can be approved automatically; higher-risk or uncertain reviews include risk level, complexity, and refusal reason, then prompt the user for the final allow/deny decision when an interactive UI is available. Without an interactive UI, non-allow reviews and reviewer failures remain fail-closed.

Enable it with --auto-review, --approvals-reviewer auto_review, /permission auto-review, or /permissions auto-review. By default the reviewer uses the active pi model; set auto_review_model, --auto-review-model provider/model-id, or /permission model provider/model-id to use a dedicated reviewer model. The reviewer must return strict JSON with outcome, risk_level, complexity, rationale, and optional refusal_reason.

Native sandbox behavior

This package enforces the permission model directly in pi:

• Linux: bubblewrap with read-only root, writable cwd/add_dir roots (and temp when allow_tmp_write is true) in workspace-write, and network namespace isolation unless network_access is true.
• macOS: sandbox-exec Seatbelt profile when available.
• Windows/unsupported: fail closed unless the user explicitly selects danger-full-access.

Non-bash pi tools cannot be placed inside the process sandbox by pi today, so write and edit are preflight-gated with the same read-only/workspace-write root policy, including temp writes when allow_tmp_write is enabled.

Acknowledgements

Thanks to OpenAI Codex CLI for inspiring the permission-model design and portions of the implementation approach. Codex CLI GitHub repository: https://github.com/openai/codex