@loophubs/agent-guard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agent-guard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,91 @@
+# agent-guard
+
+`agent-guard` is a macOS pre-tool hook for Claude Code, Codex, and Pi that blocks risky filesystem scans and credential reads. It helps avoid agent commands that traverse `~/Library` and trigger macOS App Data prompts recorded as `SystemPolicyAppDataDetailed`.
+
+## Install
+
+Install globally with npm or Bun (Bun 1.4 or newer must be available at runtime):
+
+```sh
+npm install --global @loophubs/agent-guard
+# or
+bun add --global @loophubs/agent-guard
+command -v agent-guard
+```
+
+Use the absolute path printed by the last command in the examples below.
+
+## Register a runtime
+
+### Claude Code
+
+Add this `PreToolUse` hook to `~/.claude/settings.json`, replacing the command path. It covers Claude Code's Bash and file-reading tools; [Claude Code's hook settings](https://code.claude.com/docs/en/hooks#hook-locations) describe the user-level location.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash|Read|Edit|Write|Grep",
+      "hooks": [{ "type": "command", "command": "/absolute/path/to/agent-guard --runtime claude", "timeout": 5 }]
+    }]
+  }
+}
+```
+
+### Codex
+
+Add this to `~/.codex/config.toml`, replacing the command path. [OpenAI's hook documentation](https://learn.chatgpt.com/docs/hooks) specifies `PreToolUse`, the Bash matcher, and `/hooks` trust review; open `/hooks` in Codex and trust the new hook before testing it.
+
+```toml
+[[hooks.PreToolUse]]
+matcher = "^Bash$"
+
+[[hooks.PreToolUse.hooks]]
+type = "command"
+command = "/absolute/path/to/agent-guard --runtime codex"
+timeout = 5
+```
+
+### Pi
+
+Create `~/.pi/agent/extensions/agent-guard.ts` with this adapter, replacing the command path. [Pi's extension API](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md) loads files in that directory and lets `tool_call` block a tool before execution.
+
+```ts
+import { spawnSync } from "node:child_process";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const guard = "/absolute/path/to/agent-guard";
+
+export default function (pi: ExtensionAPI) {
+  pi.on("tool_call", (event, ctx) => {
+    if (!["bash", "read", "edit", "write", "grep"].includes(event.toolName)) return;
+    const input = event.input as Record<string, unknown>;
+    const toolInput = event.toolName === "bash" ? input : {
+      ...input,
+      file_path: input.path,
+    };
+    const result = spawnSync(guard, ["--runtime", "pi"], {
+      cwd: ctx.cwd,
+      input: JSON.stringify({ tool_name: event.toolName, tool_input: toolInput, cwd: ctx.cwd }),
+      encoding: "utf8",
+      timeout: 4500,
+    });
+    if (result.status === 0) return;
+    return { block: true, reason: result.stderr?.trim() || result.error?.message || "agent-guard failed" };
+  });
+}
+```
+
+## Verify it blocks
+
+From a project directory, ask the configured agent to run `du -sh ~/Library`. It should report the guard's denial **without running `du`**. You can check the package entry directly without reading `~/Library`:
+
+```sh
+printf '%s\n' '{"tool_name":"Bash","tool_input":{"command":"du -sh ~/Library"}}' | agent-guard --runtime claude
+```
+
+The direct check should exit 2 and print a `DENIED:` reason on stderr. A direct check confirms the package works; the agent check confirms that runtime loaded its hook.
+
+## Limits
+
+The guard checks supported tool calls and recognizable shell commands; it does not sandbox the agent or cover every custom tool, dynamic shell expansion, or process outside a registered hook. Codex's example covers Bash calls, while the Pi adapter covers Bash, read, edit, write, and grep; other Pi tools need their own adapter handling. A broken or timed-out package entry denies a checked call, but a hook disabled or skipped by its runtime cannot inspect that call.

package/bin/agent-guard

@@ -0,0 +1,48 @@
+#!/bin/zsh -f
+# PreToolUse entry for the agent guard:
+#   agent-guard --runtime claude|codex|pi < event.json
+# Runs src/guard.ts from the package directory and passes its denial through
+# with exit 2. Exit 0 only means no objection; it never approves a call. Every
+# other outcome denies too, because Claude lets a hook's other failures and
+# timeouts through, Codex is assumed to, and nothing else stands between an
+# agent and ~/Library.
+emulate zsh
+setopt no_bg_nice
+zmodload zsh/zselect
+
+fail() {
+    print -u2 -- "The agent guard could not complete its check ($1), so this call is blocked. Inspect the guard installation, repair the reported failure, then retry the call."
+    exit 2
+}
+
+pkg=${0:A:h:h}
+bun=$(command -v bun) || fail 'bun missing'
+guard=$pkg/src/guard.ts
+[[ -r $guard ]] || fail 'guard.ts missing'
+event=$(/bin/cat)
+# bun reads bunfig.toml, tsconfig.json and .env from its working directory,
+# which is the agent's project, so a project file could preload code into the
+# guard or remap its parser. The guard runs from the package directory, with
+# the hook's directory passed as --cwd.
+hook_cwd=$PWD
+cd -q $pkg || fail 'package directory unreadable'
+
+# The deadline sits below every runtime's hook timeout, so an overrun denies
+# here instead of timing out as a pass. Reading the coprocess under the same
+# deadline keeps anything the guard started from holding this hook open.
+coproc { print -r -- "$event" | exec $bun $guard "$@" --cwd $hook_cwd 2>&1 }
+pid=$!
+{ zselect -t 300; kill -KILL $pid } >/dev/null 2>&1 &!
+watchdog=$!
+read -r -t 3 -p reason
+wait $pid
+rc=$?
+kill -KILL $watchdog 2>/dev/null
+case $rc in
+    (0) [[ -n $reason ]] && print -r -- "$reason"; exit 0 ;;
+    (2) ;;
+    (*) fail 'guard failed' ;;
+esac
+[[ -n $reason ]] || fail 'guard gave no reason'
+print -u2 -r -- "$reason"
+exit 2

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@loophubs/agent-guard",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Blocks filesystem scans and credential reads that macOS records as TCC App Data access, and points the agent at a safe alternative.",
+  "license": "MIT",
+  "engines": {
+    "bun": ">=1.4"
+  },
+  "bin": {
+    "agent-guard": "bin/agent-guard"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "dependencies": {
+    "mvdan-sh": "0.10.1"
+  },
+  "devDependencies": {
+    "typescript": "6.0.3"
+  },
+  "scripts": {
+    "test": "bunx tsc --noEmit --strict --target es2022 --module esnext --moduleResolution bundler --allowImportingTsExtensions tests/*.ts tests/fixtures/*.ts && bun test tests/"
+  }
+}

package/src/argv.ts

@@ -0,0 +1,196 @@
+import { basename, resolve } from "node:path";
+import { expandHome } from "./paths.ts";
+import type { Command, Word } from "./record.ts";
+import { searchRoles } from "./search-roles.ts";
+
+const shellPrograms = new Set(["sh", "bash", "zsh", "dash", "ksh"]);
+const codePrograms = new Set(["python", "python3", "node", "bun", "deno", "ruby", "perl", "php", "osascript", "lua"]);
+const zshBuiltins = new Set(["echo", "printf", "print", "export", "typeset", "declare", "set", "command", "eval", "source", "."]);
+const shellCodeFlag = /^-[a-z]*c[a-z]*$/;
+
+export function resolveCommand(cmd: Command, home: string): { children: string[]; code: string[] } {
+  const w = cmd.argv;
+  const children: string[] = [];
+  const code: string[] = [];
+  let i = 0;
+  let shell = true;
+  let lastPrecommand = "";
+  // Bash reads an assignment after nocorrect as an argument; zsh does not.
+  const assignment = (word: Word) => word.role === "assign" || /^[A-Za-z_][A-Za-z0-9_]*=/.test(word.raw);
+  while (i < w.length && (assignment(w[i]) || w[i].raw === "nocorrect")) w[i++].role = "precommand";
+  while (i < w.length && ["builtin", "-", "noglob"].includes(w[i].text)) {
+    lastPrecommand = w[i].text;
+    w[i++].role = "precommand";
+  }
+  // builtin runs nothing when the next word is not a builtin.
+  if (lastPrecommand === "builtin" && !zshBuiltins.has(w[i]?.text ?? "")) i = w.length;
+  wrappers: while (i < w.length) {
+    const name = basename(w[i].text);
+    switch (name) {
+      case "command":
+        if (w[i].text !== "command") break wrappers;
+        w[i++].role = "precommand";
+        while (["-p", "--"].includes(w[i]?.text)) i++;
+        // command -v only looks the name up.
+        if (["-v", "-V"].includes(w[i]?.text)) i = w.length;
+        break;
+      case "exec":
+        if (!shell || w[i].text !== "exec") break wrappers;
+        w[i++].role = "precommand";
+        while (["-c", "-l"].includes(w[i]?.text)) i++;
+        if (w[i]?.text === "-a") i += 2;
+        break;
+      case "nohup":
+        w[i++].role = "precommand";
+        if (w[i]?.text === "--") i++;
+        break;
+      case "timeout":
+        w[i++].role = "precommand";
+        while (w[i]?.text.startsWith("-")) {
+          if (["-s", "--signal", "-k", "--kill-after"].includes(w[i].text)) i++;
+          i++;
+        }
+        i++; // duration
+        break;
+      case "nice":
+        w[i++].role = "precommand";
+        if (w[i]?.text === "-n" || w[i]?.text === "--adjustment") i += 2;
+        else if (/^(-n|--adjustment=|-\d)/.test(w[i]?.text ?? "")) i++;
+        break;
+      case "stdbuf":
+        w[i++].role = "precommand";
+        while (/^-[ioe]/.test(w[i]?.text ?? "")) {
+          if (/^-[ioe]$/.test(w[i].text)) i++;
+          i++;
+        }
+        break;
+      case "caffeinate":
+        w[i++].role = "precommand";
+        while (/^-[disumtw]$/.test(w[i]?.text ?? "")) {
+          if (w[i].text === "-t" || w[i].text === "-w") i++;
+          i++;
+        }
+        break;
+      case "time":
+        w[i++].role = "precommand";
+        while (w[i]?.text.startsWith("-")) {
+          if (["-f", "-o", "--format", "--output"].includes(w[i].text)) i++;
+          i++;
+        }
+        break;
+      case "xargs":
+        w[i++].role = "precommand";
+        while (w[i]?.text.startsWith("-")) {
+          if (["-a", "-d", "-E", "-I", "-L", "-n", "-P", "-s", "--arg-file", "--delimiter", "--replace", "--max-args"].includes(w[i].text)) i++;
+          i++;
+        }
+        break;
+      case "env":
+        w[i++].role = "precommand";
+        while (i < w.length) {
+          const arg = w[i].text;
+          if (arg === "-C") {
+            if (w[i + 1]) {
+              cmd.cwd = resolve(cmd.cwd, w[i + 1].text);
+              w[i + 1].role = "precommand";
+            }
+            i += 2;
+          } 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 ?? "");
+            cmd.wrappers.push("env-S");
+            i = w.length;
+          } else if (arg.startsWith("-") || arg.includes("=")) i++;
+          else break;
+        }
+        break;
+      case "repeat":
+        // zsh's repeat COUNT runs the rest; bash parses it as a plain command.
+        if (!shell || w[i].text !== "repeat") break wrappers;
+        w[i++].role = "precommand";
+        i++;
+        continue;
+      case "envchain":
+        w[i++].role = "precommand";
+        // --set, --list and --unset manage the store and run nothing.
+        if (w[i]?.text.startsWith("-")) i = w.length;
+        if (w[i]) w[i].role = "namespace";
+        i++;
+        break;
+      default:
+        break wrappers;
+    }
+    cmd.wrappers.push(name);
+    shell = false;
+  }
+  cmd.shell = shell;
+  if (i >= w.length) return { children, code };
+  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 rest = w.slice(i + 1);
+  if (["rg", "grep", "ag", "ack"].includes(name)) {
+    searchRoles(cmd, rest, name);
+  } else if (name === "fd") {
+    let pattern = true;
+    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.slice(n + 1).map((word) => word.raw).join(" "));
+        break;
+      } else if ((/^(--search-path|--base-directory)(=|$)/.test(arg) || arg === "-C") && (arg.includes("=") || rest[n + 1])) {
+        const separate = !arg.includes("=");
+        const base = arg === "-C" || arg.startsWith("--base-directory");
+        if (separate) rest[n++].role = "option";
+        const path = rest[n];
+        path.role = "path";
+        path.value = separate ? path.text : arg.slice(arg.indexOf("=") + 1);
+        if (base) {
+          path.value = expandHome(path.value, home);
+          cmd.cwd = resolve(cmd.cwd, path.value);
+        }
+      } else if (["-E", "-e", "-t", "-d", "--exclude", "--extension", "--type", "--max-depth"].includes(arg)) {
+        rest[n].role = "option";
+        if (rest[n + 1]) rest[++n].role = "optarg";
+      } else if (arg.startsWith("-")) rest[n].role = "option";
+      else if (pattern) (rest[n].role = "pattern"), (pattern = false);
+      else rest[n].role = "path";
+    }
+  } else if (name === "du") {
+    for (let n = 0; n < rest.length; n++) {
+      const arg = rest[n].text;
+      if (["-d", "-I", "-B", "-t", "--max-depth", "--exclude", "--block-size", "--threshold"].includes(arg) || /^-[^-]+[dIBt]$/.test(arg)) {
+        rest[n].role = "option";
+        if (rest[n + 1]) rest[++n].role = "optarg";
+      } else if (arg.startsWith("-")) rest[n].role = "option";
+    }
+  } else if (shellPrograms.has(name)) {
+    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 ?? "");
+    }
+  } 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 ?? "");
+    }
+  }
+  return { children, code };
+}
+
+export function stdinKind(cmd: Command): "shell" | "code" | undefined {
+  const program = cmd.argv[cmd.program];
+  if (!program) return 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";
+  return undefined;
+}

package/src/comments.ts

@@ -0,0 +1,16 @@
+// mvdan/sh 3.5 starts a comment at a # right after a quote or an expansion,
+// where bash and zsh keep the # in the word and run the rest of the line.
+import sh from "mvdan-sh";
+import type { Comment, File } from "mvdan-sh";
+
+export function misreadComment(file: File, bytes: Buffer): boolean {
+  let misread = false;
+  sh.syntax.Walk(file, (node) => {
+    if (node && sh.syntax.NodeType(node) === "Comment") {
+      const at = (node as Comment).Hash.Offset();
+      misread ||= at > 0 && !" \t\n;&|()<>".includes(String.fromCharCode(bytes[at - 1]));
+    }
+    return !misread;
+  });
+  return misread;
+}

package/src/core.ts

@@ -0,0 +1,44 @@
+import { parseScript } from "./frontend.ts";
+import { linkedRequest } from "./links.ts";
+import { absPath } from "./paths.ts";
+import { reasons } from "./reasons.ts";
+import type { Request, Runtime, Tool } from "./record.ts";
+import { appdataRules } from "./rules/appdata.ts";
+import { credentialFilesystemRules, credentialRules } from "./rules/credentials.ts";
+import { claudeWorkflowRules, codexWorkflowRules } from "./rules/workflow.ts";
+
+export function buildRequest(runtime: Runtime, tool: Tool, cwd: string, input: string, glob: string, home: string): Request {
+  const req: Request = { runtime, tool, home, cwd: absPath(cwd || "/", "/", home), operation: "", target: "", searchRoot: "", glob, commands: [], uninspectable: [] };
+  if (tool === "bash") {
+    if (input) Object.assign(req, parseScript(input, req.cwd, home));
+  } else if (tool === "grep") {
+    req.operation = "search";
+    req.searchRoot = absPath(input || req.cwd, req.cwd, home);
+  } else if (input) {
+    req.operation = tool === "read" ? "read" : "write";
+    req.target = absPath(input, req.cwd, home);
+  }
+  return req;
+}
+
+export function evaluate(req: Request): string | undefined {
+  const denials = [
+    ...appdataRules(req),
+    ...credentialRules(req),
+  ];
+  // 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));
+    } catch {
+      denials.push(reasons.symlink);
+    }
+  }
+  if (!denials.length) denials.push(...credentialFilesystemRules(req));
+  return denials[0];
+}
+
+export function suggestions(req: Request): string[] {
+  return req.runtime === "claude" ? claudeWorkflowRules(req) : req.runtime === "codex" ? codexWorkflowRules(req) : [];
+}

package/src/cwd.ts

@@ -0,0 +1,5 @@
+// Keep speculative directories bounded without losing broad home roots.
+export function boundedDirectories(current: string, candidates: string[], home: string): string[] {
+  const distinct = [...new Set(candidates)].filter((path) => path !== current);
+  return distinct.length > 16 ? [home, `${home}/Library`] : distinct;
+}