@gotgenes/pi-permission-system 5.15.0 → 5.16.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.16.0](https://github.com/gotgenes/pi-permission-system/compare/v5.15.0...v5.16.0) (2026-05-13)
+
+
+### Features
+
+* decision events include file path for path-bearing tools ([#147](https://github.com/gotgenes/pi-permission-system/issues/147)) ([eea226d](https://github.com/gotgenes/pi-permission-system/commit/eea226d990d4358983cc319d54b7544849b2b453))
+* normalizeInput returns file path for path-bearing tools ([#147](https://github.com/gotgenes/pi-permission-system/issues/147)) ([0b48995](https://github.com/gotgenes/pi-permission-system/commit/0b4899563ed3aaf2dd264650a98964168e7ecba1))
+* path-scoped session approvals for path-bearing tools ([#147](https://github.com/gotgenes/pi-permission-system/issues/147)) ([1feacc5](https://github.com/gotgenes/pi-permission-system/commit/1feacc53d4ac1653bf974886ce77e13aff014b68))
+
+
+### Documentation
+
+* document per-tool path patterns ([#147](https://github.com/gotgenes/pi-permission-system/issues/147)) ([81245f6](https://github.com/gotgenes/pi-permission-system/commit/81245f6ac98500e6c4d3c2191ceb2db032284f05))
+* plan per-tool path patterns for path-bearing tools ([#147](https://github.com/gotgenes/pi-permission-system/issues/147)) ([9458706](https://github.com/gotgenes/pi-permission-system/commit/9458706d85e4711b73677ee1abcc8f3ad7d18a2e))
+
 ## [5.15.0](https://github.com/gotgenes/pi-permission-system/compare/v5.14.1...v5.15.0) (2026-05-13)
 
 

package/README.md

@@ -34,6 +34,12 @@ pi install npm:@gotgenes/pi-permission-system
     {
       "permission": {
         "*": "allow",
+        "read": {
+          "*": "allow",
+          "*.env": "deny",
+          "*.env.*": "deny",
+          "*.env.example": "allow"
+        },
         "bash": {
           "rm -rf *": "deny",
           "sudo *": "ask"
@@ -56,6 +62,9 @@ All permissions use one of three states:
 When the dialog prompts, you can approve once or approve a pattern for the rest of the session.
 See [docs/session-approvals.md](docs/session-approvals.md) for details on session-scoped rules and pattern suggestions.
 
+For path-bearing tools (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns in the permission map are matched against the file path from `input.path`.
+This lets you express rules like "allow reads but deny `.env` files" — see the example config above.
+
 ## Configuration
 
 Config lives in one JSON file per scope:

package/config/config.example.json

@@ -9,7 +9,12 @@
 
   "permission": {
     "*": "ask",
-    "read": "allow",
+    "read": {
+      "*": "allow",
+      "*.env": "deny",
+      "*.env.*": "deny",
+      "*.env.example": "allow"
+    },
     "write": "deny",
     "bash": {
       "*": "ask",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "5.15.0",
+  "version": "5.16.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "files": [

package/schemas/permissions.schema.json

@@ -41,7 +41,7 @@
     },
     "permission": {
       "description": "Flat permission policy. Each key is a surface name; values are a PermissionState string (catch-all) or a pattern→action map.",
-      "markdownDescription": "Flat permission policy.\n\nEach top-level key is a surface name:\n- `\"*\"` — universal fallback (replaces `defaultPolicy.tools` from the legacy format)\n- Tool names (`read`, `write`, `bash`, `mcp`, `skill`, `external_directory`, etc.)\n\nA **string** value is shorthand for `{ \"*\": action }` (surface-level catch-all).\nAn **object** value maps wildcard patterns to actions — last matching pattern wins.\n\n**Merge order (lowest → highest precedence):** global → project → per-agent frontmatter.",
+      "markdownDescription": "Flat permission policy.\n\nEach top-level key is a surface name:\n- `\"*\"` — universal fallback (replaces `defaultPolicy.tools` from the legacy format)\n- Tool names (`read`, `write`, `bash`, `mcp`, `skill`, `external_directory`, etc.)\n\nA **string** value is shorthand for `{ \"*\": action }` (surface-level catch-all).\nAn **object** value maps wildcard patterns to actions — last matching pattern wins.\n\nFor path-bearing tools (`read`, `write`, `edit`, `find`, `grep`, `ls`), patterns are matched against the file path from `input.path`. For example, `\"read\": { \"*\": \"allow\", \"*.env\": \"deny\" }` allows reads but denies `.env` files.\n\n**Merge order (lowest → highest precedence):** global → project → per-agent frontmatter.",
       "type": "object",
       "propertyNames": {
         "description": "A surface name or the universal fallback key '*'.",
@@ -63,7 +63,12 @@
       "examples": [
         {
           "*": "ask",
-          "read": "allow",
+          "read": {
+            "*": "allow",
+            "*.env": "deny",
+            "*.env.*": "deny",
+            "*.env.example": "allow"
+          },
           "write": "deny",
           "bash": {
             "*": "ask",

package/src/handlers/gates/helpers.ts

@@ -3,14 +3,17 @@ import type { PermissionCheckResult } from "../../types";
 
 /**
  * Derive the human-readable value for a decision event from a check result.
- * Bash → extracted command; MCP → qualified target; others → tool name.
+ * Bash → extracted command; MCP → qualified target;
+ * path-bearing tools → file path; others → tool name.
  */
 export function deriveDecisionValue(
   toolName: string,
   check: Pick<PermissionCheckResult, "command" | "target">,
+  path?: string,
 ): string {
   if (toolName === "bash") return check.command ?? toolName;
   if (toolName === "mcp") return check.target ?? toolName;
+  if (path) return path;
   return toolName;
 }
 

package/src/handlers/gates/tool.ts

@@ -1,4 +1,4 @@
-import { PATH_BEARING_TOOLS } from "../../path-utils";
+import { getPathBearingToolPath, PATH_BEARING_TOOLS } from "../../path-utils";
 import { suggestSessionPattern } from "../../pattern-suggest";
 import {
   formatAskPrompt,
@@ -11,6 +11,21 @@ import type { GateDescriptor } from "./descriptor";
 import { deriveDecisionValue } from "./helpers";
 import type { ToolCallContext } from "./types";
 
+/**
+ * Derive the value used for session-approval pattern suggestions.
+ *
+ * Bash → command string; MCP → qualified target;
+ * path-bearing tools → file path; others → catch-all wildcard.
+ */
+function deriveSuggestionValue(
+  tcc: ToolCallContext,
+  check: PermissionCheckResult,
+): string {
+  if (tcc.toolName === "bash") return check.command ?? "";
+  if (tcc.toolName === "mcp") return check.target ?? "mcp";
+  return getPathBearingToolPath(tcc.toolName, tcc.input) ?? "*";
+}
+
 /**
  * Build a pure descriptor for the normal tool permission gate.
  *
@@ -28,13 +43,10 @@ export function describeToolGate(
   );
 
   // Compute session approval suggestion for the "for this session" option.
-  const suggestionValue =
-    tcc.toolName === "bash"
-      ? (check.command ?? "")
-      : tcc.toolName === "mcp"
-        ? (check.target ?? "mcp")
-        : "*";
-  const suggestion = suggestSessionPattern(tcc.toolName, suggestionValue);
+  const suggestion = suggestSessionPattern(
+    tcc.toolName,
+    deriveSuggestionValue(tcc, check),
+  );
 
   // Build the unavailable-reason message. Bash gets the command embedded.
   const inputCommand =
@@ -85,7 +97,11 @@ export function describeToolGate(
     },
     decision: {
       surface: tcc.toolName,
-      value: deriveDecisionValue(tcc.toolName, check),
+      value: deriveDecisionValue(
+        tcc.toolName,
+        check,
+        getPathBearingToolPath(tcc.toolName, tcc.input) ?? undefined,
+      ),
     },
   };
 }

package/src/input-normalizer.ts

@@ -1,5 +1,6 @@
 import { toRecord } from "./common";
 import { createMcpPermissionTargets } from "./mcp-targets";
+import { getPathBearingToolPath, PATH_BEARING_TOOLS } from "./path-utils";
 
 /**
  * Surface-normalized representation of a tool invocation used by
@@ -85,7 +86,17 @@ export function normalizeInput(
     };
   }
 
-  // --- Tool surfaces (read, write, edit, grep, find, ls, extension tools) ---
+  // --- Path-bearing tools (read, write, edit, grep, find, ls) ---
+  if (PATH_BEARING_TOOLS.has(toolName)) {
+    const path = getPathBearingToolPath(toolName, input);
+    return {
+      surface: toolName,
+      values: [path ?? "*"],
+      resultExtras: {},
+    };
+  }
+
+  // --- Extension tools (non-path-bearing) ---
   return {
     surface: toolName,
     values: ["*"],

package/src/pattern-suggest.ts

@@ -1,4 +1,5 @@
 import { prefix } from "./bash-arity";
+import { PATH_BEARING_TOOLS } from "./path-utils";
 import { deriveApprovalPattern } from "./session-rules";
 
 /** The suggestion returned for a "Yes, for this session" dialog option. */
@@ -69,7 +70,11 @@ function buildLabel(pattern: string, surface: string): string {
     case "external_directory":
       return `Yes, allow access to external directory "${pattern}" for this session`;
     default:
-      // Tool surfaces (read, write, edit, grep, find, ls, extension tools)
+      // Path-bearing tools with a specific path pattern show the pattern.
+      if (PATH_BEARING_TOOLS.has(surface) && pattern !== "*") {
+        return `Yes, allow ${surface} "${pattern}" for this session`;
+      }
+      // Tool surfaces with catch-all or extension tools.
       return `Yes, allow tool "${surface}" for this session`;
   }
 }
@@ -100,7 +105,12 @@ export function suggestSessionPattern(
       pattern = deriveApprovalPattern(value);
       break;
     default:
-      // Tool surfaces (read, write, edit, grep, find, ls, extension tools)
+      // Path-bearing tools: derive a directory-scoped pattern from the path.
+      if (PATH_BEARING_TOOLS.has(surface) && value !== "*") {
+        pattern = deriveApprovalPattern(value);
+        break;
+      }
+      // Extension tools / fallback.
       pattern = "*";
       break;
   }

package/tests/handlers/gates/helpers.test.ts

@@ -26,9 +26,22 @@ describe("deriveDecisionValue", () => {
     expect(deriveDecisionValue("mcp", {})).toBe("mcp");
   });
 
-  it("returns toolName for other tools", () => {
+  it("returns toolName for non-path-bearing tools", () => {
+    expect(deriveDecisionValue("my_extension_tool", {})).toBe(
+      "my_extension_tool",
+    );
+  });
+
+  it("returns path for path-bearing tools when path is provided", () => {
+    expect(deriveDecisionValue("read", {}, "/project/src/main.ts")).toBe(
+      "/project/src/main.ts",
+    );
+    expect(deriveDecisionValue("write", {}, "src/.env")).toBe("src/.env");
+  });
+
+  it("falls back to toolName for path-bearing tools when path is missing", () => {
     expect(deriveDecisionValue("read", {})).toBe("read");
-    expect(deriveDecisionValue("write", { command: "ignored" })).toBe("write");
+    expect(deriveDecisionValue("write", {}, undefined)).toBe("write");
   });
 });
 

package/tests/input-normalizer.test.ts

@@ -71,22 +71,59 @@ describe("normalizeInput — non-MCP surfaces", () => {
     });
   });
 
-  describe("tool surfaces (read, write, edit, grep, find, ls, extension tools)", () => {
-    it("uses '*' as the lookup value for built-in tools", () => {
+  describe("path-bearing tools (read, write, edit, grep, find, ls)", () => {
+    it("uses input.path as the lookup value when path is present", () => {
       for (const tool of ["read", "write", "edit", "grep", "find", "ls"]) {
-        const result = normalizeInput(tool, {}, []);
+        const result = normalizeInput(
+          tool,
+          { path: "/project/src/main.ts" },
+          [],
+        );
         expect(result.surface).toBe(tool);
-        expect(result.values).toEqual(["*"]);
+        expect(result.values).toEqual(["/project/src/main.ts"]);
         expect(result.resultExtras).toEqual({});
       }
     });
 
+    it("falls back to '*' when input.path is missing", () => {
+      for (const tool of ["read", "write", "edit", "grep", "find", "ls"]) {
+        const result = normalizeInput(tool, {}, []);
+        expect(result.values).toEqual(["*"]);
+      }
+    });
+
+    it("falls back to '*' when input.path is empty string", () => {
+      const result = normalizeInput("read", { path: "" }, []);
+      expect(result.values).toEqual(["*"]);
+    });
+
+    it("falls back to '*' when input.path is not a string", () => {
+      const result = normalizeInput("write", { path: 42 }, []);
+      expect(result.values).toEqual(["*"]);
+    });
+
+    it("falls back to '*' when input is null", () => {
+      const result = normalizeInput("edit", null, []);
+      expect(result.values).toEqual(["*"]);
+    });
+  });
+
+  describe("extension tools (non-path-bearing)", () => {
     it("uses '*' as the lookup value for extension tools", () => {
       const result = normalizeInput("my_extension_tool", { some: "input" }, []);
       expect(result.surface).toBe("my_extension_tool");
       expect(result.values).toEqual(["*"]);
       expect(result.resultExtras).toEqual({});
     });
+
+    it("uses '*' even when extension tool has a path field", () => {
+      const result = normalizeInput(
+        "my_extension_tool",
+        { path: "/some/path" },
+        [],
+      );
+      expect(result.values).toEqual(["*"]);
+    });
   });
 });
 

package/tests/pattern-suggest.test.ts

@@ -121,28 +121,51 @@ describe("suggestSessionPattern", () => {
     });
   });
 
-  describe("tool surfaces", () => {
-    it("returns * for read surface", () => {
-      const result = suggestSessionPattern("read", "*");
-      expect(result).toMatchObject({ surface: "read", pattern: "*" });
+  describe("path-bearing tool surfaces", () => {
+    it("returns directory-scoped pattern for read with a file path", () => {
+      const result = suggestSessionPattern("read", "/outside/project/file.ts");
+      expect(result).toMatchObject({
+        surface: "read",
+        pattern: "/outside/project/*",
+      });
     });
 
-    it("returns * for write surface", () => {
-      const result = suggestSessionPattern("write", "*");
-      expect(result).toMatchObject({ surface: "write", pattern: "*" });
+    it("returns directory-scoped pattern for write with a file path", () => {
+      const result = suggestSessionPattern("write", "src/main.ts");
+      expect(result).toMatchObject({
+        surface: "write",
+        pattern: "src/*",
+      });
     });
 
-    it("returns * for edit surface", () => {
-      const result = suggestSessionPattern("edit", "*");
-      expect(result).toMatchObject({ surface: "edit", pattern: "*" });
+    it("returns * when value is '*' (fallback)", () => {
+      const result = suggestSessionPattern("read", "*");
+      expect(result).toMatchObject({ surface: "read", pattern: "*" });
+    });
+
+    it("label includes the path pattern for path-bearing tools", () => {
+      const result = suggestSessionPattern("read", "/tmp/data/file.txt");
+      expect(result.label).toBe(
+        'Yes, allow read "/tmp/data/*" for this session',
+      );
     });
 
-    it("label shows tool name instead of bare wildcard", () => {
+    it("label shows tool name when pattern is *", () => {
       const result = suggestSessionPattern("find", "*");
       expect(result.label).toBe('Yes, allow tool "find" for this session');
     });
   });
 
+  describe("non-path-bearing tool surfaces", () => {
+    it("returns * for extension tools", () => {
+      const result = suggestSessionPattern("my_extension_tool", "*");
+      expect(result).toMatchObject({
+        surface: "my_extension_tool",
+        pattern: "*",
+      });
+    });
+  });
+
   describe("label field", () => {
     it("bash label includes surface prefix and pattern", () => {
       const result = suggestSessionPattern("bash", "git status");
@@ -173,7 +196,12 @@ describe("suggestSessionPattern", () => {
       );
     });
 
-    it("tool label shows tool name, not wildcard pattern", () => {
+    it("path-bearing tool label includes path pattern", () => {
+      const result = suggestSessionPattern("edit", "src/file.ts");
+      expect(result.label).toBe('Yes, allow edit "src/*" for this session');
+    });
+
+    it("tool label shows tool name when value is *", () => {
       const result = suggestSessionPattern("edit", "*");
       expect(result.label).toBe('Yes, allow tool "edit" for this session');
     });

package/tests/permission-manager-unified.test.ts

@@ -980,3 +980,134 @@ describe("PermissionManager with in-memory PolicyLoader", () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Per-tool path patterns (#147)
+// ---------------------------------------------------------------------------
+
+describe("checkPermission — per-tool path patterns", () => {
+  it("denies read of .env when path pattern matches", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      read: { "*": "allow", "*.env": "deny" },
+    });
+    try {
+      const result = manager.checkPermission("read", { path: ".env" });
+      expect(result.state).toBe("deny");
+      expect(result.matchedPattern).toBe("*.env");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("allows read of non-.env file when .env is denied", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      read: { "*": "allow", "*.env": "deny" },
+    });
+    try {
+      const result = manager.checkPermission("read", {
+        path: "src/main.ts",
+      });
+      expect(result.state).toBe("allow");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("allows write to src/ when only src/ is allowed", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      write: { "*": "deny", "src/*": "allow" },
+    });
+    try {
+      const result = manager.checkPermission("write", {
+        path: "src/main.ts",
+      });
+      expect(result.state).toBe("allow");
+      expect(result.matchedPattern).toBe("src/*");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("denies write outside src/ when only src/ is allowed", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      write: { "*": "deny", "src/*": "allow" },
+    });
+    try {
+      const result = manager.checkPermission("write", {
+        path: "vendor/lib.ts",
+      });
+      expect(result.state).toBe("deny");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("backward compat: 'read': 'allow' allows read of any path", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      read: "allow",
+    });
+    try {
+      const result = manager.checkPermission("read", { path: ".env" });
+      expect(result.state).toBe("allow");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("backward compat: 'read': 'deny' denies read of any path", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      read: "deny",
+    });
+    try {
+      const result = manager.checkPermission("read", {
+        path: "src/main.ts",
+      });
+      expect(result.state).toBe("deny");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("session rule for specific path overrides config deny", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      read: { "*": "allow", "*.env": "deny" },
+    });
+    try {
+      const sessionRules: Ruleset = [sessionAllow("read", ".env")];
+      const result = manager.checkPermission(
+        "read",
+        { path: ".env" },
+        undefined,
+        sessionRules,
+      );
+      expect(result.state).toBe("allow");
+      expect(result.source).toBe("session");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("falls back to '*' when input.path is missing", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      read: { "*": "allow", "*.env": "deny" },
+    });
+    try {
+      const result = manager.checkPermission("read", {});
+      expect(result.state).toBe("allow");
+    } finally {
+      cleanup();
+    }
+  });
+
+  it("getToolPermission still returns surface-level state (not path-specific)", () => {
+    const { manager, cleanup } = makeManagerWithConfig({
+      read: { "*": "allow", "*.env": "deny" },
+    });
+    try {
+      const toolState = manager.getToolPermission("read");
+      expect(toolState).toBe("allow");
+    } finally {
+      cleanup();
+    }
+  });
+});