@pi-lab/permissions

A permission system extension for pi coding agent. Intercepts tool calls and enforces allow / deny / ask rules defined in a JSON config file.

Install

pi install npm:@pi-lab/permissions

Configuration

Rules are configured in pi settings and merged into a single list:

• ~/.pi/agent/settings.json — global
• .pi/settings.json — project

Example settings.json:

{
  "permissions": {
    "rules": [
      {
        "message": "Block rm -rf",
        "priority": 10,
        "match": { "tool": "bash", "params": { "command": "rm\\s+-rf" } },
        "action": "deny"
      },
      {
        "match": { "tool": "bash", "params": { "command": "sudo" } },
        "action": "ask"
      },
      {
        "message": "Only allow reading files inside the project",
        "priority": 10,
        "match": { "tool": "read", "paths": ["~/projects/my-app/**"] },
        "action": "allow"
      },
      {
        "message": "read is restricted to allowed paths only",
        "match": { "tool": "read" },
        "action": "deny"
      }
    ]
  }
}

Rule fields

Field	Type	Required	Description
match.tool	string	✓	Tool name, or "*" to match all tools
match.params	object	—	Param name → regex pattern. All conditions must match.
match.paths	string[]	—	Path patterns the tool's path argument must fall within. Supports glob (**, *) and plain directory prefixes. Supports ~ expansion. Pairs with a higher-priority allow rule to form a whitelist.
match.pathParam	string	—	Which input key holds the path. Defaults to "path".
action	string	✓	allow, deny, or ask
priority	number	—	Defaults to 0. Higher values are evaluated first.
message	string	—	Reason returned to the LLM when a call is blocked.

Matching order

1. Rules sorted by priority descending
2. Same priority: deny > ask > allow

No match defaults to allow.

ask mode

A dialog prompts the user with four options:

• Allow — allow this call once
• Allow always — allow identical calls for the rest of the session (not persisted)
• Deny — deny this call once
• Deny always — deny identical calls for the rest of the session (not persisted)

Events

The extension broadcasts observational events on pi.events. Listeners cannot change permission decisions, cache behavior, or blocked responses.

Event names

• permissions:deny — emitted whenever a tool call is blocked
• permissions:ask — emitted immediately before a real user prompt is shown
• permissions:user_select — emitted after the prompt resolves

Payloads

All payloads include the matched rule serialized with configured patterns only. Raw tool input is never broadcast.

type SerializedPermissionRule = {
  action: "allow" | "deny" | "ask";
  message?: string;
  priority?: number;
  match: {
    tool: string;
    params?: Record<string, string>;
    paths?: string[];
    pathParam?: string;
  };
};

type PermissionsDenyEvent = {
  toolCallId: string;
  toolName: string;
  reason: string;
  source: "rule" | "cache" | "user" | "no_ui";
  rule: SerializedPermissionRule;
};

type PermissionsAskEvent = {
  toolCallId: string;
  toolName: string;
  rule: SerializedPermissionRule;
  options: ["Allow", "Allow always", "Deny", "Deny always"];
};

type PermissionsUserSelectEvent = {
  toolCallId: string;
  toolName: string;
  selection: "Allow" | "Allow always" | "Deny" | "Deny always" | null;
  decision: "allow" | "deny";
  cached: boolean;
  rule: SerializedPermissionRule;
};

Privacy guarantee

Event payloads never include event.input or derived raw argument values such as shell commands, file paths, or file contents. The params and paths fields contain only the configured rule patterns.

Example listener

pi.events.on("permissions:deny", (event) => {
  console.log(event);
});