@loophubs/agent-guard 0.1.0

package/src/frontend.ts

@@ -0,0 +1,240 @@
+// Parse shell structure into command records; rejected syntax remains
+// available to the signature rules.
+import sh from "mvdan-sh";
+import type { Assign, BinaryCmd, CallExpr, CmdSubst, DeclClause, IfClause, Lit, Node, ParamExp, Redirect as RedirectNode, Stmt, Subshell, Word as WordNode } from "mvdan-sh";
+import { resolve } from "node:path";
+import { resolveCommand, stdinKind } from "./argv.ts";
+import { misreadComment } from "./comments.ts";
+import { boundedDirectories } from "./cwd.ts";
+import { movedOnSuccess } from "./moves.ts";
+import { expandHome } from "./paths.ts";
+import { xargsReplacements } from "./pipeline.ts";
+import type { Command, Redirect, Script, Word } from "./record.ts";
+import { readWord } from "./words.ts";
+
+const { syntax } = sh;
+const parser = syntax.NewParser(syntax.KeepComments(true), syntax.Variant(syntax.LangBash));
+
+interface Scope {
+  readonly dir: { cwd: string; previous?: string; alternatives?: string[] }; // shared by the commands a cd in this scope moves
+  readonly vars: Map<string, string>;
+  readonly slice: (start: number, end: number) => string;
+}
+
+const type = (node: Node) => syntax.NodeType(node);
+
+export function parseScript(source: string, cwd: string, home: string): Script {
+  const script: Script = { commands: [], uninspectable: [] };
+
+  function parse(src: string, cwd: string) {
+    const bytes = Buffer.from(src);
+    let file;
+    try {
+      file = parser.Parse(src, "");
+    } catch {
+      file = undefined;
+    }
+    if (!file || misreadComment(file, bytes)) {
+      script.uninspectable.push(src);
+      return;
+    }
+    const slice = (start: number, end: number) => bytes.subarray(start, end).toString();
+    const scope: Scope = { dir: { cwd }, vars: new Map(), slice };
+    for (const stmt of file.Stmts) statement(stmt, scope);
+  }
+
+  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) });
+
+  function statement(stmt: Stmt, outer: Scope) {
+    const scope = stmt.Background ? isolated(outer) : outer;
+    const cmd = stmt.Cmd;
+    const kind = cmd && type(cmd);
+    if (kind === "CallExpr" || kind === "DeclClause") return simple(cmd, stmt.Redirs, scope);
+    // Redirections on a compound command, or with no command at all, still
+    // open their files.
+    if (stmt.Redirs.length) simple(null, stmt.Redirs, scope);
+    if (!cmd) return;
+    if (kind === "BinaryCmd") return binary(cmd as BinaryCmd, scope);
+    if (kind === "Subshell") {
+      const inner = isolated(scope);
+      for (const s of (cmd as Subshell).Stmts) statement(s, inner);
+      return;
+    }
+    children(cmd, scope);
+  }
+
+  // Only the left side of && moves the directory the right side runs in.
+  function binary(cmd: BinaryCmd, scope: Scope) {
+    const op = scope.slice(cmd.OpPos.Offset(), cmd.OpPos.Offset() + 2).trim();
+    const failed = isolated(scope);
+    const start = script.commands.length;
+    statement(cmd.X, op === "&&" || op === "||" ? scope : isolated(scope));
+    const middle = script.commands.length;
+    const directCd = op === "&&" && movedOnSuccess(cmd.X, scope.slice);
+    if (directCd) {
+      const old = [failed.dir.cwd, ...(failed.dir.alternatives ?? [])];
+      scope.dir.alternatives = scope.dir.alternatives?.filter((cwd) => !old.includes(cwd));
+      statement(cmd.Y, scope);
+      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);
+    }
+  }
+
+  // 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) === "IfClause") return conditional(node as IfClause, scope);
+    const outer = scope;
+    const loop = type(node) === "WhileClause" || type(node) === "ForClause";
+    if (loop) scope = isolated(scope);
+    syntax.Walk(node, (child) => {
+      if (!child || child === node) return true;
+      const kind = type(child);
+      if (kind === "Stmt") statement(child as Stmt, scope);
+      else if (kind === "Word") {
+        const value = word(child as WordNode, scope);
+        for (const cwd of [scope.dir.cwd, ...(scope.dir.alternatives ?? [])]) {
+          script.commands.push({ argv: [value], redirects: [], cwd, program: -1, wrappers: [], shell: true, flags: new Set() });
+        }
+      }
+      else return true;
+      return false;
+    });
+    if (loop) outer.dir.alternatives = boundedDirectories(outer.dir.cwd, [...(outer.dir.alternatives ?? []), scope.dir.cwd, ...(scope.dir.alternatives ?? [])], home);
+  }
+
+  function conditional(node: IfClause, scope: Scope) {
+    const condition = isolated(scope);
+    for (const stmt of node.Cond) statement(stmt, condition);
+    const then = isolated(condition);
+    for (const stmt of node.Then) statement(stmt, then);
+    const branches = [scope, condition, then];
+    if (node.Else) {
+      const otherwise = isolated(condition);
+      conditional(node.Else, otherwise);
+      branches.push(otherwise);
+    }
+    scope.dir.alternatives = boundedDirectories(scope.dir.cwd, branches.flatMap((branch) => [branch.dir.cwd, ...(branch.dir.alternatives ?? [])]), home);
+  }
+
+  function expansions(node: Node, scope: Scope, vars: string[]) {
+    syntax.Walk(node, (child) => {
+      if (!child) return true;
+      const kind = type(child);
+      if (kind === "ParamExp") vars.push((child as ParamExp).Param.Value);
+      if (kind !== "CmdSubst" && kind !== "ProcSubst") return true;
+      const inner = isolated(scope);
+      for (const s of (child as CmdSubst).Stmts) statement(s, inner);
+      return false;
+    });
+  }
+
+  function word(node: WordNode, scope: Scope): Word {
+    return readWord(node, scope.slice, scope.vars, home, (part, names) => expansions(part, scope, names));
+  }
+
+  function assign(node: Assign, scope: Scope, role: "assign" | "arg"): Word {
+    const name = node.Name?.Value ?? "";
+    const value = node.Value ? word(node.Value, scope) : undefined;
+    // Array and index expressions can hold substitutions outside the value.
+    syntax.Walk(node, (child) => {
+      if (!child || child === node) return true;
+      if (child === node.Value) return false;
+      if (type(child) === "Word") word(child as WordNode, scope);
+      return type(child) !== "Word";
+    });
+    return {
+      ...(value ?? { expands: false, globs: false, vars: [] }),
+      text: `${name}=${value?.text ?? ""}`,
+      raw: text(node, scope),
+      role,
+      value: `${name}=${value?.text ?? ""}`,
+    };
+  }
+
+  function literal(value: string): Word {
+    return { text: value, raw: value, expands: false, globs: false, vars: [], role: "arg", value };
+  }
+
+  function simple(cmd: Node | null, redirs: RedirectNode[], scope: Scope) {
+    const argv: Word[] = [];
+    if (cmd && type(cmd) === "CallExpr") {
+      for (const a of (cmd as CallExpr).Assigns) argv.push(assign(a, scope, "assign"));
+      for (const w of (cmd as CallExpr).Args) argv.push(word(w, scope));
+    } else if (cmd) {
+      const decl = cmd as DeclClause;
+      argv.push(literal(decl.Variant.Value));
+      for (const a of decl.Args) {
+        if (!a.Naked) argv.push(assign(a, scope, "arg"));
+        else argv.push(a.Value ? word(a.Value, scope) : literal(a.Name?.Value ?? ""));
+      }
+    }
+    const redirects = redirs.map((r) => redirect(r, scope)).filter((r) => r !== undefined);
+    const command: Command = {
+      argv,
+      redirects,
+      cwd: scope.dir.cwd,
+      program: -1,
+      wrappers: [],
+      shell: true,
+      flags: new Set(),
+    };
+    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);
+    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);
+    }
+    track(command, scope);
+  }
+
+  function redirect(node: RedirectNode, scope: Scope): Redirect | undefined {
+    const op = scope.slice(node.OpPos.Offset(), node.Word.Pos().Offset()).trim();
+    if (op === "<<" || op === "<<-") {
+      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 };
+    }
+    const target = word(node.Word, scope);
+    if (op === "<<<") return { direction: "herestring", target: target.text, vars: target.vars };
+    if ((op === "<&" || op === ">&") && /^(\d+|-)$/.test(target.text)) return undefined;
+    const direction = op === "<" || op === "<>" ? "in" : "out";
+    return { direction, target: target.text, vars: [] };
+  }
+
+  function track(command: Command, scope: Scope) {
+    const program = command.argv[command.program];
+    const declaration = command.shell && ["export", "local", "declare", "typeset"].includes(program?.text ?? "");
+    for (const word of command.argv.filter((w) => ((command.program < 0 && w.role === "precommand") || (declaration && w.role === "arg")) && /^[A-Za-z_][A-Za-z0-9_]*=/.test(w.text))) {
+      const at = word.text.indexOf("=");
+      if (!word.expands) scope.vars.set(word.text.slice(0, at), expandHome(word.text.slice(at + 1), home));
+    }
+    if (!program || !command.shell || !["cd", "pushd"].includes(program.text)) return;
+    let target = command.argv.slice(command.program + 1).find((w) => !w.text.startsWith("-"))?.text;
+    const previous = command.argv.slice(command.program + 1).some((w) => w.text === "-");
+    if (previous) target = scope.dir.previous;
+    if (previous && target === undefined) return;
+    if (target === undefined && program.text === "cd") target = home;
+    if (target !== undefined) {
+      scope.dir.alternatives = boundedDirectories(resolve(scope.dir.cwd, target), [scope.dir.cwd, ...(scope.dir.alternatives ?? []), ...(scope.dir.alternatives ?? []).map((cwd) => resolve(cwd, target))], home);
+      scope.dir.previous = scope.dir.cwd;
+      scope.dir.cwd = resolve(scope.dir.cwd, target);
+    }
+  }
+
+  parse(source, cwd);
+  return script;
+}

package/src/guard.ts

@@ -0,0 +1,41 @@
+// Entry of the agent guard, run by bin/agent-guard:
+//   bun guard.ts --runtime claude|codex|pi --cwd HOOK_DIR < event.json
+// The event is a PreToolUse event in Claude's shape; Codex sends only Bash
+// events, with the cwd possibly inside tool_input. HOOK_DIR, the hook's own
+// 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 { homedir } from "node:os";
+import { buildRequest, evaluate, suggestions } from "./core.ts";
+import type { Runtime, Tool } from "./record.ts";
+
+const [flag, runtime, cwdFlag, hookCwd] = process.argv.slice(2) as [string, Runtime, string, string];
+if (flag !== "--runtime" || !["claude", "codex", "pi"].includes(runtime) || cwdFlag !== "--cwd" || !hookCwd) {
+  console.error("usage: agent-guard --runtime claude|codex|pi < event.json");
+  process.exit(2);
+}
+
+// A missing tool_input throws, which the wrapper turns into a denial. A
+// tool_input without the field a tool needs names nothing to check and passes.
+const event: { tool_name?: unknown; cwd?: unknown; tool_input: Record<string, unknown> } = JSON.parse(await Bun.stdin.text());
+const input = event.tool_input;
+const string = (value: unknown) => (typeof value === "string" ? value : undefined);
+const cwd = string(event.cwd) ?? string(input.cwd) ?? hookCwd;
+
+const tools: Record<string, [Tool, string | undefined]> = {
+  bash: ["bash", string(input.command)],
+  read: ["read", string(input.file_path)],
+  edit: ["edit", string(input.file_path)],
+  write: ["write", string(input.file_path)],
+  grep: ["grep", string(input.path) ?? ""],
+};
+const [tool, value] = tools[(string(event.tool_name) ?? "Bash").toLowerCase()] ?? [];
+const request = tool && value !== undefined ? buildRequest(runtime, tool, cwd, value, string(input.glob) ?? "", 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);
+  process.exitCode = 2;
+} else if (request) {
+  const advice = suggestions(request);
+  if (advice.length) console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", additionalContext: advice.join("\n") } }));
+}

package/src/links.ts

@@ -0,0 +1,59 @@
+import { readlinkSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { expandHome, isAppdata, isSensitive } from "./paths.ts";
+import type { Request, Word } from "./record.ts";
+import { dataPrograms } from "./rules/appdata.ts";
+
+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) {
+      path = resolve(path, parts.shift()!);
+      // 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 = resolve(dirname(path), target);
+      followed = true;
+      changed = true;
+      if (protectedPath(targetPath)) return targetPath;
+      const next = resolve(targetPath, ...parts);
+      if (protectedPath(next)) return next;
+      parts = next.split("/").filter(Boolean);
+      path = "/";
+    }
+    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 };
+  };
+  const commands = req.commands.map((cmd) => ({
+    ...cmd,
+    argv: cmd.argv.map((w, i) =>
+      dataPrograms.has(basename(cmd.argv[cmd.program]?.text ?? "")) && i > cmd.program ? w : 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),
+  }));
+  const target = req.target ? linked(req.target, req.cwd) : req.target;
+  const searchRoot = req.searchRoot ? linked(req.searchRoot, req.cwd) : req.searchRoot;
+  return changed ? { ...req, target, searchRoot, commands } : undefined;
+}

package/src/moves.ts

@@ -0,0 +1,28 @@
+import sh from "mvdan-sh";
+import type { BinaryCmd, CallExpr, Lit, Stmt } from "mvdan-sh";
+
+// Discard the prior cwd only when every move in an && chain has a literal destination.
+export function movedOnSuccess(stmt: Stmt, slice: (start: number, end: number) => string): boolean {
+  const type = sh.syntax.NodeType;
+  const state = (item: Stmt): "moved" | "unchanged" | "uncertain" => {
+    const node = item.Cmd;
+    if (!node) return "unchanged";
+    if (type(node) === "CallExpr") {
+      const call = node as CallExpr;
+      const first = call.Args[0]?.Parts[0];
+      const name = first && type(first) === "Lit" ? (first as Lit).Value : "";
+      if (name === "popd") return "uncertain";
+      if (name !== "cd" && name !== "pushd") return "unchanged";
+      const target = call.Args[1];
+      const part = target?.Parts[0];
+      return target?.Parts.length === 1 && part && type(part) === "Lit" && (part as Lit).Value !== "-" ? "moved" : "uncertain";
+    }
+    if (type(node) !== "BinaryCmd") return "uncertain";
+    const chain = node as BinaryCmd;
+    if (slice(chain.OpPos.Offset(), chain.OpPos.Offset() + 2) !== "&&") return "uncertain";
+    const left = state(chain.X);
+    const right = state(chain.Y);
+    return left === "uncertain" || right === "uncertain" ? "uncertain" : left === "moved" || right === "moved" ? "moved" : "unchanged";
+  };
+  return state(stmt) === "moved";
+}

package/src/mvdan-sh.d.ts

@@ -0,0 +1,92 @@
+// The mvdan-sh package ships no types. This declares only the AST subset the
+// front end reads, so the package needs no type dependency. Positions are
+// UTF-8 byte offsets into the parsed source.
+declare module "mvdan-sh" {
+  export interface Pos {
+    Offset(): number;
+  }
+  export interface Node {
+    Pos(): Pos;
+    End(): Pos;
+  }
+  export interface Lit extends Node {
+    Value: string;
+  }
+  export interface Comment extends Node {
+    Hash: Pos;
+  }
+  export interface Word extends Node {
+    Parts: Node[];
+  }
+  export interface Assign extends Node {
+    Naked: boolean;
+    Name: Lit | null;
+    Value: Word | null;
+  }
+  export interface Redirect extends Node {
+    OpPos: Pos;
+    Word: Word;
+    Hdoc: Word | null;
+  }
+  export interface Stmt extends Node {
+    Cmd: Node | null;
+    Background: boolean;
+    Redirs: Redirect[];
+  }
+  export interface File extends Node {
+    Stmts: Stmt[];
+  }
+  export interface CallExpr extends Node {
+    Assigns: Assign[];
+    Args: Word[];
+  }
+  export interface DeclClause extends Node {
+    Variant: Lit;
+    Args: Assign[];
+  }
+  export interface BinaryCmd extends Node {
+    OpPos: Pos;
+    X: Stmt;
+    Y: Stmt;
+  }
+  export interface Subshell extends Node {
+    Stmts: Stmt[];
+  }
+  export interface IfClause extends Node {
+    Cond: Stmt[];
+    Then: Stmt[];
+    Else: IfClause | null;
+  }
+  export interface SglQuoted extends Node {
+    Dollar: boolean;
+    Value: string;
+  }
+  export interface DblQuoted extends Node {
+    Parts: Node[];
+  }
+  export interface ParamExp extends Node {
+    Excl: boolean;
+    Length: boolean;
+    Width: boolean;
+    Param: Lit;
+    Index: Node | null;
+    Slice: object | null;
+    Repl: object | null;
+    Exp: object | null;
+  }
+  export interface CmdSubst extends Node {
+    Stmts: Stmt[];
+  }
+
+  const sh: {
+    syntax: {
+      NewParser(...options: unknown[]): { Parse(source: string, name: string): File };
+      NodeType(node: Node): string;
+      Walk(node: Node, visit: (node: Node | null) => boolean): void;
+      KeepComments(keep: boolean): unknown;
+      Variant(language: unknown): unknown;
+      LangBash: unknown;
+    };
+  };
+  export default sh;
+}

package/src/paths.ts

@@ -0,0 +1,149 @@
+// Filesystem checks run after lexical denials to avoid touching protected trees.
+import { statSync, realpathSync } from "node:fs";
+import { userInfo } from "node:os";
+import { basename, dirname, resolve } from "node:path";
+
+export const appdataTrees = ["Containers", "Group Containers", "Mobile Documents", "CloudStorage"];
+
+// The one list of credential-bearing paths, matched against absolute paths.
+export const sensitivePaths = [
+  "**/.env", "**/.env.local*", "**/.env.*.local",
+  "**/.env.production", "**/.env.staging", "**/.env.development",
+  "**/.npmrc", "**/.zprofile*", "**/.zsh_history*", "**/*.pem", "**/*.key",
+  "**/auth.json*", "**/.credentials.json*", "**/.aws/credentials*",
+  "**/private-keys-v1.d", "**/private-keys-v1.d/**",
+];
+
+const sensitiveGlobs = sensitivePaths.map((path) => new Bun.Glob(path));
+
+export function expandHome(path: string, home: string): string {
+  for (const prefix of ["~", `~${userInfo().username}`]) {
+    if (path === prefix || path.startsWith(`${prefix}/`)) return home + path.slice(prefix.length);
+  }
+  return path;
+}
+
+export function absPath(path: string, cwd: string, home: string, quoted = false): string {
+  if (!quoted) path = expandHome(path, home);
+  return resolve(cwd, path);
+}
+
+export function isAppdata(path: string, home: string, glob = false): boolean {
+  if (glob) {
+    const expanded = Bun.$.braces(path);
+    if (expanded.length > 1) return expanded.some((each) => isAppdata(each, home, true));
+  }
+  const library = `${home}/Library/`.toLowerCase();
+  if (!path.toLowerCase().startsWith(library)) return false;
+  const rest = path.slice(library.length).toLowerCase();
+  if (appdataTrees.some((tree) => rest === tree.toLowerCase() || rest.startsWith(`${tree.toLowerCase()}/`))) return true;
+  if (!glob) return false;
+  const fixed = rest.split(/[*?[]/)[0].replace(/\/$/, "");
+  return fixed !== "" && appdataTrees.some((tree) => tree.toLowerCase().startsWith(fixed));
+}
+
+export function isBroad(path: string, home: string, glob = false): boolean {
+  if (glob) {
+    const expanded = Bun.$.braces(path);
+    if (expanded.length > 1) return expanded.some((each) => isBroad(each, home, true));
+  }
+  path = path.toLowerCase();
+  home = home.toLowerCase();
+  if (path === "/") return true;
+  const trimmed = path.replace(/\/$/, "");
+  if (trimmed === home || trimmed === `${home}/library` || home.startsWith(`${trimmed}/`)) return true;
+  if (!glob) return false;
+  const pattern = new Bun.Glob(path);
+  if ([home, `${home}/library`, ...appdataTrees.flatMap((tree) => [`${home}/library/${tree.toLowerCase()}`, `${home}/library/${tree.toLowerCase()}/x`])].some((candidate) => pattern.match(candidate))) return true;
+  const prefix = path.split(/[*?[]/, 1)[0].replace(/\/$/, "");
+  return path.includes("**") && (prefix === home || prefix === `${home}/library` || home.startsWith(`${prefix}/`));
+}
+
+// ~/.ignore keeps rg and fd out of ~/Library only when they start above it.
+export function isLibrary(path: string, home: string): boolean {
+  return path.toLowerCase() === `${home}/library`.toLowerCase() || isAppdata(path, home);
+}
+
+const sshPublic = (name: string) => /^(config|config\..*|.*\.pub|allowed_signers|known_hosts.*)$/s.test(name);
+
+// Under ~/.ssh only a top-level client config, public key, allowed_signers or
+// known_hosts file is public.
+export function sshPrivate(path: string): boolean {
+  const at = path.lastIndexOf("/.ssh/");
+  if (at < 0 || at + 6 >= path.length) return false;
+  const rest = path.slice(at + 6);
+  return rest.includes("/") || !sshPublic(rest);
+}
+
+// A credential-bearing absolute path, after brace expansion. For an unquoted
+// glob, a pattern counts when it could match a listed name; a bare wildcard
+// does not.
+export function isSensitive(path: string, glob = false): boolean {
+  const expanded = Bun.$.braces(path);
+  if (expanded.length > 1) return expanded.some((each) => isSensitive(each, glob));
+  if (sshPrivate(path) || sensitiveGlobs.some((listed) => listed.match(path))) return true;
+  const base = basename(path);
+  if (!glob || /^[*?]*$/.test(base)) return false;
+  const pattern = new Bun.Glob(base);
+  return sensitivePaths.some((listed) => {
+    const name = basename(listed).replaceAll("*", "x");
+    return !/^x*$/.test(name) && pattern.match(name);
+  });
+}
+
+// A path that does not exist or cannot be searched has no inode to compare.
+function stat(path: string) {
+  try {
+    return statSync(path);
+  } catch {
+    return undefined;
+  }
+}
+
+function sameFile(a: string, b: string): boolean {
+  if (a === b) return true;
+  const x = stat(a);
+  const y = stat(b);
+  return x !== undefined && y !== undefined && x.dev === y.dev && x.ino === y.ino;
+}
+
+function real(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+function kind(path: string): "dir" | "file" | "other" {
+  const st = stat(path);
+  return st?.isDirectory() ? "dir" : st?.isFile() ? "file" : "other";
+}
+
+// Filesystem check for a file tool target, or a search root when search is
+// set. It follows symlinks and compares inodes so a link or a case alias of
+// ~/.ssh resolves to the directory it names.
+export function sshScopeDenied(target: string, home: string, search: boolean): boolean {
+  const ssh = `${home}/.ssh`;
+  const candidates = [...new Set([target, real(target)])];
+  const roots = [...new Set([ssh, real(ssh)])];
+  for (const candidate of candidates) {
+    for (const root of roots) {
+      if (sameFile(candidate, root)) return true;
+      if (search) {
+        for (let parent = root; parent !== "/"; ) {
+          parent = dirname(parent);
+          if (sameFile(candidate, parent)) return true;
+        }
+      }
+      for (let parent = candidate; parent !== "/"; ) {
+        parent = dirname(parent);
+        if (!sameFile(parent, root)) continue;
+        if (parent !== dirname(candidate) || !sshPublic(basename(candidate))) return true;
+        if (kind(target) === "dir") return true;
+        if (search && kind(target) !== "file") return true;
+      }
+    }
+  }
+  return false;
+}

package/src/pipeline.ts

@@ -0,0 +1,26 @@
+import { basename } from "node:path";
+import type { Command } from "./record.ts";
+
+// A literal printf value is known before xargs substitutes it into a command.
+export function xargsReplacements(left: Command[], right: Command[]): { source: string; cwd: string }[] {
+  const printf = left.find((cmd) => cmd.program >= 0 && basename(cmd.argv[cmd.program].text) === "printf");
+  const xargs = right.find((cmd) => cmd.program >= 0 && cmd.wrappers.includes("xargs"));
+  if (!printf || !xargs) return [];
+  const args = printf.argv.slice(printf.program + 1);
+  if (args.length !== 2 || !/^%s(?:\\n)?$/.test(args[0].text)) return [];
+
+  const options = xargs.argv.slice(0, xargs.program);
+  let marker = "";
+  for (let i = 0; i < options.length; i++) {
+    const option = options[i].text;
+    if (option === "-I" || option === "--replace") marker = options[i + 1]?.text ?? "";
+    else if (option.startsWith("-I")) marker = option.slice(2);
+    else if (option.startsWith("--replace=")) marker = option.slice("--replace=".length);
+  }
+  if (!marker) return [];
+  const quote = (value: string) => `'${value.replaceAll("'", "'\\''")}'`;
+  const source = xargs.argv.slice(xargs.program).map((word) =>
+    word.text.includes(marker) ? quote(word.text.replaceAll(marker, args[1].text)) : word.raw,
+  ).join(" ");
+  return [{ source, cwd: xargs.cwd }];
+}

package/src/reasons.ts

@@ -0,0 +1,19 @@
+export const reasons = {
+  appdata: "This reads a protected macOS app-data directory. Name a specific non-sensitive file under ~/Library/Application Support instead, or ask the user to inspect the protected file and share the needed fact.",
+  broad: "A scan rooted at the home directory or ~/Library reaches every app-data entry. Scope the scan to a project path.",
+  file: "This reads a credential or environment file. Read a non-sensitive config file instead; if a fact from this file is needed, ask the user to inspect it and share only that fact.",
+  dump: "This dumps environment or shell variables, including secrets. Name the non-sensitive variable needed and read only that variable.",
+  variable: "This prints the value of a credential variable. Ask the user for the specific non-sensitive fact needed, or let the authorized client consume the credential without printing it.",
+  token: "This prints a Git hosting token. Use auth status without token-display flags; if authentication needs repair, ask the user to update the credential in their terminal.",
+  keychain: "This extracts a password from the macOS Keychain. State the intended use and run the authorized client that consumes it without printing it.",
+  trace: "curl verbose or trace output can print HTTP headers including Authorization. Drop -v and --trace; use a normal curl request for the needed result.",
+  upload: "This sends the contents of a credential file. Send only the required non-sensitive fields explicitly, and let the client obtain authentication from its normal credential source.",
+  ssh: "This reads private material under ~/.ssh. Search public material in the project or request the exact public key or client-config path; ask the user to inspect private material locally if a specific non-sensitive fact is needed.",
+  grepSsh: "Grep would search private ~/.ssh material. Narrow the search to a project directory or an exact public key, client config, allowed_signers, or known_hosts file.",
+  symlink: "The agent guard could not complete its symlink check. Name the direct non-sensitive file outside protected trees, or ask the user to inspect the target locally.",
+  find: "find is harder to scope for this repository's searches. Use fd with a project-root path instead.",
+  replace: "rg -r means --replace. Drop -r; use -n for line numbers, or spell --replace VALUE for an intentional replacement.",
+  include: "rg has no --include flag. Filter files with -g GLOB (for example -g '*.ts') or a type filter such as -t ts.",
+  bre: "rg regex is not grep BRE: a\\|b matches a literal pipe. Write alternation as a|b; for a literal pipe, use [|] or -F.",
+  launcher: "An explicit path or wrapper bypasses the provider-aware Claude launcher. Run Claude as `claude ...` to use the persisted mode.",
+} as const;