@gotgenes/pi-permission-system 5.1.1 → 5.2.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.2.0](https://github.com/gotgenes/pi-permission-system/compare/v5.1.2...v5.2.0) (2026-05-05)
+
+
+### Features
+
+* add SUBAGENT_PARENT_SESSION_ENV_CANDIDATES, iterate in resolver ([#96](https://github.com/gotgenes/pi-permission-system/issues/96)) ([ac6831d](https://github.com/gotgenes/pi-permission-system/commit/ac6831d3418db0aee5d5ed4757d5833730a6e130))
+* broaden SUBAGENT_ENV_HINT_KEYS for nicobailon + HazAT extensions ([#96](https://github.com/gotgenes/pi-permission-system/issues/96)) ([8adafdb](https://github.com/gotgenes/pi-permission-system/commit/8adafdb45af66cf99b000b3ad011bee5a2c90476))
+
+
+### Documentation
+
+* plan broaden subagent env hint keys ([#96](https://github.com/gotgenes/pi-permission-system/issues/96)) ([9fa97b7](https://github.com/gotgenes/pi-permission-system/commit/9fa97b7385e5b9203a35c80d15f980ac4501f788))
+* update target-architecture subagent detection for [#96](https://github.com/gotgenes/pi-permission-system/issues/96) ([64cce35](https://github.com/gotgenes/pi-permission-system/commit/64cce3569c09cede690858af41d2f35611a8705f))
+
+## [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.2.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "files": [

package/src/forwarded-permissions/polling.ts

@@ -18,6 +18,7 @@ import {
   PERMISSION_FORWARDING_POLL_INTERVAL_MS,
   PERMISSION_FORWARDING_TIMEOUT_MS,
   resolvePermissionForwardingTargetSessionId,
+  SUBAGENT_PARENT_SESSION_ENV_CANDIDATES,
 } from "../permission-forwarding";
 import { isSubagentExecutionContext } from "../subagent-context";
 
@@ -110,7 +111,10 @@ export async function waitForForwardedPermissionApproval(
   if (!targetSessionId) {
     logPermissionForwardingError(
       deps.logger,
-      "Permission forwarding target session could not be resolved from subagent runtime metadata (expected PI_AGENT_ROUTER_PARENT_SESSION_ID)",
+      `Permission forwarding target session could not be resolved. ` +
+        `Checked env vars: ${SUBAGENT_PARENT_SESSION_ENV_CANDIDATES.join(", ")}. ` +
+        `If you are using nicobailon/pi-subagents or HazAT/pi-interactive-subagents, ` +
+        `parent-session forwarding is not yet supported for those extensions (see issue #98).`,
     );
     return { approved: false, state: "denied" };
   }

package/src/permission-forwarding.ts

@@ -5,12 +5,30 @@ import type { PermissionDecisionState } from "./permission-dialog";
 export const PERMISSION_FORWARDING_POLL_INTERVAL_MS = 250;
 export const PERMISSION_FORWARDING_TIMEOUT_MS = 10 * 60 * 1000;
 export const SUBAGENT_ENV_HINT_KEYS = [
+  // pi-agent-router (original)
   "PI_IS_SUBAGENT",
   "PI_SUBAGENT_SESSION_ID",
   "PI_AGENT_ROUTER_SUBAGENT",
+  // nicobailon/pi-subagents
+  "PI_SUBAGENT_CHILD",
+  "PI_SUBAGENT_RUN_ID",
+  "PI_SUBAGENT_CHILD_AGENT",
+  "PI_SUBAGENT_DEPTH",
+  // HazAT/pi-interactive-subagents
+  "PI_SUBAGENT_NAME",
+  "PI_SUBAGENT_ID",
+  "PI_SUBAGENT_SESSION",
+  "PI_SUBAGENT_ACTIVITY_FILE",
 ] as const;
+/** Ordered list of env var names to check for the parent session ID. First match wins. */
+export const SUBAGENT_PARENT_SESSION_ENV_CANDIDATES: readonly string[] = [
+  // pi-agent-router (original)
+  "PI_AGENT_ROUTER_PARENT_SESSION_ID",
+] as const;
+
+/** @deprecated Use SUBAGENT_PARENT_SESSION_ENV_CANDIDATES */
 export const SUBAGENT_PARENT_SESSION_ENV_KEY =
-  "PI_AGENT_ROUTER_PARENT_SESSION_ID";
+  SUBAGENT_PARENT_SESSION_ENV_CANDIDATES[0];
 
 const SESSION_FORWARDING_ROOT_DIRECTORY_NAME = "sessions";
 const SESSION_FORWARDING_REQUESTS_DIRECTORY_NAME = "requests";
@@ -106,9 +124,12 @@ export function resolvePermissionForwardingTargetSessionId(options: {
     return null;
   }
 
-  return normalizePermissionForwardingSessionId(
-    options.env?.[SUBAGENT_PARENT_SESSION_ENV_KEY],
-  );
+  const env = options.env ?? process.env;
+  for (const key of SUBAGENT_PARENT_SESSION_ENV_CANDIDATES) {
+    const resolved = normalizePermissionForwardingSessionId(env[key]);
+    if (resolved) return resolved;
+  }
+  return null;
 }
 
 export function isForwardedPermissionRequestForSession(

package/tests/permission-forwarding.test.ts

@@ -0,0 +1,143 @@
+import { afterEach, describe, expect, test, vi } from "vitest";
+import {
+  resolvePermissionForwardingTargetSessionId,
+  SUBAGENT_PARENT_SESSION_ENV_CANDIDATES,
+  SUBAGENT_PARENT_SESSION_ENV_KEY,
+} from "../src/permission-forwarding";
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe("SUBAGENT_PARENT_SESSION_ENV_CANDIDATES", () => {
+  test("is an array containing PI_AGENT_ROUTER_PARENT_SESSION_ID", () => {
+    expect(Array.isArray(SUBAGENT_PARENT_SESSION_ENV_CANDIDATES)).toBe(true);
+    expect(SUBAGENT_PARENT_SESSION_ENV_CANDIDATES).toContain(
+      "PI_AGENT_ROUTER_PARENT_SESSION_ID",
+    );
+  });
+
+  test("deprecated SUBAGENT_PARENT_SESSION_ENV_KEY equals the first candidate", () => {
+    expect(SUBAGENT_PARENT_SESSION_ENV_KEY).toBe(
+      SUBAGENT_PARENT_SESSION_ENV_CANDIDATES[0],
+    );
+  });
+});
+
+describe("resolvePermissionForwardingTargetSessionId", () => {
+  test("hasUI=true returns the current session ID (UI host owns forwarding)", () => {
+    expect(
+      resolvePermissionForwardingTargetSessionId({
+        hasUI: true,
+        isSubagent: false,
+        currentSessionId: "parent-session-abc",
+        env: {},
+      }),
+    ).toBe("parent-session-abc");
+  });
+
+  test("hasUI=true with isSubagent=true still returns current session ID", () => {
+    expect(
+      resolvePermissionForwardingTargetSessionId({
+        hasUI: true,
+        isSubagent: true,
+        currentSessionId: "session-xyz",
+        env: { PI_AGENT_ROUTER_PARENT_SESSION_ID: "other" },
+      }),
+    ).toBe("session-xyz");
+  });
+
+  test("hasUI=false, isSubagent=false returns null", () => {
+    expect(
+      resolvePermissionForwardingTargetSessionId({
+        hasUI: false,
+        isSubagent: false,
+        currentSessionId: "session-xyz",
+        env: { PI_AGENT_ROUTER_PARENT_SESSION_ID: "parent-session-abc" },
+      }),
+    ).toBeNull();
+  });
+
+  test("isSubagent=true, no candidates set returns null", () => {
+    expect(
+      resolvePermissionForwardingTargetSessionId({
+        hasUI: false,
+        isSubagent: true,
+        currentSessionId: "session-xyz",
+        env: {},
+      }),
+    ).toBeNull();
+  });
+
+  test("isSubagent=true, PI_AGENT_ROUTER_PARENT_SESSION_ID set returns its value", () => {
+    expect(
+      resolvePermissionForwardingTargetSessionId({
+        hasUI: false,
+        isSubagent: true,
+        currentSessionId: "session-xyz",
+        env: { PI_AGENT_ROUTER_PARENT_SESSION_ID: "parent-session-abc" },
+      }),
+    ).toBe("parent-session-abc");
+  });
+
+  test("isSubagent=true, first candidate absent but second set returns second value", () => {
+    // Inject a second candidate at test-time to validate the iteration logic
+    // without waiting for a real extension to adopt the convention.
+    const originalCandidates = [...SUBAGENT_PARENT_SESSION_ENV_CANDIDATES];
+    // Mutate the array via index-assignment through a cast so we can test
+    // multi-candidate iteration without changing the exported constant type.
+    // This is test-only; production code never mutates the array.
+    (SUBAGENT_PARENT_SESSION_ENV_CANDIDATES as unknown as string[]).push(
+      "PI_SUBAGENT_PARENT_SESSION_ID_TEST_ONLY",
+    );
+
+    try {
+      expect(
+        resolvePermissionForwardingTargetSessionId({
+          hasUI: false,
+          isSubagent: true,
+          currentSessionId: "session-xyz",
+          env: {
+            PI_SUBAGENT_PARENT_SESSION_ID_TEST_ONLY: "parent-from-second",
+          },
+        }),
+      ).toBe("parent-from-second");
+    } finally {
+      // Restore original array contents.
+      (SUBAGENT_PARENT_SESSION_ENV_CANDIDATES as unknown as string[]).length =
+        originalCandidates.length;
+    }
+  });
+
+  test("isSubagent=true, candidate value is empty string returns null", () => {
+    expect(
+      resolvePermissionForwardingTargetSessionId({
+        hasUI: false,
+        isSubagent: true,
+        currentSessionId: "session-xyz",
+        env: { PI_AGENT_ROUTER_PARENT_SESSION_ID: "" },
+      }),
+    ).toBeNull();
+  });
+
+  test("isSubagent=true, candidate value is 'unknown' returns null", () => {
+    expect(
+      resolvePermissionForwardingTargetSessionId({
+        hasUI: false,
+        isSubagent: true,
+        currentSessionId: "session-xyz",
+        env: { PI_AGENT_ROUTER_PARENT_SESSION_ID: "unknown" },
+      }),
+    ).toBeNull();
+  });
+
+  test("env defaults to process.env when omitted", () => {
+    vi.stubEnv("PI_AGENT_ROUTER_PARENT_SESSION_ID", "env-session-abc");
+    expect(
+      resolvePermissionForwardingTargetSessionId({
+        hasUI: false,
+        isSubagent: true,
+      }),
+    ).toBe("env-session-abc");
+  });
+});

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/subagent-context.test.ts

@@ -61,11 +61,86 @@ describe("isSubagentExecutionContext — env hint detection", () => {
     ).toBe(true);
   });
 
-  test("covers all three declared SUBAGENT_ENV_HINT_KEYS", () => {
+  // nicobailon/pi-subagents keys
+  test("returns true when PI_SUBAGENT_CHILD is set", () => {
+    vi.stubEnv("PI_SUBAGENT_CHILD", "1");
+    expect(
+      isSubagentExecutionContext(makeCtx(null), "/sessions/subagents"),
+    ).toBe(true);
+  });
+
+  test("returns true when PI_SUBAGENT_RUN_ID is set", () => {
+    vi.stubEnv("PI_SUBAGENT_RUN_ID", "run-abc");
+    expect(
+      isSubagentExecutionContext(makeCtx(null), "/sessions/subagents"),
+    ).toBe(true);
+  });
+
+  test("returns true when PI_SUBAGENT_CHILD_AGENT is set", () => {
+    vi.stubEnv("PI_SUBAGENT_CHILD_AGENT", "worker");
+    expect(
+      isSubagentExecutionContext(makeCtx(null), "/sessions/subagents"),
+    ).toBe(true);
+  });
+
+  test("returns true when PI_SUBAGENT_DEPTH is set", () => {
+    vi.stubEnv("PI_SUBAGENT_DEPTH", "1");
+    expect(
+      isSubagentExecutionContext(makeCtx(null), "/sessions/subagents"),
+    ).toBe(true);
+  });
+
+  test("returns true when PI_SUBAGENT_DEPTH is zero (depth-0 is still a subagent context)", () => {
+    vi.stubEnv("PI_SUBAGENT_DEPTH", "0");
+    expect(
+      isSubagentExecutionContext(makeCtx(null), "/sessions/subagents"),
+    ).toBe(true);
+  });
+
+  // HazAT/pi-interactive-subagents keys
+  test("returns true when PI_SUBAGENT_NAME is set", () => {
+    vi.stubEnv("PI_SUBAGENT_NAME", "my-agent");
+    expect(
+      isSubagentExecutionContext(makeCtx(null), "/sessions/subagents"),
+    ).toBe(true);
+  });
+
+  test("returns true when PI_SUBAGENT_ID is set", () => {
+    vi.stubEnv("PI_SUBAGENT_ID", "id-xyz");
+    expect(
+      isSubagentExecutionContext(makeCtx(null), "/sessions/subagents"),
+    ).toBe(true);
+  });
+
+  test("returns true when PI_SUBAGENT_SESSION is set", () => {
+    vi.stubEnv("PI_SUBAGENT_SESSION", "session-xyz");
+    expect(
+      isSubagentExecutionContext(makeCtx(null), "/sessions/subagents"),
+    ).toBe(true);
+  });
+
+  test("returns true when PI_SUBAGENT_ACTIVITY_FILE is set", () => {
+    vi.stubEnv("PI_SUBAGENT_ACTIVITY_FILE", "/tmp/activity.json");
+    expect(
+      isSubagentExecutionContext(makeCtx(null), "/sessions/subagents"),
+    ).toBe(true);
+  });
+
+  test("covers all declared SUBAGENT_ENV_HINT_KEYS", () => {
     // Verify the keys we test match what the module declares.
     expect(SUBAGENT_ENV_HINT_KEYS).toContain("PI_IS_SUBAGENT");
     expect(SUBAGENT_ENV_HINT_KEYS).toContain("PI_SUBAGENT_SESSION_ID");
     expect(SUBAGENT_ENV_HINT_KEYS).toContain("PI_AGENT_ROUTER_SUBAGENT");
+    // nicobailon/pi-subagents
+    expect(SUBAGENT_ENV_HINT_KEYS).toContain("PI_SUBAGENT_CHILD");
+    expect(SUBAGENT_ENV_HINT_KEYS).toContain("PI_SUBAGENT_RUN_ID");
+    expect(SUBAGENT_ENV_HINT_KEYS).toContain("PI_SUBAGENT_CHILD_AGENT");
+    expect(SUBAGENT_ENV_HINT_KEYS).toContain("PI_SUBAGENT_DEPTH");
+    // HazAT/pi-interactive-subagents
+    expect(SUBAGENT_ENV_HINT_KEYS).toContain("PI_SUBAGENT_NAME");
+    expect(SUBAGENT_ENV_HINT_KEYS).toContain("PI_SUBAGENT_ID");
+    expect(SUBAGENT_ENV_HINT_KEYS).toContain("PI_SUBAGENT_SESSION");
+    expect(SUBAGENT_ENV_HINT_KEYS).toContain("PI_SUBAGENT_ACTIVITY_FILE");
   });
 
   test("returns false when env hint value is empty string", () => {