@gotgenes/pi-permission-system 9.1.0 → 9.2.0

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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).
 
+## [9.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v9.1.0...pi-permission-system-v9.2.0) (2026-06-02)
+
+
+### Features
+
+* flag relative paths conservatively after a non-literal cd ([6e631a0](https://github.com/gotgenes/pi-packages/commit/6e631a0c62633e0be3a498752a3bf3614d357d65)), closes [#307](https://github.com/gotgenes/pi-packages/issues/307)
+* fold sequential current-shell cd into the bash effective directory ([7fd8e95](https://github.com/gotgenes/pi-packages/commit/7fd8e9525196ffa558a2b59ea9f4cf66943f9010)), closes [#307](https://github.com/gotgenes/pi-packages/issues/307)
+* scope cd inside subshells and persist it across brace groups ([37b948c](https://github.com/gotgenes/pi-packages/commit/37b948c7e9fd5d9ddac3aa8c6b456039132f7c4e)), closes [#307](https://github.com/gotgenes/pi-packages/issues/307)
+
 ## [9.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v9.0.1...pi-permission-system-v9.1.0) (2026-06-02)
 
 

package/package.json

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

package/src/handlers/gates/bash-program.ts

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import { basename, resolve } from "node:path";
+import { basename, isAbsolute, join, resolve } from "node:path";
 
 import {
   classifyTokenAsPathCandidate,
@@ -75,6 +75,29 @@ export interface BashCommand {
   readonly context?: BashCommandContext;
 }
 
+/**
+ * The working directory in force where a path candidate appears.
+ *
+ * A `known` base carries an `offset` to be joined with `cwd` at resolution time
+ * (the parse-time walk never sees `cwd`): a relative-or-absolute path string
+ * built by folding the literal targets of current-shell `cd` commands (`""` =
+ * `cwd`); an absolute offset (from `cd /abs`) ignores `cwd` at resolution time.
+ * An `unknown` base marks a non-literal `cd` target (`cd "$DIR"`, `cd $(…)`,
+ * `cd -`, bare `cd`, `cd ~…`) that made the effective directory unresolvable.
+ */
+type EffectiveBase =
+  | { readonly kind: "known"; readonly offset: string }
+  | { readonly kind: "unknown" };
+
+/**
+ * A path-candidate token paired with the effective working directory projected
+ * onto the point in the command stream where it appears.
+ */
+interface PathCandidate {
+  readonly token: string;
+  readonly base: EffectiveBase;
+}
+
 /**
  * A bash command parsed once into a reusable representation.
  *
@@ -87,29 +110,29 @@ export interface BashCommand {
  */
 export class BashProgram {
   private constructor(
-    private readonly rawTokens: readonly string[],
-    private readonly leadingCdTarget: string | undefined,
+    private readonly rawCandidates: readonly PathCandidate[],
     private readonly commandUnits: readonly BashCommand[],
   ) {}
 
   /**
    * Parse a bash command into a `BashProgram`.
    *
-   * Uses tree-sitter-bash to build the full AST, walks command-argument and
-   * redirect-destination nodes once into raw candidate tokens, and records the
-   * leading `cd` target. Heredoc bodies, comments, and other non-argument
-   * content are skipped. An unparseable command yields an empty program.
+   * Uses tree-sitter-bash to build the full AST and walks command-argument and
+   * redirect-destination nodes once into raw candidate tokens, each tagged with
+   * the effective working directory projected onto its position by folding
+   * current-shell `cd` commands. Heredoc bodies, comments, and other
+   * non-argument content are skipped. An unparseable command yields an empty
+   * program.
    */
   static async parse(command: string): Promise<BashProgram> {
     const parser = await getParser();
     const tree = parser.parse(command);
-    if (!tree) return new BashProgram([], undefined, []);
+    if (!tree) return new BashProgram([], []);
 
     try {
-      const leadingCdTarget = extractLeadingCdTarget(tree.rootNode);
-      const rawTokens = collectPathCandidateTokens(tree.rootNode);
+      const rawCandidates = collectPathCandidates(tree.rootNode);
       const commandUnits = collectCommands(tree.rootNode);
-      return new BashProgram(rawTokens, leadingCdTarget, commandUnits);
+      return new BashProgram(rawCandidates, commandUnits);
     } finally {
       tree.delete();
     }
@@ -125,7 +148,7 @@ export class BashProgram {
   pathTokens(): string[] {
     const seen = new Set<string>();
     const result: string[] = [];
-    for (const token of this.rawTokens) {
+    for (const { token } of this.rawCandidates) {
       const candidate = classifyTokenAsRuleCandidate(token);
       if (!candidate) continue;
       if (!seen.has(candidate)) {
@@ -156,21 +179,42 @@ export class BashProgram {
   /**
    * Deduplicated paths that resolve outside `cwd`.
    *
-   * 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.
+   * Each candidate is resolved against the effective working directory in force
+   * where it appears, projected by folding a sequence of current-shell `cd`
+   * commands (joined by `&&`, `||`, `;`, or a newline). A `cd` inside a
+   * pipeline or a backgrounded command runs in a subshell and does not update
+   * the running directory.
    */
   externalPaths(cwd: string): string[] {
-    const resolveBase = computeEffectiveResolveBase(this.leadingCdTarget, cwd);
     const normalizedCwd = normalizePathForComparison(cwd, cwd);
 
     const seen = new Set<string>();
     const externalPaths: string[] = [];
 
-    for (const token of this.rawTokens) {
+    for (const { token, base } of this.rawCandidates) {
       const candidate = classifyTokenAsPathCandidate(token);
       if (!candidate) continue;
 
+      // Unknown effective directory: a relative candidate could resolve
+      // anywhere, so flag it conservatively (resolving against `cwd` only for a
+      // display path). Absolute / `~` candidates are base-independent and
+      // resolve normally below.
+      if (base.kind === "unknown" && isRelativeCandidate(candidate)) {
+        const normalized = normalizePathForComparison(candidate, cwd);
+        if (
+          normalized &&
+          normalizedCwd !== "" &&
+          !isSafeSystemPath(normalized) &&
+          !seen.has(normalized)
+        ) {
+          seen.add(normalized);
+          externalPaths.push(normalized);
+        }
+        continue;
+      }
+
+      const resolveBase =
+        base.kind === "known" ? resolve(cwd, base.offset) : cwd;
       const normalized = normalizePathForComparison(candidate, resolveBase);
       if (!normalized) continue;
 
@@ -733,75 +777,199 @@ function collectSubstitutionCommands(node: TSNode, out: BashCommand[]): void {
   }
 }
 
-// ── Leading cd detection ───────────────────────────────────────────────────
+// ── Effective working directory projection ─────────────────────────────────
+
+/** The working directory in force at the start of a program (`cwd`). */
+const CWD_BASE: EffectiveBase = { kind: "known", offset: "" };
+
+/** The effective directory after a non-literal or unresolvable `cd`. */
+const UNKNOWN_BASE: EffectiveBase = { kind: "unknown" };
 
 /**
- * Walk down from the root to find the first `command` node in the program.
+ * Walk the AST once, collecting every path-candidate token tagged with the
+ * effective working directory projected onto its position.
  *
- * 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.
+ * The effective directory is stateful: it starts at `cwd` and each current-shell
+ * `cd <literal>` (joined by `&&`, `||`, `;`, or a newline) folds into it for
+ * subsequent commands. A `cd` inside a pipeline or a backgrounded command runs
+ * in a subshell and does not update the running directory; subshell and
+ * brace-group interiors inherit the enclosing base without folding their own
+ * `cd`s (a conservative first tier).
  */
-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);
+function collectPathCandidates(rootNode: TSNode): PathCandidate[] {
+  const out: PathCandidate[] = [];
+  walkForCandidates(rootNode, CWD_BASE, out);
+  return out;
+}
+
+/**
+ * Collect a single node's candidates tagged with `base`, returning the
+ * effective base in force *after* the node (the input base unless the node is a
+ * current-shell `cd <literal>` that folds the running directory).
+ */
+function walkForCandidates(
+  node: TSNode,
+  base: EffectiveBase,
+  out: PathCandidate[],
+): EffectiveBase {
+  switch (node.type) {
+    case "program":
+    case "list":
+    case "redirected_statement":
+      return walkCurrentShellSequence(node, base, out);
+    case "command":
+      tagTokens(collectCommandTokens(node), base, out);
+      return foldCd(node, base);
+    case "subshell":
+      // A subshell runs in a child shell: its interior `cd`s fold within the
+      // subshell but reset on exit, so the folded base is discarded.
+      walkCurrentShellSequence(node, base, out);
+      return base;
+    case "compound_statement":
+      // A `{ … }` brace group runs in the current shell, so its `cd`s persist
+      // to following commands — thread and return the folded base.
+      return walkCurrentShellSequence(node, base, out);
+    default:
+      // Pipelines, control-flow bodies, redirect targets, and command/process
+      // substitution interiors: collect every candidate in the subtree tagged
+      // with the enclosing base and do not fold their internal `cd`s. (Folding
+      // inside substitutions is deferred — conservative, never under-flags.)
+      tagTokens(collectPathCandidateTokens(node), base, out);
+      return base;
   }
-  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 ~…`).
+ * Fold a current-shell sequence (`program` / `list` / `redirected_statement`):
+ * thread the effective base left-to-right through the children so a `cd` updates
+ * the base for following siblings. A statement immediately followed by the
+ * background operator (`&`) runs in a subshell, so its folded base is discarded.
+ */
+function walkCurrentShellSequence(
+  seqNode: TSNode,
+  base: EffectiveBase,
+  out: PathCandidate[],
+): EffectiveBase {
+  let current = base;
+  for (let i = 0; i < seqNode.childCount; i++) {
+    const child = seqNode.child(i);
+    if (!child?.isNamed) continue;
+    if (SKIP_SUBTREE_TYPES.has(child.type)) continue;
+    const after = walkForCandidates(child, current, out);
+    current = isBackgrounded(seqNode, i) ? current : after;
+  }
+  return current;
+}
+
+/**
+ * True when the statement at `index` is immediately followed by the background
+ * operator (`&`) — distinct from the `&&` / `||` / `;` current-shell separators.
+ */
+function isBackgrounded(seqNode: TSNode, index: number): boolean {
+  const next = seqNode.child(index + 1);
+  if (!next || next.isNamed) return false;
+  return next.type === "&";
+}
+
+function tagTokens(
+  tokens: readonly string[],
+  base: EffectiveBase,
+  out: PathCandidate[],
+): void {
+  for (const token of tokens) out.push({ token, base });
+}
+
+/**
+ * True when a path candidate is relative (resolved against the effective
+ * directory) rather than absolute (`/…`) or home-relative (`~…`), which are
+ * base-independent. Used to decide which candidates an unknown base affects.
  */
-function extractLeadingCdTarget(rootNode: TSNode): string | undefined {
-  const firstCmd = findFirstCommand(rootNode);
-  if (!firstCmd) return undefined;
+function isRelativeCandidate(candidate: string): boolean {
+  return !candidate.startsWith("/") && !candidate.startsWith("~");
+}
 
-  const cmdName = extractCommandName(firstCmd);
-  if (cmdName !== "cd") return undefined;
+/**
+ * Compute the effective base after a command runs. Returns `base` unchanged
+ * unless the command is `cd`:
+ *
+ * - `cd /abs` (absolute literal) → a fresh known base, recovering from an
+ *   earlier unknown base.
+ * - `cd rel` (relative literal) → fold into a known base, or stay unknown if the
+ *   base was already unknown.
+ * - `cd "$DIR"` / `cd $(…)` / `cd -` / bare `cd` / `cd ~…` (non-literal) →
+ *   unknown.
+ */
+function foldCd(commandNode: TSNode, base: EffectiveBase): EffectiveBase {
+  if (extractCommandName(commandNode) !== "cd") return base;
+  const target = cdLiteralTarget(commandNode);
+  if (target === null) return UNKNOWN_BASE;
+  if (isAbsolute(target)) return { kind: "known", offset: target };
+  if (base.kind === "unknown") return UNKNOWN_BASE;
+  return { kind: "known", offset: join(base.offset, target) };
+}
 
-  for (let i = 0; i < firstCmd.childCount; i++) {
-    const child = firstCmd.child(i);
+/**
+ * Resolve the literal target of a `cd` command, or `null` when the first
+ * argument is not a static literal (contains an expansion or command
+ * substitution) or cannot be resolved against the working directory (`cd -`,
+ * `cd ~…`, bare `cd`).
+ */
+function cdLiteralTarget(commandNode: TSNode): string | null {
+  for (let i = 0; i < commandNode.childCount; i++) {
+    const child = commandNode.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;
+    if (!child.isNamed) continue;
+    // Skip the `--` end-of-flags marker; the next argument is the target.
+    if (child.type === "word" && child.text === "--") continue;
+    if (!ARG_NODE_TYPES.has(child.type)) return null;
+    return literalTextOf(child);
   }
-  return undefined;
+  return null;
 }
 
 /**
- * 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`.
+ * The literal string value of an argument node, or `null` when it contains a
+ * variable expansion / command substitution or is a non-resolvable `cd`
+ * destination (`-`, `~…`).
  */
-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;
+function literalTextOf(node: TSNode): string | null {
+  switch (node.type) {
+    case "word": {
+      const text = node.text;
+      if (text === "-" || text.startsWith("~")) return null;
+      return text;
+    }
+    case "raw_string": {
+      const text = node.text;
+      return text.length >= 2 && text.startsWith("'") && text.endsWith("'")
+        ? text.slice(1, -1)
+        : text;
+    }
+    case "concatenation": {
+      let result = "";
+      for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (!child) continue;
+        const part = literalTextOf(child);
+        if (part === null) return null;
+        result += part;
+      }
+      return result;
+    }
+    case "string": {
+      let result = "";
+      for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (!child) continue;
+        if (child.type === '"') continue;
+        if (child.type !== "string_content") return null;
+        result += child.text;
+      }
+      return result;
+    }
+    default:
+      return null;
+  }
 }

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

@@ -852,15 +852,16 @@ describe("extractExternalPathsFromBashCommand", () => {
       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.
+    test("cd to external dir: subsequent paths resolve against the (external) effective directory", async () => {
+      // The effective directory is tracked faithfully: `cd /tmp` makes /tmp the
+      // base, so the cd target itself is flagged AND ../etc/hosts resolves to
+      // /etc/hosts (both outside cwd).
       const result = await extractExternalPathsFromBashCommand(
         "cd /tmp && cat ../etc/hosts",
         cwd,
       );
-      expect(result.length).toBeGreaterThan(0);
+      expect(result).toContain("/tmp");
+      expect(result).toContain("/etc/hosts");
     });
 
     test("cd with relative target: resolves inside cwd", async () => {
@@ -880,14 +881,14 @@ describe("extractExternalPathsFromBashCommand", () => {
       expect(result.length).toBeGreaterThan(0);
     });
 
-    test("cd is not first command: cd is ignored", async () => {
-      // cd after another command should not affect path resolution.
+    test("sequential fold: a cd that is not the first command still updates the base", async () => {
+      // The current-shell `cd` folds even though it is not the first command;
+      // ../../outside.txt resolves against /projects/my-app/src → /projects/outside.txt.
       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);
+      expect(result).toContain("/projects/outside.txt");
     });
 
     test("cd with semicolon separator", async () => {

package/test/handlers/gates/bash-program.test.ts

@@ -33,6 +33,115 @@ describe("BashProgram", () => {
       const program = await BashProgram.parse("cat src/index.ts");
       expect(program.externalPaths(cwd)).toHaveLength(0);
     });
+
+    describe("effective working directory projection", () => {
+      it("folds a sequence of current-shell cd commands", async () => {
+        // cd a → cwd/a, cd b → cwd/a/b; ../c resolves to cwd/a/c (inside).
+        const program = await BashProgram.parse("cd a && cd b && cat ../c");
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("catches an escape masked by a later cd that the single-base model missed", async () => {
+        // Effective dir after `cd nested/deep && cd ..` is cwd/nested, so
+        // ../../etc/passwd escapes to /projects/etc/passwd.
+        const program = await BashProgram.parse(
+          "cd nested/deep && cd .. && cat ../../etc/passwd",
+        );
+        expect(program.externalPaths(cwd)).toContain("/projects/etc/passwd");
+      });
+
+      it("folds a cd that is not the first command", async () => {
+        // The single-base model ignored a cd that was not first; now `cd a`
+        // folds, so ../b resolves to cwd/b (inside) and is not flagged.
+        const program = await BashProgram.parse("mkdir d && cd a && cat ../b");
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("does not fold a backgrounded cd", async () => {
+        // `cd a &` runs in a subshell, so it must not update the running
+        // directory; ../b resolves against cwd and escapes.
+        const program = await BashProgram.parse("cd a & cat ../b");
+        expect(program.externalPaths(cwd)).toContain("/projects/b");
+      });
+
+      it("does not fold a cd inside a pipeline", async () => {
+        // Pipeline members run in subshells; the cd must not leak.
+        const program = await BashProgram.parse("cd nested | cat ../b");
+        expect(program.externalPaths(cwd)).toContain("/projects/b");
+      });
+
+      it("folds a cd inside a subshell for paths within that subshell", async () => {
+        // Inside the subshell the effective dir is cwd/sub, so ../x → cwd/x.
+        const program = await BashProgram.parse("( cd sub && cat ../x )");
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("does not leak a subshell cd to following commands", async () => {
+        // The subshell cd resets on exit, so ../y resolves against cwd.
+        const program = await BashProgram.parse("( cd sub ) && cat ../y");
+        expect(program.externalPaths(cwd)).toContain("/projects/y");
+      });
+
+      it("persists a cd inside a brace group to later commands in the group", async () => {
+        // Brace groups run in the current shell, so cd sub persists to cat ../x.
+        const program = await BashProgram.parse("{ cd sub; cat ../x; }");
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("persists a brace-group cd to following sibling commands", async () => {
+        const program = await BashProgram.parse("{ cd sub; } && cat ../x");
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("conservatively flags a relative path inside a command substitution", async () => {
+        // Interior cd folding inside substitutions is deferred: the interior
+        // inherits the enclosing base (cwd), so ../r is flagged rather than
+        // resolved against cwd/q. Conservative — never misses an escape.
+        const program = await BashProgram.parse("echo $(cd q && cat ../r)");
+        expect(program.externalPaths(cwd)).toContain("/projects/r");
+      });
+
+      it("flags relative paths conservatively after a non-literal cd", async () => {
+        // cd "$DIR" makes the effective dir unknowable; ../x could be anywhere,
+        // so it is flagged (least-privilege).
+        const program = await BashProgram.parse('cd "$DIR" && cat ../x');
+        expect(program.externalPaths(cwd)).toContain("/projects/x");
+      });
+
+      it("flags even a within-cwd relative path after a non-literal cd", async () => {
+        // Conservative cost: src/../within.txt resolves inside cwd but is still
+        // flagged because the effective dir is unknown.
+        const program = await BashProgram.parse(
+          'cd "$DIR" && cat src/../within.txt',
+        );
+        expect(program.externalPaths(cwd)).toContain(
+          "/projects/my-app/within.txt",
+        );
+      });
+
+      it("still resolves an absolute path normally after a non-literal cd", async () => {
+        // Absolute paths are base-independent; one inside cwd is not flagged
+        // even when the effective dir is unknown.
+        const program = await BashProgram.parse(
+          'cd "$DIR" && cat /projects/my-app/x.txt',
+        );
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("treats `cd -` as an unknown effective directory", async () => {
+        const program = await BashProgram.parse("cd - && cat ../x");
+        expect(program.externalPaths(cwd)).toContain("/projects/x");
+      });
+
+      it("recovers a known base when a later cd is absolute", async () => {
+        // cd "$DIR" → unknown, then cd /projects/my-app/src → known again, so
+        // ../x resolves to cwd and is not flagged.
+        const program = await BashProgram.parse(
+          'cd "$DIR" && cd /projects/my-app/src && cat ../x',
+        );
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+    });
   });
 
   describe("commands", () => {