pi-permissions

Claude Code-style permission modes for pi. Controls when the agent needs approval for file writes, edits, and bash commands.

Installation

pi install npm:@rhedbull/pi-permissions

Or from git:

pi install git:github.com/rHedBull/pi-permissions

Permission Modes

Mode	Status	Write/Edit	Normal Bash	Dangerous Bash	Catastrophic
default	⏵ Default	❓ Confirm	❓ Confirm	❓ Confirm	🚫 Blocked
acceptEdits	⏵⏵ Accept Edits	✅ Auto	❓ Confirm	❓ Confirm	🚫 Blocked
fullAuto	⏵⏵⏵ Full Auto	✅ Auto	✅ Auto	❓ Confirm	🚫 Blocked
bypassPermissions	⏵⏵⏵⏵ Bypass Permissions	✅ Auto	✅ Auto	✅ Auto	🚫 Blocked

Approval Options

When prompted for confirmation, you can:

• Allow once — approve this specific call only
• Allow for session — auto-approve this tool (or exact bash command) for the rest of the session
• Deny — block the operation

CLI Flags

pi --default              # Confirm everything
pi --accept-edits         # Auto-approve file edits
pi --full-auto            # Auto-approve safe bash too
pi --bypass-permissions   # Allow everything (except catastrophic)

Commands

Command	Description
/permissions	Interactive mode selector
/permissions <mode>	Set mode directly (tab-completion supported)
/permissions:status	Show current mode and session approvals

Keyboard Shortcut

Ctrl+Shift+P — Cycle through permission modes

Catastrophic Command Protection

These commands are always blocked in every mode, including bypassPermissions. They cannot be overridden:

• sudo rm -rf /, rm -rf /, rm -rf /*
• mkfs.*, dd if=, sudo dd
• :(){ :|:& };: (fork bomb)
• sudo chmod -R 777 /, sudo chown -R
• > /dev/sda, > /dev/nvme

Protected Path Enforcement

Writes and edits to sensitive paths are always blocked in every mode:

• ~/.ssh — SSH keys, authorized_keys, config
• ~/.aws — AWS credentials
• ~/.gnupg, ~/.gpg — GPG keys
• ~/.bashrc, ~/.bash_profile, ~/.profile, ~/.zshrc, ~/.zprofile — Shell startup files
• ~/.config/git/credentials — Git credentials
• ~/.netrc — Network credentials
• ~/.npmrc — npm auth tokens
• ~/.docker/config.json — Docker registry auth
• ~/.kube/config — Kubernetes cluster access
• ~/.pi/agent/auth.json — Pi API keys

This covers both direct write/edit tool calls and bash commands referencing these paths.

Configuration

Configuration is loaded from two optional JSON files, merged in order (project overrides global):

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

Example Configuration

{
  "mode": "acceptEdits",
  "dangerousPatterns": [
    { "pattern": "rm -rf", "description": "recursive force delete" },
    { "pattern": "docker system prune", "description": "docker cleanup" }
  ],
  "catastrophicPatterns": [
    { "pattern": "sudo rm -rf /", "description": "sudo recursive delete root" }
  ],
  "protectedPaths": [
    "~/.ssh",
    "~/.aws",
    "/etc/passwd"
  ]
}

Configuration Fields

Field	Default	Description
mode	"acceptEdits"	Default permission mode
dangerousPatterns	See defaults	Commands requiring confirmation in fullAuto
catastrophicPatterns	See defaults	Commands always blocked, all modes
protectedPaths	See defaults	Paths where writes are always blocked

Shell Trick Detection

Commands containing shell constructs that can hide arbitrary execution are flagged as ⚠️ SHELL TRICK and always require confirmation (except in bypassPermissions mode). These cannot be session-approved — each occurrence prompts individually.

Detected patterns:

• Command substitution: $(cmd), `cmd`
• Process substitution: <(cmd), >(cmd)
• Eval/exec: eval "...", exec ...
• Shell invocation: bash -c "...", sh -c "..."
• Pipe to shell: ... | bash, ... | sh
• Source: source script.sh

Limitations

Pattern matching uses substring matching against the raw command string. This means:

• Extra whitespace can bypass: sudo rm -rf / won't match sudo rm -rf /
• Path traversal can bypass: rm -rf /tmp/../../../ resolves to root but won't match
• Nested invocations can bypass: bash -c "rm -rf /" won't match

This is the same limitation Claude Code has with its built-in permission system. For AST-based structural matching that catches these edge cases, use @aliou/pi-guardrails alongside this extension — guardrails parses the shell command into an AST and matches against the parsed structure.

Protected path checking for bash commands also uses substring matching, which may produce false positives if a protected path string appears in a non-file context (e.g. inside a string argument or comment).

Works With

Designed to work alongside @aliou/pi-guardrails. Guardrails handles .env file protection and AST-based dangerous command detection, while this extension handles the broader permission mode workflow.