@odingard/guardian-hook 0.3.0 → 0.4.0

package/dist/agent-sdk.js

@@ -3,6 +3,461 @@ import { createGuardianClient } from "@odingard/guardian-sdk";
 
 // src/classify.ts
 import { createHash } from "node:crypto";
+import {
+  CONTENT_PIN_INVALID_ARGUMENT,
+  CONTENT_PIN_KEY,
+  pinFile
+} from "@odingard/guardian-sdk";
+
+// src/shell.ts
+var MAX_NESTING = 16;
+var isBlank = (c) => c === " " || c === "	";
+var OPERATOR_START = /* @__PURE__ */ new Set([";", "&", "|", "\n", "(", ")", "<", ">"]);
+function parseShell(src) {
+  const st = {
+    src,
+    pos: 0,
+    ambiguous: false,
+    nesting: 0,
+    heredocs: [],
+    bodySubs: []
+  };
+  const parsed = parseList(st, false);
+  if (st.pos < src.length) st.ambiguous = true;
+  if (st.bodySubs.length > 0) {
+    parsed.commands.push(bodyCommand(st.bodySubs));
+  }
+  return {
+    commands: parsed.commands,
+    ambiguous: st.ambiguous || parsed.ambiguous
+  };
+}
+function bodyCommand(subs) {
+  return { words: [], writes: [], pipeline: -1, stage: 0, subs };
+}
+function parseList(st, inSub) {
+  const commands = [];
+  let pipeline = 0;
+  let stage = 0;
+  let words = [];
+  let writes = [];
+  let depth = 0;
+  let pendingWrite = false;
+  let pendingHeredoc = null;
+  let pendingHereString = false;
+  const endCommand = (nextIsPipe) => {
+    if (words.length > 0 || writes.length > 0) {
+      commands.push({ words, writes, pipeline, stage, subs: [] });
+    }
+    words = [];
+    writes = [];
+    if (nextIsPipe) stage++;
+    else {
+      pipeline++;
+      stage = 0;
+    }
+  };
+  const { src } = st;
+  while (st.pos < src.length) {
+    const c = src[st.pos];
+    if (isBlank(c)) {
+      st.pos++;
+      continue;
+    }
+    if (c === "\\" && src[st.pos + 1] === "\n") {
+      st.pos += 2;
+      continue;
+    }
+    if (c === "#") {
+      while (st.pos < src.length && src[st.pos] !== "\n") st.pos++;
+      continue;
+    }
+    if (c === "\n") {
+      st.pos++;
+      endCommand(false);
+      readHeredocBodies(st);
+      continue;
+    }
+    if (c === ";" || c === "&" || c === "|") {
+      const two = src.slice(st.pos, st.pos + 2);
+      if (c === "&" && src[st.pos + 1] === ">") {
+        st.pos += src[st.pos + 2] === ">" ? 3 : 2;
+        pendingWrite = true;
+        continue;
+      }
+      if (two === "&&" || two === "||" || two === ";;" || two === "|&") {
+        st.pos += 2;
+        endCommand(two === "|&");
+        continue;
+      }
+      st.pos++;
+      endCommand(c === "|");
+      continue;
+    }
+    if (c === "(") {
+      st.pos++;
+      depth++;
+      endCommand(false);
+      continue;
+    }
+    if (c === ")") {
+      if (depth > 0) {
+        st.pos++;
+        depth--;
+        endCommand(false);
+        continue;
+      }
+      if (inSub) {
+        endCommand(false);
+        return { commands, ambiguous: false };
+      }
+      st.pos++;
+      st.ambiguous = true;
+      endCommand(false);
+      continue;
+    }
+    if (c === "<" || c === ">") {
+      if (src[st.pos + 1] === "(") {
+        const w2 = readWord(st);
+        if (w2) addWord(w2);
+        continue;
+      }
+      const op = /^(<<<|<<-|<<|<>|<&|>>|>&|>\||<|>)/.exec(src.slice(st.pos))[0];
+      st.pos += op.length;
+      if (op === "<<" || op === "<<-") pendingHeredoc = { stripTabs: op === "<<-" };
+      else if (op === "<<<") pendingHereString = true;
+      else if (op === ">&" || op === "<&") {
+        const m = /^[ \t]*([0-9]+|-)(?=[\s;&|)<>]|$)/.exec(src.slice(st.pos));
+        if (m) st.pos += m[0].length;
+        else if (op === ">&") pendingWrite = true;
+      } else if (op !== "<") pendingWrite = true;
+      continue;
+    }
+    const w = readWord(st);
+    if (!w) continue;
+    addWord(w);
+  }
+  if (inSub) st.ambiguous = true;
+  if (depth > 0) st.ambiguous = true;
+  endCommand(false);
+  return { commands, ambiguous: false };
+  function addWord(w) {
+    if (pendingHeredoc) {
+      st.heredocs.push({
+        delimiter: w.value,
+        stripTabs: pendingHeredoc.stripTabs,
+        quoted: w.quoted
+      });
+      pendingHeredoc = null;
+      return;
+    }
+    if (pendingHereString) {
+      pendingHereString = false;
+      collectSubs(w);
+      return;
+    }
+    if (pendingWrite) {
+      pendingWrite = false;
+      writes.push(w);
+      return;
+    }
+    const next = src[st.pos];
+    if (/^[0-9]+$/.test(w.value) && !w.quoted && (next === ">" || next === "<")) {
+      return;
+    }
+    words.push(w);
+  }
+  function collectSubs(w) {
+    if (w.subs.length > 0) {
+      commands.push({ words: [], writes: [], pipeline: -1, stage: 0, subs: w.subs });
+    }
+  }
+}
+function readHeredocBodies(st) {
+  while (st.heredocs.length > 0) {
+    const doc = st.heredocs.shift();
+    const lines = [];
+    let found = false;
+    while (st.pos < st.src.length) {
+      let end = st.src.indexOf("\n", st.pos);
+      if (end < 0) end = st.src.length;
+      const raw = st.src.slice(st.pos, end);
+      st.pos = Math.min(end + 1, st.src.length);
+      const line = doc.stripTabs ? raw.replace(/^\t+/, "") : raw;
+      if (line === doc.delimiter) {
+        found = true;
+        break;
+      }
+      lines.push(raw);
+    }
+    void found;
+    if (!doc.quoted) {
+      const body = lines.join("\n");
+      if (/\$\(|`/.test(body)) {
+        const inner = { ...st, src: body, pos: 0, heredocs: [], bodySubs: [] };
+        const w = readDoubleQuotedBody(inner);
+        st.ambiguous ||= inner.ambiguous;
+        if (w.subs.length > 0) st.bodySubs.push(...w.subs);
+      }
+    }
+  }
+}
+function readDoubleQuotedBody(st) {
+  const word = { value: "", dynamic: false, subs: [] };
+  while (st.pos < st.src.length) {
+    const c = st.src[st.pos];
+    if (c === "\\") {
+      st.pos += 2;
+      continue;
+    }
+    if (c === "$" || c === "`") {
+      readExpansion(st, word);
+      continue;
+    }
+    st.pos++;
+  }
+  return word;
+}
+function readWord(st) {
+  const { src } = st;
+  const word = {
+    value: "",
+    dynamic: false,
+    subs: [],
+    quoted: false
+  };
+  const start = st.pos;
+  while (st.pos < src.length) {
+    const c = src[st.pos];
+    if (isBlank(c) || c === "\n") break;
+    if ((c === "<" || c === ">") && src[st.pos + 1] === "(") {
+      st.pos += 2;
+      word.dynamic = true;
+      word.subs.push(parseNested(st));
+      continue;
+    }
+    if (OPERATOR_START.has(c)) break;
+    if (c === "\\") {
+      if (st.pos + 1 < src.length) {
+        if (src[st.pos + 1] !== "\n") word.value += src[st.pos + 1];
+        st.pos += 2;
+      } else {
+        st.pos++;
+      }
+      word.quoted = true;
+      continue;
+    }
+    if (c === "'") {
+      const end = src.indexOf("'", st.pos + 1);
+      if (end < 0) {
+        st.ambiguous = true;
+        word.value += src.slice(st.pos + 1);
+        st.pos = src.length;
+        break;
+      }
+      word.value += src.slice(st.pos + 1, end);
+      st.pos = end + 1;
+      word.quoted = true;
+      continue;
+    }
+    if (c === '"') {
+      st.pos++;
+      word.quoted = true;
+      let closed = false;
+      while (st.pos < src.length) {
+        const d = src[st.pos];
+        if (d === '"') {
+          st.pos++;
+          closed = true;
+          break;
+        }
+        if (d === "\\") {
+          const n = src[st.pos + 1];
+          if (n === void 0) {
+            st.pos++;
+            continue;
+          }
+          if ('$`"\\\n'.includes(n)) {
+            if (n !== "\n") word.value += n;
+          } else {
+            word.value += d + n;
+          }
+          st.pos += 2;
+          continue;
+        }
+        if (d === "$" || d === "`") {
+          readExpansion(st, word);
+          continue;
+        }
+        word.value += d;
+        st.pos++;
+      }
+      if (!closed) st.ambiguous = true;
+      continue;
+    }
+    if (c === "$" && src[st.pos + 1] === "'") {
+      let i = st.pos + 2;
+      let out = "";
+      let closed = false;
+      while (i < src.length) {
+        const d = src[i];
+        if (d === "'") {
+          closed = true;
+          i++;
+          break;
+        }
+        if (d === "\\" && i + 1 < src.length) {
+          const n = src[i + 1];
+          const simple = { n: "\n", t: "	", "\\": "\\", "'": "'", '"': '"' };
+          if (simple[n] !== void 0) {
+            out += simple[n];
+            i += 2;
+            continue;
+          }
+          const hex = /^x([0-9a-fA-F]{1,2})/.exec(src.slice(i + 1));
+          if (hex) {
+            out += String.fromCharCode(parseInt(hex[1], 16));
+            i += 1 + hex[0].length;
+            continue;
+          }
+          const oct = /^([0-7]{1,3})/.exec(src.slice(i + 1));
+          if (oct) {
+            out += String.fromCharCode(parseInt(oct[1], 8));
+            i += 1 + oct[0].length;
+            continue;
+          }
+          st.ambiguous = true;
+          out += n;
+          i += 2;
+          continue;
+        }
+        out += d;
+        i++;
+      }
+      if (!closed) st.ambiguous = true;
+      word.value += out;
+      word.quoted = true;
+      st.pos = i;
+      continue;
+    }
+    if (c === "$" || c === "`") {
+      readExpansion(st, word);
+      continue;
+    }
+    word.value += c;
+    st.pos++;
+  }
+  return st.pos > start ? word : null;
+}
+function readExpansion(st, word) {
+  const { src } = st;
+  const c = src[st.pos];
+  if (c === "`") {
+    let i = st.pos + 1;
+    let inner = "";
+    while (i < src.length && src[i] !== "`") {
+      if (src[i] === "\\" && i + 1 < src.length) {
+        inner += src[i + 1];
+        i += 2;
+        continue;
+      }
+      inner += src[i];
+      i++;
+    }
+    if (i >= src.length) st.ambiguous = true;
+    word.value += "`" + inner + "`";
+    word.dynamic = true;
+    word.subs.push(parseString(st, inner));
+    st.pos = Math.min(i + 1, src.length);
+    return;
+  }
+  const n = src[st.pos + 1];
+  if (n === "(" && src[st.pos + 2] === "(") {
+    let i = st.pos + 3;
+    let level = 2;
+    while (i < src.length && level > 0) {
+      if (src[i] === "(") level++;
+      else if (src[i] === ")") level--;
+      i++;
+    }
+    if (level > 0) st.ambiguous = true;
+    word.value += src.slice(st.pos, i);
+    word.dynamic = true;
+    st.pos = i;
+    return;
+  }
+  if (n === "(") {
+    const start = st.pos;
+    st.pos += 2;
+    word.subs.push(parseNested(st));
+    word.value += src.slice(start, st.pos);
+    word.dynamic = true;
+    return;
+  }
+  if (n === "{") {
+    let i = st.pos + 2;
+    let level = 1;
+    while (i < src.length && level > 0) {
+      if (src[i] === "{") level++;
+      else if (src[i] === "}") level--;
+      i++;
+    }
+    if (level > 0) st.ambiguous = true;
+    const text = src.slice(st.pos, i);
+    word.value += text;
+    word.dynamic = true;
+    if (/\$\(|`/.test(text)) {
+      word.subs.push(parseString(st, text.slice(2, -1)));
+    }
+    st.pos = i;
+    return;
+  }
+  const name = /^\$([A-Za-z_][A-Za-z0-9_]*|[0-9@*#?$!-])/.exec(src.slice(st.pos));
+  if (name) {
+    word.value += name[0];
+    word.dynamic = true;
+    st.pos += name[0].length;
+    return;
+  }
+  word.value += "$";
+  st.pos++;
+}
+function parseNested(st) {
+  if (st.nesting >= MAX_NESTING) {
+    st.ambiguous = true;
+    st.pos = st.src.length;
+    return { commands: [], ambiguous: true };
+  }
+  st.nesting++;
+  const savedHeredocs = st.heredocs;
+  st.heredocs = [];
+  const inner = parseList(st, true);
+  st.heredocs = savedHeredocs;
+  st.nesting--;
+  if (st.src[st.pos] === ")") st.pos++;
+  else st.ambiguous = true;
+  return inner;
+}
+function parseString(st, text) {
+  if (st.nesting >= MAX_NESTING) {
+    st.ambiguous = true;
+    return { commands: [], ambiguous: true };
+  }
+  const inner = {
+    src: text,
+    pos: 0,
+    ambiguous: false,
+    nesting: st.nesting + 1,
+    heredocs: [],
+    bodySubs: []
+  };
+  const parsed = parseList(inner, false);
+  if (inner.bodySubs.length) parsed.commands.push(bodyCommand(inner.bodySubs));
+  st.ambiguous ||= inner.ambiguous;
+  return { commands: parsed.commands, ambiguous: inner.ambiguous };
+}
+
+// src/classify.ts
 var HOOK_TOOLS = [
   {
     name: "shell",
@@ -17,7 +472,7 @@ var HOOK_TOOLS = [
   {
     name: "shell_destructive",
     suggestedMode: "ask",
-    description: "Destructive commands: rm -rf, git reset --hard, git clean, force pushes, dropping databases, disk formatting."
+    description: "Destructive commands: rm -rf (also through xargs or find -exec), git reset --hard, git clean, force pushes and remote branch deletes, dropping databases, disk formatting, piping a download into a shell. Also changes to the agent's own MCP servers, hooks or permissions (claude mcp add, writes to .mcp.json or .claude/settings.json), and commands the hook cannot parse."
   },
   {
     name: "git_push",
@@ -68,6 +523,9 @@ var DESTRUCTIVE = [
   /\b(drop|truncate)\s+(table|database|schema)\b/i,
   /\bdelete\s+from\s+\w+\s*(;|$)/i,
   /\b(mkfs|dd\s+if=|shred|wipefs)\b/,
+  /\bdd\b.*\bof=/,
+  /\brsync\b.*\s--(delete\S*|remove-source-files)\b/,
+  /\btruncate\b.*(\s-s\s*0\b|\s--size[= ]0\b)/,
   /\bchmod\s+-R\s+777\b/,
   /\bfind\b.*\s-delete\b/
 ];
@@ -163,12 +621,599 @@ function startsInteractiveSession(command) {
   if (/\bwhile\s+(?:IFS=\S*\s+)?read\b/.test(command)) return true;
   return command.split(/&&|\|\||[;&|\n()]|\$\(|`/).some((segment) => startsSession(segment));
 }
+var RANK = {
+  shell: 0,
+  shell_session: 1,
+  git_push: 2,
+  shell_deploy: 3,
+  shell_destructive: 4
+};
+var BY_RANK = [
+  "shell",
+  "shell_session",
+  "git_push",
+  "shell_deploy",
+  "shell_destructive"
+];
+var ASK = RANK.shell_destructive;
+var MAX_DEPTH = 12;
+var EDGE = String.raw`(?:^|[\s/\\'"=:,(~])`;
+var AGENT_CONFIG_PATH = new RegExp(
+  [
+    EDGE + String.raw`(?:\.?mcp\.json|\.claude\.json|settings\.local\.json|managed-settings\.json|managed-mcp\.json|claude_desktop_config\.json|guardian-hooks\.json|cordis\.patch\.ya?ml)(?![\w-])`,
+    EDGE + String.raw`\.claude(?:[/\\](?:settings[^/\\\s'"]*\.json|hooks|agents|commands|skills|plugins|output-styles)(?![\w-])|[/\\]?(?=$|[\s'"]))`,
+    EDGE + String.raw`\.(?:codex|cursor|gemini|dsh)(?=$|[/\\\s'"])`
+  ].join("|"),
+  "i"
+);
+var READERS = new Set(
+  "cat tac less more head tail grep egrep fgrep zgrep rg ag ack ls dir stat file wc diff cmp comm jq bat batcat md5sum sha1sum sha256sum sha512sum shasum b2sum cksum echo printf test [ [[ find fd realpath readlink dirname basename du tree type which".split(" ")
+);
+var GIT_READS = new Set(
+  "status log show diff blame ls-files grep add commit check-ignore cat-file rev-parse ls-tree shortlog describe".split(" ")
+);
+var RESERVED = new Set(
+  "if then else elif fi do done while until for in case esac ! { } select function".split(
+    " "
+  )
+);
+var ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*(\[[^\]]*\])?\+?=/;
+var SHELLS = new Set(
+  "sh bash zsh dash ksh mksh ash yash posh fish busybox".split(" ")
+);
+var FETCHERS = new Set(
+  "curl wget fetch http https xh aria2c iwr irm invoke-webrequest invoke-restmethod".split(
+    " "
+  )
+);
+var BULK_DELETE = /* @__PURE__ */ new Set(["rm", "unlink", "shred"]);
+var EVALUATORS = /* @__PURE__ */ new Set(["eval", "source", ".", "iex", "invoke-expression"]);
+var WRAPPER_SPECS = {
+  nohup: {},
+  command: {},
+  builtin: {},
+  chronic: {},
+  unbuffer: {},
+  busybox: {},
+  time: { value: ["-f", "-o", "--format", "--output"] },
+  nice: { value: ["-n", "--adjustment"] },
+  ionice: { value: ["-c", "-n", "-p", "-P", "-u", "--class", "--classdata"] },
+  stdbuf: { value: ["-i", "-o", "-e", "--input", "--output", "--error"] },
+  timeout: { value: ["-s", "-k", "--signal", "--kill-after"], positional: 1 },
+  exec: { value: ["-a"] },
+  sudo: {
+    value: [
+      ...SUDO_VALUE_OPTS,
+      "--user",
+      "--group",
+      "--host",
+      "--prompt",
+      "--chdir",
+      "--role",
+      "--type",
+      "--close-from",
+      "--other-user",
+      "--command-timeout"
+    ]
+  },
+  doas: { value: ["-u", "-C"] },
+  xargs: {
+    value: [
+      "-a",
+      "--arg-file",
+      "-d",
+      "--delimiter",
+      "-E",
+      "-I",
+      "-L",
+      "-n",
+      "--max-args",
+      "-P",
+      "--max-procs",
+      "-s",
+      "--max-chars",
+      "--process-slot-var",
+      "--max-lines"
+    ]
+  },
+  chroot: { value: ["--userspec", "--groups"], positional: 1 },
+  taskset: { positional: 1 },
+  flock: {
+    value: ["-w", "-E", "--timeout", "--conflict-exit-code"],
+    positional: 1
+  },
+  setsid: {},
+  caffeinate: { value: ["-t", "-w"] }
+};
+var leaf = (rank, base = "", args = []) => ({
+  rank,
+  base,
+  args
+});
+function baseName(value) {
+  return (value.split(/[\\/]/).pop() ?? "").toLowerCase().replace(/\.exe$/, "");
+}
+var literal = (value) => ({ value, dynamic: false, subs: [] });
+function skipOptions(args, spec) {
+  const value = new Set(spec.value ?? []);
+  let i = 0;
+  let unknown = false;
+  while (i < args.length) {
+    const a = args[i].value;
+    if (a === "--") {
+      i++;
+      break;
+    }
+    if (a.startsWith("--")) {
+      if (a.includes("=")) i++;
+      else if (value.has(a)) i += 2;
+      else {
+        unknown = true;
+        i++;
+      }
+      continue;
+    }
+    if (a.startsWith("-") && a.length > 1) {
+      let takes = false;
+      for (let k = 1; k < a.length; k++) {
+        if (value.has(`-${a[k]}`)) {
+          takes = k === a.length - 1;
+          break;
+        }
+      }
+      i += takes ? 2 : 1;
+      continue;
+    }
+    break;
+  }
+  let positional = spec.positional ?? 0;
+  while (positional-- > 0 && i < args.length) i++;
+  return { start: i, unknown };
+}
+function rankText(text, depth) {
+  if (depth > MAX_DEPTH) return ASK;
+  return rankParsed(parseShell(text), depth + 1);
+}
+function rankParsed(parsed, depth) {
+  if (depth > MAX_DEPTH) return ASK;
+  let rank = parsed.ambiguous ? ASK : 0;
+  const stages = /* @__PURE__ */ new Map();
+  for (const cmd of parsed.commands) {
+    const l = rankArgv(cmd.words, depth);
+    rank = Math.max(rank, l.rank);
+    if (cmd.writes.some((w) => AGENT_CONFIG_PATH.test(w.value))) rank = ASK;
+    const subs = [
+      ...cmd.subs,
+      ...cmd.words.flatMap((w) => w.subs),
+      ...cmd.writes.flatMap((w) => w.subs)
+    ];
+    for (const sub of subs) rank = Math.max(rank, rankParsed(sub, depth + 1));
+    if (runsCode(l) && cmd.words.some((w) => w.subs.some((s) => fetches(s, depth + 1)))) {
+      rank = ASK;
+    }
+    if (cmd.pipeline >= 0) {
+      const list = stages.get(cmd.pipeline) ?? [];
+      list.push(l);
+      stages.set(cmd.pipeline, list);
+    }
+  }
+  for (const list of stages.values()) {
+    const first = list.findIndex((l) => FETCHERS.has(l.base));
+    if (first >= 0 && list.slice(first + 1).some((l) => readsCodeFromStdin(l))) {
+      rank = ASK;
+    }
+  }
+  return rank;
+}
+function fetches(parsed, depth) {
+  return parsed.commands.some(
+    (c) => FETCHERS.has(rankArgv(c.words, depth).base) || [...c.subs, ...c.words.flatMap((w) => w.subs)].some(
+      (s) => fetches(s, depth + 1)
+    )
+  );
+}
+var isInterpreter = (base) => INTERPRETERS.has(base) || /^python[0-9.]*$/.test(base);
+function runsCode(l) {
+  return EVALUATORS.has(l.base) || isInterpreter(l.base);
+}
+function readsCodeFromStdin(l) {
+  if (EVALUATORS.has(l.base)) return true;
+  if (!isInterpreter(l.base)) return false;
+  const options = [];
+  let script = false;
+  for (const a of l.args) {
+    if (a === "--") break;
+    if (a === "-") return true;
+    if (a.startsWith("-") || a.startsWith("+")) options.push(a);
+    else {
+      script = true;
+      break;
+    }
+  }
+  if (options.some((a) => /^-[a-zA-Z]*s[a-zA-Z]*$/.test(a))) return true;
+  if (options.some((a) => /^-[a-zA-Z]*[cem][a-zA-Z]*$/.test(a))) return false;
+  return !script;
+}
+function rankArgv(words, depth) {
+  if (depth > MAX_DEPTH) return leaf(ASK);
+  let i = 0;
+  while (i < words.length && (ASSIGNMENT.test(words[i].value) || RESERVED.has(words[i].value))) {
+    i++;
+  }
+  if (i >= words.length) return leaf(0);
+  const head = words[i];
+  const argWords = words.slice(i + 1);
+  if (head.dynamic) return leaf(ASK);
+  const base = baseName(head.value);
+  const args = argWords.map((w) => w.value);
+  const joined = [base, ...args].join(" ");
+  let rank = 0;
+  if (DESTRUCTIVE.some((re) => re.test(joined))) rank = ASK;
+  else if (DEPLOY.some((re) => re.test(joined))) rank = RANK.shell_deploy;
+  const done = (r, b = base, a = args) => leaf(Math.max(rank, r), b, a);
+  const inner = (from) => rankArgv(from, depth + 1);
+  const pathCheck = (values) => values.some((v) => AGENT_CONFIG_PATH.test(v)) ? ASK : 0;
+  if (base === "env") return done(rankEnv(argWords, depth));
+  if (base === "sudoedit") return done(pathCheck(args));
+  if (Object.hasOwn(WRAPPER_SPECS, base)) {
+    if (base === "sudo" && args.some((a) => /^-[a-zA-Z]*e[a-zA-Z]*$/.test(a))) {
+      return done(pathCheck(args));
+    }
+    if (base === "command" && args.some((a) => /^-[a-zA-Z]*[vV]/.test(a))) {
+      return done(0);
+    }
+    if (base === "flock") {
+      const c = args.findIndex((a) => a === "-c" || a === "--command");
+      if (c >= 0) return done(rankText(args[c + 1] ?? "", depth));
+    }
+    const { start, unknown } = skipOptions(argWords, WRAPPER_SPECS[base]);
+    let rest = argWords.slice(start);
+    if (base === "xargs" && rest.length === 0) rest = [literal("echo")];
+    const l = inner(rest);
+    if (base === "xargs" && BULK_DELETE.has(l.base)) l.rank = ASK;
+    const alt = unknown ? inner(argWords.slice(start + 1)).rank : 0;
+    return leaf(Math.max(rank, l.rank, alt), l.base, l.args);
+  }
+  if (base === "watch") {
+    const { start } = skipOptions(argWords, {
+      value: ["-n", "--interval", "-d", "-q", "--equexit"]
+    });
+    return done(rankText(args.slice(start).join(" "), depth));
+  }
+  if (SHELLS.has(base)) {
+    return done(rankShell(base, argWords, depth));
+  }
+  if (base === "su") {
+    const c = args.findIndex((a) => /^(-c|--command)$/.test(a));
+    const eq = args.find((a) => a.startsWith("--command="));
+    if (c >= 0) return done(rankText(args[c + 1] ?? "", depth));
+    if (eq) return done(rankText(eq.slice("--command=".length), depth));
+    return done(0);
+  }
+  if (base === "eval" || base === "iex" || base === "invoke-expression") {
+    return done(rankText(args.join(" "), depth));
+  }
+  if (base === "find") return done(rankFind(argWords, depth));
+  if (["npx", "bunx", "pnpx", "npm", "pnpm", "yarn"].includes(base)) {
+    const l = rankRunner(base, argWords, depth);
+    if (l) return leaf(Math.max(rank, l.rank), l.base, l.args);
+    return done(0);
+  }
+  if (base === "rm") {
+    const recursive = argsBeforeDashDash(args).some(
+      (a) => a === "--recursive" || /^-[a-zA-Z]*[rR]/.test(a)
+    );
+    return done(Math.max(recursive ? ASK : 0, pathCheck(args)));
+  }
+  if (base === "chmod") return done(Math.max(rankChmod(args), pathCheck(args)));
+  if (base === "git") return done(rankGit(argWords, depth));
+  if (base === "claude" || base === "codex" || base === "gemini") {
+    return done(rankAgentCli(base, args));
+  }
+  if (READERS.has(base)) return done(0);
+  return done(pathCheck(args));
+}
+function argsBeforeDashDash(args) {
+  const end = args.indexOf("--");
+  return end < 0 ? args : args.slice(0, end);
+}
+function rankEnv(argWords, depth) {
+  let i = 0;
+  while (i < argWords.length) {
+    const a = argWords[i].value;
+    if (a === "--") {
+      i++;
+      break;
+    }
+    if (a === "-S" || a === "--split-string") {
+      const text = [a, ...argWords.slice(i + 1).map((w) => w.value)].slice(1).join(" ");
+      return rankText(text, depth);
+    }
+    if (a.startsWith("--split-string=") || /^-S./.test(a)) {
+      const first = a.startsWith("--") ? a.slice(15) : a.slice(2);
+      return rankText(
+        [first, ...argWords.slice(i + 1).map((w) => w.value)].join(" "),
+        depth
+      );
+    }
+    if (/^(-u|-C|-P|--unset|--chdir)$/.test(a)) {
+      i += 2;
+      continue;
+    }
+    if (a.startsWith("-") && a.length > 1) {
+      i++;
+      continue;
+    }
+    break;
+  }
+  return rankArgv(argWords.slice(i), depth + 1).rank;
+}
+function rankShell(base, argWords, depth) {
+  let code = false;
+  for (let i = 0; i < argWords.length; i++) {
+    const a = argWords[i].value;
+    if (a === "--") break;
+    if (/^(--rcfile|--init-file|-o|\+o|-O|\+O)$/.test(a)) {
+      i++;
+      continue;
+    }
+    if (a === "--command" || base === "fish" && a === "-c") {
+      return rankText(argWords[i + 1]?.value ?? "", depth);
+    }
+    if (/^[-+][a-zA-Z]+$/.test(a)) {
+      if (/^-[a-zA-Z]*c/.test(a)) code = true;
+      continue;
+    }
+    if (a.startsWith("-")) continue;
+    if (code) {
+      if (base === "busybox")
+        return rankArgv(argWords.slice(i), depth + 1).rank;
+      return rankText(a, depth);
+    }
+    if (base === "busybox") return rankArgv(argWords.slice(i), depth + 1).rank;
+    return 0;
+  }
+  return 0;
+}
+function rankFind(argWords, depth) {
+  let rank = 0;
+  for (let i = 0; i < argWords.length; i++) {
+    const a = argWords[i].value;
+    if (a === "-delete") rank = ASK;
+    if (/^-(exec|execdir|ok|okdir)$/.test(a)) {
+      let end = i + 1;
+      while (end < argWords.length && argWords[end].value !== ";" && argWords[end].value !== "+") {
+        end++;
+      }
+      const l = rankArgv(argWords.slice(i + 1, end), depth + 1);
+      rank = Math.max(rank, BULK_DELETE.has(l.base) ? ASK : l.rank);
+      i = end;
+    }
+    if (/^-f(print|print0|printf|ls)$/.test(a)) {
+      if (AGENT_CONFIG_PATH.test(argWords[i + 1]?.value ?? "")) rank = ASK;
+    }
+  }
+  return rank;
+}
+function rankRunner(base, argWords, depth) {
+  let rest = argWords;
+  if (base === "npm" || base === "pnpm" || base === "yarn") {
+    const sub = rest[0]?.value;
+    if (!["exec", "x", "dlx"].includes(sub ?? "")) return null;
+    rest = rest.slice(1);
+  }
+  let i = 0;
+  while (i < rest.length) {
+    const a = rest[i].value;
+    if (a === "--") {
+      i++;
+      break;
+    }
+    if (a === "-c" || a === "--call")
+      return leaf(rankText(rest[i + 1]?.value ?? "", depth));
+    if (a.startsWith("--call=")) return leaf(rankText(a.slice(7), depth));
+    if (a === "-p" || a === "--package") {
+      i += 2;
+      continue;
+    }
+    if (a.startsWith("-")) {
+      i++;
+      continue;
+    }
+    break;
+  }
+  const pkg = rest[i];
+  if (!pkg) return null;
+  if (pkg.dynamic) return leaf(ASK);
+  const name = /^(?:@[^/]+\/)?([^@]+)(?:@.*)?$/.exec(pkg.value)?.[1] ?? pkg.value;
+  const bin = name === "claude-code" ? "claude" : name;
+  return rankArgv([literal(bin), ...rest.slice(i + 1)], depth + 1);
+}
+function rankChmod(args) {
+  const opts = argsBeforeDashDash(args);
+  const recursive = opts.some(
+    (a) => a === "--recursive" || /^-[a-zA-Z]*R/.test(a)
+  );
+  if (!recursive) return 0;
+  const modes = args.filter(
+    (a) => !a.startsWith("-") || /^-[rwxXst]+$/.test(a)
+  );
+  const worldWritable = modes.some(
+    (m) => /^0*[0-7]?[0-7]?[0-7]?[2367]$/.test(m) && m.length >= 3 || /(^|,)[ugo]*[ao][ugo]*[+=][rwxXst]*w/.test(m)
+  );
+  return worldWritable ? ASK : 0;
+}
+var GIT_VALUE_OPTS = /* @__PURE__ */ new Set([
+  "-C",
+  "-c",
+  "--git-dir",
+  "--work-tree",
+  "--namespace",
+  "--super-prefix",
+  "--config-env",
+  "--exec-path",
+  "--list-cmds",
+  "--attr-source"
+]);
+var GIT_EXEC_KEY = /^(core\.(pager|editor|sshcommand|askpass|gitproxy)|pager\..+|sequence\.editor|.+\.(textconv|command|cmd|helper|program|clean|smudge|process|driver|tool)|credential\..*|uploadpack\.packobjectshook|gpg\..*program|.*\.(receivepack|uploadpack))$/i;
+function rankGit(argWords, depth) {
+  const args = argWords.map((w) => w.value);
+  let rank = 0;
+  const aliases = /* @__PURE__ */ new Map();
+  let i = 0;
+  while (i < args.length) {
+    const a = args[i];
+    if (!a.startsWith("-")) break;
+    let opt = a;
+    let val;
+    if (a.startsWith("--") && a.includes("=")) {
+      opt = a.slice(0, a.indexOf("="));
+      val = a.slice(a.indexOf("=") + 1);
+      i++;
+    } else if (GIT_VALUE_OPTS.has(a)) {
+      val = args[i + 1] ?? "";
+      if (argWords[i + 1]?.dynamic && (a === "-c" || a === "--config-env")) {
+        rank = ASK;
+      }
+      i += 2;
+    } else {
+      i++;
+    }
+    if (opt === "-c" && val !== void 0) {
+      const eq = val.indexOf("=");
+      const key = (eq < 0 ? val : val.slice(0, eq)).toLowerCase();
+      const value = eq < 0 ? "" : val.slice(eq + 1);
+      if (key.startsWith("alias.")) aliases.set(key.slice(6), value);
+      else if (key === "core.hookspath" || key === "core.fsmonitor") {
+        if (!/^(false|0|no|off|)$/i.test(value)) rank = ASK;
+      } else if (GIT_EXEC_KEY.test(key)) {
+        rank = Math.max(rank, rankText(value, depth));
+      }
+    }
+    if (opt === "--config-env" && val !== void 0) {
+      const key = val.split("=")[0].toLowerCase();
+      if (key.startsWith("alias.") || GIT_EXEC_KEY.test(key) || /hookspath|fsmonitor/.test(key)) {
+        rank = ASK;
+      }
+    }
+  }
+  if (i >= args.length) return rank;
+  if (argWords[i].dynamic) return ASK;
+  const sub = args[i];
+  const rest = args.slice(i + 1);
+  const alias = aliases.get(sub.toLowerCase());
+  if (alias !== void 0) {
+    if (alias.startsWith("!")) {
+      return Math.max(
+        rank,
+        rankText(`${alias.slice(1)} ${rest.join(" ")}`, depth)
+      );
+    }
+    const expanded = parseShell(alias);
+    const aliasWords = expanded.commands[0]?.words ?? [];
+    return Math.max(
+      rank,
+      expanded.ambiguous ? ASK : 0,
+      rankGit([...aliasWords, ...argWords.slice(i + 1)], depth + 1)
+    );
+  }
+  const opts = argsBeforeDashDash(rest);
+  const has = (...names) => opts.some((a) => names.includes(a.split("=")[0]));
+  const short = (letter) => opts.some((a) => new RegExp(`^-[a-zA-Z]*${letter}`).test(a));
+  let sr = 0;
+  switch (sub) {
+    case "push": {
+      const forced = has(
+        "--force",
+        "--force-with-lease",
+        "--force-if-includes",
+        "--mirror",
+        "--delete",
+        "--prune"
+      ) || opts.some(
+        (a) => /^-[a-zA-Z]+$/.test(a) && /[fd]/.test(a.replace(/o.*$/, ""))
+      ) || rest.some((a) => /^[+:]/.test(a));
+      sr = forced ? ASK : RANK.git_push;
+      break;
+    }
+    case "reset":
+      sr = has("--hard", "--merge") ? ASK : 0;
+      break;
+    case "clean":
+      sr = has("--force") || short("f") ? ASK : 0;
+      break;
+    case "branch":
+      sr = short("D") || (has("--delete") || short("d")) && (has("--force") || short("f")) ? ASK : 0;
+      break;
+    case "checkout":
+      sr = rest.includes("--") || has("--force") || short("f") ? ASK : 0;
+      break;
+    case "switch":
+      sr = has("--discard-changes", "--force") || short("f") ? ASK : 0;
+      break;
+    case "restore":
+      sr = has("--source") || short("s") ? ASK : 0;
+      break;
+    case "stash":
+      sr = ["drop", "clear"].includes(rest[0] ?? "") ? ASK : 0;
+      break;
+    case "update-ref":
+      sr = short("d") ? ASK : 0;
+      break;
+    case "reflog":
+      sr = ["expire", "delete"].includes(rest[0] ?? "") ? ASK : 0;
+      break;
+    case "filter-branch":
+    case "filter-repo":
+      sr = ASK;
+      break;
+  }
+  if (!GIT_READS.has(sub) && rest.some((a) => AGENT_CONFIG_PATH.test(a)))
+    sr = ASK;
+  return Math.max(rank, sr);
+}
+var AGENT_CONFIG_SUBCOMMANDS = /* @__PURE__ */ new Set([
+  "mcp",
+  "plugin",
+  "plugins",
+  "config"
+]);
+var AGENT_READ_ACTIONS = /* @__PURE__ */ new Set([
+  "list",
+  "ls",
+  "get",
+  "show",
+  "serve",
+  "help",
+  "--help",
+  "-h"
+]);
+var AGENT_WIDENING_OPTS = /^(--mcp-config|--settings|--dangerously-skip-permissions|--allow-dangerously-skip-permissions|--allowed-tools|--allowedtools|--add-dir|--plugin-dir|--dangerously-bypass-approvals-and-sandbox|--yolo|--config)(=|$)/i;
+function rankAgentCli(base, args) {
+  if (args.some((a) => AGENT_WIDENING_OPTS.test(a))) return ASK;
+  if (base === "codex" && args.includes("-c")) return ASK;
+  const mode = args.findIndex((a) => a === "--permission-mode");
+  const modeValue = mode >= 0 ? args[mode + 1] : args.find((a) => a.startsWith("--permission-mode="))?.slice(18);
+  if (modeValue !== void 0 && !/^(default|plan)$/i.test(modeValue))
+    return ASK;
+  const positionals2 = args.filter((a) => !a.startsWith("-"));
+  const sub = positionals2.findIndex((p) => AGENT_CONFIG_SUBCOMMANDS.has(p));
+  if (sub < 0) return 0;
+  const action = positionals2[sub + 1];
+  if (action === void 0 || AGENT_READ_ACTIONS.has(action)) return 0;
+  return ASK;
+}
 function classifyCommand(command) {
-  if (DESTRUCTIVE.some((re) => re.test(command))) return "shell_destructive";
-  if (DEPLOY.some((re) => re.test(command))) return "shell_deploy";
-  if (GIT_PUSH.test(command)) return "git_push";
-  if (startsInteractiveSession(command)) return "shell_session";
-  return "shell";
+  let rank = 0;
+  if (DESTRUCTIVE.some((re) => re.test(command))) rank = ASK;
+  else if (DEPLOY.some((re) => re.test(command))) rank = RANK.shell_deploy;
+  else if (GIT_PUSH.test(command)) rank = RANK.git_push;
+  else if (startsInteractiveSession(command)) rank = RANK.shell_session;
+  if (rank < ASK) rank = Math.max(rank, rankText(command, 0));
+  return BY_RANK[rank];
+}
+function isAgentConfigPath(path) {
+  return AGENT_CONFIG_PATH.test(path);
 }
 function mcpToolName(server, tool) {
   const part = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").replace(/^(\d)/, "x$1") || "x";
@@ -204,6 +1249,54 @@ var FILE_TOOLS = /* @__PURE__ */ new Set([
   "edit"
   // DeepSeek Harness
 ]);
+var CONTENT_PIN_TOOLS = /* @__PURE__ */ new Set([
+  "Edit",
+  "MultiEdit",
+  "NotebookEdit",
+  "edit"
+  // DeepSeek Harness
+]);
+var EditPinRefused = class extends Error {
+  constructor(reasonCode, message) {
+    super(message);
+    this.reasonCode = reasonCode;
+    this.name = "EditPinRefused";
+  }
+  reasonCode;
+};
+async function pinEditTarget(call, governed) {
+  if (!CONTENT_PIN_TOOLS.has(call.tool)) return governed;
+  const path = governed.arguments.path;
+  if (typeof path !== "string" || !path.startsWith("/")) {
+    throw new EditPinRefused(
+      CONTENT_PIN_INVALID_ARGUMENT,
+      `${call.tool} needs an absolute file path; the hook does not resolve relative paths`
+    );
+  }
+  let pin;
+  try {
+    pin = await pinFile(path, { allowAbsent: true });
+  } catch (err) {
+    const code = typeof err?.reasonCode === "string" ? err.reasonCode : "CONTENT_PIN_UNREADABLE";
+    throw new EditPinRefused(
+      code,
+      `the current contents of ${path} could not be pinned`
+    );
+  }
+  const record = "absent" in pin ? { arg: "path", index: 0, mode: "recheck", absent: true } : {
+    arg: "path",
+    index: 0,
+    mode: "recheck",
+    name: pin.name,
+    size: pin.size,
+    sha256: pin.sha256
+  };
+  return {
+    ...governed,
+    arguments: { ...governed.arguments, [CONTENT_PIN_KEY]: [record] },
+    contentPin: { path, pin }
+  };
+}
 function commandText(value) {
   if (typeof value === "string") return value;
   if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
@@ -222,17 +1315,20 @@ function patchTargets(patch) {
   }
   return targets;
 }
+var AGENT_CONFIG_NOTE = "(agent MCP, hook, permission or plugin config)";
 function fileWrite(operation, path, content, cwd, summaryVerb) {
+  const config = isAgentConfigPath(path);
   return {
-    toolName: "file_write",
+    toolName: config ? "shell_destructive" : "file_write",
     arguments: {
       operation,
       path,
       contentBytes: Buffer.byteLength(content),
       contentDigest: digest(content),
+      ...config ? { touches: "agent-config" } : {},
       ...cwd
     },
-    summary: `${summaryVerb} ${path}`
+    summary: `${summaryVerb} ${path}${config ? ` ${AGENT_CONFIG_NOTE}` : ""}`
   };
 }
 function governedCall(call) {
@@ -280,10 +1376,12 @@ function governedCall(call) {
     const targets = patchTargets(patch);
     const paths = [...new Set(targets.map((t) => t.path))];
     const shown = paths.slice(0, MAX_PATHS).map((p) => bounded(p, 500));
+    const config = paths.some((p) => isAgentConfigPath(p));
     return {
-      toolName: "file_write",
+      toolName: config ? "shell_destructive" : "file_write",
       arguments: {
         operation: "apply_patch",
+        ...config ? { touches: "agent-config" } : {},
         path: shown[0] ?? "",
         paths: shown,
         ...paths.length > MAX_PATHS ? { morePaths: paths.length - MAX_PATHS } : {},
@@ -292,7 +1390,7 @@ function governedCall(call) {
         contentDigest: digest(patch),
         ...cwd
       },
-      summary: paths.length === 0 ? "Apply a patch (no file headers found)" : paths.length === 1 ? `Patch ${bounded(paths[0], 160)}` : `Patch ${paths.length} files: ${bounded(paths.join(", "), 160)}`
+      summary: (paths.length === 0 ? "Apply a patch (no file headers found)" : paths.length === 1 ? `Patch ${bounded(paths[0], 160)}` : `Patch ${paths.length} files: ${bounded(paths.join(", "), 160)}`) + (config ? ` ${AGENT_CONFIG_NOTE}` : "")
     };
   }
   if (tool === "WebFetch" || tool === "web_fetch") {
@@ -326,6 +1424,7 @@ function tierOf(toolName) {
 }
 
 // src/decide.ts
+import { verifyPin } from "@odingard/guardian-sdk";
 var PLAIN = {
   NOT_AUTHORIZED: "this agent is not authorized for it",
   APPROVAL_DENIED: "the approver declined it",
@@ -336,6 +1435,16 @@ var PLAIN = {
   SERVICE_UNAVAILABLE: "Guardian could not be reached",
   REQUEST_CONFLICT: "Guardian saw a conflicting request"
 };
+async function contentPinRefusal(call) {
+  if (!call.contentPin) return void 0;
+  try {
+    await verifyPin(call.contentPin.path, call.contentPin.pin);
+    return void 0;
+  } catch (err) {
+    const code = err?.reasonCode;
+    return typeof code === "string" ? code : "CONTENT_PIN_UNREADABLE";
+  }
+}
 function plain(code) {
   return PLAIN[code] ?? code;
 }
@@ -416,6 +1525,17 @@ async function decide(call, options) {
       guardianDecision: "DENY"
     });
   }
+  const pinRefusal = await contentPinRefusal(call);
+  if (pinRefusal !== void 0) {
+    const path = call.contentPin.path;
+    return {
+      decision: "deny",
+      reason: pinRefusal === "CONTENT_CHANGED_SINCE_APPROVAL" ? `Guardian hook: ${path} changed since this edit was proposed (CONTENT_CHANGED_SINCE_APPROVAL). Nothing ran. Read the file again and propose the edit again; it needs a new approval.` : `Guardian hook: ${path} could not be checked against its approval (${pinRefusal}). Nothing ran.`,
+      requestId: result.requestId,
+      guardianDecision: approvedByHuman ? "ASK" : "ALLOW",
+      approvedByHuman
+    };
+  }
   let executed;
   try {
     executed = await options.client.execute({
@@ -542,12 +1662,21 @@ async function evaluate(dialect, stdinText, env, deps, deadlineMs) {
   if (!input || typeof input.tool_name !== "string") {
     return failClosed("the tool call had no tool name. Nothing ran.");
   }
-  const call = governedCall({
+  const toolCall = {
     tool: input.tool_name,
     input: input.tool_input && typeof input.tool_input === "object" ? input.tool_input : {},
     ...typeof input.cwd === "string" ? { cwd: input.cwd } : {}
-  });
-  if (call === null) return null;
+  };
+  const classified = governedCall(toolCall);
+  if (classified === null) return null;
+  let call;
+  try {
+    call = await pinEditTarget(toolCall, classified);
+  } catch (err) {
+    const code = err instanceof EditPinRefused ? err.reasonCode : "CONTENT_PIN_UNREADABLE";
+    const detail = err instanceof EditPinRefused ? err.message : "the target file could not be pinned";
+    return failClosed(`${detail} (${code}). Nothing ran.`);
+  }
   const connectionId = connectionFor(call.toolName, env);
   const credential = env.GUARDIAN_AGENT_CREDENTIAL?.trim();
   const baseUrl = (env.GUARDIAN_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(