failproofai 0.0.14 → 0.0.15-beta.1

package/src/hooks/custom-hooks-loader.ts

@@ -3,7 +3,7 @@
  * Supports transitive local imports and `import { ... } from 'failproofai'`.
  *
  * Two loading modes:
- * 1. Explicit: a single file via `customPoliciesPath` in policies-config.json
+ * 1. Explicit: files via `customPoliciesPaths` in policies-config.json
  * 2. Convention: auto-discovered *policies.{js,mjs,ts} files from
  *    .failproofai/policies/ at project and user level (git-hooks style)
  *
@@ -27,6 +27,14 @@ const LOADING_KEY = "__FAILPROOFAI_LOADING_HOOKS__";
 /** Regex matching convention policy filenames: *policies.{js,mjs,ts} */
 const CONVENTION_FILE_RE = /policies\.(js|mjs|ts)$/;
 
+/**
+ * Monotonic counter used to cache-bust each dynamic import. Loading N files
+ * creates N module instances rather than reusing one; every caller here is
+ * either a one-shot CLI command or a short-lived hook process, so the
+ * lifetime cost is bounded by the process, not by uptime.
+ */
+let loadSequence = 0;
+
 /** Script extensions we could load, used to spot near-miss filenames. */
 const LOADABLE_EXT_RE = /\.(js|mjs|ts)$/;
 
@@ -96,7 +104,19 @@ async function loadSingleFile(
     tmpFiles = await rewriteFileTree(absPath, distUrl, distIndex);
 
     const entryTmp = absPath + TMP_SUFFIX;
-    const fileUrl = pathToFileURL(entryTmp).href;
+    // Cache-bust the specifier. NOTE this works under Node but NOT under Bun,
+    // which caches by resolved path and ignores the query — and the shipped
+    // binary runs under Bun. It is kept because it makes repeat loads behave
+    // the same on both runtimes where it can, but nothing may DEPEND on a
+    // repeat load re-executing; callers dedupe paths instead (see above).
+    // The temp path is deterministic, so a second
+    // load of the same file inside one process hit the ESM module cache, the
+    // module body never re-ran, no `customPolicies.add` fired, and the caller
+    // saw zero hooks — indistinguishable from a broken policy file. That is
+    // exactly what `failproofai policies` rendered as "failed to load" for
+    // every file when it walked a shared project/user directory twice.
+    // A distinct query string makes it a distinct module to the loader.
+    const fileUrl = `${pathToFileURL(entryTmp).href}?v=${++loadSequence}`;
     await import(/* webpackIgnore: true */ fileUrl);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -157,6 +177,14 @@ export interface LoadAllResult {
   conventionSources: ConventionSource[];
 }
 
+export function customPolicyId(file: string, name: string): string {
+  return `custom:${file}:${name}`;
+}
+
+export function conventionPolicyId(scope: "project" | "user", file: string, name: string): string {
+  return `convention:${scope}:${file}:${name}`;
+}
+
 /**
  * Load ALL custom hooks: explicit customPoliciesPath + convention-discovered files.
  *
@@ -185,7 +213,7 @@ function warnSkippedPolicyFiles(dir: string, scope: "project" | "user"): void {
 }
 
 export async function loadAllCustomHooks(
-  customPoliciesPath: string | undefined,
+  customPoliciesPaths: string | string[] | undefined,
   opts?: { sessionCwd?: string; customPoliciesEnabled?: boolean },
 ): Promise<LoadAllResult> {
   clearCustomHooks();
@@ -201,28 +229,57 @@ export async function loadAllCustomHooks(
   // purpose, so switching off *discovery* shouldn't silently drop it too.
   const conventionEnabled = opts?.customPoliciesEnabled !== false;
 
-  // 1. Explicit customPoliciesPath (existing behavior)
-  if (customPoliciesPath) {
-    const absPath = isAbsolute(customPoliciesPath)
-      ? customPoliciesPath
-      : resolve(projectRoot, customPoliciesPath);
+  // Every file already imported this call, by resolved absolute path. Loading
+  // one twice is never right: `customPolicies.add` is an unconditional push, so
+  // the second import registers every hook a second time and the policy runs
+  // twice per event. Seeded by the explicit path below and consulted by both
+  // convention passes.
+  const loadedPaths = new Set<string>();
+
+  // 1. Explicit custom policy paths. Accept a string for callers/configs using
+  // the legacy singular form.
+  for (const customPoliciesPath of typeof customPoliciesPaths === "string"
+    ? [customPoliciesPaths]
+    : customPoliciesPaths ?? []) {
+    // resolve() also normalizes absolute paths, so aliases containing `.` or
+    // `..` share a dedup key with convention-discovered canonical paths.
+    const absPath = resolve(projectRoot, customPoliciesPath);
     if (existsSync(absPath)) {
-      await loadSingleFile(absPath);
+      if (!loadedPaths.has(absPath)) {
+        loadedPaths.add(absPath);
+        const hooksBefore = getCustomHooks().length;
+        await loadSingleFile(absPath);
+        for (const hook of getCustomHooks().slice(hooksBefore)) {
+          (hook as CustomHook & { __policyId?: string }).__policyId = customPolicyId(absPath, hook.name);
+        }
+      }
     } else {
-      hookLogWarn(`customPoliciesPath not found: ${absPath}`);
+      hookLogWarn(`custom policy path not found: ${absPath}`);
     }
   }
 
   const hooksBeforeConvention = getCustomHooks().length;
 
   // 2. Project convention: {projectRoot}/.failproofai/policies/*policies.{js,mjs,ts}
+  //
+  // A `customPoliciesPath` pointing INTO this directory at a file whose name
+  // also matches the convention (`*policies.{js,mjs,ts}`) is an ordinary setup —
+  // `failproofai policies -i -c .failproofai/policies/my-policies.mjs` produces
+  // exactly that — and it is discovered here as well. Skip what step 1 loaded,
+  // or the file is imported twice and every hook in it fires twice per event.
   const projectDir = resolve(projectRoot, ".failproofai", "policies");
   if (conventionEnabled) warnSkippedPolicyFiles(projectDir, "project");
-  const projectFiles = conventionEnabled ? discoverPolicyFiles(projectDir) : [];
+  const projectFiles = conventionEnabled
+    ? discoverPolicyFiles(projectDir).filter((f) => !loadedPaths.has(f))
+    : [];
   for (const file of projectFiles) {
+    loadedPaths.add(file);
     const hooksBefore = getCustomHooks().length;
     await loadSingleFile(file, { conventionScope: "project" });
     const newHooks = getCustomHooks().slice(hooksBefore);
+    for (const hook of newHooks) {
+      (hook as CustomHook & { __policyId?: string }).__policyId = conventionPolicyId("project", basename(file), hook.name);
+    }
     if (newHooks.length > 0) {
       conventionSources.push({
         scope: "project",
@@ -233,13 +290,33 @@ export async function loadAllCustomHooks(
   }
 
   // 3. User convention: ~/.failproofai/policies/*policies.{js,mjs,ts}
+  //
+  // Skipped entirely when it resolves to the directory already loaded above —
+  // which happens whenever the project root IS the home directory, a normal
+  // setup for a gateway. Without this, every file is loaded a second time and
+  // `customPolicies.add` (an unconditional push) registers each hook twice, so
+  // every policy fires twice per event. For a counting policy that means the
+  // count doubles and its ceiling trips at half the real number.
+  //
+  // Today that is masked by the runtime rather than prevented: Bun caches
+  // dynamic imports by resolved path and IGNORES the `?v=` cache-buster below,
+  // so the second import is a no-op — but Node honours the query and would
+  // double-register. The binary runs under Bun and the tests under Node, so the
+  // bug is invisible from both sides. Do not rely on that; dedupe the paths.
   const userDir = resolve(homedir(), ".failproofai", "policies");
-  if (conventionEnabled) warnSkippedPolicyFiles(userDir, "user");
-  const userFiles = conventionEnabled ? discoverPolicyFiles(userDir) : [];
+  if (conventionEnabled && userDir !== projectDir) warnSkippedPolicyFiles(userDir, "user");
+  const userFiles =
+    conventionEnabled && userDir !== projectDir
+      ? discoverPolicyFiles(userDir).filter((f) => !loadedPaths.has(f))
+      : [];
   for (const file of userFiles) {
+    loadedPaths.add(file);
     const hooksBefore = getCustomHooks().length;
     await loadSingleFile(file, { conventionScope: "user" });
     const newHooks = getCustomHooks().slice(hooksBefore);
+    for (const hook of newHooks) {
+      (hook as CustomHook & { __policyId?: string }).__policyId = conventionPolicyId("user", basename(file), hook.name);
+    }
     if (newHooks.length > 0) {
       conventionSources.push({
         scope: "user",

package/src/hooks/enforcement-capability.ts

@@ -0,0 +1,266 @@
+/**
+ * Does a policy DENY on this (cli, event) pair actually change the agent's
+ * behaviour, given the wire shape failproofai emits TODAY?
+ *
+ * This exists because the same claim used to live in prose, and prose drifted:
+ * CLAUDE.md documented Hermes `subagent_stop` as a working gate while upstream
+ * discarded its return, so every customer policy on that event enforced
+ * nothing, silently, for months. A table a test can assert against cannot rot
+ * that way.
+ *
+ * ABSENT MEANS UNKNOWN, NOT "block". Only rows traced to a consuming call site,
+ * an official contract, or a recorded live probe appear here. Callers must
+ * treat a missing entry as "say nothing" — a hedge rendered in the UI is still
+ * a claim, and an unverified claim is what this file exists to prevent.
+ */
+// src/hooks/enforcement-capability.ts
+//
+// Does a policy DENY on this (cli, event) pair actually change the agent's
+// behaviour, given the wire shape failproofai emits TODAY?
+//
+//   "block"   — the verdict is read at a call site that prevents the action
+//               or forces the agent to continue/retry.
+//   "observe" — the action proceeds regardless. Either the CLI discards the
+//               verdict, or the tool already ran, or the CLI *could* block but
+//               our shape is inert (each such line says so).
+//   ABSENT    — NOT VERIFIED. The UI must stay silent, never assume "block".
+//
+// Only SOURCE / VENDOR_DOCS / LIVE_PROBE rows appear here. Every line carries
+// its evidence. Versions probed: claude 2.1.220 · codex fe01054a · copilot
+// 1.0.71 (some sites re-read in 1.0.68) · cursor-agent 2026.07.16-899851b ·
+// opencode 7565e035 (v1.18.9, re-checked at v1.14.33) · pi 0.80.10 (source
+// 0.82.1) · hermes-agent 5771a6e · openclaw f8ed8ecf (v2026.7.2) · droid
+// 0.175.1 · devin 3000.2.17 · agy 1.1.8 · goose 1.43.0.
+import type { HookEventType, IntegrationType } from "./types";
+
+export type EnforcementCapability = "block" | "observe";
+
+export const ENFORCEMENT_CAPABILITY: Record<
+  IntegrationType,
+  Partial<Record<HookEventType, EnforcementCapability>>
+> = {
+  // ── claude ────────────────────────────────────────────────────────────────
+  // Closed source, but the shipped launcher embeds its minified JS as plaintext.
+  // Offsets are BYTE offsets into the shipped claude 2.1.220 launcher bundle.
+  // The hook RUNNER is event-agnostic (exit 2 -> blockingError @259223339); all
+  // asymmetry lives in the ~29 call sites that read or ignore it.
+  claude: {
+    PreToolUse: "block",           // @256826565 gan() -> behavior==="deny" short-circuits the permission pipeline; tool.call never reached (@256827907)
+    UserPromptSubmit: "block",     // @262298150 blockingError -> {shouldQuery:false} early return; prompt never sent to the model
+    PermissionRequest: "block",    // @255767400 runHooks reads permissionRequestResult -> buildDeny. NOTE exit 2 is IGNORED here (docs are wrong); we emit hookSpecificOutput.decision.behavior:"deny" which IS the honoured shape — do not "simplify" to exit 2
+    Stop: "block",                 // @254572503 blockingErrors -> stopHookActive + `continue` re-enters the loop. CAP: CLAUDE_CODE_STOP_HOOK_BLOCK_CAP (default 8); discarded on end-turn paths (@254511900)
+    SubagentStop: "block",         // @259180818 VEe emits SubagentStop when agentId set -> same consumer @254572503. Same cap + same end-turn discard
+    PreCompact: "block",           // MEe @259170280 blockedBy -> consumers @254317851 / @254328121 return early; compaction does not run
+    PostToolBatch: "block",        // @254577316 -> yields hook_stopped_continuation and RETURNS from the query generator. Tools in the batch already ran
+    ConfigChange: "block",         // slt @259171700 -> consumer @251465990 skips the reload. CAVEAT: source==="policy_settings" is force-unblocked (MDM immune)
+    UserPromptExpansion: "block",  // producer @254678081, real consumer @254672418 `if("blocked" in C) return C.blocked`. Slash-command / MCP-prompt only
+    TaskCreated: "block",          // TaskCreate.call @256302400: blockingError -> task deleted (yAo) + tool throws
+    TaskCompleted: "block",        // @254518449 -> same honoured consumer @254572503. GATE: teammate mode only (oy() @249372028)
+    TeammateIdle: "block",         // @254518714 -> same consumer @254572503. Same teammate-mode gate
+    Elicitation: "block",          // oOt @259172011 -> $_o @253296308 -> MCP handler U_y @253294456 returns {action:"decline"} to the server
+    ElicitationResult: "block",    // iOt @259172485 -> N_o @253296535 / Zbo @253568095 force {action:"decline"}. Vetoes the response, does NOT stop the agent
+    PostToolUse: "observe",        // OVERTURNED from "block". We emit hookSpecificOutput.additionalContext (policy-evaluator.ts:520-534) -> man's additionalContexts branch @256141810, never blockingError; and the tool already ran either way
+    PostToolUseFailure: "observe", // OVERTURNED. han @256143680 yields only cancelled / blocking_error / additional_context; consumer @256840799 just appends messages after the failed tool result. No stop channel exists
+    SessionStart: "observe",       // @254090768 blockingError -> Pur() = hook_non_blocking_error; session proceeds. Only additionalContext has effect
+    Setup: "observe",              // @254092164 -> same Pur() downgrade
+    SubagentStart: "observe",      // @254689000 -> same Pur() downgrade; the subagent launches anyway
+    SessionEnd: "observe",         // TFt @259174994 reads only !succeeded -> stderr passthrough; `blocked` never read
+    StopFailure: "observe",        // zpt @~259180670 discards the EM() return entirely. Docs concur: "output and exit code are ignored"
+    PermissionDenied: "observe",   // @256829448 reads ONLY hookSpecificOutput.retry; also fires only for classifier==="auto-mode"
+    Notification: "observe",       // h9 @259174090 — return value not assigned
+    InstructionsLoaded: "observe", // nPt @259173437 — return value not assigned
+    CwdChanged: "observe",         // vtn @259173188 -> zop @259172968 reads only watchPaths/systemMessage
+    FileChanged: "observe",        // Atn @259173298 -> same zop consumer
+    PostCompact: "observe",        // xpt @259170833 builds a display message; `blocked` never read (contrast MEe/PreCompact directly above it)
+    WorktreeRemove: "observe",     // Zor @259183361 only records whether some hook succeeded; a deny just logs
+    // WorktreeCreate DELIBERATELY OMITTED: ODt @259182432 is a path PROVIDER, not
+    // a gate — with no stdout it throws "hook succeeded but returned no worktree
+    // path", so an ALLOW aborts creation exactly like a deny. Degenerate, not a
+    // capability. Fix the bug (emit a path on allow) before classifying it.
+  },
+
+  // ── codex ─────────────────────────────────────────────────────────────────
+  // openai/codex @fe01054a. Every verdict funnels through codex-rs/core/src/hook_runtime.rs.
+  codex: {
+    PreToolUse: "block",           // tools/registry.rs:528 PreToolUseHookResult::Blocked -> FunctionCallError::RespondToModel; handler never runs. CAVEAT hook_runtime.rs:202 an empty reason silently degrades to Continue
+    PermissionRequest: "block",    // tools/approvals.rs:220 Deny -> ReviewDecision::denied. CAVEAT only consulted when the call reaches the approval path (orchestrator.rs:168 Skip bypasses it)
+    UserPromptSubmit: "block",     // events/user_prompt_submit.rs:226 Some(2)+stderr -> should_stop; turn.rs:588 skips record_pending_input, turn.rs:237 returns. CAVEAT turn.rs:603 — a co-submitted accepted message lets the turn proceed
+    Stop: "block",                 // events/stop.rs:303 Some(2) -> should_block + continuation_prompt; turn.rs:473-489 records it and `continue`s. CAVEAT turn.rs:490 a block with no prompt is warned + ignored
+    SubagentStop: "block",         // shared parse_completed (stop.rs:202) + same consumer turn.rs:473. CAVEAT hook_runtime.rs:345 — only ThreadSpawn subagents dispatch it; all other SubAgent sources never run the hook
+    PostToolUse: "observe",        // codex CAN block here (registry.rs:678) but we emit hookSpecificOutput.additionalContext with no top-level `decision`, and output_parser.rs:215 needs decision==="block". Inert by our choice; tool already ran regardless
+    SessionStart: "observe",       // events/session_start.rs:243-322 has NO Some(2) arm — our exit-2 deny is logged as HookRunStatus::Failed. CLI blocks only on exit 0 + {"continue":false} (session_start.rs:273 -> turn.rs:233)
+    SubagentStart: "observe",      // permanently unblockable: session_start.rs:273 guard excludes it, output schema has no `decision`, vendor doc says continue:false does not stop it
+    PreCompact: "observe",         // compact.rs:246-260 no Some(2) arm; latent block needs {"continue":false} (-> core/src/compact.rs:190 TurnAborted). Inert as we emit
+    PostCompact: "observe",        // compact.rs:349-363 same structure; latent block needs {"continue":false} (-> compact.rs:216). Inert as we emit
+  },
+
+  // ── copilot ───────────────────────────────────────────────────────────────
+  // Closed source; vendor build ships readable JS. Offsets are BYTE offsets into
+  // the @github/copilot-linux-x64 app.js (c71/ = 1.0.71, copilot/ = 1.0.68).
+  // CRITICAL: exit 2 is NEVER a deny channel on copilot, for any event
+  // (runtime.node@60056587 "Hook command exited with code 2 (warning)").
+  copilot: {
+    PreToolUse: "block",           // 1.0.68 app.js@2878277 permissionDecision==="deny" -> resultType:"denied"; 1.0.71 moved to Rust, runtime.node@60059067 "Denied by preToolUse hook". Corroborated LIVE on 1.0.71 (session events success:false code:denied) + daily integration-suite probe
+    Stop: "block",                 // 1.0.71 app.js@2855430 agentStop: decision==="block" && string reason -> enqueueUserMessage(reason). We emit exactly that shape
+    SubagentStop: "block",         // 1.0.71 app.js@1074101 subagentStop: decision==="block" && reason -> `continue` re-runs the subagent turn. CAVEAT skipped entirely for isSidekick subagents
+    UserPromptSubmit: "block",     // FIXED: we now emit {decision:"block",reason} at exit 0 (gate V$t @2547438, consumer @2823018). Was inert — we sent exit 2 + stderr, which copilot logs as a warning for EVERY event and never treats as a deny
+    PermissionRequest: "block",    // FIXED: we now emit the FLAT {behavior,message} copilot parses (normalizer CMn @179042 -> mapper h4t @2686538). Was inert — the Codex-shaped nested hookSpecificOutput.decision normalized to {}
+    PostToolUse: "observe",        // OVERTURNED. Gate vK @173853 needs top-level decision==="block"; we emit hookSpecificOutput.additionalContext. Post-hoc anyway (result-rewrite only). Vendor docs: "Can block? No"
+    SessionStart: "observe",       // 1.0.71 app.js@2836633 reads ONLY additionalContext
+    SessionEnd: "observe",         // 1.0.71 app.js@2627263 `.then(()=>{})` — return explicitly thrown away
+    PostToolUseFailure: "observe", // 1.0.68 app.js@2883424 and @3038111 destructure only additionalContext
+    PreCompact: "observe",         // 1.0.71 app.js@2758186 and @2852753 — result unassigned at both call sites
+    Notification: "observe",       // 1.0.71 app.js@2746820 reads only additionalContext
+    // ErrorOccurred is installed but has no canonical HookEventType, so it
+    // cannot be keyed here. It is observe: 1.0.71 app.js@2846297, result unassigned.
+  },
+
+  // ── cursor ────────────────────────────────────────────────────────────────
+  // Closed source; local install ships webpack-minified JS. Offsets are CHAR
+  // offsets into the shipped cursor-agent 2026.07.16-899851b bundle.
+  cursor: {
+    PreToolUse: "block",           // 3143.index.js char 26967 permission==="deny" -> {type:"rejected"}; second MCP consumer char 42084
+    Stop: "block",                 // 1931.index.js char 881820 followup_message queued as the next user message. CAPS: loop_limit default 5 (index.js char 4123300); consumed ONLY on the status:"completed" path — user-abort (char 870298) and turn-error (char 883549) discard it
+    UserPromptSubmit: "block",     // FIXED: we now emit {continue:false,user_message} (1931.index.js char 887883 — the only block key). Was inert: {permission:"deny"} validates as an unknown-key object and is dropped on this event
+    PostToolUse: "observe",        // 3143.index.js char 26339 fireSuccessAsync reads only additional_context; validator accepts nothing else (index.js char 4126700)
+    SessionStart: "observe",       // 1931.index.js char 731566 consumes only env + additional_context; `continue` never read even though Cursor's own q() builds it
+    SessionEnd: "observe",         // 1931.index.js char 724540 — result assigned to nothing
+    // SubagentStop OMITTED: producer exists (index.js char 3769676 forwards
+    // followupMessage) and vendor docs describe loop-style follow-ups, but no
+    // code in the shipped install ever CONSTRUCTS a subagentStop request, so
+    // the consumer is outside the bundle. unknown.
+  },
+
+  // ── opencode ──────────────────────────────────────────────────────────────
+  // sst/opencode @7565e035 (v1.18.9); every finding re-checked at tag v1.14.33.
+  opencode: {
+    PreToolUse: "block",           // session/tools.ts:106-110 trigger runs BEFORE item.execute (:111) inside run.promise; a throw is an Effect defect that kills the fiber. Upstream test test/tool/code-mode.test.ts:428 proves the tool body never executed
+    PostToolUse: "observe",        // session/tools.ts:121-125 sits after item.execute; a throw replaces the output with a tool-error the model sees, but the write/command already happened
+    SessionStart: "observe",       // plugin/index.ts:255 `void hook["event"]?.(…)` — fire-and-forget, return structurally unreadable
+    SessionEnd: "observe",         // plugin/index.ts:255 — same void dispatch
+    UserPromptSubmit: "observe",   // plugin/index.ts:255 same void dispatch; and message.updated is published from session.ts:631 AFTER the message is persisted. The real gate is chat.message, which we do not install (§4)
+    PermissionRequest: "observe",  // ☠ DEAD HOOK: permission.ask is DECLARED (packages/plugin/src/index.ts:261) and documented upstream, but NEVER INVOKED — the only two dispatch sites are hook["event"] (:255) and Plugin.trigger (:288), and permission.ask is not among the 13 names passed to .trigger(). The policy does not even run. See §5.3 for the copy hazard
+    // Stop OMITTED: session.idle's plugin return is definitively discarded
+    // (plugin/index.ts:255), so we instead call client.session.prompt(...)
+    // out-of-band (integrations.ts:886-897). That SDK route does start a fresh
+    // turn, but the composite (alive at idle? one-shot `opencode run`?) is
+    // unverified end to end. unknown.
+  },
+
+  // ── pi ────────────────────────────────────────────────────────────────────
+  // @earendil-works/pi-coding-agent 0.80.10 installed (d.ts read directly);
+  // source cross-read at repo cced6a2 (0.82.1). Identical result shapes.
+  pi: {
+    PreToolUse: "block",           // tool_call: ToolCallEventResult{block,reason} (types.d.ts:766) -> runner.emitToolCall returns on result.block -> agent-loop.ts:626 `if(beforeResult?.block) return createErrorToolResult(...)`; tool never executes. user_bash also maps here and is now FIXED too: the shim returns a full-replacement {result:BashResult} (types.d.ts:772) so the command is not run — {block,reason} had no matching field
+    UserPromptSubmit: "block",     // FIXED: the shim now returns {action:"handled"} (InputEventResult, types.d.ts:629) so the prompt is never submitted. Was inert — {block,reason} matched no branch. CAVEAT: `handled` drops the prompt SILENTLY; Pi shows the user nothing, so the shim logs the reason to stderr
+    PostToolUse: "observe",        // tool_result: ToolResultEventResult{content,details,isError,usage} (types.d.ts:778) — no block field; mutation only
+    SessionStart: "observe",       // on(event:"session_start", ExtensionHandler<SessionStartEvent>) — NO Result type param (types.d.ts:842); runner.emit() only consumes returns for session_before_* (runner.ts:787-813)
+    SessionEnd: "observe",         // session_shutdown: same — handler declared with no Result type (types.d.ts:848)
+    Stop: "observe",               // agent_end: handler has NO Result type (types.d.ts:857) — the turn cannot be retried. Our shim stashes the reason and injects it into the NEXT turn via before_agent_start.systemPrompt (index.ts:458). Real, but it is a next-turn instruction, not a gate
+  },
+
+  // ── hermes ────────────────────────────────────────────────────────────────
+  // hermes-agent @5771a6e. agent/shell_hooks.py _parse_response is EVENT-GATED:
+  // it returns a verdict only for pre_tool_call and pre_verify.
+  hermes: {
+    PreToolUse: "block",           // pre_tool_call — the only tool gate; the tool does not run
+    PostToolUse: "observe",        // post_tool_call — not in _parse_response's gate
+    SubagentStop: "observe",       // OVERTURNED from CLAUDE.md's "✅ block". Not in _parse_response's gate, AND the call site (tools/delegate_tool.py) discards the return. Customers with a SubagentStop deny had ZERO enforcement
+    SessionStart: "observe",       // on_session_start — not gated in
+    SessionEnd: "observe",         // on_session_end — call site discards the return
+    // Stop: NOT KEYED — `pre_verify` is a real turn-end gate upstream but we do
+    // not install it, so no canonical Stop event ever fires for hermes.
+  },
+
+  // ── openclaw ──────────────────────────────────────────────────────────────
+  // openclaw/openclaw @f8ed8ecf (v2026.7.2) + our own shipped shim
+  // openclaw-plugin/index.js, which returns undefined for 5 of the 8 hooks.
+  openclaw: {
+    PreToolUse: "block",           // before_tool_call -> shim returns {block:true, blockReason}
+    UserPromptSubmit: "block",     // before_agent_run -> shim returns {outcome:"block", reason}
+    Stop: "block",                 // before_agent_finalize -> shim returns {action:"revise", reason}; the turn re-runs
+    PostToolUse: "observe",        // void upstream AND our shim returns undefined
+    SessionStart: "observe",       // void upstream AND our shim returns undefined
+    SessionEnd: "observe",         // void upstream AND our shim returns undefined
+    SubagentStop: "observe",       // subagent_ended cannot veto upstream; our shim also returns undefined
+    PreCompact: "observe",         // before_compaction — same
+  },
+
+  // ── factory (droid) ───────────────────────────────────────────────────────
+  // droid 0.175.1 (the shipped droid binary, ELF not stripped, embedded JS readable).
+  // Anchors below are unique grep-able strings in that bundle.
+  factory: {
+    PreToolUse: "block",           // grep `throwing ToolExecutionControlError`: exit 2 -> throw $SH(stderr); also hookSpecificOutput.permissionDecision==="deny" -> throw $SH, continue===false -> throw LSH, exit 3 -> AgentAbortError. We emit exit 2 + stderr
+    UserPromptSubmit: "block",     // executeUserPromptSubmitHooks: `if(B.exitCode===2||B.continue===!1){ … return {prompt,hookContext,blocked:!0} }` — the turn never starts
+    Stop: "block",                 // grep `[Agent] Stop hook blocking with decision: block`: {decision:"block",reason} sets the continue flag; grep `[Agent] Stop hook blocking with exit code 2` shows exit 2 is a FALLBACK too (CLAUDE.md says otherwise — harmless, we emit the JSON)
+    PreCompact: "block",           // grep `[Compaction] PreCompact hook blocked compaction`: exit 2 or 3 -> returns the uncompacted conversation
+    PostToolUse: "observe",        // exit 2 -> ADD_MESSAGE(role:"system", visibility:"llm_only") with the postToolUseFeedbackPrefix — feedback, not a block; tool already ran. (continue===false / exit 3 WOULD stop, but we emit neither)
+    SubagentStop: "observe",       // `await MR("SubagentStop",{…})` — the awaited result is not assigned to anything. Hermes-class: our SubagentStop deny is discarded
+    SessionStart: "observe",       // applySessionStartHookResults consumes only the env file + additionalContext; `if(L.exitCode!==0) TH("[Session] SessionStart hook failed")` just logs
+    SessionEnd: "observe",         // executeSessionEndHooks: `for(let r of n) if(r.exitCode!==0) TH("[Session] SessionEnd hook failed")` — logs only
+    Notification: "observe",       // `await MR("Notification",{…})` — return unassigned
+  },
+
+  // ── devin ─────────────────────────────────────────────────────────────────
+  // devin 3000.2.17 is a STRIPPED Rust ELF — no readable call sites. Tier is
+  // LIVE_PROBE: 11 recorded runs against the real binary with an isolated
+  // --config, each verified by side effect (marker file) AND by absence of the
+  // reason in ~/.local/share/devin/cli/{transcripts,sessions.db}.
+  devin: {
+    PreToolUse: "block",           // probe L9: "Error: A tool was rejected by the user", RAN_MARKER absent — and it overrode --permission-mode dangerous
+    UserPromptSubmit: "block",     // probe L10: "Prompt blocked: <reason>"; no PreToolUse/Stop hook fired; no model turn
+    Stop: "block",                 // probe L11 + transcript orchid-pillow.json /steps/8,/steps/10: the reason is injected as a USER message and the agent takes extra turns
+    PermissionRequest: "block",    // probe L17: {"decision":"block"} -> marker absent, run aborted; L16: {"decision":"approve"} flipped a rejection into an execution, proving the channel is live. ⚠⚠ CONDITIONAL — see §5.1: never fires under --permission-mode dangerous (L8) and never for auto-approved read-only tools (L18, where a secret leaked)
+    PostToolUse: "observe",        // probe L12: marker created, session finished normally, reason absent from transcript AND sessions.db
+    SessionStart: "observe",       // probe L13: session ran normally, reason absent from transcript and DB
+    SessionEnd: "observe",         // probe L14: session ended normally, reason absent
+    // Static corroboration (strings @82817071): "Ignoring pre_stop decision type:",
+    // "Ignoring permission decision type:", "Blocked by hook", "Denied by hook",
+    // "Prevented by hook" — agent-ext/src/hooks/event_handler.rs.
+  },
+
+  // ── antigravity (agy) ─────────────────────────────────────────────────────
+  // agy 1.1.8. Two independent kinds of evidence: live probes, plus the
+  // embedded FileDescriptorProto (binary @80315228, exa.hooks_pb) which is
+  // AUTHORITATIVE about which fields a response can even carry.
+  antigravity: {
+    PreToolUse: "block",           // probe [1]: `touch PROBE_RAN` never ran; agent reported the tool "blocked with … PROBE: denied". Proto: PreToolHookResult{decision, reason, allow_tool, deny_reason}
+    Stop: "block",                 // probe [4]: {"decision":"continue",reason} re-entered the loop AND the agent obeyed the reason (STOP_GATE_PROOF created). Proto: StopHookResult{decision, reason}
+    PostToolUse: "observe",        // probe [2]: agy logged `unknown field "decision"` (protojson unmarshal failure) 5x and continued. Proto: PostToolHookResult is an EMPTY MESSAGE — nothing is consumable
+    UserPromptSubmit: "observe",   // PreInvocation. probe [3]: our {"decision":"deny"} caused `failed to call custom pre-invocation hook … unknown field "decision"`; 4 invocations ran unimpeded. Proto: PreInvocationHookResult carries ONLY inject_steps. (instruct works — probe [5] injectSteps honoured)
+  },
+
+  // ── goose ─────────────────────────────────────────────────────────────────
+  // block/goose, read AT TAG v1.43.0 (the installed version) as well as HEAD
+  // 0b234bdc. Two dispatchers: emit() is fire-and-forget (crates/goose/src/
+  // hooks/mod.rs:295 — the return only feeds a warn! log); emit_blocking()
+  // (:364) consumes exit 2 or {"decision":"block","reason"} via deny_reason(:429).
+  goose: {
+    PreToolUse: "block",           // v1.43.0 agent.rs:1080 emit_blocking -> HookDecision::Deny -> returns Err(ErrorData "Tool call denied by policy hook `<plugin>`: …"); the tool is never dispatched
+    UserPromptSubmit: "observe",   // v1.43.0 agent.rs:1609 and :1935 use emit() — verdict discarded
+    PostToolUse: "observe",        // v1.43.0 agent.rs:~593 with_post_tool_hook uses emit() — verdict discarded, and it is post-hoc
+    SessionStart: "observe",       // v1.43.0 agent.rs:1595 emit_hook -> emit() — verdict discarded
+    SessionEnd: "observe",         // goose-cli/src/session/mod.rs:529 and :1294 emit_hook -> emit() — verdict discarded
+    // Goose HAS a blocking Stop event we do not install — see §4. CLAUDE.md and
+    // 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).
+  },
+};
+
+/**
+ * Capability for a (cli, event) pair, or `undefined` when not verified.
+ *
+ * Callers MUST branch on `undefined` and render nothing. Defaulting it to
+ * "block" would assert protection nobody confirmed; defaulting to "observe"
+ * would tell a user a working policy is inert. Silence is the only honest
+ * answer for a pair we have not traced.
+ */
+export function enforcementFor(
+  cli: IntegrationType | undefined,
+  event: HookEventType | string | undefined,
+): EnforcementCapability | undefined {
+  if (!cli || !event) return undefined;
+  const perCli = ENFORCEMENT_CAPABILITY[cli];
+  if (!perCli) return undefined;
+  return perCli[event as HookEventType];
+}

package/src/hooks/handler.ts

@@ -29,7 +29,7 @@ import type { PolicyFunction, PolicyResult } from "./policy-types";
 import { readMergedHooksConfig } from "./hooks-config";
 import { registerBuiltinPolicies } from "./builtin-policies";
 import { evaluatePolicies } from "./policy-evaluator";
-import { clearPolicies, registerPolicy } from "./policy-registry";
+import { clearPolicies, registerPolicy, getPoliciesForEvent } from "./policy-registry";
 import { loadAllCustomHooks } from "./custom-hooks-loader";
 import type { CustomHook } from "./policy-types";
 import { persistHookActivity } from "./hook-activity-store";
@@ -243,14 +243,20 @@ export async function handleHookEvent(
     registerBuiltinPolicies(config.enabledPolicies);
 
     // Load and register custom hooks (layer 2, after builtins)
-    const loadResult = await loadAllCustomHooks(config.customPoliciesPath, {
+    const loadResult = await loadAllCustomHooks(
+      config.customPoliciesPaths ?? config.customPoliciesPath,
+      {
       sessionCwd: session.cwd,
       customPoliciesEnabled: config.customPoliciesEnabled,
-    });
+      },
+    );
     const customHooksList = loadResult.hooks;
+    const disabledCustomPolicies = new Set(config.disabledCustomPolicies ?? []);
     const conventionHookNames = new Set(loadResult.conventionSources.flatMap((s) => s.hookNames));
 
     for (const hook of customHooksList) {
+      const policyId = (hook as CustomHook & { __policyId?: string }).__policyId;
+      if (policyId && disabledCustomPolicies.has(policyId)) continue;
       const hookName = hook.name;
       const conventionScope = (hook as CustomHook & { __conventionScope?: string }).__conventionScope;
       const isConvention = !!conventionScope;
@@ -324,6 +330,16 @@ export async function handleHookEvent(
       process.stderr.write(result.stderr);
     }
 
+    // Which policies actually ran for this event, regardless of how they
+    // decided. `result.policyName` names only the decider — null on a plain
+    // allow — so without this a row cannot tell "your policy ran and allowed"
+    // from "no policy covers this event". The lookup is the same cached call
+    // the evaluator already made, so it costs nothing.
+    const matchedPolicies = getPoliciesForEvent(
+      canonicalEventType,
+      parsed.tool_name as string | undefined,
+    ).map((p) => p.name);
+
     // Persist activity to disk (visible in /policies activity tab)
     const activityEntry = {
       timestamp: Date.now(),
@@ -332,6 +348,7 @@ export async function handleHookEvent(
       toolName: (parsed.tool_name as string) ?? null,
       policyName: result.policyName,
       policyNames: result.policyNames,
+      matchedPolicies,
       decision: result.decision,
       reason: result.reason,
       durationMs,

package/src/hooks/hook-activity-store.ts

@@ -47,6 +47,20 @@ export interface HookActivityEntry {
   toolName: string | null;
   policyName: string | null;
   policyNames?: string[];
+  /**
+   * Every policy that MATCHED this event and ran, whichever way it decided.
+   *
+   * `policyName` only ever names the policy that *decided* — on a plain
+   * `allow()` it is null, so a row could not distinguish "no policy applies
+   * here" from "your policy ran and allowed". That is the whole reason a user
+   * cannot tell whether a policy fired, and why an observation-only event looks
+   * identical to an uncovered one.
+   *
+   * Optional because rows written before this existed have no such field; every
+   * consumer must tolerate `undefined` rather than render an empty list as
+   * "nothing ran".
+   */
+  matchedPolicies?: string[];
   decision: "allow" | "deny" | "instruct";
   reason: string | null;
   durationMs: number;