@gotgenes/pi-permission-system 4.1.1 → 4.2.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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).
 
+## [4.2.0](https://github.com/gotgenes/pi-permission-system/compare/v4.1.1...v4.2.0) (2026-05-04)
+
+
+### Features
+
+* replace shell-quote with tree-sitter-bash for AST-based path extraction ([7dce2a4](https://github.com/gotgenes/pi-permission-system/commit/7dce2a4d264d26171a1d54db265f12f3f1d342c6))
+
+
+### Documentation
+
+* note tree-sitter follow-up addressed by [#74](https://github.com/gotgenes/pi-permission-system/issues/74) ([bd835bd](https://github.com/gotgenes/pi-permission-system/commit/bd835bda62af9aa9149149c24ddb14927d52abf4))
+* note tree-sitter-bash AST parser in architecture docs ([ecec2a6](https://github.com/gotgenes/pi-permission-system/commit/ecec2a6db375434a4bc2f920a21741fe29786896))
+* plan tree-sitter-bash AST-based path extraction ([#74](https://github.com/gotgenes/pi-permission-system/issues/74)) ([1693794](https://github.com/gotgenes/pi-permission-system/commit/1693794fd423eaf872400a2a6dc3b0d0faeba13a))
+* rename current-architecture.md to v3-architecture.md ([38d91c5](https://github.com/gotgenes/pi-permission-system/commit/38d91c587a842caa71b32f379ed5723e73f490f4))
+* **retro:** add retro notes for issue [#73](https://github.com/gotgenes/pi-permission-system/issues/73) ([d73097d](https://github.com/gotgenes/pi-permission-system/commit/d73097d7dcda097fb79b6213b482bac8642f4a90))
+* update bash external-directory description for tree-sitter AST parser ([d022d3d](https://github.com/gotgenes/pi-permission-system/commit/d022d3d87ab0cc0192ba9adbaf3b9bf379dfa414))
+
 ## [4.1.1](https://github.com/gotgenes/pi-permission-system/compare/v4.1.0...v4.1.1) (2026-05-04)
 
 

package/README.md

@@ -91,7 +91,7 @@ The extension integrates via Pi's lifecycle hooks:
 - Generic extension-tool approval prompts include a bounded input preview; built-in file tools use concise human-readable summaries instead of raw multiline JSON
 - Permission review logs include bounded `toolInputPreview` values for non-bash/non-MCP tool calls so approvals can be audited without writing raw full payloads
 - Path-bearing file tools (`read`, `write`, `edit`, `find`, `grep`, `ls`) evaluate `permission.external_directory` before their normal tool permission when an explicit path points outside `ctx.cwd`
-- Bash commands are scanned for path tokens (absolute, `~/`, or `..`-relative) that resolve outside `ctx.cwd`; matching commands trigger the same `permission.external_directory` gate before the normal bash pattern check
+- Bash commands are parsed with a full bash AST (`web-tree-sitter` + `tree-sitter-bash`) to extract path-bearing arguments; only genuine command arguments and redirect destinations are checked — heredoc bodies, comments, and quoted string contents are correctly excluded — and paths that resolve outside `ctx.cwd` trigger the same `permission.external_directory` gate before the normal bash pattern check
 
 ## Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "4.1.1",
+  "version": "4.2.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "files": [
@@ -56,13 +56,13 @@
     "@mariozechner/pi-coding-agent": "^0.72.1",
     "@mariozechner/pi-tui": "^0.72.1",
     "@types/node": "^25.6.0",
-    "@types/shell-quote": "^1.7.5",
     "markdownlint-cli2": "^0.22.1",
     "typescript": "6.0.3",
     "vitest": "^4.1.5"
   },
   "dependencies": {
-    "shell-quote": "^1.8.3"
+    "tree-sitter-bash": "^0.25.1",
+    "web-tree-sitter": "^0.26.8"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/external-directory.ts

@@ -1,8 +1,7 @@
+import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { join, normalize, resolve, sep } from "node:path";
 
-import { parse } from "shell-quote";
-
 import { getNonEmptyString, toRecord } from "./common";
 
 /**
@@ -157,6 +156,197 @@ export function formatBashExternalDirectoryDenyReason(
   return `${subject} is not permitted to run bash command '${command}' which references path(s) outside working directory '${cwd}': ${pathList}. ${formatExternalDirectoryHardStopHint()}`;
 }
 
+// ── tree-sitter-bash lazy parser ───────────────────────────────────────────
+
+/**
+ * Minimal subset of web-tree-sitter's SyntaxNode used by the AST walker.
+ * Defined locally so callers do not need to import web-tree-sitter types.
+ */
+interface TSNode {
+  readonly type: string;
+  readonly text: string;
+  readonly childCount: number;
+  child(index: number): TSNode | null;
+}
+
+/**
+ * Minimal subset of web-tree-sitter's Parser used by this module.
+ */
+interface TSParser {
+  parse(input: string): { rootNode: TSNode; delete(): void } | null;
+  delete(): void;
+}
+
+let parserPromise: Promise<TSParser> | null = null;
+
+async function initParser(): Promise<TSParser> {
+  // Use named imports — web-tree-sitter exports Parser as a named class.
+  const { Parser, Language } = await import("web-tree-sitter");
+  const req = createRequire(import.meta.url);
+  const treeSitterWasm = req.resolve("web-tree-sitter/web-tree-sitter.wasm");
+  await Parser.init({ locateFile: () => treeSitterWasm });
+
+  const parser = new Parser();
+  const bashWasm = req.resolve("tree-sitter-bash/tree-sitter-bash.wasm");
+  const bash = await Language.load(bashWasm);
+  parser.setLanguage(bash);
+  return parser as TSParser;
+}
+
+function getParser(): Promise<TSParser> {
+  if (!parserPromise) {
+    parserPromise = initParser();
+  }
+  return parserPromise;
+}
+
+/**
+ * Reset the cached parser promise.  Only used by tests to avoid
+ * cross-test pollution or to inject a mock parser.
+ */
+export function resetParserForTesting(): void {
+  parserPromise = null;
+}
+
+// ── AST walker ─────────────────────────────────────────────────────────────
+
+/**
+ * Node types whose subtrees must never be descended into for
+ * path extraction — their text content is not a command argument.
+ */
+const SKIP_SUBTREE_TYPES = new Set(["heredoc_body", "heredoc_end", "comment"]);
+
+/**
+ * Resolve the "shell value" of an argument node — the string the shell
+ * would pass to the command after quote removal.
+ *
+ * - `word`          → `.text` (already unquoted)
+ * - `raw_string`    → strip surrounding single quotes
+ * - `string`        → strip surrounding double quotes, concatenate children text
+ * - `concatenation` → concatenate resolved children
+ * - other           → `.text` as fallback
+ */
+function resolveNodeText(node: TSNode): string {
+  switch (node.type) {
+    case "word":
+      return node.text;
+    case "raw_string": {
+      // Strip surrounding single quotes: 'content' → content
+      const t = node.text;
+      if (t.length >= 2 && t[0] === "'" && t[t.length - 1] === "'") {
+        return t.slice(1, -1);
+      }
+      return t;
+    }
+    case "string": {
+      // Double-quoted string: concatenate the resolved text of inner children,
+      // skipping the quote-delimiter nodes (literal `"`).
+      let result = "";
+      for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (!child) continue;
+        // Skip the literal `"` delimiters
+        if (child.type === '"') continue;
+        result += resolveNodeText(child);
+      }
+      return result;
+    }
+    case "string_content":
+    case "simple_expansion":
+    case "expansion":
+      return node.text;
+    case "concatenation": {
+      let result = "";
+      for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (!child) continue;
+        result += resolveNodeText(child);
+      }
+      return result;
+    }
+    default:
+      return node.text;
+  }
+}
+
+/**
+ * Recursively visit the AST and collect resolved text of nodes that
+ * represent command arguments or redirect destinations.
+ *
+ * Skips `heredoc_body`, `heredoc_end`, and `comment` subtrees entirely.
+ */
+function collectPathCandidateTokens(node: TSNode, tokens: string[]): void {
+  if (SKIP_SUBTREE_TYPES.has(node.type)) return;
+
+  // Extract arguments from `command` nodes (skip the command name).
+  if (node.type === "command") {
+    let seenCommandName = false;
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (!child) continue;
+
+      if (child.type === "command_name") {
+        seenCommandName = true;
+        continue;
+      }
+      // Skip variable_assignment nodes (FOO=/bar)
+      if (child.type === "variable_assignment") continue;
+
+      // If there was no explicit command_name node, the first word-like
+      // child is the command name itself — skip it.
+      if (
+        !seenCommandName &&
+        (child.type === "word" ||
+          child.type === "concatenation" ||
+          child.type === "string" ||
+          child.type === "raw_string")
+      ) {
+        seenCommandName = true;
+        continue;
+      }
+
+      // Argument nodes: resolve their text and collect.
+      if (
+        child.type === "word" ||
+        child.type === "concatenation" ||
+        child.type === "string" ||
+        child.type === "raw_string"
+      ) {
+        tokens.push(resolveNodeText(child));
+        continue;
+      }
+
+      // Recurse into other children (e.g. command_substitution nested in args)
+      collectPathCandidateTokens(child, tokens);
+    }
+    return;
+  }
+
+  // Extract redirect destinations from `file_redirect` nodes.
+  if (node.type === "file_redirect") {
+    for (let i = 0; i < node.childCount; i++) {
+      const child = node.child(i);
+      if (!child) continue;
+      if (
+        child.type === "word" ||
+        child.type === "concatenation" ||
+        child.type === "string" ||
+        child.type === "raw_string"
+      ) {
+        tokens.push(resolveNodeText(child));
+      }
+    }
+    return;
+  }
+
+  // For all other node types, recurse into children.
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child) continue;
+    collectPathCandidateTokens(child, tokens);
+  }
+}
+
 /**
  * URL pattern to skip tokens that look like URLs rather than paths.
  */
@@ -200,18 +390,25 @@ function classifyTokenAsPathCandidate(token: string): string | null {
 
 /**
  * Extracts paths from a bash command string that resolve outside CWD.
- * Uses shell-quote to tokenize so that quoted strings, operators, and comments
- * are handled correctly, eliminating false positives from the old regex approach.
+ * 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.
  */
-export function extractExternalPathsFromBashCommand(
+export async function extractExternalPathsFromBashCommand(
   command: string,
   cwd: string,
-): string[] {
-  // shell-quote parse() returns strings (resolved arguments), operator objects,
-  // glob objects, and comment objects. Only string entries are path candidates.
-  const tokens = parse(command).filter(
-    (entry): entry is string => typeof entry === "string",
-  );
+): Promise<string[]> {
+  const parser = await getParser();
+  const tree = parser.parse(command);
+  if (!tree) return [];
+
+  const tokens: string[] = [];
+  try {
+    collectPathCandidateTokens(tree.rootNode, tokens);
+  } finally {
+    tree.delete();
+  }
+
   const seen = new Set<string>();
   const externalPaths: string[] = [];
 

package/src/handlers/tool-call.ts

@@ -252,7 +252,7 @@ export async function handleToolCall(
   if (ctx.cwd && toolName === "bash") {
     const command = getNonEmptyString(toRecord(input).command);
     if (command) {
-      const externalPaths = extractExternalPathsFromBashCommand(
+      const externalPaths = await extractExternalPathsFromBashCommand(
         command,
         ctx.cwd,
       );

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

@@ -23,13 +23,16 @@ describe("extractExternalPathsFromBashCommand", () => {
   const cwd = "/projects/my-app";
 
   describe("absolute paths", () => {
-    test("detects absolute path outside CWD", () => {
-      const result = extractExternalPathsFromBashCommand("cat /etc/hosts", cwd);
+    test("detects absolute path outside CWD", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        "cat /etc/hosts",
+        cwd,
+      );
       expect(result).toContain("/etc/hosts");
     });
 
-    test("detects multiple absolute paths outside CWD", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("detects multiple absolute paths outside CWD", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "diff /etc/hosts /var/log/syslog",
         cwd,
       );
@@ -37,8 +40,8 @@ describe("extractExternalPathsFromBashCommand", () => {
       expect(result).toContain("/var/log/syslog");
     });
 
-    test("does not flag absolute path within CWD", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("does not flag absolute path within CWD", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "cat /projects/my-app/src/index.ts",
         cwd,
       );
@@ -47,17 +50,17 @@ describe("extractExternalPathsFromBashCommand", () => {
   });
 
   describe("home-relative paths", () => {
-    test("detects ~/path outside CWD", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("detects ~/path outside CWD", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "cat ~/documents/secret.txt",
         cwd,
       );
       expect(result).toContain("/mock/home/documents/secret.txt");
     });
 
-    test("does not flag ~/path that resolves within CWD", () => {
+    test("does not flag ~/path that resolves within CWD", async () => {
       // CWD is under /mock/home for this test
-      const result = extractExternalPathsFromBashCommand(
+      const result = await extractExternalPathsFromBashCommand(
         "cat ~/myproject/file.ts",
         "/mock/home/myproject",
       );
@@ -66,16 +69,16 @@ describe("extractExternalPathsFromBashCommand", () => {
   });
 
   describe("dot-dot relative paths", () => {
-    test("detects ../ path that resolves outside CWD", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("detects ../ path that resolves outside CWD", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "cat ../../other-project/secrets.env",
         cwd,
       );
       expect(result).toContain("/other-project/secrets.env");
     });
 
-    test("does not flag ../ path that stays within CWD", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("does not flag ../ path that stays within CWD", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "cat src/../lib/utils.ts",
         cwd,
       );
@@ -84,31 +87,34 @@ describe("extractExternalPathsFromBashCommand", () => {
   });
 
   describe("commands within CWD only", () => {
-    test("returns empty for relative paths within CWD", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("returns empty for relative paths within CWD", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "cat src/index.ts",
         cwd,
       );
       expect(result).toHaveLength(0);
     });
 
-    test("returns empty for bare command with no path arguments", () => {
-      const result = extractExternalPathsFromBashCommand("git status", cwd);
+    test("returns empty for bare command with no path arguments", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        "git status",
+        cwd,
+      );
       expect(result).toHaveLength(0);
     });
   });
 
   describe("flags are skipped", () => {
-    test("does not treat flags as paths", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("does not treat flags as paths", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "ls -la --color=auto",
         cwd,
       );
       expect(result).toHaveLength(0);
     });
 
-    test("detects path after flags", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("detects path after flags", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "ls -la /etc/passwd",
         cwd,
       );
@@ -117,8 +123,8 @@ describe("extractExternalPathsFromBashCommand", () => {
   });
 
   describe("env assignments are skipped", () => {
-    test("does not treat FOO=/bar as a path", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("does not treat FOO=/bar as a path", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "FOO=/usr/local/bin command",
         cwd,
       );
@@ -127,32 +133,32 @@ describe("extractExternalPathsFromBashCommand", () => {
   });
 
   describe("shell metacharacters split correctly", () => {
-    test("detects path after pipe", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("detects path after pipe", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "echo hello | tee /tmp/output.txt",
         cwd,
       );
       expect(result).toContain("/tmp/output.txt");
     });
 
-    test("detects path after semicolon", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("detects path after semicolon", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "echo done; cat /etc/hosts",
         cwd,
       );
       expect(result).toContain("/etc/hosts");
     });
 
-    test("detects path after &&", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("detects path after &&", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "true && cat /etc/hosts",
         cwd,
       );
       expect(result).toContain("/etc/hosts");
     });
 
-    test("detects path in redirect target", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("detects path in redirect target", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "echo hello > /tmp/out.txt",
         cwd,
       );
@@ -161,16 +167,16 @@ describe("extractExternalPathsFromBashCommand", () => {
   });
 
   describe("URLs are skipped", () => {
-    test("does not treat http:// URL as a path", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("does not treat http:// URL as a path", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "curl http://example.com/path",
         cwd,
       );
       expect(result).toHaveLength(0);
     });
 
-    test("does not treat https:// URL as a path", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("does not treat https:// URL as a path", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "curl https://example.com/etc/hosts",
         cwd,
       );
@@ -179,8 +185,8 @@ describe("extractExternalPathsFromBashCommand", () => {
   });
 
   describe("@scope/package patterns are skipped", () => {
-    test("does not treat @scope/package as a path", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("does not treat @scope/package as a path", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "npm install @types/node",
         cwd,
       );
@@ -189,34 +195,34 @@ describe("extractExternalPathsFromBashCommand", () => {
   });
 
   describe("quoted strings are ignored", () => {
-    test("does not flag path inside double-quoted string", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("does not flag path inside double-quoted string", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         'git commit -m "fix: update /etc/hosts handler"',
         cwd,
       );
       expect(result).toHaveLength(0);
     });
 
-    test("does not flag path inside single-quoted string", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("does not flag path inside single-quoted string", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "echo 'see /usr/local/docs for info'",
         cwd,
       );
       expect(result).toHaveLength(0);
     });
 
-    test("still flags unquoted path alongside quoted content", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("still flags unquoted path alongside quoted content", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         'cat /etc/hosts && echo "done"',
         cwd,
       );
       expect(result).toContain("/etc/hosts");
     });
 
-    test("does not flag path when adjacent quoted segments form one word", () => {
-      // shell-quote concatenates adjacent quoted/unquoted segments into one word:
-      // '"path is "/etc/hosts""' → 'path is /etc/hosts' (one token, not a path candidate).
-      const result = extractExternalPathsFromBashCommand(
+    test("does not flag path when adjacent quoted segments form one word", async () => {
+      // tree-sitter parses adjacent quoted/unquoted segments as a concatenation node
+      // whose resolved text is 'path is /etc/hosts' (one token, not a path candidate).
+      const result = await extractExternalPathsFromBashCommand(
         'echo "path is "/etc/hosts""',
         cwd,
       );
@@ -225,45 +231,48 @@ describe("extractExternalPathsFromBashCommand", () => {
   });
 
   describe("safe system paths are filtered", () => {
-    test("does not flag /dev/null in stderr redirect", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("does not flag /dev/null in stderr redirect", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "command 2>/dev/null",
         cwd,
       );
       expect(result).toHaveLength(0);
     });
 
-    test("does not flag /dev/null as a redirect target", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("does not flag /dev/null as a redirect target", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "echo hello > /dev/null",
         cwd,
       );
       expect(result).toHaveLength(0);
     });
 
-    test("does not flag /dev/stdin", () => {
-      const result = extractExternalPathsFromBashCommand("cat /dev/stdin", cwd);
+    test("does not flag /dev/stdin", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        "cat /dev/stdin",
+        cwd,
+      );
       expect(result).toHaveLength(0);
     });
 
-    test("does not flag /dev/stdout", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("does not flag /dev/stdout", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "cat /dev/stdout",
         cwd,
       );
       expect(result).toHaveLength(0);
     });
 
-    test("does not flag /dev/stderr", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("does not flag /dev/stderr", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "cat /dev/stderr",
         cwd,
       );
       expect(result).toHaveLength(0);
     });
 
-    test("still flags a real external path alongside /dev/null", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("still flags a real external path alongside /dev/null", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "cat /etc/hosts 2>/dev/null",
         cwd,
       );
@@ -271,8 +280,8 @@ describe("extractExternalPathsFromBashCommand", () => {
       expect(result).not.toContain("/dev/null");
     });
 
-    test("does not flag /dev/null/subdir (not a safe path)", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("does not flag /dev/null/subdir (not a safe path)", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "cat /dev/null/subdir",
         cwd,
       );
@@ -281,37 +290,46 @@ describe("extractExternalPathsFromBashCommand", () => {
   });
 
   describe("bare-slash tokens are skipped", () => {
-    test("does not flag // token", () => {
-      const result = extractExternalPathsFromBashCommand("echo //", cwd);
+    test("does not flag // token", async () => {
+      const result = await extractExternalPathsFromBashCommand("echo //", cwd);
       expect(result).toHaveLength(0);
     });
 
-    test("does not flag / token", () => {
-      const result = extractExternalPathsFromBashCommand("echo /", cwd);
+    test("does not flag / token", async () => {
+      const result = await extractExternalPathsFromBashCommand("echo /", cwd);
       expect(result).toHaveLength(0);
     });
 
-    test("does not flag /// token", () => {
-      const result = extractExternalPathsFromBashCommand("echo ///", cwd);
+    test("does not flag /// token", async () => {
+      const result = await extractExternalPathsFromBashCommand("echo ///", cwd);
       expect(result).toHaveLength(0);
     });
 
-    test("does not flag // in echo with other args", () => {
-      const result = extractExternalPathsFromBashCommand("echo // hello", cwd);
+    test("does not flag // in echo with other args", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        "echo // hello",
+        cwd,
+      );
       expect(result).toHaveLength(0);
     });
 
-    test("bare-slash guard is still needed: shell-quote emits / as a string token", () => {
-      // shell-quote.parse('echo /') returns ['echo', '/'] — the bare slash IS a string
-      // token, not an operator. classifyTokenAsPathCandidate must still reject it.
+    test("bare-slash guard is still needed: tree-sitter emits / as a word node", async () => {
+      // tree-sitter parses 'echo /' with '/' as a word argument node.
+      // classifyTokenAsPathCandidate must still reject it.
       // This test documents that the /^\/+$/ guard remains a necessary
-      // defense-in-depth layer even with shell-quote as the tokenizer.
-      const result = extractExternalPathsFromBashCommand("echo /", cwd);
+      // defense-in-depth layer even with tree-sitter as the parser.
+      const result = await extractExternalPathsFromBashCommand("echo /", cwd);
+      expect(result).toHaveLength(0);
+    });
+
+    test("bare double-slash guard with tree-sitter", async () => {
+      // tree-sitter also emits '//' as a word node — guard must reject it.
+      const result = await extractExternalPathsFromBashCommand("echo //", cwd);
       expect(result).toHaveLength(0);
     });
 
-    test("still flags real external path alongside //", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("still flags real external path alongside //", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "cat /etc/hosts; echo //",
         cwd,
       );
@@ -321,23 +339,23 @@ describe("extractExternalPathsFromBashCommand", () => {
   });
 
   describe("node -e and multi-line commands", () => {
-    test("does not flag path inside single-quoted string in node -e argument", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("does not flag path inside single-quoted string in node -e argument", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "node -e \"const p = '/etc/hosts'; console.log(p);\"",
         cwd,
       );
       expect(result).toHaveLength(0);
     });
 
-    test("does not flag path inside multi-line node -e argument", () => {
+    test("does not flag path inside multi-line node -e argument", async () => {
       // Actual newlines inside the double-quoted -e argument.
       const cmd =
         "node -e \"\nimport('x').then(() => {\n  console.log('/etc/hosts');\n});\n\"";
-      const result = extractExternalPathsFromBashCommand(cmd, cwd);
+      const result = await extractExternalPathsFromBashCommand(cmd, cwd);
       expect(result).toHaveLength(0);
     });
 
-    test("does not flag path that appears after escaped quote in multi-line node -e argument", () => {
+    test("does not flag path that appears after escaped quote in multi-line node -e argument", async () => {
       // This is the shape of the command that triggered a prompt during dog-fooding.
       // The outer \"...\" arg contains both actual newlines and \\" escape sequences,
       // with /etc/hosts appearing after a \\" boundary.
@@ -349,32 +367,31 @@ describe("extractExternalPathsFromBashCommand", () => {
         "});",
         '"',
       ].join("\n");
-      const result = extractExternalPathsFromBashCommand(cmd, cwd);
+      const result = await extractExternalPathsFromBashCommand(cmd, cwd);
       expect(result).toHaveLength(0);
     });
   });
 
-  describe("shell-quote tokenizer edge cases", () => {
-    test("does not flag path inside string when escaped quote is present", () => {
-      // stripQuotedStrings regex breaks at \" — content after it leaks into the token stream.
-      // shell-quote correctly parses the escaped quote and keeps the path inside the string.
-      const result = extractExternalPathsFromBashCommand(
+  describe("tokenizer edge cases", () => {
+    test("does not flag path inside string when escaped quote is present", async () => {
+      // tree-sitter correctly parses the escaped quote and keeps the path inside the string.
+      const result = await extractExternalPathsFromBashCommand(
         'git commit -m "fix: update \\"the /etc/hosts\\" handler"',
         cwd,
       );
       expect(result).toHaveLength(0);
     });
 
-    test("does not flag path appearing only in a shell comment", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("does not flag path appearing only in a shell comment", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "echo hello # /etc/shadow",
         cwd,
       );
       expect(result).toHaveLength(0);
     });
 
-    test("flags real path before comment but not path inside comment", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("flags real path before comment but not path inside comment", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "cat /etc/hosts # see also /etc/shadow",
         cwd,
       );
@@ -384,9 +401,142 @@ describe("extractExternalPathsFromBashCommand", () => {
     });
   });
 
+  describe("heredoc handling", () => {
+    test("does not flag path inside single-quoted heredoc delimiter", async () => {
+      const cmd = "cat << 'EOF'\n/etc/hosts\nEOF";
+      const result = await extractExternalPathsFromBashCommand(cmd, cwd);
+      expect(result).toHaveLength(0);
+    });
+
+    test("does not flag path inside double-quoted heredoc delimiter", async () => {
+      const cmd = 'cat << "EOF"\n/etc/hosts\nEOF';
+      const result = await extractExternalPathsFromBashCommand(cmd, cwd);
+      expect(result).toHaveLength(0);
+    });
+
+    test("does not flag path inside unquoted heredoc delimiter", async () => {
+      const cmd = "cat << EOF\n/etc/hosts\nEOF";
+      const result = await extractExternalPathsFromBashCommand(cmd, cwd);
+      expect(result).toHaveLength(0);
+    });
+
+    test("flags real path alongside heredoc but not heredoc content", async () => {
+      const cmd = "cat /etc/hosts << 'EOF'\nsome content\nEOF";
+      const result = await extractExternalPathsFromBashCommand(cmd, cwd);
+      expect(result).toContain("/etc/hosts");
+      expect(result).toHaveLength(1);
+    });
+
+    test("does not flag path inside indented heredoc (<<-)", async () => {
+      const cmd = "cat <<- 'EOF'\n\t/etc/hosts\nEOF";
+      const result = await extractExternalPathsFromBashCommand(cmd, cwd);
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe("defense-in-depth guards with tree-sitter", () => {
+    test("env assignment is a variable_assignment node, not a command argument", async () => {
+      // tree-sitter parses FOO=/usr/local/bin as a variable_assignment node.
+      // The walker skips variable_assignment, so the env-assignment guard in
+      // classifyTokenAsPathCandidate is defense-in-depth.
+      const result = await extractExternalPathsFromBashCommand(
+        "FOO=/usr/local/bin command",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("URL is a word argument, classifyTokenAsPathCandidate rejects it", async () => {
+      // tree-sitter emits the URL as a plain word argument.
+      // classifyTokenAsPathCandidate's URL pattern must still reject it.
+      const result = await extractExternalPathsFromBashCommand(
+        "curl https://example.com/etc/hosts",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+
+    test("flag arguments are word nodes, classifyTokenAsPathCandidate rejects them", async () => {
+      // tree-sitter emits '-la' as a word argument.
+      // classifyTokenAsPathCandidate's flag check must still reject it.
+      const result = await extractExternalPathsFromBashCommand(
+        "ls -la --color=auto",
+        cwd,
+      );
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe("command substitution", () => {
+    test("detects path inside command substitution", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        "echo $(cat /etc/hosts)",
+        cwd,
+      );
+      expect(result).toContain("/etc/hosts");
+    });
+
+    test("detects path inside nested command substitution", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        "echo $(echo $(cat /etc/hosts))",
+        cwd,
+      );
+      expect(result).toContain("/etc/hosts");
+    });
+
+    test("does not flag command substitution inside single-quoted heredoc", async () => {
+      // Single-quoted heredoc delimiter prevents expansion — content is literal.
+      const cmd = "cat << 'EOF'\n$(cat /etc/hosts)\nEOF";
+      const result = await extractExternalPathsFromBashCommand(cmd, cwd);
+      expect(result).toHaveLength(0);
+    });
+
+    test("detects path in subshell", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        "(cat /etc/hosts)",
+        cwd,
+      );
+      expect(result).toContain("/etc/hosts");
+    });
+  });
+
+  describe("redirect targets", () => {
+    test("detects path in output redirect", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        "echo hello > /tmp/out.txt",
+        cwd,
+      );
+      expect(result).toContain("/tmp/out.txt");
+    });
+
+    test("detects path in append redirect", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        "echo hello >> /tmp/out.txt",
+        cwd,
+      );
+      expect(result).toContain("/tmp/out.txt");
+    });
+
+    test("detects path in input redirect", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        "sort < /etc/hosts",
+        cwd,
+      );
+      expect(result).toContain("/etc/hosts");
+    });
+
+    test("detects path in stderr redirect", async () => {
+      const result = await extractExternalPathsFromBashCommand(
+        "command 2>/tmp/errors.log",
+        cwd,
+      );
+      expect(result).toContain("/tmp/errors.log");
+    });
+  });
+
   describe("deduplication", () => {
-    test("returns deduplicated paths", () => {
-      const result = extractExternalPathsFromBashCommand(
+    test("returns deduplicated paths", async () => {
+      const result = await extractExternalPathsFromBashCommand(
         "cat /etc/hosts; grep foo /etc/hosts",
         cwd,
       );