failproofai 0.0.14-beta.2 → 0.0.15-beta.0

package/src/audit/cli-adapters/openclaw.ts

@@ -7,13 +7,13 @@
  * shared LogEntry[] shape, so `logEntriesToEvents` handles the rest.
  *
  * Gateway sessions run in the container workspace, not a host repo, so they
- * group by agentId (`openclaw:<agentId>`) and contribute nothing to a
- * cwd-scoped audit.
+ * group by (agentId, channel) — `openclaw:<agentId>:<channel>` — and contribute
+ * nothing to a cwd-scoped audit. That is the SAME key the dashboard groups by;
+ * the two used to disagree (adapter by agent, panel by channel), so a report and
+ * the projects panel sliced identical data on different axes.
  */
-import {
-  listOpenClawTranscripts,
-  getOpenClawSessionLog,
-} from "../../../lib/openclaw-sessions";
+import { getOpenClawSessions, openClawProjectPath } from "../../../lib/openclaw-projects";
+import { getOpenClawSessionLog } from "../../../lib/openclaw-sessions";
 import type { NormalizedToolEvent, TranscriptMetadata } from "../types";
 import type { ListOpts } from "./claude";
 import { logEntriesToEvents } from "./shared";
@@ -28,15 +28,19 @@ export async function listOpenClawTranscriptMetadata(
 
   const sinceMs = opts.sinceMs ?? 0;
   const out: TranscriptMetadata[] = [];
-  for (const t of listOpenClawTranscripts()) {
-    if (t.mtimeMs < sinceMs) continue;
+  // getOpenClawSessions layers the per-agent sessions.json index over the same
+  // transcript walk, which is what carries `channel`. It reads one small index
+  // file per AGENT (not per session) and is memoized, so grouping by channel
+  // costs no meaningful extra IO on the audit path.
+  for (const s of await getOpenClawSessions()) {
+    if (s.mtimeMs < sinceMs) continue;
     out.push({
       cli: "openclaw",
-      projectName: `openclaw:${t.agentId}`,
-      sessionId: t.sessionId,
-      transcriptPath: t.transcriptPath,
-      mtimeMs: t.mtimeMs,
-      sizeBytes: t.sizeBytes,
+      projectName: openClawProjectPath(s.agentId, s.channel),
+      sessionId: s.sessionId,
+      transcriptPath: s.transcriptPath,
+      mtimeMs: s.mtimeMs,
+      sizeBytes: s.sizeBytes,
     });
   }
   return out;

package/src/hooks/configure-wizard.ts

@@ -29,6 +29,8 @@ import {
 import {
   detectInstalledClis,
   getIntegration,
+  settingsPathsFor,
+  unhookedHermesProfiles,
 } from "./integrations";
 import { INTEGRATION_TYPES, type IntegrationType, type HookScope } from "./types";
 import { installHooks } from "./manager";
@@ -126,12 +128,28 @@ export function buildAgentChoices(scope: HookScope, cwd: string): MultiChoice<In
     } catch {
       installedHere = false;
     }
+    // Hermes reports installed only when EVERY profile is hooked, so a profile
+    // added after install flips it to false. Say which ones, otherwise a mostly
+    // configured gateway just reads as "not configured".
+    let partialHint: string | undefined;
+    if (id === "hermes" && !installedHere) {
+      try {
+        const unhooked = unhookedHermesProfiles();
+        if (unhooked.length > 0) {
+          partialHint = `${unhooked.length} unhooked profile(s): ${unhooked.join(", ")}`;
+        }
+      } catch {
+        // Profile discovery is best-effort — never block the wizard.
+      }
+    }
     return {
       label: integration.displayName,
       value: id,
       checked: isDetected || installedHere,
       section: isDetected ? "Detected" : "Not installed · set up ahead of time",
-      hint: installedHere ? "already configured" : isDetected ? undefined : "not on PATH",
+      hint: installedHere
+        ? "already configured"
+        : (partialHint ?? (isDetected ? undefined : "not on PATH")),
     };
   });
 }
@@ -322,7 +340,11 @@ export function reviewLines(state: {
   lines.push("  This will update:");
   for (const cli of clis) {
     const integration = getIntegration(cli);
-    lines.push(`    ${homeify(integration.getSettingsPath(scope, cwd))}   ${integration.displayName} hooks`);
+    // Usually one path; Hermes lists one per profile so the operator sees every
+    // home dir that is about to be written.
+    for (const p of settingsPathsFor(integration, scope, cwd)) {
+      lines.push(`    ${homeify(p)}   ${integration.displayName} hooks`);
+    }
   }
   lines.push(`    ${homeify(getConfigPathForScope(scope, cwd))}   ${policies.length} policies`);
   return lines;

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

@@ -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);
@@ -201,12 +221,20 @@ export async function loadAllCustomHooks(
   // purpose, so switching off *discovery* shouldn't silently drop it too.
   const conventionEnabled = opts?.customPoliciesEnabled !== false;
 
+  // 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 customPoliciesPath (existing behavior)
   if (customPoliciesPath) {
     const absPath = isAbsolute(customPoliciesPath)
       ? customPoliciesPath
       : resolve(projectRoot, customPoliciesPath);
     if (existsSync(absPath)) {
+      loadedPaths.add(absPath);
       await loadSingleFile(absPath);
     } else {
       hookLogWarn(`customPoliciesPath not found: ${absPath}`);
@@ -216,10 +244,19 @@ export async function loadAllCustomHooks(
   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);
@@ -233,10 +270,27 @@ 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);

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";
@@ -324,6 +324,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 +342,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;

package/src/hooks/hooks-config.ts

@@ -4,7 +4,7 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { homedir } from "node:os";
-import type { HooksConfig } from "./policy-types";
+import type { HooksConfig, ConventionPolicyRecord } from "./policy-types";
 import type { HookScope } from "./types";
 import { hookLogInfo, hookLogWarn } from "./hook-logger";
 
@@ -171,6 +171,64 @@ export function writeScopedHooksConfig(config: HooksConfig, scope: HookScope, cw
   writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
 }
 
+/**
+ * Mirror the convention policies discovered at `scope` into that scope's
+ * config file, so `policies-config.json` shows what is installed rather than
+ * only what was explicitly enabled.
+ *
+ * Wholesale replace, not merge: the point is to reflect the directory as it is
+ * now, so a deleted file must vanish from the record. Writes only when the
+ * value actually changes, so repeated `failproofai policies` runs do not
+ * rewrite the file (and do not churn its mtime) for no reason.
+ *
+ * Callers must be one-shot commands. This is never safe to call from the hook
+ * path — see the `conventionPolicies` doc comment on `HooksConfig`.
+ *
+ * Returns true when the file was written.
+ */
+export function syncConventionPolicies(
+  entries: ConventionPolicyRecord[],
+  scope: HookScope,
+  cwd?: string,
+): boolean {
+  const configPath = getConfigPathForScope(scope, cwd);
+
+  // Never bring a config file into existence just to record an empty list —
+  // that would litter every directory the CLI is run from.
+  if (!existsSync(configPath) && entries.length === 0) return false;
+
+  // NEVER write over a file we could not parse. `readScopedHooksConfig` fails
+  // soft, returning `{enabledPolicies: []}` on a syntax error — correct for the
+  // hook path, which must not die because a config is malformed, but fatal
+  // here: writing that default back silently DESTROYS the user's real settings.
+  // A hand-edited file with one stray comma would lose every enabled policy the
+  // moment someone ran `failproofai policies`, a read-only command. Bail and
+  // leave the file exactly as it is; the parse warning already surfaced.
+  if (existsSync(configPath)) {
+    try {
+      JSON.parse(readFileSync(configPath, "utf8"));
+    } catch {
+      hookLogWarn(
+        `not recording convention policies: ${configPath} is not valid JSON — ` +
+          `fix the syntax error and re-run. Nothing was written.`,
+      );
+      return false;
+    }
+  }
+
+  const config = readScopedHooksConfig(scope, cwd);
+  const sorted = [...entries].sort((a, b) => a.file.localeCompare(b.file));
+  const next: HooksConfig = { ...config };
+  if (sorted.length === 0) delete next.conventionPolicies;
+  else next.conventionPolicies = sorted;
+
+  if (JSON.stringify(next.conventionPolicies ?? null) === JSON.stringify(config.conventionPolicies ?? null)) {
+    return false;
+  }
+  writeScopedHooksConfig(next, scope, cwd);
+  return true;
+}
+
 export interface ResolvedLlmConfig {
   baseUrl: string;
   apiKey: string;