@hasna/hooks 0.12.2 → 0.12.4

package/hooks/hook-workspace-repos-guard/src/hook.ts

@@ -36,7 +36,9 @@
  * off, so a later read-only stage never supplies an earlier stage's target.
  * apply_patch tools are inspected through their `*** Add File:` /
  * `*** Update File:` / `*** Delete File:` markers. Parenthesized command
- * groups are unwrapped.
+ * groups are unwrapped. A here-document body is data unless something in the
+ * command can run it (see dataHeredocs): its words are then never resolved
+ * against the cwd, and only protected paths it names explicitly count.
  *
  * Allowed orgs default to hasna,hasnaxyz,hasna-products and are overridable
  * with the WORKSPACE_REPOS_GUARD_ORGS env var (comma-separated) or, where
@@ -49,10 +51,19 @@
  * or evaluation error so a guard defect cannot wedge the agent.
  */
 
-import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, statSync } from "fs";
-import { homedir } from "os";
-import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "path";
-import { commandWordIndex, decodeWord, envSplitCommandText, gitSubcommand, lexCommand, mentionsDeleteVerb } from "../../hook-trash-guard/src/hook";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+import {
+  commandWordIndex,
+  decodeWord,
+  envSplitCommandText,
+  gitSubcommand,
+  heredocMarkerAt,
+  lexCommand,
+  mentionsDeleteVerb,
+  type HeredocMarker,
+} from "../../hook-trash-guard/src/hook";
 import {
   getCommand,
   readInput,
@@ -352,6 +363,20 @@ function shellWords(command: string): ShellWord[] {
   return words;
 }
 
+/**
+ * Whether the word at `at`, the first one after a delete verb or subcommand,
+ * asks for help or a version: such a call prints and exits, acting on
+ * nothing. Only that first position counts. Any earlier option may take the
+ * request as its value (`git clean -f -e --help` excludes the pattern
+ * `--help` and still deletes), so a request after another option stays a
+ * delete. `-h`/`-V` count only where `short` (Trash and git subcommands,
+ * whose `-h` is help).
+ */
+function asksForHelp(words: string[], at: number, short: boolean): boolean {
+  const word = words[at];
+  return word === "--help" || word === "--version" || (short && (word === "-h" || word === "-V"));
+}
+
 /**
  * Classify the operation of one command segment (a `&&`/`||`/`;`-delimited
  * unit). Git is handled by its subcommand: clean|rm delete, clone|init write,
@@ -373,7 +398,10 @@ function segmentOperation(segment: string): Operation {
     if (index < 0) return "read";
     const words = part.words.filter((_, at) => at >= index && !part.redirects.has(at)).map((word) => decodeWord(word.text));
     const tool = words[0].split("/").pop();
-    if (["rm", "rmdir", "unlink", "shred", "rmtree", "del"].includes(tool ?? "")) return "delete";
+    if (["rm", "rmdir", "shred"].includes(tool ?? "")) return asksForHelp(words, 1, false) ? "read" : "delete";
+    // POSIX/BSD unlink takes no options, so `unlink --help` removes a file
+    // named `--help`; rmtree and del are not modelled. Always deletes.
+    if (["unlink", "rmtree", "del"].includes(tool ?? "")) return "delete";
     if (tool === "trash") {
       // Hasna metadata/setup verbs take identifiers, not paths to remove.
       // Keep legacy positional Trash clients and capture verbs guarded.
@@ -386,11 +414,14 @@ function segmentOperation(segment: string): Operation {
       }
       if (at === words.length || ["status", "doctor", "list", "info", "get", "pending", "station", "setup", "backup", "storage", "retrieval", "backup-storage", "backup-inspect", "backup-refresh", "help"].includes(words[at])) return "read";
       if (["restore", "restore-capsule"].includes(words[at])) return "write";
+      if (["put", "rm", "delete", "remove"].includes(words[at]) && asksForHelp(words, at + 1, true)) return "read";
       return "delete";
     }
     if (tool === "git") {
       const sub = gitSubcommand(part, index);
-      if (sub === "clean" || sub === "rm") return "delete";
+      // Honoured only for `git rm|clean <request>`: a global option before the
+      // subcommand is not modelled here, so it keeps the delete.
+      if (sub === "clean" || sub === "rm") return words[1] === sub && asksForHelp(words, 2, true) ? "read" : "delete";
       return sub === "clone" || sub === "init" ? "write" : "read";
     }
     if (tool === "env" && mentionsDeleteVerb(envSplitCommandText(words))) return "delete";
@@ -499,6 +530,384 @@ function cdDestinations(operand: string | undefined, bases: string[], home: stri
 
 const REL_OPERAND = /(?:^|\s)(\.\.?|[^\s"';&|<>()\x60/]+(?:\/[^\s"';&|<>()\x60]*)?)\s*$/;
 
+interface HeredocSpan {
+  /** Line of the `<<` operator, and the operator's columns on it. */
+  line: number;
+  from: number;
+  to: number;
+  /** First body line, and the terminator line just past the last. */
+  start: number;
+  end: number;
+  quoted: boolean;
+}
+
+/**
+ * Here-document bodies in a command, located line by line. Bash reads a body
+ * from the line after the one holding its `<<` operator, whatever quoting or
+ * `$( )` that operator sits in, so each line is scanned with a stack of open
+ * contexts (a `"..."` string, a `$( )` with its unclosed `(` count) carried
+ * across lines. Returns null when the scan cannot be followed to the end: a
+ * `'...'`, backtick or arithmetic `(( ))` spanning lines, an operator with no
+ * word, a body with no exact terminator line (bash's `DELIM)` form included),
+ * or a quote or substitution still open at the end.
+ */
+export function heredocSpans(command: string): HeredocSpan[] | null {
+  const lines = command.split("\n");
+  const spans: HeredocSpan[] = [];
+  const stack: Array<'"' | number> = [];
+  let n = 0;
+  while (n < lines.length) {
+    const lineIndex = n;
+    const line = lines[n++].replace(/\r$/, "");
+    const pending: Array<{ marker: HeredocMarker; from: number }> = [];
+    for (let i = 0; i < line.length; i++) {
+      const ch = line[i];
+      const top = stack[stack.length - 1];
+      if (ch === "\\") {
+        i++;
+        continue;
+      }
+      if (ch === "$" && line[i + 1] === "(" && line[i + 2] === "(") {
+        const close = line.indexOf("))", i + 3);
+        if (close < 0) return null;
+        i = close + 1;
+        continue;
+      }
+      if (ch === "$" && line[i + 1] === "(") {
+        stack.push(0);
+        i++;
+        continue;
+      }
+      // `$[ ]` is arithmetic, so a `<<` in it is a shift, not an operator.
+      if (ch === "$" && line[i + 1] === "[") return null;
+      // Inside `${...}` a `<<` is not an operator either (`${x:-<<EOF}` starts
+      // no body), so a parameter expansion is skipped only when it holds no
+      // quote, substitution, nested expansion or `<<`; otherwise the scan
+      // gives up and the command keeps the line-by-line analysis.
+      if (ch === "$" && line[i + 1] === "{") {
+        const close = line.indexOf("}", i + 2);
+        if (close < 0 || /['"\x60$]|<</.test(line.slice(i + 2, close))) return null;
+        i = close;
+        continue;
+      }
+      if (ch === "\x60") {
+        const close = line.indexOf("\x60", i + 1);
+        if (close < 0) return null;
+        i = close;
+        continue;
+      }
+      if (top === '"') {
+        if (ch === '"') stack.pop();
+        continue;
+      }
+      // Command text, at the top level or inside `$( )`.
+      if (ch === "'") {
+        const close = line.indexOf("'", i + 1);
+        if (close < 0) return null;
+        i = close;
+        continue;
+      }
+      if (ch === '"') {
+        stack.push('"');
+        continue;
+      }
+      if (ch === "#" && (i === 0 || /[\s;&|()]/.test(line[i - 1]))) break;
+      if (ch === "(" && line[i + 1] === "(" && (i === 0 || /[\s;&|(]/.test(line[i - 1]))) {
+        const close = line.indexOf("))", i + 2);
+        if (close < 0) return null;
+        i = close + 1;
+        continue;
+      }
+      if (typeof top === "number" && (ch === "(" || ch === ")")) {
+        if (ch === "(") stack[stack.length - 1] = top + 1;
+        else if (top === 0) stack.pop();
+        else stack[stack.length - 1] = top - 1;
+        continue;
+      }
+      if (ch === "<" && line[i + 1] === "<") {
+        if (line[i + 2] === "<") {
+          i += 2;
+          continue;
+        }
+        const marker = heredocMarkerAt(line, i);
+        if (!marker) return null;
+        pending.push({ marker, from: i });
+        i = marker.end - 1;
+      }
+    }
+    for (const { marker, from } of pending) {
+      const start = n;
+      for (;;) {
+        if (n >= lines.length) return null;
+        let text = lines[n++].replace(/\r$/, "");
+        if (marker.stripTabs) text = text.replace(/^\t+/, "");
+        if (text === marker.delimiter) break;
+      }
+      spans.push({ line: lineIndex, from, to: marker.end, start, end: n - 1, quoted: marker.quoted });
+    }
+  }
+  return stack.length === 0 ? spans : null;
+}
+
+/**
+ * Words that can run a here-document body as code, or run something that
+ * may: shells, interpreters, remote, privileged and deferred runners, and
+ * tools with a shell escape. Matched as any word of the command, because
+ * wrappers (`sudo -u x bash`, `timeout 9 sh`, `xargs rm`) put the runner after
+ * the command word.
+ */
+const BODY_RUNNERS = new Set([
+  "sh", "bash", "zsh", "dash", "ksh", "mksh", "ash", "fish", "csh", "tcsh", "nu", "xonsh", "elvish", "busybox", "toybox",
+  "ssh", "su", "runuser", "sudo", "doas", "pkexec", "xargs", "parallel", "expect", "script", "at", "batch", "crontab",
+  "watch", "flock", "chroot", "nsenter", "unshare", "docker", "podman", "kubectl", "lxc",
+  "python", "pypy", "node", "nodejs", "bun", "deno", "tsx", "ts-node", "zx", "npx", "bunx", "pnpx", "perl", "ruby", "irb",
+  "php", "lua", "luajit", "osascript", "pwsh", "powershell", "Rscript", "R", "julia", "tclsh", "wish",
+  "awk", "gawk", "mawk", "nawk", "sed", "make", "gmake", "gdb", "lldb", "sqlite3", "psql", "mysql", "sftp", "ftp", "lftp",
+  "vim", "vi", "nvim", "ex", "ed", "emacs",
+  // Making a file executable is how a written body becomes a runnable script.
+  "chmod",
+]);
+
+/** Builtins that run a file or string as shell code, or rename a command, in command position. */
+const BODY_RUNNER_COMMANDS = new Set([".", "source", "eval", "env", "alias", "hash"]);
+
+/** Commands whose operands name files they write. */
+const FILE_WRITERS = new Set(["tee", "cp", "mv", "install", "ln"]);
+
+/**
+ * The only command words a command holding a data body may use: commands that
+ * read, write, move or delete files but never run their input or arguments as
+ * code, plus the Hasna record CLIs a body is usually filed through. The rest
+ * of the command is still analysed, so a delete here still counts. A list of
+ * runners can never be complete (`rbash`, `newgrp`, `sg`, `tclsh8.6`, any
+ * installed interpreter), so any other command word keeps the line-by-line
+ * analysis. `git` and `gh` are checked by subcommand (dataCommand).
+ */
+const DATA_COMMANDS = new Set([
+  "cat", "tac", "tee", "head", "tail", "wc", "cut", "tr", "nl", "rev", "fold", "fmt", "paste", "uniq",
+  "grep", "egrep", "fgrep", "jq", "diff", "cmp", "comm", "iconv", "od", "xxd", "hexdump",
+  "base64", "base32", "md5sum", "sha1sum", "sha224sum", "sha256sum", "sha384sum", "sha512sum", "b2sum", "cksum",
+  "echo", "printf", "true", "false", ":", "test", "[", "read", "cd", "pwd", "ls", "mkdir", "touch", "stat", "sleep",
+  "cp", "mv", "ln", "rm", "rmdir", "unlink", "shred", "trash",
+  "todos", "conversations", "mementos", "knowledge", "files", "asks",
+]);
+
+/** git subcommands that take a body only as a message, patch or blob. */
+const GIT_DATA_SUBCOMMANDS = new Set([
+  "add", "commit", "tag", "notes", "status", "diff", "log", "show", "rev-parse", "branch", "switch", "push", "fetch",
+  "hash-object", "apply",
+]);
+
+/** gh commands that take a body only as text or a request payload. */
+const GH_DATA_COMMANDS = new Set(["pr", "issue", "api", "release", "gist"]);
+
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*\+?=/;
+
+/**
+ * Whether the command word at `index` of `words` is a data command. git is
+ * accepted only with `-C <dir>`, `--no-pager` or `-P` before a data
+ * subcommand (`-c` can define an alias that runs a shell on stdin), and gh
+ * only for its built-in commands (an extension or shell alias can run
+ * anything).
+ */
+function dataCommand(words: string[], index: number): boolean {
+  const name = words[index];
+  if (name === "gh") return GH_DATA_COMMANDS.has(words[index + 1] ?? "");
+  if (name !== "git") return DATA_COMMANDS.has(name);
+  for (let at = index + 1; at < words.length; at++) {
+    const word = words[at];
+    if (word === "-C") at++;
+    else if (word === "--no-pager" || word === "-P") continue;
+    else return !word.startsWith("-") && GIT_DATA_SUBCOMMANDS.has(word);
+  }
+  return false;
+}
+
+const baseName = (word: string): string => word.split("/").pop() ?? "";
+
+/**
+ * Index of the `"` closing the one at `open`, past escapes and the
+ * substitutions inside it; -1 when there is none.
+ */
+function closingDoubleQuote(text: string, open: number): number {
+  for (let i = open + 1; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "\\") i++;
+    else if (ch === '"') return i;
+    else if (ch === "$" && text[i + 1] === "(") {
+      i = closingParen(text, i + 1);
+      if (i < 0) return -1;
+    } else if (ch === "\x60") {
+      i = text.indexOf("\x60", i + 1);
+      if (i < 0) return -1;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Index of the `)` closing the `(` at `open`, skipping quoted text and
+ * backtick substitutions; -1 when there is none.
+ */
+function closingParen(text: string, open: number): number {
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "\\") i++;
+    else if (ch === "'" || ch === "\x60") {
+      i = text.indexOf(ch, i + 1);
+      if (i < 0) return -1;
+    } else if (ch === '"') {
+      i = closingDoubleQuote(text, i);
+      if (i < 0) return -1;
+    } else if (ch === "(") depth++;
+    else if (ch === ")" && --depth === 0) return i;
+  }
+  return -1;
+}
+
+/**
+ * The text of every `$( )` and backtick command substitution in `text` at
+ * this level, inside double quotes or not (single quotes run nothing). Their
+ * own substitutions are found when each is scanned in turn. Null when the
+ * text cannot be followed, or an arithmetic `$(( ))` holds a substitution.
+ */
+function commandSubstitutions(text: string): string[] | null {
+  const found: string[] = [];
+  let inDouble = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === "\\") i++;
+    else if (ch === "'" && !inDouble) {
+      const close = text.indexOf("'", i + 1);
+      if (close < 0) return null;
+      i = close;
+    } else if (ch === '"') inDouble = !inDouble;
+    else if (ch === "$" && text[i + 1] === "(") {
+      const close = closingParen(text, i + 1);
+      if (close < 0) return null;
+      const inner = text.slice(i + 2, close);
+      if (text[i + 2] === "(") {
+        if (/\$\(|\x60/.test(inner)) return null;
+      } else found.push(inner);
+      i = close;
+    } else if (ch === "\x60") {
+      const close = text.indexOf("\x60", i + 1);
+      if (close < 0) return null;
+      found.push(text.slice(i + 1, close));
+      i = close;
+    }
+  }
+  return inDouble ? null : found;
+}
+
+/**
+ * Whether anything in `command` (here-document bodies, terminators and
+ * operators already blanked) could execute a body, here or in a command
+ * substitution: a runner word anywhere; a process substitution; a variable
+ * assignment (`PATH=...` changes what a command word runs); or a command word
+ * that is not a data command (DATA_COMMANDS, dataCommand), is a path or an
+ * expansion, or is the bare name of a file the command writes. Text that
+ * cannot be parsed counts as yes.
+ */
+function mayRunBodies(command: string): boolean {
+  if (/[<>]\(/.test(command)) return true;
+  const segments: ReturnType<typeof lexCommand>["segments"] = [];
+  const queue = [command];
+  for (let parsed = 0; queue.length > 0; parsed++) {
+    if (parsed > 64) return true;
+    const text = queue.shift()!;
+    const lexed = lexCommand(text);
+    // lexCommand reports only top-level substitutions; one inside double
+    // quotes (`"$(sh <<'EOF' … )"`) runs just the same.
+    const nested = commandSubstitutions(text);
+    if (!lexed.trustworthy || !nested) return true;
+    segments.push(...lexed.segments);
+    queue.push(...new Set([...lexed.substitutions, ...nested]));
+  }
+  // Every file the command writes: redirect targets, writer operands, dd of=.
+  const written = new Set<string>();
+  for (const segment of segments) {
+    const words = segment.words.map((word) => decodeWord(word.text));
+    for (const at of segment.redirects) written.add(baseName(words[at] ?? ""));
+    const index = commandWordIndex(segment);
+    if (index < 0) continue;
+    const tool = baseName(words[index]);
+    if (FILE_WRITERS.has(tool)) {
+      for (const word of words.slice(index + 1)) if (!word.startsWith("-")) written.add(baseName(word));
+    }
+    if (tool === "dd") {
+      for (const word of words) if (word.startsWith("of=")) written.add(baseName(word.slice(3)));
+    }
+  }
+  written.delete("");
+  for (const segment of segments) {
+    for (const word of segment.words) {
+      const name = baseName(decodeWord(word.text));
+      if (BODY_RUNNERS.has(name) || /^(?:python|pypy|node|perl|ruby|php|lua)[0-9.]+$/.test(name)) return true;
+    }
+    const index = commandWordIndex(segment);
+    const words = segment.words
+      .map((word, at) => ({ text: decodeWord(word.text), at }))
+      .filter(({ at }) => !segment.redirects.has(at));
+    if (words.some(({ text, at }) => (index < 0 || at < index) && ASSIGNMENT.test(text))) return true;
+    if (index < 0) continue;
+    const raw = segment.words[index].text;
+    const name = decodeWord(raw);
+    if (/[$\x60]/.test(raw) || name.includes("/") || BODY_RUNNER_COMMANDS.has(name) || written.has(name)) return true;
+    if (!dataCommand(words.filter(({ at }) => at >= index).map(({ text }) => text), 0)) return true;
+  }
+  return false;
+}
+
+/**
+ * When every here-document body in `command` is data, the command with the
+ * bodies and their terminator lines blanked, and the bodies. A body is data
+ * when its delimiter is quoted, or it holds no `$( )` or backtick (expansion
+ * alone runs nothing), and nothing in the command can run it (mayRunBodies:
+ * every command word is a data command).
+ * Otherwise null: the command is analysed line by line as it stands.
+ */
+function dataHeredocs(command: string): { outer: string; bodies: string[] } | null {
+  if (!command.includes("<<")) return null;
+  const spans = heredocSpans(command);
+  if (!spans || spans.length === 0) return null;
+  const lines = command.split("\n");
+  const outer = [...lines];
+  const bodies: string[] = [];
+  for (const span of spans) {
+    const body = lines.slice(span.start, span.end);
+    if (!span.quoted && body.some((line) => /\$\(|\x60/.test(line))) return null;
+    bodies.push(body.join("\n"));
+    for (let k = span.start; k <= span.end; k++) outer[k] = "";
+  }
+  const lexed = [...outer];
+  for (const span of [...spans].reverse()) {
+    const line = lexed[span.line];
+    lexed[span.line] = line.slice(0, span.from) + " ".repeat(span.to - span.from) + line.slice(span.to);
+  }
+  return mayRunBodies(lexed.join("\n")) ? null : { outer: outer.join("\n"), bodies };
+}
+
+/**
+ * A directory outside every protected root. A data body is analysed as if run
+ * from here, so only a protected path it names, or reaches with its own `cd`,
+ * can count; its other words never resolve against the real cwd.
+ */
+const DETACHED_CWD = "/";
+
+/**
+ * Extract protected-repo-checkout targets from a Bash command. Here-document
+ * bodies that are data (dataHeredocs) are analysed on their own from
+ * DETACHED_CWD; the rest of the command is analysed by segmentTargets.
+ */
+export function bashTargets(command: string, home: string, cwd: string): PathTarget[] {
+  if (!command) return [];
+  const data = dataHeredocs(command);
+  if (!data) return segmentTargets(command, home, cwd);
+  return [...segmentTargets(data.outer, home, cwd), ...data.bodies.flatMap((body) => bashTargets(body, home, DETACHED_CWD))];
+}
+
 /**
  * Extract protected-repo-checkout targets from a Bash command. Recognises
  * explicit `~/...`, `$HOME/...`, `${HOME}/...` and literal-home references
@@ -519,7 +928,7 @@ const REL_OPERAND = /(?:^|\s)(\.\.?|[^\s"';&|<>()\x60/]+(?:\/[^\s"';&|<>()\x60]*
  * pipeline or the background does not change the outer cwd, and a cd that
  * cannot be resolved statically never narrows it.
  */
-export function bashTargets(command: string, home: string, cwd: string): PathTarget[] {
+function segmentTargets(command: string, home: string, cwd: string): PathTarget[] {
   if (!command) return [];
   const roots = protectedRoots(home);
   const underRoot = (path: string) => roots.some((root) => path === root || path.startsWith(`${root}${sep}`));
@@ -804,7 +1213,10 @@ export async function run(): Promise<void> {
   }
 }
 
+// Standalone run only. No top-level await: the CommonJS native safety worker
+// (scripts/build-native-worker.ts) bundles this module, and its parser refuses
+// top-level await even where import.meta.main=false makes the block dead.
+// A rejected run still exits non-zero, as an awaited one did.
 if (import.meta.main) {
-  await run();
-  process.exit(0);
+  void run().then(() => process.exit(0));
 }

package/hooks/native-safety-composite.ts

@@ -0,0 +1,75 @@
+import { homedir } from "node:os";
+import { isAbsolute } from "node:path";
+import { evaluate as evaluateTrash, findTrashBinary, inspectTrashBinary, scanCommand } from "./hook-trash-guard/src/hook";
+import { evaluate as evaluateRepos } from "./hook-workspace-repos-guard/src/hook";
+import { evaluate as evaluateSignedLinks } from "./hook-signed-link-guard/src/hook";
+import type { CodewithHookInput, CodewithHookOutput } from "./codewith-native-common";
+
+// The native safety composite: trash-guard, workspace-repos-guard and
+// signed-link-guard judged together for one capability name. Both the v1 entry
+// (hooks/native-safety-entry.ts) and the v2 worker (hooks/native-safety-worker.ts)
+// call it, so one guard decision has one implementation. It reads no stdin,
+// writes no stdout and never exits: the caller owns the process.
+
+export type NativeSafetyCompositeGuard = "trash-guard" | "workspace-repos-guard";
+
+/** Refuses an unknown capability name exactly as the v1 entry always has. */
+export function assertCompositeGuard(guard: unknown): asserts guard is NativeSafetyCompositeGuard {
+  if (guard !== "trash-guard" && guard !== "workspace-repos-guard") throw new Error("Invalid safety capability");
+}
+
+/**
+ * Judge one PreToolUse input for `guard`. Returns the exact text the v1 entry
+ * writes to stdout (`{"verdict":null}` or `{"verdict":{hookSpecificOutput}}`),
+ * and throws where the v1 entry exits non-zero.
+ */
+export function evaluateComposite(guard: string, inputText: string): string {
+  assertCompositeGuard(guard);
+  const name = guard;
+  const input = JSON.parse(inputText) as CodewithHookInput;
+  if (!input || Array.isArray(input) || input.hook_event_name !== "PreToolUse" || typeof input.tool_name !== "string"
+    || !input.tool_input || typeof input.tool_input !== "object" || Array.isArray(input.tool_input)
+    || typeof input.cwd !== "string" || !isAbsolute(input.cwd)) throw new Error("Invalid safety input");
+  if (input.tool_name === "Bash" && typeof input.tool_input.command !== "string") throw new Error("Invalid shell input");
+  // Claude Code's Monitor runs a shell command and streams its stdout to the
+  // model; a websocket Monitor carries `ws` and no command.
+  if (input.tool_name === "Monitor" && input.tool_input.command !== undefined && typeof input.tool_input.command !== "string") throw new Error("Invalid monitor input");
+  const requestedExecution = (input as CodewithHookInput & { hasna_execution?: { schema: string; agent: string } }).hasna_execution;
+  if (requestedExecution !== undefined && (!requestedExecution || Object.keys(requestedExecution).sort().join() !== "agent,schema"
+    || requestedExecution.schema !== "hasna.hooks.execution.v1" || typeof requestedExecution.agent !== "string"
+    || !/^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$/.test(requestedExecution.agent))) throw new Error("Invalid execution capability");
+  const execution = requestedExecution === undefined ? undefined : {
+    runtime: process.execPath, home: homedir(), path: process.env.PATH!, agent: requestedExecution.agent,
+  };
+  if (execution && (!isAbsolute(execution.runtime) || !execution.path)) throw new Error("Invalid bound execution context");
+  if (["apply_patch", "ApplyPatch", "functions.apply_patch"].includes(input.tool_name)) {
+    if (input.tool_input.command !== undefined && input.tool_input.patch !== undefined && input.tool_input.command !== input.tool_input.patch) throw new Error("Conflicting patch aliases");
+    const patch = input.tool_input.command ?? input.tool_input.patch;
+    if (typeof patch !== "string") throw new Error("Invalid patch input");
+    input.tool_input = { ...input.tool_input, command: patch, patch };
+  }
+  // Every guard judges a Monitor command exactly as it judges the same Bash command.
+  const monitor = input.tool_name === "Monitor";
+  const shellCommand = input.tool_name === "Bash" || (monitor && typeof input.tool_input.command === "string");
+  const evaluated: CodewithHookInput = monitor && shellCommand ? { ...input, tool_name: "Bash" } : input;
+  const deny = (reason: string) => ({ hookSpecificOutput: { hookEventName: "PreToolUse" as const, permissionDecision: "deny" as const, permissionDecisionReason: reason } });
+  const repos = evaluateRepos(evaluated).output;
+  // Every shell command, whatever the capability name: the guard reaches each
+  // registration of this entry. Its refusal outranks a Trash rewrite, because an
+  // allowed rewrite would also run the composite gh read.
+  const signedLinks = evaluateSignedLinks(evaluated);
+  const handoff = shellCommand && scanCommand(evaluated.tool_input!.command as string, { home: homedir(), cwd: input.cwd }).handoffHits.length > 0;
+  let trash: CodewithHookOutput = name === "trash-guard" && (!monitor || shellCommand)
+    ? evaluateTrash(evaluated, { home: homedir(), cwd: input.cwd, findTrash: findTrashBinary, inspectTrash: inspectTrashBinary, execution }) : { continue: true };
+  // A Trash rewrite is proven only for Bash. Under Monitor the deletion is
+  // refused rather than rewritten: a rewrite the harness dropped would run the
+  // raw command.
+  if (monitor && trash.hookSpecificOutput?.permissionDecision === "allow") {
+    trash = deny("[trash-guard] A deletion inside a Monitor command is refused; run it with the Bash tool, where it is redirected into trash.");
+  }
+  const verdict: CodewithHookOutput = repos.decision === "block" ? deny(repos.reason!)
+    : signedLinks.hookSpecificOutput ? signedLinks
+    : handoff ? deny("[workspace-repos-guard] Deletion under a protected repository checkout is refused.")
+    : trash;
+  return JSON.stringify({ verdict: "continue" in verdict ? null : verdict });
+}

package/hooks/native-safety-entry.ts

@@ -1,57 +1,11 @@
-import { homedir } from "node:os";
-import { isAbsolute } from "node:path";
-import { evaluate as evaluateTrash, findTrashBinary, inspectTrashBinary, scanCommand } from "./hook-trash-guard/src/hook";
-import { evaluate as evaluateRepos } from "./hook-workspace-repos-guard/src/hook";
-import { evaluate as evaluateSignedLinks } from "./hook-signed-link-guard/src/hook";
-import type { CodewithHookInput, CodewithHookOutput } from "./codewith-native-common";
+import { assertCompositeGuard, evaluateComposite } from "./native-safety-composite";
 
+// The v1 native safety entry: a thin wrapper over the composite. Its contract is
+// fixed by the v1 supervisor (src/lib/native-safety.ts): the capability name is
+// argv[1], the hook input is stdin, the verdict is one JSON write to stdout, and
+// any failure exits non-zero.
 // Bundled with import.meta.main=false, so the original standalone run wrappers
 // cannot swallow exceptions or emit a second response. Only this entry runs.
 const name = process.argv[1];
-if (name !== "trash-guard" && name !== "workspace-repos-guard") throw new Error("Invalid safety capability");
-const input = JSON.parse(await Bun.stdin.text()) as CodewithHookInput;
-if (!input || Array.isArray(input) || input.hook_event_name !== "PreToolUse" || typeof input.tool_name !== "string"
-  || !input.tool_input || typeof input.tool_input !== "object" || Array.isArray(input.tool_input)
-  || typeof input.cwd !== "string" || !isAbsolute(input.cwd)) throw new Error("Invalid safety input");
-if (input.tool_name === "Bash" && typeof input.tool_input.command !== "string") throw new Error("Invalid shell input");
-// Claude Code's Monitor runs a shell command and streams its stdout to the
-// model; a websocket Monitor carries `ws` and no command.
-if (input.tool_name === "Monitor" && input.tool_input.command !== undefined && typeof input.tool_input.command !== "string") throw new Error("Invalid monitor input");
-const requestedExecution = (input as CodewithHookInput & { hasna_execution?: { schema: string; agent: string } }).hasna_execution;
-if (requestedExecution !== undefined && (!requestedExecution || Object.keys(requestedExecution).sort().join() !== "agent,schema"
-  || requestedExecution.schema !== "hasna.hooks.execution.v1" || typeof requestedExecution.agent !== "string"
-  || !/^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$/.test(requestedExecution.agent))) throw new Error("Invalid execution capability");
-const execution = requestedExecution === undefined ? undefined : {
-  runtime: process.execPath, home: homedir(), path: process.env.PATH!, agent: requestedExecution.agent,
-};
-if (execution && (!isAbsolute(execution.runtime) || !execution.path)) throw new Error("Invalid bound execution context");
-if (["apply_patch", "ApplyPatch", "functions.apply_patch"].includes(input.tool_name)) {
-  if (input.tool_input.command !== undefined && input.tool_input.patch !== undefined && input.tool_input.command !== input.tool_input.patch) throw new Error("Conflicting patch aliases");
-  const patch = input.tool_input.command ?? input.tool_input.patch;
-  if (typeof patch !== "string") throw new Error("Invalid patch input");
-  input.tool_input = { ...input.tool_input, command: patch, patch };
-}
-// Every guard judges a Monitor command exactly as it judges the same Bash command.
-const monitor = input.tool_name === "Monitor";
-const shellCommand = input.tool_name === "Bash" || (monitor && typeof input.tool_input.command === "string");
-const evaluated: CodewithHookInput = monitor && shellCommand ? { ...input, tool_name: "Bash" } : input;
-const deny = (reason: string) => ({ hookSpecificOutput: { hookEventName: "PreToolUse" as const, permissionDecision: "deny" as const, permissionDecisionReason: reason } });
-const repos = evaluateRepos(evaluated).output;
-// Every shell command, whatever the capability name: the guard reaches each
-// registration of this entry. Its refusal outranks a Trash rewrite, because an
-// allowed rewrite would also run the composite gh read.
-const signedLinks = evaluateSignedLinks(evaluated);
-const handoff = shellCommand && scanCommand(evaluated.tool_input!.command as string, { home: homedir(), cwd: input.cwd }).handoffHits.length > 0;
-let trash: CodewithHookOutput = name === "trash-guard" && (!monitor || shellCommand)
-  ? evaluateTrash(evaluated, { home: homedir(), cwd: input.cwd, findTrash: findTrashBinary, inspectTrash: inspectTrashBinary, execution }) : { continue: true };
-// A Trash rewrite is proven only for Bash. Under Monitor the deletion is
-// refused rather than rewritten: a rewrite the harness dropped would run the
-// raw command.
-if (monitor && trash.hookSpecificOutput?.permissionDecision === "allow") {
-  trash = deny("[trash-guard] A deletion inside a Monitor command is refused; run it with the Bash tool, where it is redirected into trash.");
-}
-const verdict: CodewithHookOutput = repos.decision === "block" ? deny(repos.reason!)
-  : signedLinks.hookSpecificOutput ? signedLinks
-  : handoff ? deny("[workspace-repos-guard] Deletion under a protected repository checkout is refused.")
-  : trash;
-process.stdout.write(JSON.stringify({ verdict: "continue" in verdict ? null : verdict }));
+assertCompositeGuard(name);
+process.stdout.write(evaluateComposite(name, await Bun.stdin.text()));

package/hooks/native-safety-worker.ts

@@ -0,0 +1,19 @@
+import { evaluateComposite } from "./native-safety-composite";
+
+// The native safety worker, ABI v2 (docs/adr/0001-stable-native-safety-launcher.md
+// section 3.4). scripts/build-native-worker.ts bundles it into
+// bin/native-safety-worker.cjs: CommonJS for Node's module shape, requiring only
+// node: builtins, with no top-level await and no top-level side effects. It reads
+// no stdin, writes no stdout and never exits; the loader that evaluates the
+// verified bundle owns the process.
+
+/** Replaced at build time with the package.json version; never set at run time. */
+declare const HASNA_HOOKS_NATIVE_SAFETY_WORKER_VERSION: string;
+
+export const abi = 2;
+export const version: string = HASNA_HOOKS_NATIVE_SAFETY_WORKER_VERSION;
+
+/** The v1 entry's exact stdout text for this input; throws where the v1 entry exits non-zero. */
+export function evaluate(guard: string, inputText: string): string {
+  return evaluateComposite(guard, inputText);
+}