@gotgenes/pi-permission-system 7.3.3 → 7.4.1

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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).
 
+## [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)
+
+
+### Features
+
+* register subagent child sessions via lifecycle events ([cd324dc](https://github.com/gotgenes/pi-packages/commit/cd324dc5f8b18fe69ba8802eda0b17a6a36ccc58))
+
+
+### Documentation
+
+* document event-based subagent child lifecycle ([62621fa](https://github.com/gotgenes/pi-packages/commit/62621fa9abd093b5deadb3c15139179ae85ad519))
+
 ## [7.3.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v7.3.2...pi-permission-system-v7.3.3) (2026-05-28)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "7.3.3",
+  "version": "7.4.1",
   "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

@@ -27,6 +27,7 @@ import {
 } from "./service";
 import { createSessionLogger } from "./session-logger";
 import { isSubagentExecutionContext } from "./subagent-context";
+import { subscribeSubagentLifecycle } from "./subagent-lifecycle-events";
 import { SubagentSessionRegistry } from "./subagent-registry";
 import {
   canResolveAskPermissionRequest,
@@ -129,6 +130,13 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   };
   publishPermissionsService(permissionsService);
 
+  // Subscribe to @gotgenes/pi-subagents' child lifecycle events so child
+  // sessions register/unregister without the core calling us (ADR 0002).
+  const unsubSubagentLifecycle = subscribeSubagentLifecycle(
+    pi.events,
+    subagentRegistry,
+  );
+
   emitReadyEvent(pi.events);
 
   const toolRegistry = {
@@ -139,6 +147,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const lifecycle = new SessionLifecycleHandler(session, () => {
     rpcHandles.unsubCheck();
     rpcHandles.unsubPrompt();
+    unsubSubagentLifecycle();
     unpublishPermissionsService();
   });
   const agentPrep = new AgentPrepHandler(session, toolRegistry);

package/src/subagent-lifecycle-events.ts

@@ -0,0 +1,72 @@
+/**
+ * subagent-lifecycle-events.ts — Subscribe to @gotgenes/pi-subagents' child
+ * lifecycle events and keep the SubagentSessionRegistry in sync.
+ *
+ * @gotgenes/pi-subagents publishes its child-execution lifecycle on the Pi
+ * event bus (ADR 0002): it no longer calls this package's service directly.
+ * We register the child on `session-created` and unregister it on `disposed`.
+ *
+ * The channel names and payload shapes are declared independently here (the two
+ * packages must not depend on each other under jiti) and MUST match the
+ * publisher in `@gotgenes/pi-subagents` (`src/lifecycle/child-lifecycle.ts`).
+ *
+ * The `session-created` handler MUST stay synchronous: the core emits it on the
+ * same synchronous call stack immediately before `bindExtensions()`, and the
+ * event bus dispatches listeners synchronously, so a synchronous handler lands
+ * the registry entry before binding proceeds. Introducing an `await` before
+ * `registry.register(...)` would break the pre-bind ordering.
+ */
+
+import type { SubagentSessionRegistry } from "./subagent-registry";
+
+/** Emitted by the core after session creation, before `bindExtensions()`. */
+export const SUBAGENT_CHILD_SESSION_CREATED = "subagents:child:session-created";
+
+/** Emitted by the core in the run's `finally` (success and error). */
+export const SUBAGENT_CHILD_DISPOSED = "subagents:child:disposed";
+
+/** Minimal event-bus surface this module needs (subscribe only). */
+interface LifecycleEventBus {
+  on(channel: string, handler: (data: unknown) => void): () => void;
+}
+
+/** Fields read from the `session-created` payload (ISP). */
+interface ChildSessionCreatedEvent {
+  sessionDir: string;
+  agentName: string;
+  parentSessionId?: string;
+}
+
+/** Fields read from the `disposed` payload (ISP). */
+interface ChildDisposedEvent {
+  sessionDir: string;
+}
+
+/**
+ * Subscribe to the subagent child lifecycle.
+ *
+ * @returns an unsubscribe that detaches both handlers (call during
+ *          `session_shutdown`).
+ */
+export function subscribeSubagentLifecycle(
+  events: LifecycleEventBus,
+  registry: SubagentSessionRegistry,
+): () => void {
+  const unsubCreated = events.on(SUBAGENT_CHILD_SESSION_CREATED, (data) => {
+    const event = data as ChildSessionCreatedEvent;
+    registry.register(event.sessionDir, {
+      agentName: event.agentName,
+      parentSessionId: event.parentSessionId,
+    });
+  });
+
+  const unsubDisposed = events.on(SUBAGENT_CHILD_DISPOSED, (data) => {
+    const event = data as ChildDisposedEvent;
+    registry.unregister(event.sessionDir);
+  });
+
+  return () => {
+    unsubCreated();
+    unsubDisposed();
+  };
+}

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

@@ -0,0 +1,113 @@
+import { createEventBus } from "@earendil-works/pi-coding-agent";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  SUBAGENT_CHILD_DISPOSED,
+  SUBAGENT_CHILD_SESSION_CREATED,
+  subscribeSubagentLifecycle,
+} from "#src/subagent-lifecycle-events";
+import { SubagentSessionRegistry } from "#src/subagent-registry";
+
+describe("subscribeSubagentLifecycle", () => {
+  let registry: SubagentSessionRegistry;
+
+  beforeEach(() => {
+    registry = new SubagentSessionRegistry();
+  });
+
+  it("registers a child session on session-created", () => {
+    const bus = createEventBus();
+    subscribeSubagentLifecycle(bus, registry);
+
+    bus.emit(SUBAGENT_CHILD_SESSION_CREATED, {
+      sessionDir: "/sessions/child-abc",
+      agentName: "Explore",
+      parentSessionId: "parent-42",
+    });
+
+    expect(registry.get("/sessions/child-abc")).toEqual({
+      agentName: "Explore",
+      parentSessionId: "parent-42",
+    });
+  });
+
+  it("populates the registry synchronously — before emit() returns", () => {
+    // Guards the pre-bindExtensions ordering: the core emits session-created
+    // on the same synchronous call stack right before bindExtensions(), so the
+    // handler must complete before emit() returns. A real EventEmitter-backed
+    // bus dispatches synchronously; this fails loudly if the handler ever
+    // becomes async (awaiting before registry.register).
+    const bus = createEventBus();
+    subscribeSubagentLifecycle(bus, registry);
+
+    bus.emit(SUBAGENT_CHILD_SESSION_CREATED, {
+      sessionDir: "/sessions/child-sync",
+      agentName: "Explore",
+    });
+
+    // No await between emit and this assertion.
+    expect(registry.has("/sessions/child-sync")).toBe(true);
+  });
+
+  it("omits parentSessionId when the event does not carry one", () => {
+    const bus = createEventBus();
+    subscribeSubagentLifecycle(bus, registry);
+
+    bus.emit(SUBAGENT_CHILD_SESSION_CREATED, {
+      sessionDir: "/sessions/child-xyz",
+      agentName: "general-purpose",
+    });
+
+    expect(registry.get("/sessions/child-xyz")).toEqual({
+      agentName: "general-purpose",
+      parentSessionId: undefined,
+    });
+  });
+
+  it("unregisters a child session on disposed", () => {
+    const bus = createEventBus();
+    subscribeSubagentLifecycle(bus, registry);
+    registry.register("/sessions/child-abc", { agentName: "Explore" });
+
+    bus.emit(SUBAGENT_CHILD_DISPOSED, { sessionDir: "/sessions/child-abc" });
+
+    expect(registry.has("/sessions/child-abc")).toBe(false);
+  });
+
+  it("detaches both handlers when the returned unsubscribe is called", () => {
+    const bus = createEventBus();
+    const unsubscribe = subscribeSubagentLifecycle(bus, registry);
+
+    unsubscribe();
+
+    bus.emit(SUBAGENT_CHILD_SESSION_CREATED, {
+      sessionDir: "/sessions/child-abc",
+      agentName: "Explore",
+    });
+    bus.emit(SUBAGENT_CHILD_DISPOSED, { sessionDir: "/sessions/child-abc" });
+
+    expect(registry.has("/sessions/child-abc")).toBe(false);
+  });
+
+  it("subscribes to a fake bus on the exact channel names", () => {
+    const handlers = new Map<string, (data: unknown) => void>();
+    const bus = {
+      on: vi.fn((channel: string, handler: (data: unknown) => void) => {
+        handlers.set(channel, handler);
+        return () => handlers.delete(channel);
+      }),
+    };
+
+    subscribeSubagentLifecycle(bus, registry);
+
+    expect(bus.on).toHaveBeenCalledTimes(2);
+    expect(handlers.has("subagents:child:session-created")).toBe(true);
+    expect(handlers.has("subagents:child:disposed")).toBe(true);
+  });
+
+  it("exposes the canonical channel-name strings", () => {
+    expect(SUBAGENT_CHILD_SESSION_CREATED).toBe(
+      "subagents:child:session-created",
+    );
+    expect(SUBAGENT_CHILD_DISPOSED).toBe("subagents:child:disposed");
+  });
+});