pi-perms

Pi CLI extension that enforces a cross-agent permission policy from .agents/permissions.json.

Uses agent-perms for evaluation and policy loading. See the agent-perms README for the full schema, rule syntax, and codec documentation.

Install

pnpm add pi-perms

Pi loads the extension automatically via the pi.extensions field in package.json — no additional configuration needed.

How it works

1. Subscribes to tool_call events from Pi
2. Loads the merged permission policy from .agents/permissions.json + .agents/permissions.local.json
3. Evaluates the tool call against the policy (deny-first)
4. Blocks denied calls, passes ask calls through Pi's default confirmation, and allows everything else

Policy file

Create .agents/permissions.json in your project root:

{
  "rules": [
    { "tool": "Bash", "pattern": "git status", "tier": "allow" },
    { "tool": "Bash", "pattern": "npm run test:*", "tier": "allow" },
    { "tool": "Read", "tier": "allow" },
    { "tool": "Grep", "tier": "allow" },
    { "tool": "Bash", "pattern": "sudo:*", "tier": "deny" },
    { "tool": "Bash", "pattern": "rm -rf /", "tier": "deny" },
    { "tool": "Bash", "pattern": "git push:*", "tier": "ask" },
    { "tool": "Bash", "pattern": "npm publish:*", "tier": "ask" }
  ]
}

Claude Code's permissions.allow/deny/ask arrays are also accepted — the loader normalises them into rules.

| File | Purpose | Git | |---|---|---| | .agents/permissions.json | Team-shared policy | Committed | | .agents/permissions.local.json | Personal overrides | Gitignored |

Rule syntax

Rules use structured objects with tool, optional pattern, and tier. In permissions compat arrays, they use Tool(pattern) strings:

| Pattern | Matches | |---|---| | Read | All file reads | | Bash(git status) | Exactly git status | | Bash(npm:*) | Commands starting with npm | | Bash(git commit *) | git commit followed by anything | | Bash(domain:evil.com) | Commands containing evil.com |

Evaluation order: deny → ask → allow. Deny short-circuits before all other tiers.

Dependencies

• agent-perms — evaluator, loader, Zod schemas
• @earendil-works/pi-coding-agent — Pi extension API (peer dependency, ≥0.74)

Development

pnpm install
pnpm test             # 20 tests (unit + e2e)
pnpm typecheck
pnpm lint

Source structure

src/
  extension.ts        # Pi extension factory — subscribes to tool_call events
  test/
    e2e.test.ts       # End-to-end tests with mock ExtensionAPI
    evaluate.test.ts  # Unit tests for extractInput()

The evaluator and loader live in agent-perms — pi-perms is a thin wiring layer that connects them to Pi's extension API.