@loophubs/agent-guard 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loophubs/agent-guard",
-  "version": "0.2.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,17 +1,30 @@
 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"]);
-const codePrograms = new Set(["python", "python3", "node", "bun", "deno", "ruby", "perl", "php", "osascript", "lua"]);
+const shellPrograms = new Set(["sh", "bash", "zsh", "dash", "ksh", "csh", "tcsh"]);
 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))$/;
 
-export function resolveCommand(cmd: Command, home: string): { children: string[]; code: string[] } {
+// egrep and fgrep are grep with a fixed matcher.
+export function programName(text: string): string {
+  const name = basename(text);
+  return name === "egrep" || name === "fgrep" ? "grep" : name;
+}
+
+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;
@@ -58,6 +71,31 @@ export function resolveCommand(cmd: Command, home: string): { children: string[]
         if (w[i]?.text === "-n" || w[i]?.text === "--adjustment") i += 2;
         else if (/^(-n|--adjustment=|-\d)/.test(w[i]?.text ?? "")) i++;
         break;
+      case "sudo":
+      case "doas":
+        w[i++]!.role = "precommand";
+        while (i < w.length && w[i]!.text !== "--" && (w[i]!.text.startsWith("-") || /^[A-Za-z_][A-Za-z0-9_]*=/.test(w[i]!.text))) {
+          if (sudoValueOption.test(w[i]!.text)) w[++i]!.role = "precommand";
+          w[i++]!.role = "precommand";
+        }
+        if (w[i]?.text === "--") w[i++]!.role = "precommand";
+        break;
+      case "script":
+        // script [-adkpqr] [-F pipe] [-t time] [file [command ...]]
+        w[i++]!.role = "precommand";
+        while (w[i]?.text?.startsWith("-")) {
+          if (["-F", "-t"].includes(w[i]!.text)) i++;
+          i++;
+        }
+        if (w[i]) w[i++]!.role = "precommand";
+        break;
+      case "arch":
+        w[i++]!.role = "precommand";
+        while (w[i]?.text?.startsWith("-")) {
+          if (["-e", "-d", "-arch"].includes(w[i]!.text)) i++;
+          i++;
+        }
+        break;
       case "stdbuf":
         w[i++]!.role = "precommand";
         while (/^-[ioe]/.test(w[i]?.text ?? "")) {
@@ -99,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++;
@@ -130,22 +168,32 @@ export function resolveCommand(cmd: Command, home: string): { children: string[]
   cmd.program = i;
   w[i]!.role = "program";
   if (w[i]!.text.startsWith("=") && w[i]!.text.length > 1) w[i]!.text = w[i]!.text.slice(1);
-  const name = basename(w[i]!.text);
+  const name = programName(w[i]!.text);
   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("=");
@@ -165,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++) {
@@ -179,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 };
 }
@@ -199,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

@@ -5,7 +5,7 @@ import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
-import type { Assign, BinaryCmd, CallExpr, CmdSubst, DeclClause, IfClause, Lit, Node, ParamExp, Redirect as RedirectNode, Stmt, Subshell, Word as WordNode } from "mvdan-sh";
+import type { Assign, BinaryCmd, CallExpr, CmdSubst, DeclClause, FuncDecl, IfClause, Lit, Node, ParamExp, Redirect as RedirectNode, Stmt, Subshell, Word as WordNode } from "mvdan-sh";
 import sh from "mvdan-sh";
 
 import { resolveCommand, stdinKind } from "./argv";
@@ -13,7 +13,7 @@ import { misreadComment } from "./comments";
 import { boundedDirectories } from "./cwd";
 import { movedOnSuccess } from "./moves";
 import { expandHome } from "./paths";
-import { xargsReplacements } from "./pipeline";
+import { markWalkedInput, shellInput, xargsHereInput, xargsReplacements } from "./pipeline";
 import type { Command, Redirect, Script, Word } from "./record";
 import { readWord } from "./words";
 
@@ -40,6 +40,10 @@ interface Scope {
 
 const type = (node: Node) => syntax.NodeType(node);
 
+// A function call runs the body in the caller's shell; bound the work a chain of
+// calls can multiply.
+const maxFunctionRuns = 256;
+
 export function parseScript(source: string, cwd: string, home: string): Script {
   const script: Script = { commands: [], uninspectable: [], parseFailed: false };
 
@@ -60,6 +64,10 @@ export function parseScript(source: string, cwd: string, home: string): Script {
     for (const stmt of file.Stmts) statement(stmt!, scope);
   }
 
+  const functions = new Map<string, { body: Stmt; slice: Scope["slice"] }>();
+  const running = new Set<string>();
+  let functionRuns = 0;
+
   const text = (node: Node, scope: Scope) => scope.slice(node.Pos().Offset(), node.End().Offset());
   // A cd inside runs in a separate shell and leaves this scope's cwd alone.
   const isolated = (scope: Scope): Scope => ({ ...scope, dir: { ...scope.dir }, vars: new Map(scope.vars) });
@@ -97,16 +105,26 @@ export function parseScript(source: string, cwd: string, home: string): Script {
       scope.dir.alternatives = boundedDirectories(scope.dir.cwd, [...(scope.dir.alternatives ?? []), ...old], home);
       return;
     }
-    statement(cmd.Y!, op === "||" ? failed : op === "&&" ? scope : isolated(scope));
-    if (op === "|") for (const item of xargsReplacements(script.commands.slice(start, middle), script.commands.slice(middle))) parse(item.source, item.cwd);
-    if (op === "||") {
-      scope.dir.alternatives = boundedDirectories(scope.dir.cwd, [...(scope.dir.alternatives ?? []), failed.dir.cwd, ...(failed.dir.alternatives ?? [])], home);
+    // zsh runs the last element of a pipeline in this shell and bash forks it,
+    // so a cd there may or may not move the commands after it.
+    const right = op === "||" ? failed : op === "&&" ? scope : isolated(scope);
+    statement(cmd.Y!, right);
+    if (op === "|" || op === "|&") {
+      const left = script.commands.slice(start, middle);
+      const rest = script.commands.slice(middle);
+      markWalkedInput(left, rest);
+      for (const item of [...xargsReplacements(left, rest), ...shellInput(left, rest)]) parse(item.source, item.cwd);
     }
+    if (op !== "&&") scope.dir.alternatives = boundedDirectories(scope.dir.cwd, [...(scope.dir.alternatives ?? []), right.dir.cwd, ...(right.dir.alternatives ?? [])], home);
   }
 
   // Compound words may hold substitutions; branch bodies may not run.
   function children(node: Node, scope: Scope) {
-    if (type(node) === "FuncDecl") scope = isolated(scope);
+    if (type(node) === "FuncDecl") {
+      const func = node as FuncDecl;
+      if (func.Name && func.Body) functions.set(func.Name.Value, { body: func.Body, slice: scope.slice });
+      scope = isolated(scope);
+    }
     if (type(node) === "IfClause") return conditional(node as IfClause, scope);
     const outer = scope;
     const loop = type(node) === "WhileClause" || type(node) === "ForClause";
@@ -157,7 +175,7 @@ export function parseScript(source: string, cwd: string, home: string): Script {
   }
 
   function word(node: WordNode, scope: Scope): Word {
-    return readWord(node, scope.slice, scope.vars, home, (part, names) => expansions(part, scope, names));
+    return readWord(node, scope.slice, scope.vars, home, scope.dir.cwd, (part, names) => expansions(part, scope, names));
   }
 
   function assign(node: Assign, scope: Scope, role: "assign" | "arg"): Word {
@@ -171,7 +189,7 @@ export function parseScript(source: string, cwd: string, home: string): Script {
       return type(child) !== "Word";
     });
     return {
-      ...(value ?? { expands: false, globs: false, vars: [] }),
+      ...(value ?? { expands: false, globs: false, vars: [], pwd: false }),
       text: `${name}=${value?.text ?? ""}`,
       raw: text(node, scope),
       role,
@@ -180,7 +198,7 @@ export function parseScript(source: string, cwd: string, home: string): Script {
   }
 
   function literal(value: string): Word {
-    return { text: value, raw: value, expands: false, globs: false, vars: [], role: "arg", value };
+    return { text: value, raw: value, expands: false, globs: false, vars: [], role: "arg", value, pwd: false };
   }
 
   function simple(cmd: Node | null, redirs: (RedirectNode | null)[], scope: Scope) {
@@ -208,14 +226,32 @@ export function parseScript(source: string, cwd: string, home: string): Script {
     };
     script.commands.push(command);
     const { children: sources, code } = resolveCommand(command, home);
-    for (const cwd of scope.dir.alternatives ?? []) script.commands.push({ ...command, cwd });
-    for (const src of sources) for (const cwd of [command.cwd, ...(scope.dir.alternatives ?? [])]) parse(src, cwd);
-    script.uninspectable.push(...code);
+    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 { 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;
+    const func = called === undefined ? undefined : functions.get(called);
+    if (func && !running.has(called!)) {
+      if (++functionRuns > maxFunctionRuns) script.parseFailed = true;
+      else {
+        running.add(called!);
+        statement(func.body, { ...scope, slice: func.slice });
+        running.delete(called!);
+      }
     }
     track(command, scope);
   }
@@ -226,13 +262,13 @@ export function parseScript(source: string, cwd: string, home: string): Script {
       const quoted = node.Word!.Parts.some((p) => type(p) !== "Lit" || (p as Lit).Value.includes("\\"));
       const vars: string[] = [];
       if (node.Hdoc && !quoted) expansions(node.Hdoc, scope, vars);
-      return { direction: "heredoc", target: node.Hdoc ? text(node.Hdoc, scope) : "", vars };
+      return { direction: "heredoc", target: node.Hdoc ? text(node.Hdoc, scope) : "", globs: false, vars };
     }
     const target = word(node.Word!, scope);
-    if (op === "<<<") return { direction: "herestring", target: target.text, vars: target.vars };
+    if (op === "<<<") return { direction: "herestring", target: target.text, globs: false, vars: target.vars };
     if ((op === "<&" || op === ">&") && /^(\d+|-)$/.test(target.text)) return undefined;
     const direction = op === "<" || op === "<>" ? "in" : "out";
-    return { direction, target: target.text, vars: [] };
+    return { direction, target: target.text, globs: target.globs, vars: [] };
   }
 
   function track(command: Command, scope: Scope) {
@@ -245,7 +281,7 @@ export function parseScript(source: string, cwd: string, home: string): Script {
     if (!program || !command.shell || !["cd", "pushd"].includes(program.text)) return;
     const args = command.argv.slice(command.program + 1);
     let target = args.find((w) => !w.text.startsWith("-"))?.text;
-    if (target === undefined && (!args.length || (args.length === 1 && args[0]?.text === "--")) && program.text === "cd") target = home;
+    if (target === undefined && args.every((w) => /^(--|-[PLqs]+)$/.test(w.text)) && program.text === "cd") target = home;
     if (target !== undefined) {
       scope.dir.alternatives = boundedDirectories(
         resolve(scope.dir.cwd, target),

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);