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.