@loophubs/agent-guard 0.1.0 → 0.2.0

package/src/frontend.ts

@@ -1,22 +1,39 @@
-// Parse shell structure into command records; rejected syntax remains
-// available to the signature rules.
-import sh from "mvdan-sh";
+// Parse shell structure into command records. Failed syntax blocks the call;
+// interpreter code still reaches the signature rules.
+
+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 { 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";
+import sh from "mvdan-sh";
+
+import { resolveCommand, stdinKind } from "./argv";
+import { misreadComment } from "./comments";
+import { boundedDirectories } from "./cwd";
+import { movedOnSuccess } from "./moves";
+import { expandHome } from "./paths";
+import { xargsReplacements } from "./pipeline";
+import type { Command, Redirect, Script, Word } from "./record";
+import { readWord } from "./words";
 
 const { syntax } = sh;
+let packageDir = import.meta.dir;
+let parserPath = "";
+while (!parserPath) {
+  const candidate = join(packageDir, "node_modules/mvdan-sh/index.js");
+  if (existsSync(candidate)) parserPath = candidate;
+  else {
+    const parent = dirname(packageDir);
+    if (parent === packageDir) throw new Error("mvdan-sh dependency is missing");
+    packageDir = parent;
+  }
+}
+if (sh !== (await import(pathToFileURL(parserPath).href)).default) throw new Error("mvdan-sh resolved outside its dependency package");
 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 dir: { cwd: string; alternatives?: string[] | undefined }; // shared by the commands a cd in this scope moves
   readonly vars: Map<string, string>;
   readonly slice: (start: number, end: number) => string;
 }
@@ -24,7 +41,7 @@ interface Scope {
 const type = (node: Node) => syntax.NodeType(node);
 
 export function parseScript(source: string, cwd: string, home: string): Script {
-  const script: Script = { commands: [], uninspectable: [] };
+  const script: Script = { commands: [], uninspectable: [], parseFailed: false };
 
   function parse(src: string, cwd: string) {
     const bytes = Buffer.from(src);
@@ -35,12 +52,12 @@ export function parseScript(source: string, cwd: string, home: string): Script {
       file = undefined;
     }
     if (!file || misreadComment(file, bytes)) {
-      script.uninspectable.push(src);
+      script.parseFailed = true;
       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);
+    for (const stmt of file.Stmts) statement(stmt!, scope);
   }
 
   const text = (node: Node, scope: Scope) => scope.slice(node.Pos().Offset(), node.End().Offset());
@@ -59,7 +76,7 @@ export function parseScript(source: string, cwd: string, home: string): Script {
     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);
+      for (const s of (cmd as Subshell).Stmts) statement(s!, inner);
       return;
     }
     children(cmd, scope);
@@ -70,17 +87,17 @@ export function parseScript(source: string, cwd: string, home: string): Script {
     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));
+    statement(cmd.X!, op === "&&" || op === "||" ? scope : isolated(scope));
     const middle = script.commands.length;
-    const directCd = op === "&&" && movedOnSuccess(cmd.X, scope.slice);
+    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);
+      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));
+    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);
@@ -103,8 +120,7 @@ export function parseScript(source: string, cwd: string, home: string): Script {
         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;
+      } else return true;
       return false;
     });
     if (loop) outer.dir.alternatives = boundedDirectories(outer.dir.cwd, [...(outer.dir.alternatives ?? []), scope.dir.cwd, ...(scope.dir.alternatives ?? [])], home);
@@ -112,26 +128,30 @@ export function parseScript(source: string, cwd: string, home: string): Script {
 
   function conditional(node: IfClause, scope: Scope) {
     const condition = isolated(scope);
-    for (const stmt of node.Cond) statement(stmt, condition);
+    for (const stmt of node.Cond) statement(stmt!, condition);
     const then = isolated(condition);
-    for (const stmt of node.Then) statement(stmt, then);
+    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);
+    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 === "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);
+      for (const s of (child as CmdSubst).Stmts) statement(s!, inner);
       return false;
     });
   }
@@ -163,20 +183,20 @@ export function parseScript(source: string, cwd: string, home: string): Script {
     return { text: value, raw: value, expands: false, globs: false, vars: [], role: "arg", value };
   }
 
-  function simple(cmd: Node | null, redirs: RedirectNode[], scope: Scope) {
+  function simple(cmd: Node | null, redirs: (RedirectNode | null)[], 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));
+      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));
+      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 ?? ""));
+        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 redirects = redirs.map((r) => redirect(r!, scope)).filter((r) => r !== undefined);
     const command: Command = {
       argv,
       redirects,
@@ -201,14 +221,14 @@ export function parseScript(source: string, cwd: string, home: string): Script {
   }
 
   function redirect(node: RedirectNode, scope: Scope): Redirect | undefined {
-    const op = scope.slice(node.OpPos.Offset(), node.Word.Pos().Offset()).trim();
+    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 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);
+    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";
@@ -223,14 +243,15 @@ export function parseScript(source: string, cwd: string, home: string): Script {
       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;
+    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) {
-      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.alternatives = boundedDirectories(
+        resolve(scope.dir.cwd, target),
+        [scope.dir.cwd, ...(scope.dir.alternatives ?? []), ...(scope.dir.alternatives ?? []).map((cwd) => resolve(cwd, target))],
+        home,
+      );
       scope.dir.cwd = resolve(scope.dir.cwd, target);
     }
   }

package/src/guard.ts

@@ -6,31 +6,47 @@
 // 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";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
 
-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");
+import { buildRequest, evaluate, suggestions } from "./core";
+import type { Runtime, Tool } from "./record";
+
+const usage = "usage: agent-guard --runtime claude|codex|pi < event.json";
+let flags: { runtime?: string; cwd?: string };
+try {
+  flags = parseArgs({ options: { runtime: { type: "string" }, cwd: { type: "string" } } as const }).values;
+} catch {
+  console.error(usage);
+  process.exit(2);
+}
+const runtime = flags.runtime as Runtime | undefined;
+const hookCwd = flags.cwd;
+if (!runtime || !["claude", "codex", "pi"].includes(runtime) || !hookCwd) {
+  console.error(usage);
   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.
+// A missing tool_input, or a known tool whose field is not a string, throws,
+// which the wrapper turns into a denial: a runtime that renames or retypes a
+// field must not silently stop being guarded. Tools the guard does not know pass.
 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 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 fields: Record<string, [Tool, string]> = {
+  bash: ["bash", "command"],
+  read: ["read", "file_path"],
+  edit: ["edit", "file_path"],
+  write: ["write", "file_path"],
+  grep: ["grep", "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 [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;
 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/links.ts

@@ -1,8 +1,9 @@
 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";
+
+import { absPath, expandHome, isAppdata, isSensitive } from "./paths";
+import type { Request, Word } from "./record";
+import { dataPrograms } from "./rules/appdata";
 
 export function linkedRequest(req: Request): Request | undefined {
   let changed = false;
@@ -15,7 +16,8 @@ export function linkedRequest(req: Request): Request | undefined {
     let followed = false;
     let depth = 0;
     while (parts.length) {
-      path = resolve(path, parts.shift()!);
+      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;
@@ -28,13 +30,10 @@ export function linkedRequest(req: Request): Request | undefined {
         continue;
       }
       if (++depth > 8) throw new Error("Symlink chain exceeds the agent guard limit");
-      const targetPath = resolve(dirname(path), target);
+      const targetPath = target.startsWith("/") ? target : `${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);
+      parts = [...targetPath.split("/").filter(Boolean), ...parts];
       path = "/";
     }
     return followed ? path : value;
@@ -43,17 +42,23 @@ export function linkedRequest(req: Request): Request | undefined {
     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));
+    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;
+  const commands = req.commands.map((cmd) => {
+    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 : 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 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;
 }

package/src/moves.ts

@@ -1,5 +1,5 @@
-import sh from "mvdan-sh";
 import type { BinaryCmd, CallExpr, Lit, Stmt } from "mvdan-sh";
+import sh 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 {
@@ -20,8 +20,8 @@ export function movedOnSuccess(stmt: Stmt, slice: (start: number, end: number) =
     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);
+    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/paths.ts

@@ -1,5 +1,5 @@
 // Filesystem checks run after lexical denials to avoid touching protected trees.
-import { statSync, realpathSync } from "node:fs";
+import { realpathSync, statSync } from "node:fs";
 import { userInfo } from "node:os";
 import { basename, dirname, resolve } from "node:path";
 
@@ -7,15 +7,27 @@ export const appdataTrees = ["Containers", "Group Containers", "Mobile Documents
 
 // 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/**",
+  "**/.env",
+  "**/.env.*",
+  "**/.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));
 
+// Directories that hold listed files, so a search rooted at one reads them.
+// ~/.ssh has its own inode-based check and reason.
+const credentialRoots = [".aws", ".gnupg"];
+const credentialDirectories = [".ssh", ...credentialRoots];
+
 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);
@@ -23,22 +35,34 @@ export function expandHome(path: string, home: string): string {
   return path;
 }
 
+// curl, open and git read a file:// URL as the path it names.
 export function absPath(path: string, cwd: string, home: string, quoted = false): string {
   if (!quoted) path = expandHome(path, home);
-  return resolve(cwd, path);
+  return resolve(cwd, path.replace(/^file:\/\//i, ""));
+}
+
+// Whether the shell could expand the glob's leading segments to `directory`, so
+// `~/Lib*/Cont*/x` reads inside `~/Library/Containers`. A pattern that stops at
+// the directory only names it and is left to the callers' other checks.
+function globReaches(path: string, directory: string): boolean {
+  const pattern = path.split("/");
+  const target = directory.split("/");
+  if (pattern.length <= target.length) return false;
+  return target.every((segment, i) => i === 0 || pattern[i] === "**" || new Bun.Glob(pattern[i]!.toLowerCase()).match(segment.toLowerCase()));
 }
 
 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));
+    if (appdataTrees.some((tree) => globReaches(path, `${home}/Library/${tree}`))) return 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(/\/$/, "");
+  const fixed = rest.split(/[*?[]/)[0]!.replace(/\/$/, "");
   return fixed !== "" && appdataTrees.some((tree) => tree.toLowerCase().startsWith(fixed));
 }
 
@@ -54,12 +78,12 @@ export function isBroad(path: string, home: string, glob = false): boolean {
   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(/\/$/, "");
+  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);
 }
@@ -77,13 +101,18 @@ export function sshPrivate(path: string): boolean {
 
 // 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.
+// does not, unless it sits in a credential directory. Names match regardless of
+// case because the default APFS volume ignores it.
 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 lower = path.toLowerCase();
+  if ([".env.example", ".env.age"].includes(basename(lower))) return false;
+  if (sshPrivate(path) || sensitiveGlobs.some((listed) => listed.match(lower))) return true;
+  if (!glob) return false;
+  if (globDirectory(path)) return true;
+  const base = basename(lower);
+  if (/^[*?]*$/.test(base)) return credentialDirectories.includes(basename(dirname(lower)));
   const pattern = new Bun.Glob(base);
   return sensitivePaths.some((listed) => {
     const name = basename(listed).replaceAll("*", "x");
@@ -91,6 +120,24 @@ export function isSensitive(path: string, glob = false): boolean {
   });
 }
 
+// A wildcard directory segment such as `.s*` may expand to a credential
+// directory. The shell's wildcards skip a leading dot, so only a segment that
+// starts with one counts.
+function globDirectory(path: string): boolean {
+  const segments = path.split("/");
+  return segments.slice(0, -1).some((segment, i) => {
+    if (!segment.startsWith(".") || !/[*?[]/.test(segment)) return false;
+    const pattern = new Bun.Glob(segment.toLowerCase());
+    return credentialDirectories.some((dir) => pattern.match(dir) && isSensitive([...segments.slice(0, i), dir, ...segments.slice(i + 1)].join("/"), true));
+  });
+}
+
+// A search reads everything under its root, so a credential directory counts as
+// its listed files do.
+export function isSensitiveRoot(path: string): boolean {
+  return isSensitive(path) || credentialRoots.includes(basename(path.toLowerCase()));
+}
+
 // A path that does not exist or cannot be searched has no inode to compare.
 function stat(path: string) {
   try {
@@ -131,12 +178,12 @@ export function sshScopeDenied(target: string, home: string, search: boolean): b
     for (const root of roots) {
       if (sameFile(candidate, root)) return true;
       if (search) {
-        for (let parent = root; parent !== "/"; ) {
+        for (let parent = root; parent !== "/";) {
           parent = dirname(parent);
           if (sameFile(candidate, parent)) return true;
         }
       }
-      for (let parent = candidate; parent !== "/"; ) {
+      for (let parent = candidate; parent !== "/";) {
         parent = dirname(parent);
         if (!sameFile(parent, root)) continue;
         if (parent !== dirname(candidate) || !sshPublic(basename(candidate))) return true;

package/src/pipeline.ts

@@ -1,26 +1,28 @@
 import { basename } from "node:path";
-import type { Command } from "./record.ts";
+
+import type { Command } from "./record";
 
 // 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 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 [];
+  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;
+    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(" ");
+  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

@@ -1,7 +1,10 @@
 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.",
+  syntax: "The agent guard cannot inspect this shell syntax. Rewrite it as a Bash-compatible command with explicit paths, or run a narrower command that the guard can inspect.",
+  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.",
+  hiddenSearch: "A recursive search that includes hidden files can read credentials. Use default rg on a project path, or search an exact non-sensitive file without recursive or hidden-file flags.",
   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.",
@@ -11,9 +14,7 @@ export const reasons = {
   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;

package/src/record.ts

@@ -1,7 +1,7 @@
 // A search option's value keeps the option's word as option:ROLE.
 export type ValueRole = "pattern" | "patfile" | "glob" | "nglob" | "optarg";
 export type Role = "arg" | "assign" | "precommand" | "namespace" | "program" | "code" | "option" | "path" | ValueRole | `option:${ValueRole}`;
-export type Flag = "explicit" | "files" | "help" | "noignore" | "fixed" | "recursive" | "include" | "replace";
+export type Flag = "explicit" | "files" | "help" | "fixed" | "recursive" | "include" | "replace" | "hidden";
 
 export interface Word {
   text: string; // quotes removed; ~, $HOME and ${HOME} expanded
@@ -32,6 +32,7 @@ export interface Command {
 export interface Script {
   commands: Command[];
   uninspectable: string[];
+  parseFailed: boolean;
 }
 
 export type Runtime = "claude" | "codex" | "pi";
@@ -42,10 +43,13 @@ export interface Request {
   tool: Tool;
   home: string;
   cwd: string;
+  inputCwd: string;
+  pathInput: string;
   operation: "" | "read" | "write" | "search";
   target: string;
   searchRoot: string;
   glob: string;
   commands: Command[];
   uninspectable: string[];
+  parseFailed: boolean;
 }