@loophubs/agent-guard 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loophubs/agent-guard",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Blocks filesystem scans and credential reads that macOS records as TCC App Data access, and points the agent at a safe alternative.",
   "homepage": "https://github.com/LoopHubs/agent-guard#readme",
   "bugs": {

package/src/argv.ts

@@ -1,11 +1,12 @@
 import { basename, resolve } from "node:path";
 
-import { expandHome } from "./paths";
-import type { Command, Word } from "./record";
-import { searchRoles } from "./search-roles";
+import { interpreterCode, interpreterName } from "./interpreters";
+import { absPath, expandHome } from "./paths";
+import { findRoots } from "./programs";
+import type { Command, Items, Word } from "./record";
+import { searchRoles, showsHidden } from "./search-roles";
 
 const shellPrograms = new Set(["sh", "bash", "zsh", "dash", "ksh", "csh", "tcsh"]);
-const codePrograms = new Set(["python", "python3", "node", "bun", "deno", "ruby", "perl", "php", "osascript", "lua"]);
 const zshBuiltins = new Set(["echo", "printf", "print", "export", "typeset", "declare", "set", "command", "eval", "source", "."]);
 const shellCodeFlag = /^-[a-z]*c[a-z]*$/;
 const sudoValueOption = /^(-[A-Za-z]*[ughpCDRTrtU]|--(user|group|host|prompt|chdir|chroot|role|type|other-user|close-from|command-timeout))$/;
@@ -16,9 +17,14 @@ export function programName(text: string): string {
   return name === "egrep" || name === "fgrep" ? "grep" : name;
 }
 
-export function resolveCommand(cmd: Command, home: string): { children: string[]; code: string[] } {
+export interface Child {
+  source: string;
+  items?: Items;
+}
+
+export function resolveCommand(cmd: Command, home: string): { children: Child[]; code: string[] } {
   const w = cmd.argv;
-  const children: string[] = [];
+  const children: Child[] = [];
   const code: string[] = [];
   let i = 0;
   let shell = true;
@@ -131,7 +137,7 @@ export function resolveCommand(cmd: Command, home: string): { children: string[]
           } else if (["-u", "-P"].includes(arg)) i += 2;
           else if (arg === "-S") {
             // The split string is a command line of its own.
-            children.push(w[i + 1]?.text ?? "");
+            children.push({ source: w[i + 1]?.text ?? "" });
             cmd.wrappers.push("env-S");
             i = w.length;
           } else if (arg.startsWith("-") || arg.includes("=")) i++;
@@ -166,18 +172,28 @@ export function resolveCommand(cmd: Command, home: string): { children: string[]
   const rest = w.slice(i + 1);
   if (["rg", "grep", "ag", "ack"].includes(name)) {
     searchRoles(cmd, rest, name);
+  } else if (name === "find") {
+    for (const [n, word] of rest.entries()) {
+      if (!["-exec", "-execdir", "-ok", "-okdir"].includes(word.text)) continue;
+      const end = rest.findIndex((a, k) => k > n && (a.text === ";" || a.text === "+"));
+      const clause = rest.slice(n + 1, end < 0 ? undefined : end);
+      // find hands the command every name it walks, dotfiles included.
+      children.push({ source: clause.map((a) => a.raw).join(" "), items: { root: absPath(findRoots(rest)[0]?.text ?? ".", cmd.cwd, home), hidden: true } });
+    }
   } else if (name === "fd") {
     let pattern = true;
+    const roots: string[] = [];
     for (let n = 0; n < rest.length; n++) {
       const arg = rest[n]!.text;
       if (["-x", "-X", "--exec", "--exec-batch"].includes(arg)) {
         rest[n]!.role = "option";
-        children.push(
-          rest
+        children.push({
+          source: rest
             .slice(n + 1)
             .map((word) => word.raw)
             .join(" "),
-        );
+          items: { root: absPath(roots[0] ?? ".", cmd.cwd, home), hidden: showsHidden(rest) },
+        });
         break;
       } else if ((/^(--search-path|--base-directory)(=|$)/.test(arg) || arg === "-C") && (arg.includes("=") || rest[n + 1])) {
         const separate = !arg.includes("=");
@@ -197,7 +213,10 @@ export function resolveCommand(cmd: Command, home: string): { children: string[]
       else if (pattern) {
         rest[n]!.role = "pattern";
         pattern = false;
-      } else rest[n]!.role = "path";
+      } else {
+        rest[n]!.role = "path";
+        roots.push(arg);
+      }
     }
   } else if (name === "du") {
     for (let n = 0; n < rest.length; n++) {
@@ -211,16 +230,12 @@ export function resolveCommand(cmd: Command, home: string): { children: string[]
     const flag = rest.findIndex((a) => shellCodeFlag.test(a.text));
     if (flag >= 0) {
       if (rest[flag + 1]) rest[flag + 1]!.role = "code";
-      children.push(rest[flag + 1]?.text ?? "");
+      children.push({ source: rest[flag + 1]?.text ?? "" });
     }
   } else if (name === "eval" && (shell || cmd.wrappers.includes("command"))) {
-    children.push(rest.map((a) => a.text).join(" "));
-  } else if (codePrograms.has(name)) {
-    const flag = rest.findIndex((a) => /^(-[ceE]|--eval)$/.test(a.text));
-    if (flag >= 0) {
-      if (rest[flag + 1]) rest[flag + 1]!.role = "code";
-      code.push(rest[flag + 1]?.text ?? "");
-    }
+    children.push({ source: rest.map((a) => a.text).join(" ") });
+  } else if (interpreterName(name)) {
+    code.push(...interpreterCode(interpreterName(name)!, rest));
   }
   return { children, code };
 }
@@ -231,6 +246,6 @@ export function stdinKind(cmd: Command): "shell" | "code" | undefined {
   const name = basename(program.text);
   const args = cmd.argv.slice(cmd.program + 1);
   if (shellPrograms.has(name) && !args.some((a) => shellCodeFlag.test(a.text))) return "shell";
-  if (codePrograms.has(name)) return "code";
+  if (interpreterName(name)) return "code";
   return undefined;
 }

package/src/core.ts

@@ -1,11 +1,12 @@
 import { parseScript } from "./frontend";
-import { linkedRequest } from "./links";
+import { linkedTargets } from "./links";
 import { absPath } from "./paths";
 import { reasons } from "./reasons";
 import type { Request, Runtime, Tool } from "./record";
 import { appdataRules } from "./rules/appdata";
 import { credentialFilesystemRules, credentialRules } from "./rules/credentials";
 import { claudeWorkflowRules } from "./rules/workflow";
+import { extractTargets } from "./targets";
 
 export function buildRequest(runtime: Runtime, tool: Tool, cwd: string, input: string, glob: string, home: string): Request {
   const inputCwd = cwd || "/";
@@ -38,17 +39,18 @@ export function buildRequest(runtime: Runtime, tool: Tool, cwd: string, input: s
 
 export function evaluate(req: Request): string | undefined {
   if (req.parseFailed) return reasons.syntax;
-  const denials = [...appdataRules(req), ...credentialRules(req)];
+  const targets = extractTargets(req);
+  const denials = [...appdataRules(req, targets), ...credentialRules(req, targets)];
   // Deny lexically protected paths before asking the filesystem about links.
   if (!denials.length) {
     try {
-      const linked = linkedRequest(req);
-      if (linked) denials.push(...appdataRules(linked), ...credentialRules(linked));
+      const linked = linkedTargets(targets, req.home);
+      if (linked) denials.push(...appdataRules(req, linked), ...credentialRules(req, linked));
+      if (!denials.length) denials.push(...credentialFilesystemRules(req, linked ?? targets));
     } catch {
       denials.push(reasons.symlink);
     }
   }
-  if (!denials.length) denials.push(...credentialFilesystemRules(req));
   return denials[0];
 }
 

package/src/docker-targets.ts

@@ -0,0 +1,87 @@
+import type { Context } from "./programs";
+import type { Target, Word } from "./record";
+
+const globalValueOptions = ["-H", "--host", "-c", "--context", "-l", "--log-level", "--config", "--tlscacert", "--tlscert", "--tlskey"];
+
+// The options of `docker run`, `create` and `exec` that take no value; any other option takes the next word unless its value is glued.
+const flagOptions = [
+  "--detach",
+  "--help",
+  "--init",
+  "--interactive",
+  "--no-healthcheck",
+  "--oom-kill-disable",
+  "--privileged",
+  "--publish-all",
+  "--quiet",
+  "--read-only",
+  "--rm",
+  "--sig-proxy",
+  "--tty",
+  "--use-api-socket",
+];
+const flagLetters = "diqPt";
+const composeValueOptions = ["-f", "--file", "-p", "--project-name", "--project-directory", "--profile", "--env-file", "--ansi", "--parallel", "--progress"];
+
+// Where the image (`run`, `create`) or the container (`exec`) is: every word after it belongs to the command run inside the container, not to docker.
+function commandStart(words: Word[], start: number): number {
+  for (let i = start + 1; i < words.length; i++) {
+    const text = words[i]!.text;
+    if (!text.startsWith("-")) return i;
+    if (text.startsWith("--")) {
+      if (!text.includes("=") && !flagOptions.includes(text) && !/^-\D/.test(words[i + 1]?.text ?? "")) i++;
+      continue;
+    }
+    const value = [...text.slice(1)].findIndex((letter) => !flagLetters.includes(letter));
+    if (value >= 0 && value === text.length - 2) i++;
+  }
+  return words.length;
+}
+
+// A bind mount, a copy out of the host, a build secret or an image archive hands a host file to docker; the image, container names and the command run inside it are names.
+export function dockerTargets({ words, make, claimed }: Context): Target[] {
+  const targets: Target[] = [];
+  const mount = (path: string, word: Word, effect: "read" | "write" | "use" = "read", via: "option" | "operand" = "option") => {
+    claimed.add(word);
+    targets.push(make(path, word, effect, { via }));
+  };
+  // The subcommand follows the global options and their values, and a management word such as `container` in `docker container cp`.
+  let start = 0;
+  while (words[start]?.text.startsWith("-")) start += globalValueOptions.includes(words[start]!.text) ? 2 : 1;
+  if (["container", "image", "buildx"].includes(words[start]?.text ?? "")) start++;
+  const sub = words[start]?.text;
+  const end = ["run", "create", "exec"].includes(sub ?? "") ? commandStart(words, start) : words.length;
+  // After a compose subcommand, `-f` is that subcommand's option (`logs -f` follows), not the compose file.
+  let composeSub = start + 1;
+  while (words[composeSub]?.text.startsWith("-")) composeSub += composeValueOptions.includes(words[composeSub]!.text) ? 2 : 1;
+  for (const [i, word] of words.slice(0, end).entries()) {
+    // cp names a container as `name:path`; any other operand is a host path, and the last one is where the copy lands.
+    if (sub === "cp" && i > start && !word.text.startsWith("-") && !/^[\w.-]+:/.test(word.text)) mount(word.text, word, i === words.length - 1 ? "write" : "read", "operand");
+    // A short option's value is glued (`-i.env`, `-vSPEC`, `-v=SPEC`) or the next word; pflag reads the rest of a cluster after the option that takes it.
+    const previous = words[i - 1]?.text;
+    if (sub === "load") {
+      const input = /^(?:--input=|-i)(.+)$/s.exec(word.text)?.[1] ?? (previous === "-i" || previous === "--input" ? word.text : undefined);
+      if (input) mount(input, word);
+    }
+    const secret = word.text.startsWith("--secret=") ? word.text.slice("--secret=".length) : previous === "--secret" ? word.text : undefined;
+    for (const field of secret?.split(",") ?? []) if (/^(src|source)=/.test(field)) mount(field.slice(field.indexOf("=") + 1), word);
+    // The client reads or writes these files itself; `-f` names one only for build and compose.
+    const hostFile =
+      /^--(file|label-file|cidfile|iidfile|tlscacert|tlscert|tlskey|config)(?:=(.*))?$/s.exec(word.text) ??
+      (sub === "build" || (sub === "compose" && i < composeSub) ? /^-[A-Za-z]*?(f)=?(.*)$/s.exec(word.text) : null);
+    if (hostFile) {
+      const holder = hostFile[2] ? word : words[i + 1];
+      if (holder) mount(hostFile[2] || holder.text, holder, ["cidfile", "iidfile"].includes(hostFile[1]!) ? "write" : "use");
+    }
+    const long = /^--(volume|mount)(?:=(.*))?$/s.exec(word.text);
+    const short = /^-[A-Za-z]*?v(=?)(.*)$/s.exec(word.text);
+    const key = long?.[1] ?? (short ? "volume" : undefined);
+    const inline = long ? long[2] : short?.[2];
+    const value = inline ? word : words[i + 1];
+    if (!key || !value) continue;
+    const spec = inline || value.text;
+    if (key === "volume") mount(spec.split(":")[0]!, value);
+    else for (const field of spec.split(",")) if (/^(src|source)=/.test(field)) mount(field.slice(field.indexOf("=") + 1), value);
+  }
+  return targets;
+}

package/src/frontend.ts

@@ -228,13 +228,19 @@ export function parseScript(source: string, cwd: string, home: string): Script {
     const { children: sources, code } = resolveCommand(command, home);
     const moved = (cwd: string) => command.argv.map((w) => (w.pwd ? { ...w, text: w.text.replaceAll(scope.dir.cwd, cwd), value: w.value.replaceAll(scope.dir.cwd, cwd) } : w));
     for (const cwd of scope.dir.alternatives ?? []) script.commands.push({ ...command, cwd, argv: moved(cwd) });
-    for (const src of sources) for (const cwd of [command.cwd, ...(scope.dir.alternatives ?? [])]) parse(src, cwd);
-    script.uninspectable.push(...code);
+    for (const { source, items } of sources) {
+      for (const cwd of [command.cwd, ...(scope.dir.alternatives ?? [])]) {
+        const start = script.commands.length;
+        parse(source, cwd);
+        if (items) for (const child of script.commands.slice(start)) child.items ??= items;
+      }
+    }
+    for (const text of code) script.uninspectable.push({ text, cwd: command.cwd });
     for (const r of redirects) {
       if (r.direction !== "heredoc" && r.direction !== "herestring") continue;
       const stdin = stdinKind(command);
       if (stdin === "shell") parse(r.target, command.cwd);
-      if (stdin === "code") script.uninspectable.push(r.target);
+      if (stdin === "code") script.uninspectable.push({ text: r.target, cwd: command.cwd });
       if (command.wrappers.includes("xargs")) for (const item of xargsHereInput(command, r.target)) parse(item.source, item.cwd);
     }
     const called = command.wrappers.every((w) => w === "time") ? command.argv[command.program]?.text : undefined;

package/src/git-targets.ts

@@ -0,0 +1,125 @@
+import type { Context } from "./programs";
+import type { Effect, Target, Word } from "./record";
+
+// Subcommands that print the content of a file, a commit, or the index.
+const printing = new Set(["show", "diff", "log", "cat-file", "blame", "annotate", "grep", "archive", "format-patch", "whatchanged", "difftool", "diff-index", "diff-tree", "credential"]);
+// Subcommands whose operands are paths that git stages, moves, or inspects without printing them.
+const metadata = new Set(["add", "rm", "mv", "restore", "checkout", "reset", "stash", "check-ignore", "check-attr", "update-index", "ls-files", "status", "clean", "commit"]);
+// Subcommands whose operands are refs, remotes, names, or URLs.
+const names = new Set([
+  "branch",
+  "tag",
+  "remote",
+  "switch",
+  "push",
+  "fetch",
+  "pull",
+  "merge",
+  "rebase",
+  "cherry-pick",
+  "revert",
+  "reflog",
+  "rev-parse",
+  "describe",
+  "bisect",
+  "init",
+  "clone",
+  "submodule",
+  "worktree",
+  "config",
+  "lfs",
+  "sparse-checkout",
+]);
+// Options whose value is a file git reads.
+const pathspecFile = ["--pathspec-from-file"];
+const fileOptions: Record<string, string[]> = {
+  config: ["-f", "--file", "--blob"],
+  commit: ["-F", "--file", ...pathspecFile],
+  tag: ["-F", "--file"],
+  merge: ["-F", "--file"],
+  add: pathspecFile,
+  rm: pathspecFile,
+  restore: pathspecFile,
+  reset: pathspecFile,
+  checkout: pathspecFile,
+  stash: pathspecFile,
+};
+const valueOptions = ["-C", "-c", "--git-dir", "--work-tree", "--namespace", "--exec-path"];
+
+// git grep takes its pattern from -e, or from the first operand; the pattern is text, not a path.
+function grepOperands(operands: Word[], patterns: Word[]): Word[] {
+  const rest: Word[] = [];
+  let patterned = false;
+  let options = true;
+  for (let n = 0; n < operands.length; n++) {
+    const text = operands[n]!.text;
+    if (options && text === "--") options = false;
+    else if (options && text === "-e") {
+      patterned = true;
+      if (operands[n + 1]) patterns.push(operands[++n]!);
+    } else if (options && text === "-f") {
+      // The file holds the patterns; git reads it.
+      patterned = true;
+      if (operands[n + 1]) rest.push(operands[++n]!);
+    } else if (options && text.startsWith("-")) rest.push(operands[n]!);
+    else if (!patterned) {
+      patterned = true;
+      patterns.push(operands[n]!);
+    } else rest.push(operands[n]!);
+  }
+  return rest;
+}
+
+export function gitTargets({ words, make, claimed }: Context): Target[] {
+  const targets: Target[] = [];
+  let i = 0;
+  // Operands are relative to the directory the last -C or --work-tree names.
+  let base: string | undefined;
+  while (i < words.length && words[i]!.text.startsWith("-")) {
+    const glued = /^--work-tree=(.*)$/s.exec(words[i]!.text);
+    const takesValue = !glued && valueOptions.includes(words[i]!.text);
+    const value = glued ? words[i] : words[i + 1];
+    if ((glued || (takesValue && ["-C", "--work-tree"].includes(words[i]!.text))) && value) {
+      claimed.add(value);
+      const target = make(glued ? glued[1]! : value.text, value, "enter", { via: "option", base });
+      targets.push(target);
+      base = target.path;
+    }
+    i += takesValue ? 2 : 1;
+  }
+  const sub = words[i]?.text ?? "";
+  if (words[i]) claimed.add(words[i]!);
+  // Any subcommand git has no group for reads its operands like an unmodelled program.
+  const effect: Effect = printing.has(sub) ? "read" : metadata.has(sub) ? "meta" : names.has(sub) ? "name" : "read";
+  let operands = words.slice(i + 1);
+  if (sub === "grep") {
+    const patterns: Word[] = [];
+    operands = grepOperands(operands, patterns);
+    for (const pattern of patterns) claimed.add(pattern);
+  }
+  const keys = fileOptions[sub] ?? [];
+  // A pathspec holding a glob character is one git expands itself; git grep also reads a directory whole.
+  const pathspec = effect !== "name" && sub !== "grep";
+  const add = (path: string, word: Word, as: Effect, via: "operand" | "option") => {
+    claimed.add(word);
+    const glob = pathspec && /[*?[]/.test(path);
+    targets.push(make(path, word, as, { via, glob, base }));
+    // A rev:path operand names a file in a commit or the index.
+    if (as === "read" && path.includes(":")) targets.push(make(path.slice(path.indexOf(":") + 1), word, as, { via, glob, base }));
+  };
+  // `bundle create FILE` writes FILE; the other bundle subcommands read the bundle they are given.
+  const bundleAction = sub === "bundle" ? operands.find((word) => !word.text.startsWith("-")) : undefined;
+  const bundleFile = bundleAction?.text === "create" ? operands.filter((word) => !word.text.startsWith("-"))[1] : undefined;
+  for (let n = 0; n < operands.length; n++) {
+    const word = operands[n]!;
+    // A value is glued to a long option with = and to a short one directly.
+    const glued = keys.find((key) => (key.startsWith("--") ? word.text.startsWith(`${key}=`) : word.text.length > key.length && word.text.startsWith(key)));
+    if (glued) add(word.text.slice(glued.length + (glued.startsWith("--") ? 1 : 0)), word, "read", "option");
+    else if (keys.includes(word.text) && operands[n + 1]) {
+      const file = operands[++n]!;
+      add(file.text, file, "read", "option");
+    } else if (word === bundleAction) claimed.add(word);
+    else if (!word.text.startsWith("-")) add(word.text, word, word === bundleFile ? "write" : effect, "operand");
+  }
+  return targets;
+}

package/src/guard.ts

@@ -5,6 +5,7 @@
 // working directory, stands in when the event names none. Exit 0 means no
 // objection and exit 2 denies with the reason on stderr. The wrapper turns
 // every other outcome into a denial.
+import { realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
@@ -46,7 +47,9 @@ const [tool, field] = fields[(string(event.tool_name) ?? "Bash").toLowerCase()]
 // Grep searches the working directory when it names no path.
 const value = field && (tool === "grep" && input[field] === undefined ? "" : string(input[field]));
 if (field && value === undefined) throw new Error(`tool_input.${field} is not a string`);
-const request = tool && value !== undefined ? buildRequest(runtime, tool, cwd, value, string(input["glob"]) ?? "", resolve(homedir())) : undefined;
+// The link walk reports physical paths, so a home directory spelled through a link (`/tmp`) is compared by the spelling the walk reports.
+// The home directory is not inside App Data, so resolving it cannot search a protected tree.
+const request = tool && value !== undefined ? buildRequest(runtime, tool, cwd, value, string(input["glob"]) ?? "", realpathSync(resolve(homedir()))) : undefined;
 const reason = request && evaluate(request);
 if (reason) {
   console.error(runtime === "claude" ? `DENIED: ${reason} Do NOT bypass this restriction or retry the same blocked command.` : reason);

package/src/interpreters.ts

@@ -0,0 +1,61 @@
+import type { Word } from "./record";
+
+// Per interpreter: the short flags after which the code follows, in the rest of the cluster when `glued` and in the next word otherwise,
+// and the flags whose value is the rest of the cluster, so a value such as `-rtime` does not read its last letter as a code flag.
+const flags: Record<string, { code: string; value: string; glued: boolean }> = {
+  python: { code: "c", value: "WX", glued: true },
+  python3: { code: "c", value: "WX", glued: true },
+  node: { code: "ep", value: "", glued: false },
+  bun: { code: "ep", value: "", glued: true },
+  ruby: { code: "e", value: "rICEix", glued: true },
+  perl: { code: "eE", value: "MmIidDCFx", glued: true },
+  php: { code: "rR", value: "dcfz", glued: true },
+  osascript: { code: "e", value: "", glued: true },
+  lua: { code: "e", value: "l", glued: true },
+  deno: { code: "", value: "", glued: false },
+};
+
+// The table entry a program name selects, ignoring a version suffix such as `python3.14`.
+export function interpreterName(name: string): string | undefined {
+  return [name, name.replace(/[\d.]+$/, "")].find((candidate) => candidate in flags);
+}
+
+// The code an interpreter runs from its command line: the word after a code flag, the value glued to `--eval=`, or deno's eval operand.
+export function interpreterCode(name: string, args: Word[]): string[] {
+  const { code, value, glued } = flags[name]!;
+  const found: string[] = [];
+  const take = (word: Word | undefined) => {
+    if (!word) return;
+    word.role = "code";
+    found.push(word.text);
+  };
+  if (name === "deno") {
+    // Flags such as `-p` and `--ext=ts` sit between `eval` and the code.
+    // `eval` follows the global flags and the value of a flag such as `--log-level debug`.
+    const operands = args.filter((word) => !word.text.startsWith("-"));
+    const at = operands.slice(0, 2).findIndex((word) => word.text === "eval");
+    if (at >= 0) for (const word of operands.slice(at + 1)) take(word);
+    return found;
+  }
+  for (let i = 0; i < args.length; i++) {
+    const text = args[i]!.text;
+    // node's --run names a package script; only php's takes code.
+    const long = (name === "php" ? /^--(eval|print|run)(=(.*))?$/s : /^--(eval|print)(=(.*))?$/s).exec(text);
+    if (long) {
+      if (long[2] === undefined) take(args[++i]);
+      else found.push(long[3]!);
+      continue;
+    }
+    if (!/^-[^-]/.test(text)) continue;
+    for (let k = 1; k < text.length; k++) {
+      if (value.includes(text[k]!)) break;
+      if (code.includes(text[k]!)) {
+        if (k < text.length - 1 && !glued) continue;
+        if (k < text.length - 1) found.push(text.slice(k + 1));
+        else take(args[++i]);
+        break;
+      }
+    }
+  }
+  return found;
+}

package/src/links.ts

@@ -1,77 +1,71 @@
-import { readlinkSync } from "node:fs";
-import { basename, dirname, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 
-import { programName } from "./argv";
-import { absPath, expandHome, isAppdata, isSensitive } from "./paths";
-import type { Request, Word } from "./record";
-import { dataPrograms } from "./rules/appdata";
+import { isAppdata, isSensitive, unfirmlink } from "./paths";
+import { probes } from "./probes";
+import type { Target } from "./record";
 
-export function linkedRequest(req: Request): Request | undefined {
-  let changed = false;
-  const protectedPath = (path: string) => isAppdata(path, req.home) || isSensitive(path);
-  const linked = (value: string, cwd: string, quoted = false): string => {
-    const input = quoted ? value : expandHome(value, req.home);
-    const absolute = input.startsWith("/") ? input : `${cwd}/${input}`;
-    let path = "/";
-    let parts = absolute.split("/").filter(Boolean);
-    let followed = false;
-    let depth = 0;
-    while (parts.length) {
-      const part = parts.shift()!;
-      path = part === ".." ? dirname(path) : resolve(path, part);
-      // Do not ask the filesystem about a path inside a protected tree.
-      if (protectedPath(path)) {
-        changed = true;
-        return path;
-      }
-      let target: string;
-      try {
-        target = readlinkSync(path);
-      } catch {
-        continue;
-      }
-      if (++depth > 8) throw new Error("Symlink chain exceeds the agent guard limit");
-      const targetPath = target.startsWith("/") ? target : `${dirname(path)}/${target}`;
-      followed = true;
-      changed = true;
-      parts = [...targetPath.split("/").filter(Boolean), ...parts];
-      path = "/";
+// Errors that mean the path is not a link: it names a regular file or directory, or nothing (a component past NAME_MAX cannot exist). Any other
+// failure means the check did not run.
+export const notALink = ["EINVAL", "ENOENT", "ENOTDIR", "ENAMETOOLONG"];
+
+// The directories of the Data volume that are also reached from the root, in the kernel's own table. The kernel resolves `..` from one of them
+// in the root tree, and from any other directory of the Data volume in place. The table is a fixed system file, not a path taken from a command;
+// if it is missing the import fails and the guard denies.
+const firmlinks = new Set(
+  readFileSync("/usr/share/firmlinks", "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((line) => `/system/volumes/data/${line.split("\t")[1]!.toLowerCase()}`),
+);
+
+// Follow the symlinks in an absolute path with readlink alone, so a link into a protected tree is judged by where it leads. A path for which
+// `stopAt` holds is returned at the point it is reached, because the filesystem is not asked about anything beyond it.
+export function followLinks(absolute: string, home: string, stopAt = (path: string) => isAppdata(path, home) || isSensitive(path)): string {
+  let path = "/";
+  let parts = absolute.split("/").filter(Boolean);
+  let followed = false;
+  let depth = 0;
+  while (parts.length) {
+    const part = parts.shift()!;
+    // The walk keeps the physical spelling, because `..` after the firmlink prefix leaves it, and only the check and the result use the plain one.
+    path = part === ".." ? dirname(firmlinks.has(path.toLowerCase()) ? unfirmlink(path) : path) : resolve(path, part);
+    if (stopAt(unfirmlink(path))) return unfirmlink(path);
+    let target: string;
+    try {
+      target = probes.readlink(path);
+    } catch (error) {
+      if (notALink.includes((error as NodeJS.ErrnoException).code ?? "")) continue;
+      throw error;
     }
-    return followed ? path : value;
-  };
-  const word = (w: Word, cwd: string): Word => {
-    if (w.expands || w.globs || !w.value || w.value.startsWith("-")) return w;
-    if (w.role === "program" && !w.value.includes("/")) return w;
-    if (!["arg", "path", "patfile", "option:patfile", "program"].includes(w.role)) return w;
-    const value = linked(w.value, cwd, /^['"]/.test(w.raw));
-    return value === w.value ? w : { ...w, value, text: w.role.startsWith("option:") ? w.text : value };
-  };
-  // curl reads the file after @ or < in a data or form value, or one glued to -T, -K, --upload-file or --config.
-  const curlOperand = /^((?:-[A-Za-z]|--[a-z-]+=|[^=@<-][^=@<]*=)?[@<])([^;]+)(.*)$/s;
-  const curlFile = /^(-[TK]|--(?:upload-file|config)=)([^;]+)()$/s;
-  const curlWord = (w: Word, cwd: string): Word | undefined => {
-    const operand = curlOperand.exec(w.text) ?? curlFile.exec(w.text);
-    if (!operand || w.expands) return undefined;
-    const value = linked(operand[2]!, cwd);
-    return value === operand[2] ? w : { ...w, text: `${operand[1]}${value}${operand[3]}` };
-  };
-  const commands = req.commands.map((cmd) => {
-    const curl = cmd.program >= 0 && programName(cmd.argv[cmd.program]!.text) === "curl";
-    const checkedCwd = linked(cmd.cwd, "/");
-    const cwd = checkedCwd === cmd.cwd ? absPath(cmd.cwd, "/", req.home) : checkedCwd;
-    if (cwd !== cmd.cwd) changed = true;
-    return {
-      ...cmd,
-      cwd,
-      argv: cmd.argv.map((w, i) =>
-        dataPrograms.has(basename(cmd.argv[cmd.program]?.text ?? "")) && i > cmd.program ? w : curl && i > cmd.program ? (curlWord(w, cmd.cwd) ?? word(w, cmd.cwd)) : word(w, cmd.cwd),
-      ),
-      redirects: cmd.redirects.map((r) => ((r.direction === "in" || r.direction === "out") && r.target ? { ...r, target: linked(r.target, cmd.cwd) } : r)),
-    };
+    if (++depth > 8) throw new Error("Symlink chain exceeds the agent guard limit");
+    const targetPath = target.startsWith("/") ? target : `${dirname(path)}/${target}`;
+    followed = true;
+    parts = [...targetPath.split("/").filter(Boolean), ...parts];
+    path = "/";
+  }
+  return followed ? unfirmlink(path) : absolute;
+}
+
+// The path a glob target names up to its first wildcard segment: only that prefix exists as a path before the shell expands the rest.
+function followGlob(absolute: string, home: string): string {
+  const segments = absolute.split("/");
+  const wildcard = segments.findIndex((segment) => /[*?[{]/.test(segment));
+  if (wildcard < 0) return followLinks(absolute, home);
+  const prefix = segments.slice(0, wildcard).join("/") || "/";
+  const followed = followLinks(prefix, home);
+  return followed === prefix ? absolute : [followed === "/" ? "" : followed, ...segments.slice(wildcard)].join("/");
+}
+
+// Returns the same targets with followed paths replaced, or undefined when no path changed.
+export function linkedTargets(targets: Target[], home: string): Target[] | undefined {
+  let changed = false;
+  const result = targets.map((target) => {
+    if (target.expands || target.effect === "name" || (target.via === "tool" && target.glob)) return target;
+    const path = target.glob ? followGlob(target.unresolved, home) : followLinks(target.unresolved, home);
+    if (path === target.unresolved) return target;
+    changed = true;
+    return { ...target, path, unresolved: path };
   });
-  const checkedCwd = linked(req.inputCwd, "/");
-  const cwd = checkedCwd === req.inputCwd ? req.cwd : checkedCwd;
-  const target = req.target ? linked(req.pathInput, req.inputCwd) : req.target;
-  const searchRoot = req.searchRoot ? linked(req.pathInput || req.inputCwd, req.inputCwd) : req.searchRoot;
-  return changed ? { ...req, cwd, target, searchRoot, commands } : undefined;
+  return changed ? result : undefined;
 }