@gotgenes/pi-permission-system 5.1.1 → 5.1.2

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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)
 
 

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.
 

package/package.json

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

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");