@gotgenes/pi-permission-system 5.1.0 → 5.1.2

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.1.2](https://github.com/gotgenes/pi-permission-system/compare/v5.1.1...v5.1.2) (2026-05-05)
+
+
+### Documentation
+
+* fix README per-agent frontmatter example to flat format ([#78](https://github.com/gotgenes/pi-permission-system/issues/78)) ([1295427](https://github.com/gotgenes/pi-permission-system/commit/129542795218a6ada1f8d069a22b5ace5ec6c445))
+* plan fix README frontmatter example and add missing tests ([#78](https://github.com/gotgenes/pi-permission-system/issues/78)) ([3fc99e1](https://github.com/gotgenes/pi-permission-system/commit/3fc99e1b3adf8193c94ac778617ca830488fa621))
+* **retro:** add retro notes for issue [#93](https://github.com/gotgenes/pi-permission-system/issues/93) ([c9e8e89](https://github.com/gotgenes/pi-permission-system/commit/c9e8e89eb4057866198402add374d72a90a2fa2e))
+
+## [5.1.1](https://github.com/gotgenes/pi-permission-system/compare/v5.1.0...v5.1.1) (2026-05-05)
+
+
+### Bug Fixes
+
+* discover global node_modules root from dev checkout via npm root -g fallback ([93aac81](https://github.com/gotgenes/pi-permission-system/commit/93aac81bd830ec260d2156b34ca8074f6c533255))
+
+
+### Documentation
+
+* note npm root -g fallback for dev checkout infrastructure reads ([d06caf7](https://github.com/gotgenes/pi-permission-system/commit/d06caf73371c7ea73f1c56a5efb86b2023292dd3))
+* plan createRequire fallback for dev checkout infra read bypass ([#93](https://github.com/gotgenes/pi-permission-system/issues/93)) ([7750044](https://github.com/gotgenes/pi-permission-system/commit/775004477efff0d3cd2eb5ba7a0fcbdd98f3d122))
+* plan npm root -g fallback for dev checkout infra read bypass ([#93](https://github.com/gotgenes/pi-permission-system/issues/93)) ([85e697c](https://github.com/gotgenes/pi-permission-system/commit/85e697c5062a36fd150bd4d6b377ca906b3a1dbf))
+* **retro:** add retro notes for issue [#91](https://github.com/gotgenes/pi-permission-system/issues/91) ([d2d1263](https://github.com/gotgenes/pi-permission-system/commit/d2d1263955741053b2cf8718830d88043b9cdd8e))
+
 ## [5.1.0](https://github.com/gotgenes/pi-permission-system/compare/v5.0.0...v5.1.0) (2026-05-05)
 
 

package/README.md

@@ -170,22 +170,21 @@ Override global permissions for specific agents via YAML frontmatter in the glob
 ---
 name: my-agent
 permission:
-  tools:
-    read: allow
-    write: deny
-    mcp: allow
+  read: allow
+  write: deny
+  mcp: allow
   bash:
     git status: allow
     git *: ask
   mcp:
     chrome_devtools_*: deny
     exa_*: allow
-  skills:
+  skill:
     "*": ask
 ---
 ```
 
-**MCP behavior:** `permission.tools.mcp` is the coarse entry/fallback permission for a registered `mcp` tool when one is available. More specific `permission.mcp` target rules override that fallback when they match.
+**MCP behavior:** `permission.mcp` is the coarse entry/fallback permission for a registered `mcp` tool when one is available. More specific `permission.mcp` target rules override that fallback when they match.
 
 **Limitations:** The frontmatter parser is intentionally minimal. Use only `key: value` scalars and nested maps. Avoid arrays, multi-line scalars, and YAML anchors.
 
@@ -379,7 +378,7 @@ Infrastructure directories include:
 
 1. The agent config directory (`~/.pi/agent/` or `$PI_CODING_AGENT_DIR`)
 2. Git-cloned global packages (`<agentDir>/git/`)
-3. The global `node_modules` root (auto-discovered from the extension's own install path — works for npm, pnpm, bun, Homebrew)
+3. The global `node_modules` root (auto-discovered from the extension's own install path; falls back to `npm root -g` when running from a local development checkout)
 4. Project-local Pi packages (`<cwd>/.pi/npm/` and `<cwd>/.pi/git/`)
 5. Any paths listed in `piInfrastructureReadPaths`
 

package/package.json

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

package/schemas/permissions.schema.json

@@ -31,7 +31,7 @@
     },
     "piInfrastructureReadPaths": {
       "description": "Additional directories to auto-allow for reads as Pi infrastructure, bypassing the external_directory gate. Supports ~ expansion. Directory prefixes only (no globs).",
-      "markdownDescription": "Additional directories to auto-allow for reads as Pi infrastructure, bypassing the `external_directory` gate.\n\nThe extension auto-discovers the global node_modules root, `agentDir`, `agentDir/git`, and project-local `.pi/npm/` and `.pi/git/`. Add entries here for edge cases where auto-discovery is insufficient.\n\nSupports `~` expansion. Directory prefixes only — no glob patterns.",
+      "markdownDescription": "Additional directories to auto-allow for reads as Pi infrastructure, bypassing the `external_directory` gate.\n\nThe extension auto-discovers the global node_modules root (walks up from the extension's install path; falls back to `npm root -g` from a dev checkout), `agentDir`, `agentDir/git`, and project-local `.pi/npm/` and `.pi/git/`. Add entries here for edge cases where auto-discovery is insufficient (e.g. custom `npmCommand` pointing to pnpm).\n\nSupports `~` expansion. Directory prefixes only — no glob patterns.",
       "type": "array",
       "items": {
         "type": "string",

package/src/external-directory.ts

@@ -1,3 +1,5 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { basename, dirname, join, normalize, resolve, sep } from "node:path";
@@ -6,21 +8,16 @@ import { fileURLToPath } from "node:url";
 import { getNonEmptyString, toRecord } from "./common";
 
 /**
- * Discover the global node_modules root by walking up from the given file URL
- * (defaults to this module's own `import.meta.url`).
+ * Walk up the directory tree from the given file URL until a directory
+ * literally named `node_modules` is found.
  *
- * Works regardless of package manager (npm, pnpm, bun, Homebrew) because the
- * extension itself is installed inside the directory we want to find.
- * Returns `null` when the file is not inside any node_modules tree, or when
- * the URL cannot be parsed — callers must degrade gracefully.
+ * Returns the `node_modules` path, or `null` if the URL cannot be parsed or
+ * no `node_modules` ancestor exists.
  */
-export function discoverGlobalNodeModulesRoot(
-  fromUrl = import.meta.url,
-): string | null {
+function walkUpToNodeModules(fromUrl: string): string | null {
   try {
     const thisFile = fileURLToPath(fromUrl);
     let dir = dirname(thisFile);
-    // Walk up until we find a directory named "node_modules" or hit the root.
     while (dir !== dirname(dir)) {
       if (basename(dir) === "node_modules") {
         return dir;
@@ -33,6 +30,55 @@ export function discoverGlobalNodeModulesRoot(
   }
 }
 
+/**
+ * Run `npm root -g` synchronously and return the trimmed output, or `null` on
+ * any failure (non-zero exit, ENOENT, timeout, non-existent path).
+ *
+ * Only called when the walk-up-from-self strategy fails (i.e. the extension is
+ * running from a local development checkout, not a global install).
+ */
+function discoverGlobalNodeModulesViaSubprocess(): string | null {
+  try {
+    const result = spawnSync("npm", ["root", "-g"], {
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const root = result.stdout?.trim();
+    if (result.status === 0 && root && existsSync(root)) {
+      return root;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Discover the global node_modules root.
+ *
+ * Strategy 1 (zero-cost, covers all global installs): walk up from
+ * `fromUrl` (defaults to this module's own `import.meta.url`) looking for a
+ * directory named `node_modules`. This works whenever the extension is
+ * installed inside a `node_modules` tree.
+ *
+ * Strategy 2 (subprocess fallback, dev checkout only): when Strategy 1 fails
+ * because the extension is running from a local development checkout with no
+ * `node_modules` ancestor, run `npm root -g` to discover the global root.
+ * Pi installs skills and extensions via `npm` by default, so `npm root -g`
+ * returns the correct root regardless of the user's own project package
+ * manager.
+ *
+ * Returns `null` when both strategies fail — callers must degrade gracefully.
+ */
+export function discoverGlobalNodeModulesRoot(
+  fromUrl = import.meta.url,
+): string | null {
+  const fromSelf = walkUpToNodeModules(fromUrl);
+  if (fromSelf) return fromSelf;
+  return discoverGlobalNodeModulesViaSubprocess();
+}
+
 /**
  * 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.

package/tests/external-directory.test.ts

@@ -1,5 +1,23 @@
 import { join } from "node:path";
-import { afterEach, describe, expect, test, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+
+// Hoisted stubs for mocks that reference them in vi.mock factories.
+const { mockSpawnSync, mockExistsSync } = vi.hoisted(() => ({
+  mockSpawnSync: vi.fn(),
+  mockExistsSync: vi.fn(),
+}));
+
+// Mock node:child_process so tests don't spawn real subprocesses.
+vi.mock("node:child_process", () => ({
+  spawnSync: mockSpawnSync,
+  default: { spawnSync: mockSpawnSync },
+}));
+
+// Mock node:fs so existsSync is controllable.
+vi.mock("node:fs", () => ({
+  existsSync: mockExistsSync,
+  default: { existsSync: mockExistsSync },
+}));
 
 // Mock node:os so tilde-expansion is deterministic across platforms.
 vi.mock("node:os", () => {
@@ -11,6 +29,7 @@ vi.mock("node:os", () => {
 });
 
 import {
+  discoverGlobalNodeModulesRoot,
   formatExternalDirectoryAskPrompt,
   formatExternalDirectoryDenyReason,
   formatExternalDirectoryHardStopHint,
@@ -317,3 +336,90 @@ describe("formatExternalDirectoryUserDeniedReason", () => {
     expect(result).not.toContain("Reason:");
   });
 });
+
+describe("discoverGlobalNodeModulesRoot", () => {
+  // The walk-up-from-self strategy uses import.meta.url which resolves to a
+  // path inside the source tree during tests — there is no node_modules
+  // ancestor. So the fallback path is exercised naturally here.
+  //
+  // For the "walk-up succeeds" case, we verify the subprocess is NOT called
+  // by confirming spawnSync call count stays at zero when the URL has a
+  // node_modules ancestor.
+
+  beforeEach(() => {
+    mockSpawnSync.mockReset();
+    mockExistsSync.mockReset();
+  });
+
+  test("returns node_modules root when URL is inside a node_modules tree", () => {
+    // Simulate a URL whose file path contains a node_modules ancestor.
+    const fakeUrl =
+      "file:///opt/homebrew/lib/node_modules/@gotgenes/pi-permission-system/dist/external-directory.js";
+    const result = discoverGlobalNodeModulesRoot(fakeUrl);
+    expect(result).toBe("/opt/homebrew/lib/node_modules");
+    // Subprocess should NOT have been invoked — walk-up succeeds.
+    expect(mockSpawnSync).not.toHaveBeenCalled();
+  });
+
+  test("calls npm root -g as fallback when walk-up finds no node_modules ancestor", () => {
+    const npmRootPath = "/opt/homebrew/lib/node_modules";
+    mockSpawnSync.mockReturnValue({
+      status: 0,
+      stdout: `${npmRootPath}\n`,
+    });
+    mockExistsSync.mockReturnValue(true);
+
+    // Use a file URL with no node_modules ancestor.
+    const fakeUrl = "file:///Users/dev/my-project/src/external-directory.ts";
+    const result = discoverGlobalNodeModulesRoot(fakeUrl);
+
+    expect(mockSpawnSync).toHaveBeenCalledWith(
+      "npm",
+      ["root", "-g"],
+      expect.objectContaining({ encoding: "utf-8" }),
+    );
+    expect(result).toBe(npmRootPath);
+  });
+
+  test("returns null when walk-up fails and npm root -g returns non-zero exit", () => {
+    mockSpawnSync.mockReturnValue({ status: 1, stdout: "" });
+
+    const fakeUrl = "file:///Users/dev/my-project/src/external-directory.ts";
+    const result = discoverGlobalNodeModulesRoot(fakeUrl);
+
+    expect(result).toBeNull();
+  });
+
+  test("returns null when walk-up fails and spawnSync throws", () => {
+    mockSpawnSync.mockImplementation(() => {
+      throw new Error("ENOENT");
+    });
+
+    const fakeUrl = "file:///Users/dev/my-project/src/external-directory.ts";
+    const result = discoverGlobalNodeModulesRoot(fakeUrl);
+
+    expect(result).toBeNull();
+  });
+
+  test("returns null when walk-up fails and npm root -g returns non-existent path", () => {
+    mockSpawnSync.mockReturnValue({
+      status: 0,
+      stdout: "/some/nonexistent/node_modules\n",
+    });
+    mockExistsSync.mockReturnValue(false);
+
+    const fakeUrl = "file:///Users/dev/my-project/src/external-directory.ts";
+    const result = discoverGlobalNodeModulesRoot(fakeUrl);
+
+    expect(result).toBeNull();
+  });
+
+  test("returns null when walk-up fails and npm root -g returns empty stdout", () => {
+    mockSpawnSync.mockReturnValue({ status: 0, stdout: "   " });
+
+    const fakeUrl = "file:///Users/dev/my-project/src/external-directory.ts";
+    const result = discoverGlobalNodeModulesRoot(fakeUrl);
+
+    expect(result).toBeNull();
+  });
+});

package/tests/permission-system.test.ts

@@ -7,7 +7,7 @@ import {
   rmSync,
   writeFileSync,
 } from "node:fs";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { test } from "vitest";
 
@@ -1831,6 +1831,188 @@ test("external_directory permission is not affected by unrelated surface keys",
   }
 });
 
+test("skill pattern map in agent frontmatter overrides global skill policy", () => {
+  const { manager, cleanup } = createManager(
+    {
+      permission: { "*": "deny", skill: "deny" },
+    },
+    {
+      reviewer: `---
+name: reviewer
+permission:
+  skill:
+    "*": ask
+    "pi-*": allow
+---
+`,
+    },
+  );
+
+  try {
+    // Matches agent frontmatter pi-* pattern
+    const allowed = manager.checkPermission(
+      "skill",
+      { name: "pi-code-review" },
+      "reviewer",
+    );
+    assert.equal(allowed.state, "allow");
+    assert.equal(allowed.matchedPattern, "pi-*");
+    assert.equal(allowed.source, "skill");
+
+    // Falls through to agent frontmatter catch-all
+    const asked = manager.checkPermission(
+      "skill",
+      { name: "other-skill" },
+      "reviewer",
+    );
+    assert.equal(asked.state, "ask");
+    assert.equal(asked.matchedPattern, "*");
+
+    // No agent override — global deny applies
+    const denied = manager.checkPermission("skill", { name: "pi-code-review" });
+    assert.equal(denied.state, "deny");
+    assert.equal(denied.source, "skill");
+  } finally {
+    cleanup();
+  }
+});
+
+test("external_directory pattern map in agent frontmatter overrides global policy", () => {
+  const { manager, cleanup } = createManager(
+    {
+      permission: { "*": "allow", external_directory: "deny" },
+    },
+    {
+      trusted: `---
+name: trusted
+permission:
+  external_directory:
+    "*": deny
+    "~/Downloads/*": allow
+---
+`,
+    },
+  );
+
+  try {
+    // Matches agent frontmatter ~/Downloads/* pattern
+    const allowed = manager.checkPermission(
+      "external_directory",
+      { path: `${homedir()}/Downloads/file.txt` },
+      "trusted",
+    );
+    assert.equal(allowed.state, "allow");
+    assert.equal(allowed.matchedPattern, "~/Downloads/*");
+    assert.equal(allowed.source, "special");
+
+    // Falls through to agent frontmatter catch-all deny
+    const denied = manager.checkPermission(
+      "external_directory",
+      { path: `${homedir()}/Documents/secret.txt` },
+      "trusted",
+    );
+    assert.equal(denied.state, "deny");
+    assert.equal(denied.matchedPattern, "*");
+
+    // No agent override — global deny applies
+    const globalDenied = manager.checkPermission("external_directory", {});
+    assert.equal(globalDenied.state, "deny");
+    assert.equal(globalDenied.source, "special");
+  } finally {
+    cleanup();
+  }
+});
+
+test("project-agent frontmatter skill rules override global-agent frontmatter skill rules", () => {
+  const { manager, cleanup } = createManagerWithProject(
+    {
+      permission: { "*": "deny" },
+    },
+    {
+      analyst: `---
+name: analyst
+permission:
+  skill:
+    "*": ask
+---
+`,
+    },
+    {
+      projectAgentFiles: {
+        analyst: `---
+name: analyst
+permission:
+  skill:
+    "pi-*": allow
+    "*": deny
+---
+`,
+      },
+    },
+  );
+
+  try {
+    // Project-agent pi-* wins over global-agent *: ask
+    const allowed = manager.checkPermission(
+      "skill",
+      { name: "pi-code-review" },
+      "analyst",
+    );
+    assert.equal(allowed.state, "allow");
+    assert.equal(allowed.matchedPattern, "pi-*");
+
+    // Project-agent *: deny wins over global-agent *: ask
+    const denied = manager.checkPermission(
+      "skill",
+      { name: "other-skill" },
+      "analyst",
+    );
+    assert.equal(denied.state, "deny");
+    assert.equal(denied.matchedPattern, "*");
+  } finally {
+    cleanup();
+  }
+});
+
+test("project-agent frontmatter external_directory rules override global-agent frontmatter rules", () => {
+  const { manager, cleanup } = createManagerWithProject(
+    {
+      permission: { "*": "allow", external_directory: "deny" },
+    },
+    {
+      analyst: `---
+name: analyst
+permission:
+  external_directory: ask
+---
+`,
+    },
+    {
+      projectAgentFiles: {
+        analyst: `---
+name: analyst
+permission:
+  external_directory: allow
+---
+`,
+      },
+    },
+  );
+
+  try {
+    // Project-agent allow wins over global-agent ask
+    const result = manager.checkPermission("external_directory", {}, "analyst");
+    assert.equal(result.state, "allow");
+    assert.equal(result.source, "special");
+
+    // Without agent context, global config deny applies
+    const globalResult = manager.checkPermission("external_directory", {});
+    assert.equal(globalResult.state, "deny");
+  } finally {
+    cleanup();
+  }
+});
+
 test("tool_call blocks path-bearing tools outside cwd when external_directory is denied", async () => {
   const rootDir = mkdtempSync(join(tmpdir(), "pi-permission-system-boundary-"));
   const cwd = join(rootDir, "repo");

package/tests/pi-infrastructure-read.test.ts

@@ -1,5 +1,18 @@
 import { join } from "node:path";
-import { describe, expect, test } from "vitest";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+// Hoisted stub so the vi.mock factory can reference it.
+const { mockSpawnSync } = vi.hoisted(() => ({
+  mockSpawnSync: vi.fn(),
+}));
+
+// Mock node:child_process so tests that exercise the subprocess fallback path
+// don't actually invoke npm.  Default: subprocess fails (non-zero exit), so
+// tests focused on the walk-up strategy continue to expect null.
+vi.mock("node:child_process", () => ({
+  spawnSync: mockSpawnSync,
+  default: { spawnSync: mockSpawnSync },
+}));
 
 import {
   discoverGlobalNodeModulesRoot,
@@ -9,6 +22,13 @@ import {
 // ── discoverGlobalNodeModulesRoot ──────────────────────────────────────────
 
 describe("discoverGlobalNodeModulesRoot", () => {
+  beforeEach(() => {
+    // Default: subprocess fails, so walk-up-focused tests see null for URLs
+    // with no node_modules ancestor.
+    mockSpawnSync.mockReset();
+    mockSpawnSync.mockReturnValue({ status: 1, stdout: "" });
+  });
+
   test("returns the node_modules dir when the file is inside one", () => {
     const url =
       "file:///opt/homebrew/lib/node_modules/pi-permission-system/dist/external-directory.js";