@loophubs/agent-guard 0.1.0 → 0.2.0

package/README.md

@@ -1,91 +1,15 @@
-# agent-guard
+# 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`.
+`agent-guard` is a macOS pre-tool guard for Claude Code, Codex, and Pi. It checks supported tool calls before execution and blocks risky filesystem scans and credential reads.
 
-## Install
+macOS can record App Data access as `SystemPolicyAppDataDetailed` when a command reads or enumerates another app's data under `~/Library`. Broad scans from the home directory can cross those containers and trigger repeated permission prompts.
 
-Install globally with npm or Bun (Bun 1.4 or newer must be available at runtime):
+## What it does
 
-```sh
-npm install --global @loophubs/agent-guard
-# or
-bun add --global @loophubs/agent-guard
-command -v agent-guard
-```
+The guard blocks broad home and `~/Library` walks, protected App Data access, and recognizable attempts to display credentials. It allows project-scoped searches and named non-sensitive file reads; a clean guard result still leaves the runtime's own permissions in force. It covers only calls routed through a registered hook, not every tool or process.
 
-Use the absolute path printed by the last command in the examples below.
+To install the package and register and verify a runtime, follow [the setup guide](docs/setup.md).
 
-## Register a runtime
+[GitHub Releases](https://github.com/LoopHubs/agent-guard/releases) describe version-specific changes to what the guard blocks or allows.
 
-### 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.
+> **AI agents:** Read `docs/setup.md` first, then ask your user whether to install and register the guard. Do not install it or change configuration without consent.

package/bin/agent-guard

@@ -1,7 +1,7 @@
 #!/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
+# Runs the Bun supervisor from the package directory and passes denials 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
@@ -15,24 +15,28 @@ fail() {
     exit 2
 }
 
+[[ $HOME == /* ]] || fail 'HOME is not an absolute path'
 pkg=${0:A:h:h}
 bun=$(command -v bun) || fail 'bun missing'
 guard=$pkg/src/guard.ts
 [[ -r $guard ]] || fail 'guard.ts missing'
+runner=$pkg/src/runner.ts
+[[ -r $runner ]] || fail 'runner.ts missing'
+[[ -r $pkg/tsconfig.json ]] || fail 'tsconfig.json 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.
+# Bun reads bunfig.toml and environment files from its working directory;
+# the package config owns TypeScript paths. Pass the hook's directory 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 }
+# The runner kills the guard's process group. This outer deadline still denies
+# if the runner itself does not return before the hook timeout.
+coproc { print -r -- "$event" | exec $bun $runner "$@" --cwd $hook_cwd 2>&1 }
 pid=$!
-{ zselect -t 300; kill -KILL $pid } >/dev/null 2>&1 &!
+read -r -t 1 -p group || { kill -KILL $pid 2>/dev/null; fail 'supervisor did not report its process group' }
+[[ $group == AGENT_GUARD_PGID=<-> ]] || { kill -KILL $pid 2>/dev/null; fail 'invalid supervisor process group' }
+pgid=${group#AGENT_GUARD_PGID=}
+{ zselect -t 300; kill -KILL -- -$pgid; kill -KILL $pid } >/dev/null 2>&1 &!
 watchdog=$!
 read -r -t 3 -p reason
 wait $pid

package/package.json

@@ -1,26 +1,47 @@
 {
   "name": "@loophubs/agent-guard",
-  "version": "0.1.0",
-  "type": "module",
+  "version": "0.2.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": {
+    "url": "https://github.com/LoopHubs/agent-guard/issues"
+  },
   "license": "MIT",
-  "engines": {
-    "bun": ">=1.4"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LoopHubs/agent-guard.git"
   },
   "bin": {
     "agent-guard": "bin/agent-guard"
   },
   "files": [
     "bin",
-    "src"
+    "src",
+    "tsconfig.json"
   ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint . && oxfmt --check .",
+    "format": "oxfmt .",
+    "check": "bun run lint && bun run typecheck && bun run test"
+  },
   "dependencies": {
     "mvdan-sh": "0.10.1"
   },
   "devDependencies": {
-    "typescript": "6.0.3"
+    "@types/bun": "1.4.2",
+    "@types/mvdan-sh": "0.10.9",
+    "@types/node": "26.6.3",
+    "oxfmt": "0.71.0",
+    "oxlint": "1.86.0",
+    "typescript": "7.0.2"
   },
-  "scripts": {
-    "test": "bunx tsc --noEmit --strict --target es2022 --module esnext --moduleResolution bundler --allowImportingTsExtensions tests/*.ts tests/fixtures/*.ts && bun test tests/"
+  "engines": {
+    "bun": ">=1.4"
   }
 }

package/src/argv.ts

@@ -1,7 +1,8 @@
 import { basename, resolve } from "node:path";
-import { expandHome } from "./paths.ts";
-import type { Command, Word } from "./record.ts";
-import { searchRoles } from "./search-roles.ts";
+
+import { expandHome } from "./paths";
+import type { Command, Word } from "./record";
+import { searchRoles } 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"]);
@@ -17,82 +18,82 @@ export function resolveCommand(cmd: Command, home: string): { children: string[]
   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";
+  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);
+    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++;
+        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;
+        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 (!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";
+        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++;
+        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";
+        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";
+        w[i++]!.role = "precommand";
         while (/^-[ioe]/.test(w[i]?.text ?? "")) {
-          if (/^-[ioe]$/.test(w[i].text)) i++;
+          if (/^-[ioe]$/.test(w[i]!.text)) i++;
           i++;
         }
         break;
       case "caffeinate":
-        w[i++].role = "precommand";
+        w[i++]!.role = "precommand";
         while (/^-[disumtw]$/.test(w[i]?.text ?? "")) {
-          if (w[i].text === "-t" || w[i].text === "-w") i++;
+          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++;
+        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++;
+        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";
+        w[i++]!.role = "precommand";
         while (i < w.length) {
-          const arg = w[i].text;
+          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";
+              cmd.cwd = resolve(cmd.cwd, w[i + 1]!.text);
+              w[i + 1]!.role = "precommand";
             }
             i += 2;
           } else if (["-u", "-P"].includes(arg)) i += 2;
@@ -107,15 +108,15 @@ export function resolveCommand(cmd: Command, home: string): { children: string[]
         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";
+        if (!shell || w[i]!.text !== "repeat") break wrappers;
+        w[i++]!.role = "precommand";
         i++;
         continue;
       case "envchain":
-        w[i++].role = "precommand";
+        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";
+        if (w[i]?.text?.startsWith("-")) i = w.length;
+        if (w[i]) w[i]!.role = "namespace";
         i++;
         break;
       default:
@@ -127,25 +128,30 @@ export function resolveCommand(cmd: Command, home: string): { children: string[]
   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);
+  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;
+      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(" "));
+        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];
+        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) {
@@ -153,24 +159,26 @@ export function resolveCommand(cmd: Command, home: string): { children: string[]
           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";
+        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;
+      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";
+        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";
+      if (rest[flag + 1]) rest[flag + 1]!.role = "code";
       children.push(rest[flag + 1]?.text ?? "");
     }
   } else if (name === "eval" && (shell || cmd.wrappers.includes("command"))) {
@@ -178,7 +186,7 @@ export function resolveCommand(cmd: Command, home: string): { children: string[]
   } 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";
+      if (rest[flag + 1]) rest[flag + 1]!.role = "code";
       code.push(rest[flag + 1]?.text ?? "");
     }
   }

package/src/comments.ts

@@ -1,14 +1,15 @@
 // 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";
+import sh 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]));
+      misread ||= at > 0 && !" \t\n;&|()<>".includes(String.fromCharCode(bytes[at - 1]!));
     }
     return !misread;
   });

package/src/core.ts

@@ -1,16 +1,31 @@
-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";
+import { parseScript } from "./frontend";
+import { linkedRequest } 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";
 
 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: [] };
+  const inputCwd = cwd || "/";
+  const req: Request = {
+    runtime,
+    tool,
+    home,
+    cwd: absPath(inputCwd, "/", home),
+    inputCwd,
+    pathInput: input,
+    operation: "",
+    target: "",
+    searchRoot: "",
+    glob,
+    commands: [],
+    uninspectable: [],
+    parseFailed: false,
+  };
   if (tool === "bash") {
-    if (input) Object.assign(req, parseScript(input, req.cwd, home));
+    if (input) Object.assign(req, parseScript(input, inputCwd, home));
   } else if (tool === "grep") {
     req.operation = "search";
     req.searchRoot = absPath(input || req.cwd, req.cwd, home);
@@ -22,10 +37,8 @@ export function buildRequest(runtime: Runtime, tool: Tool, cwd: string, input: s
 }
 
 export function evaluate(req: Request): string | undefined {
-  const denials = [
-    ...appdataRules(req),
-    ...credentialRules(req),
-  ];
+  if (req.parseFailed) return reasons.syntax;
+  const denials = [...appdataRules(req), ...credentialRules(req)];
   // Deny lexically protected paths before asking the filesystem about links.
   if (!denials.length) {
     try {
@@ -40,5 +53,5 @@ export function evaluate(req: Request): string | undefined {
 }
 
 export function suggestions(req: Request): string[] {
-  return req.runtime === "claude" ? claudeWorkflowRules(req) : req.runtime === "codex" ? codexWorkflowRules(req) : [];
+  return req.runtime === "claude" ? claudeWorkflowRules(req) : [];
 }