failproofai 0.0.14 → 0.0.15-beta.1

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 { configuredCustomPolicyPaths, 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));
 
@@ -109,7 +110,7 @@ export async function installHooks(
   cwd?: string,
   includeBeta = false,
   source?: string,
-  customPoliciesPath?: string,
+  customPoliciesPath?: string | string[],
   removeCustomHooks = false,
   cli?: IntegrationType[],
   options: InstallHooksOptions = {},
@@ -140,7 +141,7 @@ async function installHooksImpl(
   cwd?: string,
   includeBeta = false,
   source?: string,
-  customPoliciesPath?: string,
+  customPoliciesPath?: string | string[],
   removeCustomHooks = false,
   cli?: IntegrationType[],
   replace = false,
@@ -211,62 +212,104 @@ async function installHooksImpl(
     selectedPolicies = await promptPolicySelection(preSelected, { includeBeta });
   }
 
-  // Preserve existing config fields (policyParams, customPoliciesPath, llm) when updating
+  // Preserve existing config fields when updating. New writes use the plural
+  // form, while reads continue to accept the legacy singular field.
   const configToWrite = { ...previousConfig, enabledPolicies: selectedPolicies };
   if (removeCustomHooks) {
     delete configToWrite.customPoliciesPath;
-  } else if (customPoliciesPath) {
-    configToWrite.customPoliciesPath = resolve(customPoliciesPath);
-    // Validate the file before committing it to config
-    let validatedHooks: Awaited<ReturnType<typeof loadCustomHooks>> = [];
-    try {
-      validatedHooks = await loadCustomHooks(configToWrite.customPoliciesPath, { strict: true });
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      try {
-        await trackHookEvent(getInstanceId(), "custom_policy_validation_failed", {
-          scope,
-          error_type: /not found/i.test(msg) ? "file_not_found" : "load_error",
-        });
-      } catch {}
-      console.error(`Error: ${msg}`);
-      process.exit(1);
-    }
-    if (validatedHooks.length === 0) {
+    delete configToWrite.customPoliciesPaths;
+  } else if (
+    customPoliciesPath &&
+    (typeof customPoliciesPath === "string" || customPoliciesPath.length > 0)
+  ) {
+    const incoming = (typeof customPoliciesPath === "string" ? [customPoliciesPath] : customPoliciesPath)
+      .map((path) => resolve(path));
+
+    // Additive by default, mirroring `enabledPolicies` directly above: a second
+    // `--custom` ADDS to what is configured rather than silently discarding it.
+    // Replacing was the surprising half of the old single-path field — running
+    // `-c a` then `-c b` left only `b`, with nothing printed to say `a` had
+    // stopped applying. `replace` (passed by the configure wizard) still makes
+    // the given set authoritative, exactly as it does for enabled policies.
+    //
+    // Carried-over paths are filtered by existence first: a file deleted after
+    // it was configured must not make every future install fail, which is what
+    // the strict validation below would do.
+    const carried = (
+      previousConfig.customPoliciesPaths ??
+      (previousConfig.customPoliciesPath ? [previousConfig.customPoliciesPath] : [])
+    )
+      .map((path) => resolve(path))
+      .filter((path) => {
+        if (existsSync(path)) return true;
+        console.log(`Dropping custom policies path (file no longer exists): ${path}`);
+        return false;
+      });
+
+    configToWrite.customPoliciesPaths = replace
+      ? [...new Set(incoming)]
+      : [...new Set([...carried, ...incoming])];
+    delete configToWrite.customPoliciesPath;
+
+    // Validate only what this invocation added. Carried-over paths were
+    // validated when they were added, and re-validating them here would let one
+    // stale file block an unrelated install.
+    for (const path of incoming) {
+      let validatedHooks: Awaited<ReturnType<typeof loadCustomHooks>> = [];
       try {
-        await trackHookEvent(getInstanceId(), "custom_policy_validation_failed", {
-          scope,
-          error_type: "no_hooks_registered",
-        });
-      } catch {}
-      console.error(
-        `Error: no hooks registered in ${customPoliciesPath}. ` +
-          `Make sure your file calls customPolicies.add(...) at least once.`,
+        validatedHooks = await loadCustomHooks(path, { strict: true });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        try {
+          await trackHookEvent(getInstanceId(), "custom_policy_validation_failed", {
+            scope,
+            error_type: /not found/i.test(msg) ? "file_not_found" : "load_error",
+          });
+        } catch {}
+        console.error(`Error: ${msg}`);
+        process.exit(1);
+      }
+      if (validatedHooks.length === 0) {
+        try {
+          await trackHookEvent(getInstanceId(), "custom_policy_validation_failed", {
+            scope,
+            error_type: "no_hooks_registered",
+          });
+        } catch {}
+        console.error(
+          `Error: no hooks registered in ${path}. ` +
+            `Make sure your file calls customPolicies.add(...) at least once.`,
+        );
+        process.exit(1);
+      }
+      console.log(
+        `\nValidated ${validatedHooks.length} custom hook(s) from ${path}: ${validatedHooks.map((h) => h.name).join(", ")}`,
       );
-      process.exit(1);
     }
-    console.log(
-      `\nValidated ${validatedHooks.length} custom hook(s): ${validatedHooks.map((h) => h.name).join(", ")}`,
-    );
   }
   writeScopedHooksConfig(configToWrite, scope, cwd);
   console.log(`\nEnabled ${selectedPolicies.length} policy(ies): ${selectedPolicies.join(", ")}\n`);
   if (removeCustomHooks) {
     console.log("Custom hooks path cleared.");
-  } else if (configToWrite.customPoliciesPath) {
-    console.log(`Custom hooks path: ${configToWrite.customPoliciesPath}`);
+  } else if (configToWrite.customPoliciesPaths?.length || configToWrite.customPoliciesPath) {
+    const paths = configToWrite.customPoliciesPaths ?? [configToWrite.customPoliciesPath!];
+    console.log(`Custom hooks paths: ${paths.join(", ")}`);
   }
 
   // Write hooks for each selected CLI
   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"
@@ -303,7 +346,7 @@ async function installHooksImpl(
       arch: arch(),
       os_release: release(),
       hostname_hash: hashToId(hostname()),
-      has_custom_hooks_path: !!(configToWrite.customPoliciesPath),
+      has_custom_hooks_path: !!(configToWrite.customPoliciesPaths?.length || configToWrite.customPoliciesPath),
       has_policy_params: !!(configToWrite.policyParams && Object.keys(configToWrite.policyParams).length > 0),
       param_policy_names: configToWrite.policyParams ? Object.keys(configToWrite.policyParams) : [],
       command_format: scope === "project" ? "npx" : "absolute",
@@ -382,6 +425,7 @@ export async function removeHooks(policyNames?: string[], scope: HookScope | "al
   if (opts?.removeCustomHooks) {
     const config = readScopedHooksConfig(configScope, cwd);
     delete config.customPoliciesPath;
+    delete config.customPoliciesPaths;
     writeScopedHooksConfig(config, configScope, cwd);
     console.log("Custom hooks path cleared.");
   }
@@ -452,9 +496,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 +508,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 +534,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}`);
+        }
       }
     }
   }
@@ -513,14 +565,14 @@ export async function removeHooks(policyNames?: string[], scope: HookScope | "al
     // Clear config across all three scopes
     for (const s of HOOK_SCOPES) {
       const existing = readScopedHooksConfig(s, cwd);
-      if (existing.enabledPolicies.length > 0 || existing.customPoliciesPath || existing.policyParams) {
-        const { customPoliciesPath: _drop, policyParams: _dropParams, ...rest } = existing;
+      if (existing.enabledPolicies.length > 0 || existing.customPoliciesPaths?.length || existing.customPoliciesPath || existing.policyParams) {
+        const { customPoliciesPath: _drop, customPoliciesPaths: _dropMany, policyParams: _dropParams, ...rest } = existing;
         writeScopedHooksConfig({ ...rest, enabledPolicies: [] }, s, cwd);
       }
     }
   } else if (!HOOK_SCOPES.some((s) => hooksInstalledInSettings(s, cwd))) {
     const existing = readScopedHooksConfig(configScope, cwd);
-    const { customPoliciesPath: _drop, policyParams: _dropParams, ...rest } = existing;
+    const { customPoliciesPath: _drop, customPoliciesPaths: _dropMany, policyParams: _dropParams, ...rest } = existing;
     writeScopedHooksConfig({ ...rest, enabledPolicies: [] }, configScope, cwd);
   }
 }
@@ -540,6 +592,7 @@ export async function removeHooks(policyNames?: string[], scope: HookScope | "al
 export async function listHooks(cwd?: string): Promise<void> {
   const config = readMergedHooksConfig(cwd);
   const enabledSet = new Set(config.enabledPolicies);
+  const disabledCustomSet = new Set(config.disabledCustomPolicies ?? []);
 
   // Determine which scopes have hooks installed (deduplicate when paths overlap, e.g. cwd === home)
   const uniqueScopes = deduplicateScopes(HOOK_SCOPES, cwd);
@@ -676,19 +729,29 @@ export async function listHooks(cwd?: string): Promise<void> {
     }
   }
 
-  // Custom Policies section
-  if (config.customPoliciesPath) {
-    console.log(`\n  \u2500\u2500 Custom Policies (${config.customPoliciesPath}) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
-    if (!existsSync(config.customPoliciesPath)) {
-      console.log(`  \x1B[31m\u2717 File not found: ${config.customPoliciesPath}\x1B[0m`);
-    } else {
-      const hooks = await loadCustomHooks(config.customPoliciesPath);
+  // Explicit Custom Policies section
+  const explicitPaths = configuredCustomPolicyPaths(config);
+  if (explicitPaths.length > 0) {
+    console.log(`\n  \u2500\u2500 Custom Policies \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
+    for (const path of explicitPaths) {
+      // Enforcement resolves configured paths from the project config root.
+      // Use the same canonical path here so the ID checked by the CLI exactly
+      // matches the ID written by the dashboard.
+      const absPath = resolve(findProjectConfigDir(cwd ?? process.cwd()), path);
+      console.log(`  ${absPath}`);
+      if (!existsSync(absPath)) {
+        console.log(`  \x1B[31m\u2717 File not found: ${absPath}\x1B[0m`);
+        continue;
+      }
+      const hooks = await loadCustomHooks(absPath);
       if (hooks.length === 0) {
         console.log(`  \x1B[31m\u2717 ERR  failed to load (check ~/.failproofai/logs/hooks.log)\x1B[0m`);
       } else {
         const descColWidth = nameColWidth;
         for (const hook of hooks) {
-          console.log(`  \x1B[32m\u2713\x1B[0m       ${hook.name.padEnd(descColWidth)}${hook.description ?? ""}`);
+          const disabled = disabledCustomSet.has(`custom:${absPath}:${hook.name}`);
+          const status = disabled ? "\x1B[2m  OFF\x1B[0m" : "\x1B[32m\u2713 ON\x1B[0m";
+          console.log(`  ${status}    ${hook.name.padEnd(descColWidth)}${hook.description ?? ""}`);
         }
       }
     }
@@ -696,33 +759,101 @@ 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"];
+    // When both directories are the same, runtime discovery loads the file as
+    // project convention policy and skips the duplicate user pass.
+    const policyScope: "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}`);
+          const hookStates = hooks.map((hook) => ({
+            hook,
+            disabled: disabledCustomSet.has(`convention:${policyScope}:${filename}:${hook.name}`),
+          }));
+          const disabledCount = hookStates.filter((entry) => entry.disabled).length;
+          const status = disabledCount === 0
+            ? "\x1B[32m\u2713 ON\x1B[0m"
+            : disabledCount === hooks.length
+              ? "\x1B[2m  OFF\x1B[0m"
+              : "\x1B[33m\u25D0 MIXED\x1B[0m";
+          const hookSummary = hookStates
+            .map(({ hook, disabled }) => `${hook.name}${disabled ? " (OFF)" : ""}`)
+            .join(", ");
+          console.log(`  ${status}    ${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

@@ -84,7 +84,12 @@ export interface HooksConfig {
   enabledPolicies: string[];
   llm?: LlmConfig;
   policyParams?: Record<string, Record<string, unknown>>;
+  /** Explicit custom policy files, loaded in array order. */
+  customPoliciesPaths?: string[];
+  /** @deprecated Use customPoliciesPaths. Kept for existing config files. */
   customPoliciesPath?: string;
+  /** Source-qualified custom policy IDs that should not be registered. */
+  disabledCustomPolicies?: string[];
   /**
    * Turn off convention-discovered custom policies (`.failproofai/policies/`)
    * without deleting or renaming the files. Absent means enabled — the default
@@ -93,4 +98,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 {