failproofai 1.0.3 → 1.0.4-beta.1

package/src/hooks/batch-expand.ts

@@ -0,0 +1,380 @@
+/**
+ * Expand a CLI's BATCH tool call into per-element canonical scalar inputs.
+ *
+ * failproofai's builtins read SCALARS — `tool_input.command`, `.file_path`,
+ * `.pattern`, `.old_string`. Cline delivers ARRAYS: `run_commands{commands[]}`,
+ * `read_files{files[]}`, `search_codebase{queries[]}`, plus one multi-file blob
+ * in `apply_patch{input}`. With only a key rename, `block-sudo`,
+ * `block-env-files`, `block-secrets-write`, `block-force-push` and
+ * `block-read-outside-cwd` all read `undefined` and ALLOW SILENTLY — the
+ * inert-hook failure this repo has already shipped twice (grok, and our own
+ * Claude hooks running inside grok).
+ *
+ * Joining the array into one string is NOT a fix, and the reason is specific:
+ * `SECRET_FILE_RE` is `/\.(?:pem|key)$/`. Under any join only the LAST element
+ * can ever match, so a `.pem` at `files[0]` rides straight through. That is why
+ * this expands and the evaluator runs the policy set once per element.
+ *
+ * PURE: no evaluator import, no fs, no policy registry — so the audit path can
+ * call it without dragging the policy engine along.
+ *
+ * CONTAINMENT: returns null for every CLI except cline and every tool except
+ * cline's four containers. `null` means "take the existing single-shot path,
+ * byte-for-byte unchanged", so this cannot regress the other 15 integrations.
+ */
+import type { IntegrationType } from "./types";
+import {
+  ENV_FILE_PATH_RE,
+  SECRET_FILE_RE,
+  SECRET_FILE_ID_RSA_RE,
+  SECRET_FILE_CREDENTIALS_RE,
+} from "./risk-patterns";
+
+export interface FanoutElement {
+  /** Canonical SCALAR tool input: {command} | {file_path,…} | {pattern} |
+   *  {file_path, old_string, new_string, patch}. */
+  input: Record<string, unknown>;
+  /** Short human locator; goes into the deny message and the activity row. */
+  label: string;
+  index: number;
+  /** True when this element is a COLLAPSE of several that the cap or the
+   *  wall-clock budget refused to run apart. A weaker guarantee we state
+   *  explicitly, never a silent skip. */
+  degraded?: boolean;
+}
+
+export interface BatchExpansion {
+  /** Canonical tool name (Bash | Read | Grep | Edit). */
+  tool: string;
+  elements: FanoutElement[];
+  /** The un-expanded original, so a batch-aware policy still sees the whole call. */
+  raw: Record<string, unknown>;
+}
+
+/**
+ * The separator used wherever a command list still has to collapse to one
+ * string. `" &&\n"` is DERIVED, not chosen:
+ *   • `"\n"` alone silently disables `READ_LIKE_CMDS` — its boundary
+ *     alternation `(?:^|;|&&|\|\||\|)` contains no newline, so a batched
+ *     `cat /etc/passwd` stops looking read-like and `block-read-outside-cwd`
+ *     never inspects it.
+ *   • `" && "` alone manufactures a FALSE deny: a `.`-based lookahead can cross
+ *     the boundary and fire on two commands neither of which triggers it alone.
+ * `" &&\n"` keeps every `&&`-aware segmenter alive while the newline stops
+ * `.`-based lookaheads crossing a boundary.
+ */
+export const BATCH_JOIN = " &&\n";
+
+function omit(o: Record<string, unknown>, key: string): Record<string, unknown> {
+  const { [key]: _dropped, ...rest } = o;
+  return rest;
+}
+
+export function expandBatchToolInput(
+  cli: IntegrationType,
+  toolName: string | undefined,
+  rawInput: unknown,
+): BatchExpansion | null {
+  if (cli !== "cline" || !toolName) return null;
+  if (!rawInput || typeof rawInput !== "object" || Array.isArray(rawInput)) return null;
+  const raw = rawInput as Record<string, unknown>;
+
+  // An expansion to ZERO elements would evaluate nothing and report a clean
+  // allow — the exact inert-hook failure this exists to prevent. So an empty or
+  // mis-shaped container returns null and falls back to the collapse safety net
+  // in canonicalizeClineToolInput, which at least still reads SOMETHING.
+  const mk = (
+    parts: Array<{ input: Record<string, unknown>; label: string }>,
+  ): BatchExpansion | null =>
+    parts.length === 0
+      ? null
+      : { tool: toolName, raw, elements: parts.map((e, index) => ({ ...e, index })) };
+
+  switch (toolName) {
+    // run_commands {commands: ["cd '<dir>' && ls -la", …]}
+    case "Bash": {
+      const cmds = raw.commands;
+      if (!Array.isArray(cmds)) return null;
+      return mk(
+        cmds
+          .filter((c): c is string => typeof c === "string")
+          .map((c) => ({ input: { ...omit(raw, "commands"), command: c }, label: c })),
+      );
+    }
+    // read_files {files: [{path, start_line, …}, …]}
+    case "Read": {
+      const files = raw.files;
+      if (!Array.isArray(files)) return null;
+      return mk(
+        files.flatMap((f) => {
+          if (!f || typeof f !== "object" || Array.isArray(f)) return [];
+          const e = f as Record<string, unknown>;
+          if (typeof e.path !== "string") return [];
+          // Spread the entry so start_line/limit survive for policies that read
+          // them; `path` is KEPT too, because a cline-aware custom policy may
+          // already be reading it.
+          return [{ input: { ...e, file_path: e.path }, label: e.path }];
+        }),
+      );
+    }
+    // search_codebase {queries: ["alpha", …]}
+    case "Grep": {
+      const qs = raw.queries;
+      if (!Array.isArray(qs)) return null;
+      return mk(
+        qs
+          .filter((q): q is string => typeof q === "string")
+          .map((q) => ({ input: { ...omit(raw, "queries"), pattern: q }, label: q })),
+      );
+    }
+    // apply_patch {input: "*** Begin Patch …"} — byte-identical to the OpenAI
+    // apply_patch blob ori's `edit` tool carries, so this splitter is
+    // back-portable to ori and closes ori's documented multi-file KNOWN GAP.
+    case "Edit": {
+      const blob = raw.input;
+      if (typeof blob !== "string") return null;
+      return mk(
+        splitApplyPatch(blob).map((s) => ({
+          input: {
+            file_path: s.path,
+            old_string: s.oldText,
+            new_string: s.newText,
+            patch: s.subPatch,
+            cline_patch_op: s.op,
+          },
+          label: `${s.op} ${s.path}`,
+        })),
+      );
+    }
+    default:
+      return null;
+  }
+}
+
+export interface PatchSection {
+  op: "add" | "update" | "delete" | "move";
+  path: string;
+  oldText: string;
+  newText: string;
+  /** A standalone, re-emittable patch for just this file. */
+  subPatch: string;
+}
+
+const FILE_OP_RE = /^\*\*\* (Add File|Update File|Delete File|Move to): (.+)$/;
+const OPS: Record<string, PatchSection["op"]> = {
+  "Add File": "add",
+  "Update File": "update",
+  "Delete File": "delete",
+  "Move to": "move",
+};
+const HEADERS: Record<PatchSection["op"], string> = {
+  add: "Add File",
+  update: "Update File",
+  delete: "Delete File",
+  move: "Move to",
+};
+
+interface OpenSection {
+  op: PatchSection["op"];
+  path: string;
+  body: string[];
+}
+
+function build(cur: OpenSection, op: PatchSection["op"], path: string): PatchSection {
+  const minus: string[] = [];
+  const plus: string[] = [];
+  for (const l of cur.body) {
+    if (l.startsWith("-")) minus.push(l.slice(1));
+    else if (l.startsWith("+")) plus.push(l.slice(1));
+  }
+  return {
+    op,
+    path,
+    oldText: minus.join("\n"),
+    newText: plus.join("\n"),
+    subPatch: ["*** Begin Patch", `*** ${HEADERS[op]}: ${path}`, ...cur.body, "*** End Patch"].join("\n"),
+  };
+}
+
+/**
+ * Split an OpenAI apply_patch blob into one section per file it touches.
+ *
+ * Serves BOTH cline's `apply_patch` and ori's `edit` — the format is identical,
+ * and one implementation is what stops a third CLI adding a third regex.
+ */
+export function splitApplyPatch(patch: string): PatchSection[] {
+  const out: PatchSection[] = [];
+  let cur: OpenSection | null = null;
+
+  for (const line of patch.split("\n")) {
+    const m = FILE_OP_RE.exec(line);
+    if (m) {
+      const op = OPS[m[1]!]!;
+      const path = m[2]!.trim();
+      if (op === "move") {
+        // `Move to:` is a RENAME MODIFIER on the preceding Update File, not an
+        // independent op. We emit it as its OWN element anyway — deliberately —
+        // so a rename INTO `.env` is seen by the path builtins. It inherits the
+        // in-progress body so old/new_string stay right, and the Update element
+        // is still emitted at the next flush. Cost: one rename yields two
+        // elements. That is the trade: a duplicate row, never a missed path.
+        // Flush the section being renamed FIRST, then emit the move, so paths
+        // come out in literal file order — `Update File: a` + `Move to: b`
+        // yields [a, b], never [b, a]. Getting this backwards silently changes
+        // which path `pickRiskiestPath` and `file_path = paths[0]` land on.
+        if (cur) {
+          out.push(build(cur, cur.op, cur.path));
+          out.push(build(cur, "move", path));
+          cur = null;
+        } else
+          out.push({
+            op: "move",
+            path,
+            oldText: "",
+            newText: "",
+            subPatch: `*** Begin Patch\n*** Move to: ${path}\n*** End Patch`,
+          });
+        continue;
+      }
+      if (cur) out.push(build(cur, cur.op, cur.path));
+      cur = { op, path, body: [] };
+      continue;
+    }
+    if (line.startsWith("*** ")) continue; // Begin Patch / End Patch / End of File
+    if (cur) cur.body.push(line);
+  }
+  if (cur) out.push(build(cur, cur.op, cur.path));
+  return out;
+}
+
+/** Every path an apply_patch blob touches, in file order. */
+export function applyPatchFilePaths(patch: string): string[] {
+  return splitApplyPatch(patch).map((s) => s.path);
+}
+
+/**
+ * When a path list must still collapse to ONE (the overflow tail, and the
+ * non-fan-out safety net), pick the one a builtin is most likely to deny on
+ * rather than element [0]. The probes IMPORT the real builtin regexes — a
+ * second hand-maintained copy is how a bypass gets reintroduced by a builtin
+ * edit nobody thought to mirror. Falls back to paths[0] when nothing matches.
+ *
+ * NOT the primary mechanism, and it cannot be: it runs before params are bound,
+ * so `block-secrets-write`'s `additionalPatterns` and `block-read-outside-cwd`'s
+ * `allowPaths` have no influence on it, and neither does any custom policy.
+ * That is exactly why PreToolUse fans out instead of relying on this.
+ */
+export function pickRiskiestPath(paths: string[]): string | undefined {
+  if (paths.length === 0) return undefined;
+  for (const re of [
+    ENV_FILE_PATH_RE,
+    SECRET_FILE_RE,
+    SECRET_FILE_ID_RSA_RE,
+    SECRET_FILE_CREDENTIALS_RE,
+  ]) {
+    const hit = paths.find((p) => re.test(p));
+    if (hit) return hit;
+  }
+  return paths[0];
+}
+
+/** Everything past the cap / budget, joined into ONE degraded element. It is
+ *  still EVALUATED — a weaker guarantee we can state honestly, never a silent
+ *  skip. */
+export function collapseElements(tool: string, els: FanoutElement[]): FanoutElement {
+  const first = els[0]!;
+  const base = { label: `${els.length} collapsed`, index: first.index, degraded: true as const };
+  switch (tool) {
+    case "Bash":
+      return {
+        ...base,
+        input: {
+          ...first.input,
+          command: els.map((e) => String(e.input.command ?? "")).join(BATCH_JOIN),
+        },
+      };
+    case "Read":
+    case "Edit": {
+      const paths = els.map((e) => String(e.input.file_path ?? "")).filter(Boolean);
+      return {
+        ...base,
+        input: { ...first.input, file_path: pickRiskiestPath(paths), cline_collapsed_paths: paths },
+      };
+    }
+    case "Grep":
+      return {
+        ...base,
+        input: { ...first.input, pattern: els.map((e) => String(e.input.pattern ?? "")).join("|") },
+      };
+    default:
+      return { ...first, ...base };
+  }
+}
+
+/**
+ * Cline → canonical, for every path that does NOT fan out: PostToolUse, audit
+ * replay, fail-closed shaping, and a policy reading `ctx.payload`. Derives the
+ * best single scalar and PRESERVES the arrays under `cline_*` so a batch-aware
+ * policy can still see everything.
+ *
+ * This is a SAFETY NET, not the enforcement mechanism: a collapse cannot make
+ * an anchored regex match every element, which is precisely why PreToolUse fans
+ * out instead. `pickRiskiestPath` is what makes the net worth having — element
+ * [0] would silently miss a `.env` at `files[1]`.
+ */
+export function canonicalizeClineToolInput(
+  toolName: string,
+  input: Record<string, unknown>,
+): Record<string, unknown> {
+  switch (toolName) {
+    case "Bash": {
+      const cs = input.commands;
+      if (!Array.isArray(cs)) return input;
+      const commands = cs.filter((c): c is string => typeof c === "string");
+      if (commands.length === 0) return input;
+      return { ...omit(input, "commands"), command: commands.join(BATCH_JOIN), cline_commands: commands };
+    }
+    case "Read": {
+      const files = input.files;
+      if (!Array.isArray(files)) return input;
+      const paths = files
+        .map((f) =>
+          f && typeof f === "object" && !Array.isArray(f)
+            ? (f as Record<string, unknown>).path
+            : undefined,
+        )
+        .filter((p): p is string => typeof p === "string");
+      if (paths.length === 0) return input;
+      return {
+        ...omit(input, "files"),
+        file_path: pickRiskiestPath(paths),
+        cline_files: files,
+        cline_file_paths: paths,
+      };
+    }
+    case "Grep": {
+      const qs = input.queries;
+      if (!Array.isArray(qs)) return input;
+      const queries = qs.filter((q): q is string => typeof q === "string");
+      if (queries.length === 0) return input;
+      return { ...omit(input, "queries"), pattern: queries.join("|"), cline_queries: queries };
+    }
+    case "Edit": {
+      const blob = input.input;
+      if (typeof blob !== "string") return input;
+      const sections = splitApplyPatch(blob);
+      if (sections.length === 0) return input;
+      const paths = sections.map((s) => s.path);
+      return {
+        ...input,
+        patch: blob,
+        file_path: pickRiskiestPath(paths),
+        old_string: sections.map((s) => s.oldText).join("\n"),
+        new_string: sections.map((s) => s.newText).join("\n"),
+        cline_patch_files: paths,
+      };
+    }
+    default:
+      return input;
+  }
+}

package/src/hooks/batch-fanout.ts

@@ -0,0 +1,142 @@
+/**
+ * Run the policy set once per element of an expanded batch tool call.
+ *
+ * Why this exists rather than a cleverer canonicalization: cline's tools carry
+ * ARRAYS, and collapsing an array into one scalar cannot preserve an ANCHORED
+ * regex. `SECRET_FILE_RE` is `/\.(?:pem|key)$/`, so under any join only the last
+ * path can match and a `.pem` at `files[0]` rides straight through — a silent
+ * allow, which is the failure mode this repo has already shipped twice.
+ *
+ * Combination rules:
+ *   all allow, no notes       → plain allow, identical to a non-batch call
+ *   any deny                  → LOWEST element index wins, returned verbatim,
+ *                               short-circuiting the rest
+ *   no deny, >=1 instruct     → union deduped by (policy, reason), shaped ONCE
+ *   no deny/instruct, >=1 note→ same
+ *
+ * The deny is returned verbatim because `evaluatePolicies` already shaped it for
+ * the calling CLI and already embedded the element locator (it received
+ * `opts.batch`). No re-shaping, and therefore nothing to keep in sync with the
+ * 16 per-CLI deny shapes.
+ */
+import { evaluatePolicies, type EvaluationResult } from "./policy-evaluator";
+import { collapseElements, type BatchExpansion, type FanoutElement } from "./batch-expand";
+import { hookLogWarn } from "./hook-logger";
+import type { HookEventType, SessionMetadata } from "./types";
+import type { HooksConfig } from "./policy-types";
+
+/** A shape guard, not the real one: 32 elements of registered policies sits
+ *  comfortably inside daemon-client.ts's 30s RESPONSE budget. The wall clock
+ *  below is what actually protects that budget. */
+const MAX_ELEMENTS = 32;
+const WALL_CLOCK_BUDGET_MS = 5_000;
+
+export interface BatchOutcome {
+  size: number;
+  evaluated: number;
+  decidedIndex: number | null;
+  decidedLabel: string | null;
+  degraded: boolean;
+}
+
+type Entry = { policyName: string; reason: string };
+
+/** Policy P saying the SAME thing about elements 3 and 7 contributes one line;
+ *  P saying two different things contributes both. Keyed on (name, reason). */
+function pushDeduped(into: Entry[], from: Entry[] | undefined): void {
+  for (const e of from ?? []) {
+    const k = `${e.policyName}\t${e.reason}`;
+    if (!into.some((x) => `${x.policyName}\t${x.reason}` === k)) into.push(e);
+  }
+}
+
+export async function evaluateExpandedBatch(
+  eventType: HookEventType,
+  payload: Record<string, unknown>,
+  session: SessionMetadata | undefined,
+  config: HooksConfig | undefined,
+  expansion: BatchExpansion,
+  dedupe: Set<string>,
+): Promise<EvaluationResult & { batch: BatchOutcome }> {
+  const started = Date.now();
+
+  let queue: FanoutElement[] =
+    expansion.elements.length > MAX_ELEMENTS
+      ? [
+          ...expansion.elements.slice(0, MAX_ELEMENTS),
+          collapseElements(expansion.tool, expansion.elements.slice(MAX_ELEMENTS)),
+        ]
+      : [...expansion.elements];
+
+  const instructs: Entry[] = [];
+  const allows: Entry[] = [];
+  let evaluated = 0;
+  let sawDegraded = false;
+
+  for (let i = 0; i < queue.length; i++) {
+    // Checked BETWEEN elements only — a policy already inside its own timeout
+    // race is not interruptible from here.
+    if (i > 0 && Date.now() - started > WALL_CLOCK_BUDGET_MS) {
+      const rest = queue.slice(i);
+      hookLogWarn(
+        `batch fan-out budget exceeded after ${i}/${queue.length} elements; the remaining ` +
+          `${rest.length} are being evaluated COLLAPSED — anchored patterns may not match`,
+      );
+      queue = [...queue.slice(0, i), collapseElements(expansion.tool, rest)];
+    }
+    const el = queue[i]!;
+    sawDegraded = sawDegraded || !!el.degraded;
+
+    const r = await evaluatePolicies(
+      eventType,
+      { ...payload, tool_input: el.input },
+      session,
+      config,
+      {
+        dedupe,
+        collectEntries: true,
+        batch: {
+          index: el.index,
+          count: expansion.elements.length,
+          label: el.label,
+          degraded: !!el.degraded,
+          all: expansion.elements.map((e) => e.input),
+          raw: expansion.raw,
+        },
+      },
+    );
+    evaluated++;
+
+    if (r.decision === "deny") {
+      return {
+        ...r,
+        batch: {
+          size: expansion.elements.length,
+          evaluated,
+          decidedIndex: el.index,
+          decidedLabel: el.label,
+          degraded: sawDegraded,
+        },
+      };
+    }
+    pushDeduped(instructs, r.instructEntries);
+    pushDeduped(allows, r.allowEntries);
+  }
+
+  // One shaping pass over the deduped union, through the SAME per-CLI tails
+  // every other integration uses — no shaping code was extracted to get here.
+  const shaped = await evaluatePolicies(eventType, payload, session, config, {
+    dedupe,
+    preEvaluated: { instructEntries: instructs, allowEntries: allows },
+  });
+  return {
+    ...shaped,
+    batch: {
+      size: expansion.elements.length,
+      evaluated,
+      decidedIndex: null,
+      decidedLabel: null,
+      degraded: sawDegraded,
+    },
+  };
+}

package/src/hooks/builtin-policies.ts

@@ -16,6 +16,12 @@ import { POLICY_CATALOG } from "./policy-catalog";
 import { allow, deny, instruct } from "./policy-helpers";
 import { normalizePolicyName, registerPolicy } from "./policy-registry";
 import { hookLogWarn } from "./hook-logger";
+import {
+  ENV_FILE_PATH_RE,
+  SECRET_FILE_RE,
+  SECRET_FILE_ID_RSA_RE,
+  SECRET_FILE_CREDENTIALS_RE,
+} from "./risk-patterns";
 
 /**
  * Whether `resolved` lives under an agent CLI's home directory
@@ -192,7 +198,6 @@ const DOTNET_GETENV_RE = /\[Environment\]::GetEnvironment/i;
 const CMD_ECHO_ENV_RE = /echo\s+%[A-Za-z_]/i;
 
 // blockEnvFiles
-const ENV_FILE_PATH_RE = /(?:^|[\\/])\.env(?:\.|$)/;
 const ENV_CMD_RE = /\.env(?:\b|\s|$|\.)/;
 
 // blockSudo
@@ -444,9 +449,6 @@ const SHORT_FLAG_BUNDLE_RE = /^-[a-zA-Z]*f[a-zA-Z]*$/;
 const SAFE_FORCE_PREFIXES = ["--force-with-lease", "--force-if-includes"] as const;
 
 // blockSecretsWrite
-const SECRET_FILE_RE = /\.(?:pem|key)$/;
-const SECRET_FILE_ID_RSA_RE = /id_rsa/;
-const SECRET_FILE_CREDENTIALS_RE = /credentials/;
 
 // blockWorkOnMain
 const GIT_COMMIT_MERGE_RE = /git\s+(commit|merge|rebase|cherry-pick)\b/;

package/src/hooks/enforcement-capability.ts

@@ -253,6 +253,103 @@ export const ENFORCEMENT_CAPABILITY: Record<
     // the policy-evaluator comment both claim "Goose has NO Stop event"; that is
     // false at v1.43.0 (agent.rs:1956, :2840 emit_stop_hook_blocking).
   },
+
+  // grok 1.0.3 (1a29d5bc12). Every "block" row below was proven by a live
+  // probe, not read from grok's hooks doc — which is also where two of the
+  // three surprises came from (see types.ts): the doc's own tool name for the
+  // shell tool disagrees with the wire, and nothing documents that project
+  // hooks need a git repo. grok's capability advertisement corroborates the
+  // blocking set: its ACP initialize response carries
+  //   x.ai/hooks: {blockingEvents:["pre_tool_use","stop","subagent_stop"],
+  //                decisions:["deny","block"], stopSignals:[…]}
+  // — exactly the three rows marked "block" here.
+  grok: {
+    PreToolUse: "block",           // VERIFIED live: {decision:"deny",reason} blocked `echo` and beat --yolo (permissionMode bypassPermissions); Claude's hookSpecificOutput shape did NOT block (A/B on the same hook)
+    Stop: "block",                 // VERIFIED live: {decision:"block",reason} forced another turn — the agent ran the required command, then stopped. ONLY on reason==="end_turn"; the session-shutdown fire is parsed and discarded upstream. Cap: 8 continuations/turn
+    SubagentStop: "block",         // advertised in x.ai/hooks blockingEvents; not exercised by a probe
+    UserPromptSubmit: "observe",   // fired live; not in blockingEvents
+    PostToolUse: "observe",        // fired live; post-hoc, and not in blockingEvents
+    PostToolUseFailure: "observe",
+    SessionStart: "observe",       // fired live
+    SessionEnd: "observe",         // fired live
+    // The six below are the widened set. All OBSERVE by construction, not by
+    // caution: blockingEvents lists exactly three events, so grok cannot honour
+    // a deny on any of these no matter what we send.
+    StopFailure: "observe",        // VERIFIED firing (a 429 turn): {error:"rate_limit", errorDetails, lastAssistantMessage}
+    Notification: "observe",       // VERIFIED firing: notificationType "agent_error" — a type grok's own docs do not list
+    PermissionDenied: "observe",   // config key accepted (count=14); firing not exercised — needs a real permission denial
+    SubagentStart: "observe",      // config key accepted; firing not exercised — needs a subagent
+    PreCompact: "observe",         // config key accepted; firing not exercised — needs compaction
+    PostCompact: "observe",        // config key accepted; firing not exercised — needs compaction
+  },
+
+  // qwen-code 0.21.12. A near-pure Claude clone on the wire, so most rows
+  // inherit Claude's semantics — but only the two proven ones are "block".
+  qwen: {
+    PreToolUse: "block",           // VERIFIED live: hookSpecificOutput.permissionDecision:"deny" blocked run_shell_command and beat -y (yolo); reason reached the model verbatim. ("ask" degrades to deny in headless and background subagents)
+    Stop: "block",                 // VERIFIED live: top-level {decision:"block",reason} forced another turn. NOTE stop_hook_active is true on the FIRST fire, so it is not a usable loop guard here
+    UserPromptSubmit: "observe",   // docs accept a decision, unverified — and it fires per MODEL INVOCATION (4× in one observed turn), so treat as observation until probed
+    PostToolUse: "observe",        // docs accept `decision`, unverified; post-hoc regardless
+    PostToolUseFailure: "observe",
+    PermissionRequest: "observe",
+    PermissionDenied: "observe",
+    SubagentStart: "observe",
+    SubagentStop: "observe",       // sibling of Stop upstream, but not probed — left honest rather than assumed
+    PreCompact: "observe",
+    SessionStart: "observe",       // fired live
+    SessionEnd: "observe",
+    // Widened set. Every one has a real executeHooks() dispatch site in the
+    // shipped bundle; the three marked VERIFIED were also observed firing.
+    TaskCreated: "block",          // qwen's TodoCreated. VERIFIED firing ×4 with phase:"validation", where upstream docs state a {decision:"block"} PREVENTS the write and returns the reason to the model
+    TaskCompleted: "block",        // qwen's TodoCompleted. VERIFIED firing ×4, same validation-phase contract
+    InstructionsLoaded: "observe", // VERIFIED firing: {file_path, memory_type, load_reason}
+    Notification: "observe",       // VERIFIED firing: notification_type "auth_success"
+    StopFailure: "observe",        // upstream documents it fire-and-forget — output and exit code ignored
+    PostCompact: "observe",
+    UserPromptExpansion: "observe",
+  },
+
+  // ── ori ───────────────────────────────────────────────────────────────────
+  // ori 0.12.0+68f9a36, probed LIVE against the built-in `@ori-runloop/
+  // agent-loop` harness driving nvidia/nemotron-3.5-lightning:free. Enforcement
+  // is the `approval-asker` / `unattended-approvals` extension points rather
+  // than a hook-event stream, so PreToolUse is the only row there can be: ori
+  // exposes no prompt-submit, post-tool, session or stop gate to subscribe to.
+  ori: {
+    PreToolUse: "block",           // LIVE: {outcome:"deny"} from our approval-asker provision turned 3 tool.started into 3 tool.failed with ZERO tool.succeeded, and ori held the deny across the model's retries. MODE-GATED — read the note below before quoting this row
+    // DELIBERATELY NO OTHER ROWS. Two things this table cannot express, both
+    // verified live and both load-bearing:
+    //   1. ori's approval mode defaults to `self-drive`, and in that mode the
+    //      DYNAMIC points are never called — so no deny is ever PRODUCED, and
+    //      the row above never gets a chance to apply. Isolated three ways: no
+    //      callback under self-drive; still none after claiming approval-policy
+    //      with defaultAction:"ask"; but defaultAction:"reject" DID block every
+    //      call, which proves the static point is wired and that self-drive
+    //      skips specifically the dynamic asker. Coverage therefore requires
+    //      `--approvals manual` (or /approvals in the TUI).
+    //   2. There is no Stop event at all, so the 5 require-*-before-stop
+    //      builtins are INAPPLICABLE on ori, exactly as on Hermes and Goose.
+  },
+
+  // ── cline ─────────────────────────────────────────────────────────────────
+  // cline v3.0.60. Its hooks are event-NAMED scripts under a hooks directory,
+  // and THE EXIT CODE IS IGNORED on every event — so every row here is a claim
+  // about a stdout SHAPE, never about exit 2. cline's verdict schema has no
+  // `decision` / `block` / `permissionDecision` field at all, which is why every
+  // generic branch in policy-evaluator.ts is inert for it.
+  cline: {
+    PreToolUse: "block",  // LIVE: {"cancel":true,"errorMessage":…} on stdout stopped a real run_commands call and the side effect never happened. CAVEAT, and it is a product decision rather than a footnote: `cancel` becomes {stop:true} -> applyStopControl THROWS ControlledStopError, ABORTING THE WHOLE RUN ("[abort] aborted by another client"), not just this tool call. A STRONGER action than a per-tool deny, not a weaker one
+    Stop: "observe",      // TaskComplete maps here, and `cancel` is NOT a force-retry channel: the task has already completed, so a cancel kills a finished run rather than re-entering the loop. The 5 require-*-before-stop builtins are INAPPLICABLE on cline, exactly as on Hermes, Goose and ori
+    // DELIBERATELY NO OTHER ROWS. PostToolUse, UserPromptSubmit, TaskStart,
+    // TaskResume, TaskCancel, TaskError and SessionShutdown ARE installed — for
+    // the audit trail and for observe-mode custom policies — but nothing has
+    // been probed showing a verdict on any of them changes what the agent does,
+    // and ABSENT MEANS UNKNOWN in this file.
+    //
+    // FAIL-OPEN across the whole surface, and unlike ori there is no
+    // failureBehavior:"deny" to inherit: a timeout (120s default), a parse
+    // failure or a spawn error makes cline SKIP the hook and run the tool.
+  },
 };
 
 /**