@gotgenes/pi-permission-system 7.4.0 → 8.0.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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).
 
+## [8.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v7.4.1...pi-permission-system-v8.0.0) (2026-05-30)
+
+
+### ⚠ BREAKING CHANGES
+
+* `registerSubagentSession` and `unregisterSubagentSession` are removed from the `PermissionsService` interface and its implementation. The `SubagentSessionInfo` type is no longer re-exported from the public service module.
+
+### Features
+
+* remove inbound subagent-registration methods from PermissionsService ([#267](https://github.com/gotgenes/pi-packages/issues/267)) ([552735a](https://github.com/gotgenes/pi-packages/commit/552735a97eec939fc06130bce059c78f03eb8e58))
+
+
+### Documentation
+
+* **pi-permission-system:** describe event-driven subagent registration ([#267](https://github.com/gotgenes/pi-packages/issues/267)) ([8c39b87](https://github.com/gotgenes/pi-packages/commit/8c39b8785aa389d96b5f38996711d8aa3dbeb284))
+
+## [7.4.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v7.4.0...pi-permission-system-v7.4.1) (2026-05-30)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** resolve bash paths against leading cd target ([c655a7e](https://github.com/gotgenes/pi-packages/commit/c655a7e737aeac9a8f10909804260c65d339c8b7))
+
+
+### Documentation
+
+* **pi-permission-system:** document cd-aware bash path resolution ([a2e6541](https://github.com/gotgenes/pi-packages/commit/a2e65410e89eb1e62579078c16af05aead013603))
+
 ## [7.4.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v7.3.3...pi-permission-system-v7.4.0) (2026-05-29)
 
 

package/package.json

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

package/src/handlers/gates/bash-path-extractor.ts

@@ -1,8 +1,9 @@
 import { createRequire } from "node:module";
-import { basename } from "node:path";
+import { basename, resolve } from "node:path";
 
 import {
-  isPathOutsideWorkingDirectory,
+  isPathWithinDirectory,
+  isSafeSystemPath,
   normalizePathForComparison,
 } from "#src/path-utils";
 
@@ -501,11 +502,90 @@ function classifyTokenAsPathCandidate(token: string): string | null {
   return null;
 }
 
+// ── Leading cd detection ───────────────────────────────────────────────────
+
+/**
+ * Walk down from the root to find the first `command` node in the program.
+ *
+ * Only descends into `program` and `list` nodes — subshells, pipelines, and
+ * other compound statements are ignored because a `cd` inside them does not
+ * affect the outer shell's working directory.
+ */
+function findFirstCommand(node: TSNode): TSNode | null {
+  if (node.type === "command") return node;
+  if (node.type === "program" || node.type === "list") {
+    const firstChild = node.child(0);
+    if (firstChild) return findFirstCommand(firstChild);
+  }
+  return null;
+}
+
+/**
+ * Extract the target directory of a leading `cd` command from the parsed AST.
+ *
+ * When a bash command begins with `cd <dir> && …`, the shell resolves
+ * subsequent relative paths against `<dir>`, not the original working
+ * directory.  The external-directory guard must do the same, otherwise a
+ * path that the shell keeps inside the working directory can appear to
+ * escape it and trigger a spurious permission prompt.
+ *
+ * Returns `undefined` when the first command is not `cd`, or when the
+ * target cannot be meaningfully resolved (`cd -`, bare `cd`, or `cd ~…`).
+ */
+function extractLeadingCdTarget(rootNode: TSNode): string | undefined {
+  const firstCmd = findFirstCommand(rootNode);
+  if (!firstCmd) return undefined;
+
+  const cmdName = extractCommandName(firstCmd);
+  if (cmdName !== "cd") return undefined;
+
+  for (let i = 0; i < firstCmd.childCount; i++) {
+    const child = firstCmd.child(i);
+    if (!child) continue;
+    if (child.type === "command_name" || child.type === "variable_assignment")
+      continue;
+    if (!ARG_NODE_TYPES.has(child.type)) continue;
+
+    const text = resolveNodeText(child);
+    // Skip `--` (end-of-flags marker)
+    if (text === "--") continue;
+    // `cd -` jumps to $OLDPWD; `cd ~…` is home-relative — neither can be
+    // resolved against the working directory.
+    if (text === "-" || text.startsWith("~")) return undefined;
+    return text;
+  }
+  return undefined;
+}
+
+/**
+ * Compute the effective base directory for resolving relative path candidates.
+ *
+ * When the leading `cd` target stays within the working directory, subsequent
+ * relative paths should be resolved against it.  An escaping target is itself
+ * an external access (reported via its own candidate token) and must never
+ * silence checks on subsequent paths, so the function falls back to `cwd`.
+ */
+function computeEffectiveResolveBase(
+  cdTarget: string | undefined,
+  cwd: string,
+): string {
+  if (cdTarget === undefined) return cwd;
+  const resolved = resolve(cwd, cdTarget);
+  const normalizedCwd = resolve(cwd);
+  return isPathWithinDirectory(resolved, normalizedCwd) ? resolved : cwd;
+}
+
+// ── Public extractors ──────────────────────────────────────────────────────
+
 /**
  * Extracts paths from a bash command string that resolve outside CWD.
  * Uses tree-sitter-bash to parse the command into a full AST, then walks
  * command argument and redirect-destination nodes.  Heredoc bodies, comments,
  * and other non-argument content are skipped, eliminating false positives.
+ *
+ * When the command begins with `cd <dir> && …`, relative candidate paths are
+ * resolved against `<dir>` (if it stays within CWD) rather than CWD itself,
+ * mirroring how the shell would resolve them.
  */
 export async function extractExternalPathsFromBashCommand(
   command: string,
@@ -515,13 +595,18 @@ export async function extractExternalPathsFromBashCommand(
   const tree = parser.parse(command);
   if (!tree) return [];
 
+  let cdTarget: string | undefined;
   const tokens: string[] = [];
   try {
+    cdTarget = extractLeadingCdTarget(tree.rootNode);
     collectPathCandidateTokens(tree.rootNode, tokens);
   } finally {
     tree.delete();
   }
 
+  const resolveBase = computeEffectiveResolveBase(cdTarget, cwd);
+  const normalizedCwd = normalizePathForComparison(cwd, cwd);
+
   const seen = new Set<string>();
   const externalPaths: string[] = [];
 
@@ -529,11 +614,13 @@ export async function extractExternalPathsFromBashCommand(
     const candidate = classifyTokenAsPathCandidate(token);
     if (!candidate) continue;
 
-    const normalized = normalizePathForComparison(candidate, cwd);
+    const normalized = normalizePathForComparison(candidate, resolveBase);
     if (!normalized) continue;
 
     if (
-      isPathOutsideWorkingDirectory(candidate, cwd) &&
+      normalizedCwd !== "" &&
+      !isSafeSystemPath(normalized) &&
+      !isPathWithinDirectory(normalized, normalizedCwd) &&
       !seen.has(normalized)
     ) {
       seen.add(normalized);

package/src/index.ts

@@ -118,12 +118,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
         sessionRules,
       );
     },
-    registerSubagentSession(sessionKey, info) {
-      subagentRegistry.register(sessionKey, info);
-    },
-    unregisterSubagentSession(sessionKey) {
-      subagentRegistry.unregister(sessionKey);
-    },
     getToolPermission(toolName, agentName) {
       return runtime.permissionManager.getToolPermission(toolName, agentName);
     },

package/src/service.ts

@@ -11,10 +11,9 @@
  * reference — this ensures resilience across `/reload` and load-order edge cases.
  */
 
-import type { SubagentSessionInfo } from "./subagent-registry";
 import type { PermissionCheckResult, PermissionState } from "./types";
 
-export type { PermissionCheckResult, PermissionState, SubagentSessionInfo };
+export type { PermissionCheckResult, PermissionState };
 
 /** Process-global key for the service slot. */
 const SERVICE_KEY = Symbol.for("@gotgenes/pi-permission-system:service");
@@ -44,27 +43,6 @@ export interface PermissionsService {
     agentName?: string,
   ): PermissionCheckResult;
 
-  /**
-   * Register an in-process subagent session.
-   *
-   * Call this before `bindExtensions()` so that `isSubagentExecutionContext()`
-   * and permission-forwarding target resolution can detect the child session.
-   * Always pair with `unregisterSubagentSession()` in a `finally` block.
-   *
-   * @param sessionKey - Unique session identifier (use the session directory path).
-   * @param info       - Agent name and optional parent session ID.
-   */
-  registerSubagentSession(sessionKey: string, info: SubagentSessionInfo): void;
-
-  /**
-   * Remove a previously registered in-process subagent session.
-   *
-   * Safe to call even if `registerSubagentSession` was never called for this key.
-   *
-   * @param sessionKey - The same key passed to `registerSubagentSession`.
-   */
-  unregisterSubagentSession(sessionKey: string): void;
-
   /**
    * Query the tool-level permission state for pre-filtering tools before
    * creating a child session.

package/src/subagent-registry.ts

@@ -23,9 +23,9 @@ export interface SubagentSessionInfo {
 /**
  * Registry of active in-process subagent sessions.
  *
- * Owned by `ExtensionRuntime`; exposed to external callers through the
- * `PermissionsService` interface (`registerSubagentSession` /
- * `unregisterSubagentSession`).
+ * Owned by `ExtensionRuntime`; written exclusively by `subscribeSubagentLifecycle`
+ * via the `subagents:child:session-created` / `subagents:child:disposed` event
+ * subscription (ADR 0002 — the core publishes, consumers observe).
  *
  * Concurrent background agents are safe because each session has a unique
  * directory path as its key — no scalar global flag is needed.

package/test/bash-external-directory.test.ts

@@ -822,6 +822,82 @@ describe("extractExternalPathsFromBashCommand", () => {
       expect(result).toContain("/etc/hosts");
     });
   });
+
+  describe("leading cd prefix", () => {
+    test("regression: cd to subdir with relative path traversing back into cwd is not flagged", async () => {
+      // Real-world command that triggered a false-positive external-directory
+      // prompt. The relative path .pi/../../../.pi/skills/... resolves inside
+      // cwd when resolved from the cd target, but outside cwd when resolved
+      // from cwd itself.
+      const result = await extractExternalPathsFromBashCommand(
+        'cd /projects/my-app/packages/sub && grep -n "pattern" .pi/../../../.pi/skills/pkg/SKILL.md',
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("cd to subdir: still flags genuinely external paths after cd", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        "cd /projects/my-app/packages/sub && cat /etc/hosts",
+        cwd,
+      );
+      expect(result).toContain("/etc/hosts");
+    });
+
+    test("cd to subdir: relative path that stays inside cwd is not flagged", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        "cd /projects/my-app/src && cat ../README.md",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("cd to external dir: paths after cd are still checked against cwd", async () => {
+      // When cd target is outside cwd, we fall back to cwd as the resolve base.
+      // The cd target itself should be flagged, and paths after cd are resolved
+      // against cwd.
+      const result = await extractExternalPathsFromBashCommand(
+        "cd /tmp && cat ../etc/hosts",
+        cwd,
+      );
+      expect(result.length).toBeGreaterThan(0);
+    });
+
+    test("cd with relative target: resolves inside cwd", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        'cd packages/sub && grep -n "x" .pi/../../../.pi/skills/pkg/SKILL.md',
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("no cd prefix: ../ path that escapes cwd is flagged", async () => {
+      // Without the cd prefix, the path resolves against cwd and escapes.
+      const result = await extractExternalPathsFromBashCommand(
+        'grep -n "pattern" .pi/../../../.pi/skills/pkg/SKILL.md',
+        cwd,
+      );
+      expect(result.length).toBeGreaterThan(0);
+    });
+
+    test("cd is not first command: cd is ignored", async () => {
+      // cd after another command should not affect path resolution.
+      const result = await extractExternalPathsFromBashCommand(
+        "echo hello && cd /projects/my-app/src && cat ../../outside.txt",
+        cwd,
+      );
+      // ../../outside.txt resolves against cwd, not the cd target
+      expect(result.length).toBeGreaterThan(0);
+    });
+
+    test("cd with semicolon separator", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        "cd /projects/my-app/src ; cat ../README.md",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+  });
 });
 
 describe("formatBashExternalDirectoryAskPrompt", () => {

package/test/service.test.ts

@@ -6,7 +6,6 @@ import {
   publishPermissionsService,
   unpublishPermissionsService,
 } from "#src/service";
-import { SubagentSessionRegistry } from "#src/subagent-registry";
 import type { PermissionCheckResult } from "#src/types";
 
 // ── helpers ────────────────────────────────────────────────────────────────
@@ -16,8 +15,6 @@ function makeService(
 ): PermissionsService {
   return {
     checkPermission: vi.fn(),
-    registerSubagentSession: vi.fn(),
-    unregisterSubagentSession: vi.fn(),
     getToolPermission: vi.fn(),
     ...overrides,
   };
@@ -130,61 +127,12 @@ describe("service adapter delegation", () => {
     );
   });
 
-  it("registerSubagentSession delegates to the registry", () => {
-    const registry = new SubagentSessionRegistry();
-    const service: PermissionsService = {
-      checkPermission: vi.fn(),
-      registerSubagentSession(key, info) {
-        registry.register(key, info);
-      },
-      unregisterSubagentSession(key) {
-        registry.unregister(key);
-      },
-      getToolPermission: vi.fn((): "allow" => "allow"),
-    };
-
-    publishPermissionsService(service);
-    getPermissionsService()!.registerSubagentSession("/sessions/task-1", {
-      agentName: "Explore",
-      parentSessionId: "parent-abc",
-    });
-
-    expect(registry.has("/sessions/task-1")).toBe(true);
-    expect(registry.get("/sessions/task-1")).toEqual({
-      agentName: "Explore",
-      parentSessionId: "parent-abc",
-    });
-  });
-
-  it("unregisterSubagentSession delegates to the registry", () => {
-    const registry = new SubagentSessionRegistry();
-    const service: PermissionsService = {
-      checkPermission: vi.fn(),
-      registerSubagentSession(key, info) {
-        registry.register(key, info);
-      },
-      unregisterSubagentSession(key) {
-        registry.unregister(key);
-      },
-      getToolPermission: vi.fn((): "allow" => "allow"),
-    };
-
-    publishPermissionsService(service);
-    const svc = getPermissionsService()!;
-    svc.registerSubagentSession("/sessions/task-1", { agentName: "Explore" });
-    svc.unregisterSubagentSession("/sessions/task-1");
-
-    expect(registry.has("/sessions/task-1")).toBe(false);
-  });
-
   it("getToolPermission delegates to the permission manager", () => {
     const getToolPermissionFn = vi.fn(
       (_t: string, _a?: string): "deny" => "deny",
     );
     const service: PermissionsService = {
       checkPermission: vi.fn(),
-      registerSubagentSession: vi.fn(),
-      unregisterSubagentSession: vi.fn(),
       getToolPermission(toolName, agentName) {
         return getToolPermissionFn(toolName, agentName);
       },
@@ -206,8 +154,6 @@ describe("service adapter delegation", () => {
     );
     const service: PermissionsService = {
       checkPermission: vi.fn(),
-      registerSubagentSession: vi.fn(),
-      unregisterSubagentSession: vi.fn(),
       getToolPermission(toolName, agentName) {
         return getToolPermissionFn(toolName, agentName);
       },