@gotgenes/pi-permission-system 5.1.2 → 5.2.0

package/CHANGELOG.md

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

package/package.json

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