pi-guard

General-purpose permission system for pi tools. Handles permissions for bash and file tools (read/edit/write) with extensible matchers for custom tools.

Overview

pi-guard intercepts tool calls and checks them against permission rules before execution.

rules define what's allowed. matchers define how to match tool calls to rules.

Built-in matchers for bash, read, write, and edit. Other tools can be guarded by configuring matchers in settings.

Installation

pi install npm:pi-guard

Configuration

Configure in ~/.pi/agent/settings.json:

{
  "guard": {
    "enabled": true,
    "matchers": {
      "spawn": { "param": "agent", "type": "exact" },
      "webfetch": { "param": "url", "type": "glob" }
    },
    "rules": {
      "*": "ask",
      "bash": {
        "*": "ask",
        "git status": "allow",
        "git log": "allow",
        "rm": "deny"
      },
      "read": {
        "*": "allow",
        "*.env": "deny",
        "*.pem": "deny"
      },
      "write": { "*": "ask" },
      "edit": { "*": "ask" },
      "spawn": {
        "build": "allow",
        "test": "allow",
        "*": "deny"
      },
      "webfetch": {
        "*": "ask",
        "https://github.com/*": "allow"
      }
    }
  }
}

Shorthand

Disable all checks:

{ "guard": { "enabled": false } }

Whole-tool action (no pattern matching needed):

{ "guard": { "rules": { "write": "allow" } } }

Environment Variable

Set PI_GUARD to inject rules from outside (e.g., by pi-spawn or CI/CD):

PI_GUARD='{"*":"deny","bash":{"git diff":"allow"}}'

Matchers

Matchers define how to extract and match input from a tool call. Each matcher has a param (which tool parameter to extract) and a type (how to match).

Tools without a matcher get simple allow/ask/deny for the whole tool.

Matching Algorithms

Bash (type: "bash")

1. Parse command with unbash AST parser
2. Extract all commands from the AST
3. For each command, check rules using subsequence matching
4. Tokens in rule must appear in order, extra arguments allowed

Example: "git log" matches git log, git log --oneline, git log --oneline -10

Glob (type: "glob")

Standard glob matching:

• * matches anything except /
• ** matches anything including /
• ? matches single character
• ~ expands to home directory

Exact (type: "exact")

Simple string equality. Rule "build" only matches input build.

Rule Precedence

DEFAULT_CONFIG → user config → project config → PI_GUARD → session rules

Last match wins within a tool's rules. Put catch-all "*" first, specific rules after:

"bash": {
  "*": "ask",
  "git status": "allow",
  "git log": "allow",
  "rm": "deny"
}

Actions

Each permission rule resolves to one of:

• "allow" — run without approval
• "ask" — prompt for approval (or block in non-interactive mode)
• "deny" — block the action

Default Rules

See src/defaults.ts for the built-in default rules.

The defaults follow a simple principle: reading is safe, writing is dangerous. Bash commands that only read (ls, cat, git log) are allowed, while anything that modifies state asks for approval. File reads are mostly allowed except for sensitive patterns (*.env, *.pem). All edits and writes require approval since they change the codebase.

To trust the agent with file modifications (useful in containers or trusted environments), allow all edits and writes:

{
  "guard": {
    "rules": {
      "edit": "allow",
      "write": "allow"
    }
  }
}

Commands

/guard

Manage pi-guard security settings.

/guard toggle    # Enable/disable guard
/guard list      # Show current rules

License

MIT