@gotgenes/pi-permission-system 5.1.2 → 5.2.1

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.1](https://github.com/gotgenes/pi-permission-system/compare/v5.2.0...v5.2.1) (2026-05-05)
+
+
+### Documentation
+
+* document subagent extension coexistence ([#97](https://github.com/gotgenes/pi-permission-system/issues/97)) ([9bf2972](https://github.com/gotgenes/pi-permission-system/commit/9bf29726de98d44d7cfd8963f666be37fe807c9a))
+* plan subagent extension coexistence documentation ([#97](https://github.com/gotgenes/pi-permission-system/issues/97)) ([4cf975f](https://github.com/gotgenes/pi-permission-system/commit/4cf975f505081c5df46b20a2dd2d65e9a9a877f9))
+* **retro:** add retro notes for issue [#96](https://github.com/gotgenes/pi-permission-system/issues/96) ([8757ffc](https://github.com/gotgenes/pi-permission-system/commit/8757ffc3f186d137c65aea7abde9a383335584f8))
+
+## [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)
 
 

package/README.md

@@ -519,6 +519,63 @@ When a delegated or routed subagent runs without direct UI access, `ask` permiss
 
 This keeps `ask` policies usable even when the original permission check happens inside a non-UI execution context.
 
+### Coexistence with Subagent Extensions
+
+Several pi-subagent extensions implement their own tool restriction mechanisms.
+These compose correctly with the permission system because the two operate at different layers: **visibility** (subagent extension) and **policy** (permission system).
+
+#### The two-layer model
+
+```text
+┌─────────────────────────────────────────────────────┐
+│  Layer 1 – Visibility  (subagent extension)          │
+│  Controls which tools are registered / active        │
+│  before the agent session starts.                    │
+├─────────────────────────────────────────────────────┤
+│  Layer 2 – Policy  (pi-permission-system)            │
+│  Controls allow / ask / deny decisions on every      │
+│  tool call, bash command, MCP operation, etc.        │
+└─────────────────────────────────────────────────────┘
+```
+
+#### Known subagent extensions and their mechanisms
+
+|Extension|Mechanism|Frontmatter key|
+|----|----------|----------|
+|[nicobailon/pi-subagents](https://github.com/nicobailon/pi-subagents)|`--tools` CLI allowlist passed to subprocess|`tools:` (CSV allowlist)|
+|[tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents)|`session.setActiveToolsByName()` in-process filter|`disallowed_tools:` (CSV denylist)|
+|[HazAT/pi-interactive-subagents](https://github.com/HazAT/pi-interactive-subagents)|`PI_DENY_TOOLS` env var + `--tools` CLI allowlist|`deny-tools:` (CSV denylist), `spawning:` (bool)|
+
+#### Interaction rules
+
+1. **Hidden tool → permission system never sees it.**
+   If a subagent extension removes a tool from the active set, the permission system receives no registration or call event for that tool.
+   The permission policy for that tool is irrelevant — it is already gone.
+2. **Denied tool → hidden regardless of the subagent extension's allowlist.**
+   If the permission system denies a tool (via `deny` policy or tool filtering), it is removed from the active set before the agent starts.
+   A `tools:` allowlist in a subagent extension cannot restore a tool that the permission system has already hidden.
+3. **The two denylist mechanisms are additive, not conflicting.**
+   A tool blocked by either layer stays blocked.
+   Neither layer can silently re-enable what the other has blocked.
+
+#### `permission:` frontmatter is exclusive to this extension
+
+The `permission:` key in an agent's YAML frontmatter is read exclusively by `pi-permission-system`.
+It has no interaction with the `tools:`, `disallowed_tools:`, or `deny-tools:` keys consumed by subagent extensions.
+You can freely use both in the same agent file:
+
+```yaml
+---
+# Subagent extension: allow only bash and read_file in the subprocess
+tools: bash,read_file
+# pi-permission-system: still enforce ask on bash within those allowed tools
+permission:
+  bash: ask
+---
+```
+
+In this example the subagent extension restricts visibility to `bash` and `read_file`, and the permission system then gates every `bash` call with an `ask` prompt — both rules apply independently.
+
 ### Logging
 
 When the extension prompts, denies, or forwards permission requests, it can append structured JSONL entries under:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "5.1.2",
+  "version": "5.2.1",
   "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/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", () => {