failproofai 0.0.14 → 0.0.15-beta.0

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;

package/src/hooks/integrations.ts

@@ -12,8 +12,10 @@ import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { parseDocument, type Document } from "yaml";
+import { listHermesProfiles, hermesRoot } from "../../lib/hermes-profiles";
 import {
   HOOK_EVENT_TYPES,
+  CLAUDE_INSTALL_EVENT_TYPES,
   HOOK_SCOPES,
   CODEX_HOOK_EVENT_TYPES,
   CODEX_HOOK_SCOPES,
@@ -118,6 +120,18 @@ export interface Integration {
   /** Resolve the per-scope settings/hooks file path. */
   getSettingsPath(scope: HookScope, cwd?: string): string;
 
+  /**
+   * Every settings file this integration must write for a scope.
+   *
+   * Optional — defaults to `[getSettingsPath(scope, cwd)]`, which is right for
+   * every CLI whose scope maps to exactly one file. Hermes overrides it because
+   * each of its PROFILES is a separate home dir with its own `config.yaml`:
+   * writing only `~/.hermes/config.yaml` would leave every other profile running
+   * unhooked, silently. Use `settingsPathsFor(integration, …)` at call sites
+   * rather than calling this directly.
+   */
+  getSettingsPaths?(scope: HookScope, cwd?: string): string[];
+
   /** Read the raw settings/hooks file (returns {} when missing). */
   readSettings(settingsPath: string): Record<string, unknown>;
 
@@ -143,13 +157,28 @@ export interface Integration {
   detectInstalled(): boolean;
 }
 
+/**
+ * Every settings file to write/remove for `(integration, scope)`.
+ *
+ * Single-file integrations (all but Hermes) return exactly one path, so callers
+ * can loop unconditionally.
+ */
+export function settingsPathsFor(
+  integration: Integration,
+  scope: HookScope,
+  cwd?: string,
+): string[] {
+  const paths = integration.getSettingsPaths?.(scope, cwd);
+  return paths && paths.length > 0 ? paths : [integration.getSettingsPath(scope, cwd)];
+}
+
 // ── Claude Code integration ─────────────────────────────────────────────────
 
 export const claudeCode: Integration = {
   id: "claude",
   displayName: "Claude Code",
   scopes: HOOK_SCOPES,
-  eventTypes: HOOK_EVENT_TYPES,
+  eventTypes: CLAUDE_INSTALL_EVENT_TYPES,
 
   getSettingsPath(scope, cwd) {
     const base = cwd ? resolve(cwd) : process.cwd();
@@ -196,7 +225,48 @@ export const claudeCode: Integration = {
     const s = settings as ClaudeSettings;
     if (!s.hooks) s.hooks = {};
 
-    for (const eventType of HOOK_EVENT_TYPES) {
+    // Drop our hook from any event we no longer install. Without this, an
+    // event removed from the list stays in settings.json forever on existing
+    // machines — reinstalling would not repair it — which is exactly the
+    // situation `WorktreeCreate` created: registered, silent on allow, and
+    // therefore breaking `claude --worktree` until hand-edited. Only OUR
+    // marked entries are touched; anyone else's hooks on the same event stay.
+    //
+    // This walks EVERY key the file happens to carry, including ones
+    // failproofai has never written — a newer Claude event, another tool's
+    // entry, a typo. Their values are therefore unvalidated input, and a
+    // non-array one (`"Foo": {}` or `"Foo": "bar"`) makes the iteration below
+    // throw. That aborts the whole install AFTER the policies were recorded as
+    // enabled, so the user is left believing they are covered while no hook was
+    // written at all — the silent non-enforcement this file exists to prevent.
+    // Skip anything not shaped like a matcher list and leave it untouched.
+    const installed = new Set<string>(CLAUDE_INSTALL_EVENT_TYPES);
+    for (const eventType of Object.keys(s.hooks)) {
+      if (installed.has(eventType)) continue;
+      const matchers = s.hooks[eventType];
+      if (!Array.isArray(matchers)) continue;
+      // Drop a matcher group only when WE emptied it. A group we never touched
+      // (no `hooks` array, or one that held nothing of ours) is somebody else's
+      // and is written back exactly as found — pruning is for our own entries,
+      // not a cleanup pass over the user's file.
+      const kept: ClaudeHookMatcher[] = [];
+      for (const matcher of matchers as ClaudeHookMatcher[]) {
+        if (!matcher || !Array.isArray(matcher.hooks)) {
+          if (matcher) kept.push(matcher);
+          continue;
+        }
+        const before = matcher.hooks.length;
+        matcher.hooks = matcher.hooks.filter(
+          (h) => !isMarkedHook(h as Record<string, unknown>),
+        );
+        const weEmptiedIt = matcher.hooks.length === 0 && before > 0;
+        if (!weEmptiedIt) kept.push(matcher);
+      }
+      s.hooks[eventType] = kept;
+      if (kept.length === 0) delete s.hooks[eventType];
+    }
+
+    for (const eventType of CLAUDE_INSTALL_EVENT_TYPES) {
       const hookEntry = this.buildHookEntry(binaryPath, eventType, scope) as unknown as ClaudeHookEntry;
       if (!s.hooks[eventType]) s.hooks[eventType] = [];
       const matchers: ClaudeHookMatcher[] = s.hooks[eventType];
@@ -1315,10 +1385,19 @@ export const hermes: Integration = {
   scopes: HERMES_HOOK_SCOPES,
   eventTypes: HERMES_HOOK_EVENT_TYPES,
 
-  // Hermes config is USER-scope only (`~/.hermes/config.yaml`); there is no
-  // project/local file, so scope/cwd are irrelevant here.
+  // Hermes config is USER-scope only (`<HERMES_HOME>/config.yaml`); there is no
+  // project/local file, so scope/cwd are irrelevant here. This is the DEFAULT
+  // profile's config — see getSettingsPaths for the rest.
   getSettingsPath() {
-    return resolve(homedir(), ".hermes", "config.yaml");
+    return resolve(hermesRoot(), "config.yaml");
+  },
+
+  // Every profile is a separate Hermes home with its own config.yaml, so a
+  // single-file install would leave non-default profiles running unhooked —
+  // silently, since Hermes never reports a missing hook. Install/uninstall
+  // therefore cover them all.
+  getSettingsPaths() {
+    return listHermesProfiles().map((p) => resolve(p.home, "config.yaml"));
   },
 
   readSettings(settingsPath) {
@@ -1403,21 +1482,13 @@ export const hermes: Integration = {
     return removed;
   },
 
+  // "Installed" means EVERY profile is hooked, not just some. A profile created
+  // after install has no hooks, and reporting green there would hide exactly the
+  // silent-unenforcement gap this integration exists to close; reporting "not
+  // installed" instead prompts a re-install, which writes the missing profiles.
   hooksInstalledInSettings(scope, cwd) {
-    const settingsPath = this.getSettingsPath(scope, cwd);
-    if (!existsSync(settingsPath)) return false;
-    try {
-      const doc = readYamlDoc(settingsPath);
-      const js = (doc.toJS() ?? {}) as { hooks?: Record<string, HermesHookEntry[]> };
-      const hooks = js.hooks;
-      if (!hooks || typeof hooks !== "object") return false;
-      for (const entries of Object.values(hooks)) {
-        if (Array.isArray(entries) && entries.some((h) => isMarkedHook(h))) return true;
-      }
-    } catch {
-      // Corrupt config — treat as not installed.
-    }
-    return false;
+    const paths = settingsPathsFor(this, scope, cwd);
+    return paths.length > 0 && paths.every((p) => hermesConfigHasHooks(p));
   },
 
   detectInstalled() {
@@ -1425,6 +1496,39 @@ export const hermes: Integration = {
   },
 };
 
+function hermesConfigHasHooks(settingsPath: string): boolean {
+  if (!existsSync(settingsPath)) return false;
+  try {
+    const doc = readYamlDoc(settingsPath);
+    const js = (doc.toJS() ?? {}) as { hooks?: Record<string, HermesHookEntry[]> };
+    const hooks = js.hooks;
+    if (!hooks || typeof hooks !== "object") return false;
+    for (const entries of Object.values(hooks)) {
+      if (Array.isArray(entries) && entries.some((h) => isMarkedHook(h))) return true;
+    }
+  } catch {
+    // Corrupt config — treat as not installed.
+  }
+  return false;
+}
+
+/**
+ * Profiles that exist but have no failproofai hooks — i.e. Hermes instances
+ * currently running unenforced. Empty when Hermes isn't installed at all.
+ *
+ * `listHermesProfiles()` always seeds a `default` entry so install has a path to
+ * write even on a fresh machine, so this filters to homes that actually exist —
+ * otherwise every machine WITHOUT Hermes would report one unhooked profile and
+ * the wizard would replace its accurate "not on PATH" hint with a phantom
+ * warning.
+ */
+export function unhookedHermesProfiles(): string[] {
+  return listHermesProfiles()
+    .filter((p) => existsSync(p.home))
+    .filter((p) => !hermesConfigHasHooks(resolve(p.home, "config.yaml")))
+    .map((p) => p.name);
+}
+
 // ── OpenClaw integration ────────────────────────────────────────────────────
 //
 // OpenClaw is a self-hosted assistant gateway. Enforcement is via its in-process