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

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

package/src/hooks/manager.ts

@@ -14,15 +14,16 @@ import {
   type HookScope,
   type IntegrationType,
 } from "./types";
-import { claudeCode, getIntegration } from "./integrations";
+import { claudeCode, getIntegration, settingsPathsFor } from "./integrations";
 import { promptPolicySelection } from "./install-prompt";
-import { readMergedHooksConfig, readScopedHooksConfig, writeScopedHooksConfig } from "./hooks-config";
-import type { HooksConfig } from "./policy-types";
+import { readMergedHooksConfig, readScopedHooksConfig, writeScopedHooksConfig, syncConventionPolicies, findProjectConfigDir } from "./hooks-config";
+import type { HooksConfig, ConventionPolicyRecord } from "./policy-types";
 import { BUILTIN_POLICIES } from "./builtin-policies";
 import { loadCustomHooks, discoverPolicyFiles } from "./custom-hooks-loader";
 import { trackHookEvent } from "./hook-telemetry";
 import { getInstanceId, hashToId } from "../../lib/telemetry-id";
 import { CliError } from "../cli-error";
+import { hookLogWarn } from "./hook-logger";
 
 const VALID_POLICY_NAMES = new Set(BUILTIN_POLICIES.map((p) => p.name));
 
@@ -261,12 +262,16 @@ async function installHooksImpl(
   const writtenSettingsPaths: { cli: IntegrationType; path: string }[] = [];
   for (const cliId of selectedClis) {
     const integration = getIntegration(cliId);
-    const settingsPath = integration.getSettingsPath(scope, cwd);
+    // Usually one path; Hermes returns one per profile (each is a separate home
+    // dir with its own config.yaml, and a missed one runs unhooked in silence).
+    const settingsPaths = settingsPathsFor(integration, scope, cwd);
     try {
-      const settings = integration.readSettings(settingsPath);
-      integration.writeHookEntries(settings, binaryPath, scope);
-      integration.writeSettings(settingsPath, settings);
-      writtenSettingsPaths.push({ cli: cliId, path: settingsPath });
+      for (const settingsPath of settingsPaths) {
+        const settings = integration.readSettings(settingsPath);
+        integration.writeHookEntries(settings, binaryPath, scope);
+        integration.writeSettings(settingsPath, settings);
+        writtenSettingsPaths.push({ cli: cliId, path: settingsPath });
+      }
     } catch (err) {
       const errorType = err instanceof Error && /EACCES|EPERM/.test(err.message)
         ? "permission_denied"
@@ -452,9 +457,11 @@ export async function removeHooks(policyNames?: string[], scope: HookScope | "al
           : [];
 
     for (const s of scopesToRemove) {
-      const settingsPath = integration.getSettingsPath(s, cwd);
+      // Usually one path; Hermes returns one per profile.
+      const settingsPaths = settingsPathsFor(integration, s, cwd);
+      const existing = settingsPaths.filter((p) => existsSync(p));
 
-      if (!existsSync(settingsPath)) {
+      if (existing.length === 0) {
         if (scope !== "all" && selectedClis.length === 1) {
           console.log("No settings file found. Nothing to remove.");
           nothingToReport = true;
@@ -462,18 +469,22 @@ export async function removeHooks(policyNames?: string[], scope: HookScope | "al
         continue;
       }
 
-      const removed = integration.removeHooksFromFile(settingsPath);
-      if (removed === 0 && scope !== "all" && selectedClis.length === 1) {
+      let removedHere = 0;
+      for (const settingsPath of existing) {
+        const removed = integration.removeHooksFromFile(settingsPath);
+        removedHere += removed;
+        if (removed > 0 && scope !== "all") {
+          console.log(`Removed ${removed} failproofai hook(s) from ${integration.displayName} settings.`);
+          console.log(`Settings: ${settingsPath}`);
+        }
+      }
+
+      if (removedHere === 0 && scope !== "all" && selectedClis.length === 1) {
         console.log("No hooks found in settings. Nothing to remove.");
         nothingToReport = true;
         continue;
       }
-      totalRemoved += removed;
-
-      if (scope !== "all") {
-        console.log(`Removed ${removed} failproofai hook(s) from ${integration.displayName} settings.`);
-        console.log(`Settings: ${settingsPath}`);
-      }
+      totalRemoved += removedHere;
     }
   }
 
@@ -484,7 +495,9 @@ export async function removeHooks(policyNames?: string[], scope: HookScope | "al
     for (const cliId of selectedClis) {
       const integration = getIntegration(cliId);
       for (const s of integration.scopes) {
-        console.log(`  ${integration.displayName} / ${s}: ${integration.getSettingsPath(s, cwd)}`);
+        for (const p of settingsPathsFor(integration, s, cwd)) {
+          console.log(`  ${integration.displayName} / ${s}: ${p}`);
+        }
       }
     }
   }
@@ -696,33 +709,86 @@ export async function listHooks(cwd?: string): Promise<void> {
   }
 
   // Convention Policies section (.failproofai/policies/*policies.{js,mjs,ts})
-  const base = cwd ? resolve(cwd) : process.cwd();
+  // Walk up to the project root like enforcement does
+  // (custom-hooks-loader -> findProjectConfigDir); resolving at the exact cwd
+  // meant running this from a subdirectory listed no project policies while the
+  // hook path was loading them.
+  const base = findProjectConfigDir(cwd ?? process.cwd());
+  const projectDir = resolve(base, ".failproofai", "policies");
+  const userDir = resolve(homedir(), ".failproofai", "policies");
+  const sameDir = userDir === projectDir;
   const conventionDirs: { label: string; dir: string }[] = [
-    { label: "Project", dir: resolve(base, ".failproofai", "policies") },
-    { label: "User", dir: resolve(homedir(), ".failproofai", "policies") },
+    { label: sameDir ? "Project + User" : "Project", dir: projectDir },
+    // Running from $HOME makes both paths identical. Listing the directory
+    // twice printed every file a second time as "failed to load" — the file was
+    // already imported by the first pass, so the module cache short-circuits
+    // `customPolicies.add` and `loadCustomHooks` legitimately returns 0 hooks.
+    // Nothing was wrong with the policy; the second listing was.
+    ...(sameDir ? [] : [{ label: "User", dir: userDir }]),
   ];
 
+  // Record of what was found, mirrored into policies-config.json below so the
+  // config shows installed convention policies and not only enabled builtins.
+  const discovered: Record<"project" | "user", ConventionPolicyRecord[]> = {
+    project: [],
+    user: [],
+  };
+
   for (const { label, dir } of conventionDirs) {
     const files = discoverPolicyFiles(dir);
     if (files.length === 0) continue;
 
+    // A shared project/user directory is listed once but belongs to both, so
+    // its record is written to both scopes' config files.
+    const targets: ("project" | "user")[] =
+      dir === projectDir && dir === userDir ? ["project", "user"] : dir === projectDir ? ["project"] : ["user"];
+    const record = (file: string, hooks: string[]) => {
+      for (const t of targets) discovered[t].push({ file, hooks });
+    };
+
     console.log(`\n  \u2500\u2500 Convention Policies \u2014 ${label} (${dir}) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+    // `nameColWidth` is sized to the longest BUILTIN name, but a convention
+    // filename can be longer \u2014 `padEnd` is then a no-op and the hook count runs
+    // straight into the filename with no space
+    // (`enforce-bengaluru-event-links-policies.mjs1 hook(s)`). Widen to fit the
+    // files actually being printed, keeping a two-space gutter.
+    const colWidth = Math.max(nameColWidth, ...files.map((f) => basename(f).length + 2));
     for (const file of files) {
       try {
         const hooks = await loadCustomHooks(file);
+        const filename = basename(file);
+        record(filename, hooks.map((h) => h.name));
         if (hooks.length === 0) {
-          const filename = basename(file);
-          console.log(`  \x1B[31m\u2717\x1B[0m       ${filename.padEnd(nameColWidth)}\x1B[31mfailed to load\x1B[0m`);
+          console.log(`  \x1B[31m\u2717\x1B[0m       ${filename.padEnd(colWidth)}\x1B[31mfailed to load\x1B[0m`);
         } else {
-          const filename = basename(file);
           const hookSummary = hooks.map((h) => h.name).join(", ");
-          console.log(`  \x1B[32m\u2713\x1B[0m       ${filename.padEnd(nameColWidth)}${hooks.length} hook(s): ${hookSummary}`);
+          console.log(`  \x1B[32m\u2713\x1B[0m       ${filename.padEnd(colWidth)}${hooks.length} hook(s): ${hookSummary}`);
         }
       } catch {
         const filename = basename(file);
-        console.log(`  \x1B[31m\u2717\x1B[0m       ${filename.padEnd(nameColWidth)}\x1B[31merror\x1B[0m`);
+        record(filename, []);
+        console.log(`  \x1B[31m\u2717\x1B[0m       ${filename.padEnd(colWidth)}\x1B[31merror\x1B[0m`);
       }
     }
     console.log();
   }
+
+  // Mirror what was just listed into the USER config. Safe here because
+  // `failproofai policies` is a one-shot command — never do this on the hook
+  // path (see the HooksConfig.conventionPolicies doc comment).
+  //
+  // User scope only, deliberately. A project's `.failproofai/policies-config.json`
+  // is routinely committed (this repo tracks its own), so writing the record
+  // there would make a plain `failproofai policies` dirty the working tree and
+  // put a spurious diff in front of every contributor — a read command must not
+  // do that. `discovered.project` is still collected so the listing above can
+  // report it; it simply is not persisted.
+  try {
+    syncConventionPolicies(discovered.user, "user");
+  } catch (err) {
+    // Listing must never fail because the mirror could not be written.
+    hookLogWarn(
+      `could not record convention policies in config: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
 }

package/src/hooks/policy-evaluator.ts

@@ -179,6 +179,21 @@ export async function evaluatePolicies(
             decision: "deny",
           };
         }
+        // `beforeSubmitPrompt` does NOT read `permission`. Its only block key
+        // is `continue: false` (+ an optional `user_message` shown to the
+        // user); an object carrying unknown keys validates and is dropped, so
+        // the flat deny below was inert and every prompt went through. Verified
+        // against cursor-agent 2026.07.16-899851b, 1931.index.js char 887883.
+        if (eventType === "UserPromptSubmit") {
+          return {
+            exitCode: 0,
+            stdout: JSON.stringify({ continue: false, user_message: blockedMessage }),
+            stderr: "",
+            policyName: policy.name,
+            reason,
+            decision: "deny",
+          };
+        }
         const response = {
           permission: "deny",
           user_message: blockedMessage,
@@ -229,13 +244,15 @@ export async function evaluatePolicies(
       }
 
       // Hermes: the block contract is `{"decision":"block","reason"}` on stdout;
-      // Hermes IGNORES exit codes, so the JSON is the only channel. This one
-      // return covers every Hermes event we install (PreToolUse / PostToolUse /
-      // SubagentStop) — there is no Stop/turn-end event to special-case (Hermes
-      // has no turn boundary; the 5 require-*-before-stop builtins never fire for
-      // it — see CLAUDE.md / the audit plan). A block on PreToolUse stops the
-      // tool before it runs, regardless of the originating platform
-      // (slack/telegram/cli/cron) or subagent.
+      // Hermes IGNORES exit codes, so the JSON is the only channel. A block on
+      // PreToolUse stops the tool before it runs, regardless of the originating
+      // platform (slack/telegram/cli/cron) or subagent.
+      //
+      // Only `pre_tool_call` and `pre_verify` are gated in upstream's
+      // `_parse_response` (agent/shell_hooks.py:567-621); the shape is still
+      // emitted for the other installed events, where it is read by nothing.
+      // We do not install `pre_verify` (see the note in types.ts), so Hermes
+      // has no canonical Stop event and no Stop branch is needed here.
       if (session?.cli === "hermes") {
         return {
           exitCode: 0,
@@ -422,6 +439,41 @@ export async function evaluatePolicies(
         };
       }
 
+      // Copilot reads two shapes we were not sending, so a deny on either of
+      // these events was emitted, logged, counted as enforcement — and ignored.
+      // Both verified against the shipped @github/copilot-linux-x64 bundle.
+      // Note exit 2 is NEVER a deny channel on copilot for any event; it is
+      // logged as `Hook command exited with code 2 (warning)`.
+      if (session?.cli === "copilot") {
+        // `userPromptSubmit` gates the turn, but only on {decision:"block"} at
+        // exit 0 (consumer app.js@2823018). We were emitting exit 2 + stderr,
+        // which copilot warns about and then submits the prompt anyway.
+        if (eventType === "UserPromptSubmit") {
+          return {
+            exitCode: 0,
+            stdout: JSON.stringify({ decision: "block", reason: blockedMessage }),
+            stderr: "",
+            policyName: policy.name,
+            reason,
+            decision: "deny",
+          };
+        }
+        // Copilot consumes a FLAT {behavior, message} here (normalizer
+        // CMn@179042 -> mapper h4t@2686538). The Codex-shaped nested
+        // hookSpecificOutput.decision below normalizes to `{}` on copilot, so
+        // the permission prompt proceeded as if no policy existed.
+        if (eventType === "PermissionRequest") {
+          return {
+            exitCode: 0,
+            stdout: JSON.stringify({ behavior: "deny", message: blockedMessage }),
+            stderr: "",
+            policyName: policy.name,
+            reason,
+            decision: "deny",
+          };
+        }
+      }
+
       if (eventType === "PermissionRequest") {
         // Codex-only: hookSpecificOutput.decision.behavior = "allow" | "deny"
         // (per https://developers.openai.com/codex/hooks#permissionrequest).

package/src/hooks/policy-types.ts

@@ -93,4 +93,30 @@ export interface HooksConfig {
    * Only ever written explicitly as `false`.
    */
   customPoliciesEnabled?: boolean;
+  /**
+   * Record of the convention policies (`.failproofai/policies/*policies.mjs`)
+   * discovered at this scope the last time a failproofai command ran.
+   *
+   * DESCRIPTIVE, NEVER AUTHORITATIVE. Enforcement always discovers from the
+   * filesystem (`loadAllCustomHooks`) and never reads this key — a policy file
+   * dropped in enforces on the very next tool call whether or not this list has
+   * caught up. Making the loader trust it would mean a freshly-copied policy
+   * silently doing nothing until some command refreshed the config, which is
+   * the exact silent-non-enforcement failure this project exists to remove.
+   *
+   * Refreshed wholesale (not merged) by `failproofai policies` and the setup
+   * wizard, so a deleted file disappears from the record on the next run. It is
+   * deliberately NOT written from the hook path: that runs on every tool call,
+   * and a read-modify-write from concurrent short-lived hook processes with no
+   * locking would corrupt the file that governs enforcement.
+   */
+  conventionPolicies?: ConventionPolicyRecord[];
+}
+
+/** One convention policy file and the hooks it registered, as last observed. */
+export interface ConventionPolicyRecord {
+  /** Basename, e.g. `hermes-guardrails.policies.mjs`. */
+  file: string;
+  /** Hook names the file registered, or `[]` if it failed to load. */
+  hooks: string[];
 }

package/src/hooks/types.ts

@@ -105,8 +105,34 @@ export const HERMES_TOOL_INPUT_MAP: Record<string, Record<string, string>> = {
 // (`~/.hermes/config.yaml`; Hermes has no project scope). `pre_tool_call` is the
 // core deny point — it fires for tool calls from every source
 // (slack/telegram/cli/cron) and internal subagents, so a single install
-// intercepts all platforms. Hermes has NO turn-end `Stop` event, so the
-// `require-*-before-stop` builtins never fire for it (see the audit plan).
+// intercepts all platforms.
+//
+// `pre_verify` IS a turn-end gate — the earlier claim here that Hermes has none
+// was wrong. We deliberately do NOT install it (product decision, 2026-07-29);
+// this note records what it would buy so the choice can be revisited without
+// re-deriving it.
+//
+// Upstream fires it once per turn when the agent has edited code and is about to
+// finish (`agent/conversation_loop.py:6754`), and its parser accepts our Claude
+// Stop shape verbatim — `{decision:"block", reason}` means "block the stop",
+// i.e. keep going (`agent/shell_hooks.py:606-615`). The reason is injected as a
+// synthetic user message and the loop re-enters
+// (`conversation_loop.py:6774-6800`). Installing it is one entry in
+// config.yaml — it is a shell hook like the other five, no Python involved.
+//
+// It would make the 5 `require-*-before-stop` builtins fire on Hermes, subject
+// to three upstream conditions:
+//   1. It fires ONLY on turns that landed a file mutation, and that means
+//      exactly `write_file` or `patch` (`agent/tool_result_classification.py:9`)
+//      — a turn that did its work through `terminal` (sed -i, rm, >) does not
+//      qualify, so a chat-only gateway may never see it.
+//   2. Capped at 3 nudges per turn (`DEFAULT_MAX_VERIFY_NUDGES`,
+//      `agent/verify_hooks.py:21`), operator-overridable; resets each turn.
+//   3. It landed upstream ~2026-06-30. Older Hermes fails the key against
+//      VALID_HOOKS and warn-and-skips it SILENTLY (`agent/shell_hooks.py:325`).
+//
+// Until it is installed, `HERMES_EVENT_MAP` emits no `Stop` and those 5
+// builtins remain inapplicable on Hermes.
 export const HERMES_HOOK_SCOPES = ["user"] as const;
 export type HermesHookScope = (typeof HERMES_HOOK_SCOPES)[number];
 
@@ -1002,8 +1028,30 @@ export const HOOK_EVENT_TYPES = [
   "Setup",
 ] as const;
 
+
+
 export type HookEventType = (typeof HOOK_EVENT_TYPES)[number];
 
+/**
+ * Events failproofai actually INSTALLS a hook for on Claude Code.
+ *
+ * Everything in `HOOK_EVENT_TYPES` except `WorktreeCreate`, which is not a
+ * permission gate at all: Claude uses it as a worktree-PATH PROVIDER, taking
+ * the stdout of the first hook that succeeds as the directory to create and
+ * failing with "WorktreeCreate hook failed" when no hook supplies one. Our
+ * allow path writes nothing to stdout — correctly, by the contract every other
+ * event uses — so merely being registered there broke `claude --worktree` and
+ * `/worktree` for every user, whatever any policy decided.
+ *
+ * It stays in `HOOK_EVENT_TYPES` because that list is the canonical set a
+ * policy may subscribe to; this one governs what we write into settings.json.
+ * No builtin matches it (all 39 match only PreToolUse / PostToolUse /
+ * PermissionRequest / Stop), so nothing is lost by not registering.
+ */
+export const CLAUDE_INSTALL_EVENT_TYPES = HOOK_EVENT_TYPES.filter(
+  (e) => e !== "WorktreeCreate",
+) as readonly HookEventType[];
+
 export const FAILPROOFAI_HOOK_MARKER = "__failproofai_hook__" as const;
 
 export interface ClaudeHookEntry {