pi-policy-gate/README.md

@enne2/pi-policy-gate

A standalone pi extension package that applies a practical policy layer to risky tool calls.

It classifies operations into four outcomes:

• allow — execute immediately
• confirm — require human approval
• deny — block outright
• refine — block and tell the model how to reformulate the command safely

The default policy is opinionated but usable:

• sudo and ssh are not denied by default
• risky commands are generally confirmed
• only objectively dangerous or ambiguous forms are denied/refined
• destructive deletes should use an explicit absolute path

What it protects against

Examples of behavior it catches by default:

• rm -rf *
• rm -rf .
• rm -rf ..
• rm -rf /
• find . -delete
• sudo ... (confirmation)
• ssh ... / scp / rsync / sftp (confirmation)
• git reset --hard, git clean -fdx, git push (confirmation)
• writes outside the workspace (confirmation)
• reads/writes to sensitive paths such as ~/.ssh or .env (confirmation)

Install

Directly in pi from git

Private Gitea/GitHub style install:

pi install git:git@git.enne2.net:enne2/pi-policy-gate.git

Or with HTTPS:

pi install https://git.enne2.net/enne2/pi-policy-gate.git

With npm from the git repository

npm install git+ssh://git@git.enne2.net/enne2/pi-policy-gate.git

Then load it from local node_modules or publish it to your npm registry later.

Config files

The extension looks for config files in this order:

1. built-in defaults
2. ~/.pi/agent/policy-gate.json
3. extra file passed with --policy-gate-config /path/to/file.json
4. .pi/policy-gate.json in the current project

Project config overrides global config.

Example config

Copy and adjust:

cp policy-gate.example.json ~/.pi/agent/policy-gate.json

Example:

{
  "workspaceRoots": ["."],
  "requireAbsolutePathForRecursiveDelete": true,
  "overrides": [
    {
      "tool": "bash",
      "commandRegex": "^sudo systemctl restart my-safe-service$",
      "action": "allow"
    }
  ]
}

Config reference

{
  "workspaceRoots": ["."],
  "requireAbsolutePathForRecursiveDelete": true,
  "requireAbsolutePathForFindDelete": true,
  "confirmSensitiveReads": true,
  "confirmSensitiveWrites": true,
  "confirmWritesOutsideWorkspace": true,
  "sensitivePathGlobs": ["~/.ssh/**", "**/.env"],
  "overrides": [
    {
      "id": "optional label",
      "tool": "bash",
      "commandRegex": "^ssh deploy@staging\\b",
      "pathGlob": "~/.ssh/**",
      "action": "allow | confirm | deny | refine",
      "reason": "Shown to the user / model",
      "suggest": "Only used with refine/deny to explain the safer alternative"
    }
  ]
}

Notes

• workspaceRoots can be absolute paths, ~ paths, or paths relative to the current project cwd.
• commandRegex is evaluated against the raw bash command string.
• pathGlob is matched against both the absolute path and the path relative to the current cwd.
• last matching override wins.

Behavior model

Allow

Low-risk reads and normal project-local writes are allowed.

Confirm

Potentially dangerous but legitimate actions prompt the human.

Examples:

• sudo systemctl restart nginx
• ssh deploy@staging 'systemctl status api'
• rm -rf /full/path/to/some/build-cache

Deny / Refine

Only clearly unsafe or ambiguous forms are blocked.

Examples:

• rm -rf *
• rm -rf .
• find . -delete

The extension tells the model to switch to a safer form such as using an explicit absolute path.

Useful commands

Inside pi:

• /policy-gate — show current policy summary

Development

Install deps and verify the package tarball:

npm install
npm run pack:check

Try it without installing globally:

pi -e /absolute/path/to/pi-policy-gate --list-models

Packaging notes

This package is intentionally TypeScript-only and relies on pi's built-in runtime loader. No build step is required.