pi-permissions 1.0.0 → 1.0.2

package/README.md

@@ -1,33 +1,42 @@
-# pi-permissions
+# pi-permissions [![npm version](https://img.shields.io/npm/v/pi-permissions)](https://www.npmjs.com/package/pi-permissions) [![license](https://img.shields.io/npm/l/pi-permissions)](./LICENSE)
 
-A [pi](https://github.com/badlogic/pi) extension that provides configurable allow/deny permission rules for tool calls — similar to Claude's permission system.
+A [pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) extension that provides **configurable allow/deny permission rules** for tool calls — control which bash commands, file reads, writes, and edits the agent can perform.
+
+- Define **allow** rules to whitelist specific commands
+- Define **deny** rules to block dangerous operations
+- Deny always wins — block `git push` even if `git *` is allowed
+- Supports glob patterns with `*` wildcards
+- Project-local or global configuration
 
 ## Install
 
 ```bash
-# From npm
 pi install npm:pi-permissions
+```
 
-# From GitHub
-pi install https://github.com/NicoAvanzDev/pi-permissions
+Alternative install methods
 
-# Project-local (shared with team)
-pi install -l https://github.com/NicoAvanzDev/pi-permissions
+From the public git repo:
 
-# Try without installing
-pi -e npm:pi-permissions
+```bash
+pi install git:github.com/NicoAvanzDev/pi-permissions
 ```
 
-## Configuration
+From a local clone:
 
-Create a `permissions.json` file in one of these locations:
+```bash
+pi install .
+```
 
-| Location | Scope |
-|----------|-------|
-| `.pi/permissions.json` | Project-local (checked first) |
-| `~/.pi/agent/permissions.json` | Global fallback |
+Load without installing:
+
+```bash
+pi --no-extensions -e npm:pi-permissions
+```
+
+## Quick start
 
-### Example
+Create `.pi/permissions.json` in your project (or `~/.pi/agent/permissions.json` for global rules):
 
 ```json
 {
@@ -38,30 +47,42 @@ Create a `permissions.json` file in one of these locations:
       "Bash(git commit *)",
       "Bash(git diff *)",
       "Bash(git status)",
-      "Bash(git log *)",
-      "Bash(* --version)",
-      "Bash(* --help *)"
+      "Bash(git log *)"
     ],
     "deny": [
       "Bash(git push *)",
-      "Bash(git add .)",
       "Bash(rm -rf *)",
       "Write(*.env)",
-      "Write(.env.*)",
       "Edit(*.env)"
     ]
   }
 }
 ```
 
-## Rule Format
+On session start, the extension loads your rules and reports how many were found. Any tool call that matches a deny rule is blocked before execution.
+
+### Example session
+
+```text
+> pi
+Permissions loaded: 6 allow, 4 deny rules
+
+> (agent tries to run `git push origin main`)
+⛔ Blocked: Bash command matches deny rule "Bash(git push *)"
+```
+
+After editing `permissions.json`, type `/reload` in pi to apply the changes.
+
+## How it works
+
+### Rule format
 
 Rules use the format `Tool(pattern)` where:
 
 - **Tool** — the pi tool name: `Bash`, `Write`, `Edit`, `Read`
 - **pattern** — a glob pattern where `*` matches any characters
 
-### Supported Tools
+### Supported tools
 
 | Tool | What the pattern matches against |
 |------|----------------------------------|
@@ -70,18 +91,20 @@ Rules use the format `Tool(pattern)` where:
 | `Edit(pattern)` | The file path being edited |
 | `Read(pattern)` | The file path being read |
 
-### Evaluation Logic
+### Evaluation logic
 
-1. **Deny rules are checked first** — if any deny rule matches, the call is blocked
-2. **Allow rules are checked next** — if allow rules exist for the tool, the call must match at least one
-3. **No rules = no restrictions** — if no allow rules exist for a tool, all calls pass (unless denied)
+For every tool call the extension:
+
+1. **checks deny rules first** — if any deny rule matches, the call is blocked
+2. **checks allow rules next** — if allow rules exist for that tool, the call must match at least one
+3. **passes through** — if no allow rules exist for the tool, all calls are permitted (unless denied)
 
 This means:
 - Use **deny** to block specific dangerous commands
 - Use **allow** to whitelist only approved commands (everything else is blocked)
 - **Deny always wins** over allow
 
-### Pattern Examples
+### Pattern examples
 
 | Pattern | Matches | Doesn't match |
 |---------|---------|---------------|
@@ -91,9 +114,22 @@ This means:
 | `Write(*.env)` | `.env`, `app.env` | `.env.example` |
 | `Write(secrets/*)` | `secrets/key.pem` | `src/secrets.ts` |
 
-## Reloading
+## Configuration
+
+| Location | Scope |
+|----------|-------|
+| `.pi/permissions.json` | Project-local (checked first) |
+| `~/.pi/agent/permissions.json` | Global fallback |
+
+The extension checks the project-local path first. If not found, it falls back to the global config.
 
-After editing `permissions.json`, type `/reload` in pi to apply the changes.
+## Notes
+
+- rules are loaded once on session start
+- use `/reload` to pick up changes without restarting
+- deny rules are always evaluated before allow rules
+- if no allow rules exist for a tool type, all calls for that tool are permitted
+- glob `*` matches any sequence of characters (including path separators in file patterns)
 
 ## License
 

package/extensions/rules.ts

@@ -0,0 +1,105 @@
+export interface PermissionsConfig {
+  permissions?: {
+    allow?: string[];
+    deny?: string[];
+  };
+}
+
+export interface ParsedRule {
+  tool: string;
+  pattern: RegExp;
+  original: string;
+}
+
+export function globToRegex(glob: string): RegExp {
+  const escaped = glob.replace(/([.+?^${}()|[\]\\])/g, "\\$1").replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`);
+}
+
+export function parseRule(rule: string): ParsedRule | null {
+  const match = rule.match(/^(\w+)\((.+)\)$/);
+  if (!match) return null;
+  const [, tool, glob] = match;
+  return {
+    tool: tool.toLowerCase(),
+    pattern: globToRegex(glob),
+    original: rule,
+  };
+}
+
+export function parseRules(rules: string[]): ParsedRule[] {
+  return rules.map(parseRule).filter((r): r is ParsedRule => r !== null);
+}
+
+// Map pi tool names to permission tool names
+export function getToolKey(toolName: string): string {
+  switch (toolName) {
+    case "bash":
+    case "write":
+    case "edit":
+    case "read":
+      return toolName;
+    default:
+      return toolName;
+  }
+}
+
+// Extract the matchable string from tool input
+export function getMatchTarget(toolName: string, input: Record<string, unknown>): string | null {
+  switch (toolName) {
+    case "bash":
+      return (input.command as string)?.trim() ?? null;
+    case "write":
+    case "edit":
+    case "read":
+      return (input.path as string) ?? null;
+    default:
+      return null;
+  }
+}
+
+export interface EvalResult {
+  blocked: boolean;
+  reason?: string;
+}
+
+/**
+ * Evaluate whether a tool call should be blocked.
+ * - Deny rules are checked first (deny always wins)
+ * - If allow rules exist for the tool, the call must match at least one
+ * - No rules = no restrictions
+ */
+export function evaluate(
+  toolName: string,
+  input: Record<string, unknown>,
+  allowRules: ParsedRule[],
+  denyRules: ParsedRule[],
+): EvalResult {
+  const toolKey = getToolKey(toolName);
+  const target = getMatchTarget(toolName, input);
+  if (!target) return { blocked: false };
+
+  // Deny rules first — deny always wins
+  for (const rule of denyRules) {
+    if (rule.tool === toolKey && rule.pattern.test(target)) {
+      return {
+        blocked: true,
+        reason: `Blocked by deny rule: ${rule.original}\nCommand: ${target}`,
+      };
+    }
+  }
+
+  // If allow rules exist for this tool, must match at least one
+  const toolAllowRules = allowRules.filter((r) => r.tool === toolKey);
+  if (toolAllowRules.length > 0) {
+    const allowed = toolAllowRules.some((rule) => rule.pattern.test(target));
+    if (!allowed) {
+      return {
+        blocked: true,
+        reason: `Blocked: no allow rule matched for ${toolName}.\nCommand: ${target}\nAllowed patterns: ${toolAllowRules.map((r) => r.original).join(", ")}`,
+      };
+    }
+  }
+
+  return { blocked: false };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-permissions",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Configurable allow/deny permission rules for pi tool calls — control which bash commands, file reads, writes, and edits the agent can perform.",
   "keywords": [
     "pi-package",
@@ -20,6 +20,7 @@
   },
   "files": [
     "extensions/permissions.ts",
+    "extensions/rules.ts",
     "README.md"
   ],
   "type": "module",