@gotgenes/pi-permission-system 3.1.0 → 3.2.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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).
 
+## [3.2.0](https://github.com/gotgenes/pi-permission-system/compare/v3.1.0...v3.2.0) (2026-05-03)
+
+
+### Features
+
+* add SAFE_SYSTEM_PATHS allowlist and isSafeSystemPath helper ([#44](https://github.com/gotgenes/pi-permission-system/issues/44)) ([331b53f](https://github.com/gotgenes/pi-permission-system/commit/331b53f1a6425c7ee641127cbc82b5aada1e7018))
+* filter safe system paths from bash external path extraction ([#44](https://github.com/gotgenes/pi-permission-system/issues/44)) ([a0a907f](https://github.com/gotgenes/pi-permission-system/commit/a0a907f020cbf08722ea47be11d3f67fc95ef448))
+* skip safe system paths in isPathOutsideWorkingDirectory ([#44](https://github.com/gotgenes/pi-permission-system/issues/44)) ([360594c](https://github.com/gotgenes/pi-permission-system/commit/360594c8ddfd6f7f45abe04352a514de292df357))
+
+
+### Documentation
+
+* clarify /dev/null redirect risks in plan [#44](https://github.com/gotgenes/pi-permission-system/issues/44) ([00c61e7](https://github.com/gotgenes/pi-permission-system/commit/00c61e75eb5bf3cd9d5fc3297024ef9642655b86))
+* note safe system path allowlist in external-directory section ([#44](https://github.com/gotgenes/pi-permission-system/issues/44)) ([eaec9ae](https://github.com/gotgenes/pi-permission-system/commit/eaec9ae4ad88155bf2630bba9607920cbbdc8583))
+* plan auto-allow /dev/null in external directory checks ([#44](https://github.com/gotgenes/pi-permission-system/issues/44)) ([90b94f4](https://github.com/gotgenes/pi-permission-system/commit/90b94f4e0ae01b3a9f9dc90c5426720742a652e2))
+
 ## [3.1.0](https://github.com/gotgenes/pi-permission-system/compare/v3.0.5...v3.1.0) (2026-05-03)
 
 

package/README.md

@@ -367,7 +367,7 @@ Reserved permission checks:
 
 `external_directory` is evaluated before the normal tool permission check. For example, `tools.read: "allow"` can permit ordinary reads while `special.external_directory: "ask"` still requires confirmation before reading `../outside.txt` or an absolute path outside `ctx.cwd`. Optional-path search tools (`find`, `grep`, `ls`) skip this check when no `path` is provided because they default to the active working directory.
 
-Bash commands are also covered: the extension extracts path-like tokens from the command string and applies the same gate when any resolve outside `ctx.cwd`. Quoted strings are stripped first to reduce false positives (e.g., paths inside `git commit -m "..."` messages). This is a best-effort heuristic — variable expansion, subshells, and escaped quotes are not parsed.
+Bash commands are also covered: the extension extracts path-like tokens from the command string and applies the same gate when any resolve outside `ctx.cwd`. Quoted strings are stripped first to reduce false positives (e.g., paths inside `git commit -m "..."` messages). This is a best-effort heuristic — variable expansion, subshells, and escaped quotes are not parsed. OS device paths (`/dev/null`, `/dev/stdin`, `/dev/stdout`, `/dev/stderr`) are always excluded from this check — they cannot hold or leak data and commonly appear in stderr-redirect idioms such as `command 2>/dev/null`.
 
 ---
 

package/package.json

@@ -1,14 +1,9 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
-  "main": "./index.ts",
-  "exports": {
-    ".": "./index.ts"
-  },
   "files": [
-    "index.ts",
     "src",
     "tests",
     "config/config.example.json",
@@ -49,7 +44,7 @@
   },
   "pi": {
     "extensions": [
-      "./index.ts"
+      "./src/index.ts"
     ]
   },
   "peerDependencies": {
@@ -71,7 +66,7 @@
     "lint:fix": "biome check --write .",
     "lint:md": "markdownlint-cli2 '*.md' 'docs/**/*.md' '.pi/prompts/**/*.md'",
     "lint:md:fix": "markdownlint-cli2 --fix '*.md' 'docs/**/*.md' '.pi/prompts/**/*.md'",
-    "lint:imports": "! grep -rn --include='*.ts' 'from \"\\.[./][^\"]*\\.js\"' src/ tests/ index.ts",
+    "lint:imports": "! grep -rn --include='*.ts' 'from \"\\.[./][^\"]*\\.js\"' src/ tests/",
     "lint:all": "pnpm run lint && pnpm run lint:md && pnpm run lint:imports",
     "format": "biome format --write .",
     "test": "vitest run",

package/src/external-directory.ts

@@ -3,6 +3,25 @@ import { join, normalize, resolve, sep } from "node:path";
 
 import { getNonEmptyString, toRecord } from "./common";
 
+/**
+ * Paths that are universally safe and should never trigger external-directory checks.
+ * These are OS device files: read returns EOF or process streams, write discards or goes to process streams.
+ */
+export const SAFE_SYSTEM_PATHS: ReadonlySet<string> = new Set([
+  "/dev/null",
+  "/dev/stdin",
+  "/dev/stdout",
+  "/dev/stderr",
+]);
+
+/**
+ * Returns true if the given normalized path is a safe OS device file
+ * that should never trigger external-directory checks.
+ */
+export function isSafeSystemPath(normalizedPath: string): boolean {
+  return SAFE_SYSTEM_PATHS.has(normalizedPath);
+}
+
 export const PATH_BEARING_TOOLS = new Set([
   "read",
   "write",
@@ -72,11 +91,13 @@ export function isPathOutsideWorkingDirectory(
 ): boolean {
   const normalizedCwd = normalizePathForComparison(cwd, cwd);
   const normalizedPath = normalizePathForComparison(pathValue, cwd);
-  return Boolean(
-    normalizedCwd &&
-      normalizedPath &&
-      !isPathWithinDirectory(normalizedPath, normalizedCwd),
-  );
+  if (!normalizedCwd || !normalizedPath) {
+    return false;
+  }
+  if (isSafeSystemPath(normalizedPath)) {
+    return false;
+  }
+  return !isPathWithinDirectory(normalizedPath, normalizedCwd);
 }
 
 export function formatExternalDirectoryHardStopHint(): string {

package/tests/bash-external-directory.test.ts

@@ -223,6 +223,62 @@ describe("extractExternalPathsFromBashCommand", () => {
     });
   });
 
+  describe("safe system paths are filtered", () => {
+    test("does not flag /dev/null in stderr redirect", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "command 2>/dev/null",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("does not flag /dev/null as a redirect target", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "echo hello > /dev/null",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("does not flag /dev/stdin", () => {
+      const result = extractExternalPathsFromBashCommand("cat /dev/stdin", cwd);
+      expect(result).toHaveLength(0);
+    });
+
+    test("does not flag /dev/stdout", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "cat /dev/stdout",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("does not flag /dev/stderr", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "cat /dev/stderr",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("still flags a real external path alongside /dev/null", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "cat /etc/hosts 2>/dev/null",
+        cwd,
+      );
+      expect(result).toContain("/etc/hosts");
+      expect(result).not.toContain("/dev/null");
+    });
+
+    test("does not flag /dev/null/subdir (not a safe path)", () => {
+      const result = extractExternalPathsFromBashCommand(
+        "cat /dev/null/subdir",
+        cwd,
+      );
+      expect(result).toContain("/dev/null/subdir");
+    });
+  });
+
   describe("deduplication", () => {
     test("returns deduplicated paths", () => {
       const result = extractExternalPathsFromBashCommand(

package/tests/external-directory.test.ts

@@ -18,8 +18,10 @@ import {
   getPathBearingToolPath,
   isPathOutsideWorkingDirectory,
   isPathWithinDirectory,
+  isSafeSystemPath,
   normalizePathForComparison,
   PATH_BEARING_TOOLS,
+  SAFE_SYSTEM_PATHS,
 } from "../src/external-directory";
 
 afterEach(() => {
@@ -39,6 +41,49 @@ describe("PATH_BEARING_TOOLS", () => {
   });
 });
 
+describe("SAFE_SYSTEM_PATHS", () => {
+  test("contains /dev/null, /dev/stdin, /dev/stdout, /dev/stderr", () => {
+    expect(SAFE_SYSTEM_PATHS.has("/dev/null")).toBe(true);
+    expect(SAFE_SYSTEM_PATHS.has("/dev/stdin")).toBe(true);
+    expect(SAFE_SYSTEM_PATHS.has("/dev/stdout")).toBe(true);
+    expect(SAFE_SYSTEM_PATHS.has("/dev/stderr")).toBe(true);
+  });
+});
+
+describe("isSafeSystemPath", () => {
+  test("returns true for /dev/null", () => {
+    expect(isSafeSystemPath("/dev/null")).toBe(true);
+  });
+
+  test("returns true for /dev/stdin", () => {
+    expect(isSafeSystemPath("/dev/stdin")).toBe(true);
+  });
+
+  test("returns true for /dev/stdout", () => {
+    expect(isSafeSystemPath("/dev/stdout")).toBe(true);
+  });
+
+  test("returns true for /dev/stderr", () => {
+    expect(isSafeSystemPath("/dev/stderr")).toBe(true);
+  });
+
+  test("returns false for an arbitrary absolute path", () => {
+    expect(isSafeSystemPath("/etc/passwd")).toBe(false);
+  });
+
+  test("returns false for a path prefixed with a safe system path", () => {
+    expect(isSafeSystemPath("/dev/null/subdir")).toBe(false);
+  });
+
+  test("returns false for an empty string", () => {
+    expect(isSafeSystemPath("")).toBe(false);
+  });
+
+  test("returns false for a relative path", () => {
+    expect(isSafeSystemPath("dev/null")).toBe(false);
+  });
+});
+
 describe("normalizePathForComparison", () => {
   const cwd = "/projects/my-app";
 
@@ -163,6 +208,26 @@ describe("isPathOutsideWorkingDirectory", () => {
   test("returns false for empty path (normalizes to empty string)", () => {
     expect(isPathOutsideWorkingDirectory("", cwd)).toBe(false);
   });
+
+  test("returns false for /dev/null regardless of cwd", () => {
+    expect(isPathOutsideWorkingDirectory("/dev/null", cwd)).toBe(false);
+  });
+
+  test("returns false for /dev/stdin regardless of cwd", () => {
+    expect(isPathOutsideWorkingDirectory("/dev/stdin", cwd)).toBe(false);
+  });
+
+  test("returns false for /dev/stdout regardless of cwd", () => {
+    expect(isPathOutsideWorkingDirectory("/dev/stdout", cwd)).toBe(false);
+  });
+
+  test("returns false for /dev/stderr regardless of cwd", () => {
+    expect(isPathOutsideWorkingDirectory("/dev/stderr", cwd)).toBe(false);
+  });
+
+  test("returns true for /dev/null/subdir (not a safe path)", () => {
+    expect(isPathOutsideWorkingDirectory("/dev/null/subdir", cwd)).toBe(true);
+  });
 });
 
 describe("formatExternalDirectoryHardStopHint", () => {

package/index.ts

@@ -1,3 +0,0 @@
-import permissionSystemExtension from "./src/index";
-
-export default permissionSystemExtension;