failproofai 1.0.1 → 1.0.2-beta.1

package/src/hooks/builtin-policies.ts

@@ -6,7 +6,13 @@ import { statSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { execSync, execFileSync } from "node:child_process";
 import { homedir } from "node:os";
-import type { BuiltinPolicyDefinition, PolicyContext, PolicyResult, PolicyParamsSchema } from "./policy-types";
+import type {
+  BuiltinPolicyDefinition,
+  PolicyContext,
+  PolicyFunction,
+  PolicyResult,
+} from "./policy-types";
+import { POLICY_CATALOG } from "./policy-catalog";
 import { allow, deny, instruct } from "./policy-helpers";
 import { normalizePolicyName, registerPolicy } from "./policy-registry";
 import { hookLogWarn } from "./hook-logger";
@@ -254,7 +260,7 @@ const SEGMENT_SEPARATORS = /[;&|\n\r(){}`]+/;
  * `/usr/bin/env` and `env` behave identically.
  */
 const COMMAND_PREFIX_TOKENS = new Set([
-  "npx", "bunx", "pnpx", "npm", "pnpm", "yarn", "dlx", "exec", "run",
+  "npx", "bunx", "pnpx", "npm", "pnpm", "yarn", "dlx", "exec", "run", "eval",
   "node", "bun", "deno", "env", "command", "builtin", "nohup", "setsid",
   "time", "timeout", "nice", "stdbuf", "xargs", "sudo", "doas",
   "sh", "bash", "zsh", "dash", "ksh", "fish", "ash",
@@ -265,6 +271,15 @@ const COMMAND_PREFIX_TOKENS = new Set([
  * `./node_modules/.bin/failproofai`, `.../failproofai/bin/failproofai.mjs`. */
 const SELF_BINARY_TOKEN_RE = /(?:^|\/)failproofai[^/]*$/;
 
+/**
+ * The same CLI, reached by path rather than by name.
+ *
+ * `node <pkg>/dist/cli.mjs config --pause` put `node` in command position, so
+ * the walk above settled on a path the binary regex did not match — and it
+ * paused enforcement. Verified as a live bypass.
+ */
+const SELF_ENTRY_PATH_RE = /failproofai\/(?:dist\/(?:cli|index)\.mjs|bin\/failproofai\.mjs)$/;
+
 /** `config`, and the two aliases the entrypoint normalizes to it. */
 const CONFIG_SUBCOMMAND_RE = /^(?:config|configure|setup)$/;
 
@@ -290,7 +305,36 @@ const RUNNER_OPERAND_RE = /^\d+[a-z]*$/i;
  * and denies. That is a far narrower miss than matching every mention, and it
  * errs toward refusing rather than toward silently suspending enforcement.
  */
-function namesSelfPause(command: string): boolean {
+type SelfInvocation = "pause" | "cli";
+
+/**
+ * Classify a command by what it does to failproofai itself, or null when it
+ * does nothing to failproofai at all.
+ *
+ * `pause` outranks `cli` wherever both appear, because the pause verdict is the
+ * one whose message has to explain that suspending enforcement is a human call.
+ */
+function classifySelfInvocation(raw: string): SelfInvocation | null {
+  // `${X}` before anything else looks at it: braces are SEGMENT SEPARATORS, so
+  // the reference was being split into `$` and `X` and matched nothing, while
+  // the shell ran it perfectly well.
+  const command = raw.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, "$$$1");
+  let found: SelfInvocation | null = null;
+  // Variables assigned the binary earlier in the SAME command.
+  //
+  // `x=failproofai; $x config --pause` put `$x` in command position, matched
+  // nothing, and paused enforcement — verified as a live bypass. A shell would
+  // have to be re-implemented to resolve this in general; what is cheap and
+  // covers the actual trick is remembering what was assigned right here.
+  const selfVars = new Set<string>();
+  for (const [, name, value] of command.matchAll(/(?:^|[\s;&|])([A-Za-z_][A-Za-z0-9_]*)=("[^"]*"|'[^']*'|[^\s;&|]+)/g)) {
+    const bare = value.replace(/^["']|["']$/g, "");
+    if (SELF_BINARY_TOKEN_RE.test(bare) || SELF_ENTRY_PATH_RE.test(bare)) selfVars.add(name);
+  }
+  const isSelfVarRef = (token: string): boolean => {
+    const m = /^\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?$/.exec(token);
+    return m ? selfVars.has(m[1]) : false;
+  };
   for (const segment of command.split(SEGMENT_SEPARATORS)) {
     const tokens = segment.split(/\s+/).filter(Boolean);
     let i = 0;
@@ -309,16 +353,24 @@ function namesSelfPause(command: string): boolean {
       i++;
     }
     if (i >= tokens.length) continue;
-    if (!SELF_BINARY_TOKEN_RE.test(tokens[i])) continue;
+    if (
+      !SELF_BINARY_TOKEN_RE.test(tokens[i]) &&
+      !SELF_ENTRY_PATH_RE.test(tokens[i]) &&
+      !isSelfVarRef(tokens[i])
+    ) {
+      continue;
+    }
 
-    // The binary IS the command here. Now require `config … --pause` in the
-    // argument order the CLI actually accepts.
+    // The binary IS the command here. `config … --pause` is singled out only for
+    // its message; every other subcommand is denied just the same.
     const args = tokens.slice(i + 1);
     const configAt = args.findIndex((a) => CONFIG_SUBCOMMAND_RE.test(a));
-    if (configAt === -1) continue;
-    if (args.slice(configAt + 1).some((a) => PAUSE_FLAG_RE.test(a))) return true;
+    if (configAt !== -1 && args.slice(configAt + 1).some((a) => PAUSE_FLAG_RE.test(a))) {
+      return "pause";
+    }
+    found = "cli";
   }
-  return false;
+  return found;
 }
 
 /**
@@ -400,7 +452,15 @@ const SECRET_FILE_CREDENTIALS_RE = /credentials/;
 const GIT_COMMIT_MERGE_RE = /git\s+(commit|merge|rebase|cherry-pick)\b/;
 
 // blockFailproofaiCommands
-const FAILPROOFAI_CLI_RE = /(?:^|;|&&|\|\||\|)\s*failproofai(?:\s|$)/;
+/**
+ * A command that removes or moves failproofai's own state.
+ *
+ * Named separately from the binary walk because it never mentions the binary:
+ * the target is a path, and the verb is an ordinary file command.
+ */
+const FAILPROOFAI_STATE_WRITE_RE =
+  /\b(?:rm|unlink|shred|mv|truncate)\b[^;&|]*\.failproofai(?:\/|\b)/;
+
 const FAILPROOFAI_UNINSTALL_RE = /(?:npm\s+(?:uninstall|remove|un|r)\s.*failproofai|bun\s+remove\s.*failproofai|yarn\s+global\s+remove\s+failproofai|pnpm\s+(?:remove|uninstall|un)\s.*failproofai)/;
 
 // warnGitAmend
@@ -968,20 +1028,6 @@ function blockSudo(ctx: PolicyContext): PolicyResult {
  * can run `failproofai audit`. Neither gap should leave pausing reachable, so
  * this stays narrow, matches the runner forms, and survives that one being off.
  */
-function blockSelfPause(ctx: PolicyContext): PolicyResult {
-  if (ctx.toolName !== "Bash") return allow();
-  const cmd = getCommand(ctx);
-  // The raw command AND its shell-unescaped form: a shell strips quotes and
-  // backslashes before running the binary, so `fail\proofai config --pause`
-  // reaches the pause CLI even though the literal name is broken.
-  if (namesSelfPause(cmd) || namesSelfPause(stripShellQuoting(cmd))) {
-    return deny(
-      "Pausing failproofai enforcement is a human action, not an agent one. " +
-        "If a policy is blocking legitimate work, say so and let the operator decide.",
-    );
-  }
-  return allow();
-}
 
 function blockCurlPipeSh(ctx: PolicyContext): PolicyResult {
   if (ctx.toolName !== "Bash") return allow();
@@ -1386,20 +1432,60 @@ function blockWorkOnMain(ctx: PolicyContext): PolicyResult {
   return allow();
 }
 
+/**
+ * The one policy that cannot be turned off — see `alwaysOn` on its definition.
+ *
+ * Merged from the former `block-self-pause` and `block-failproofai-commands`,
+ * which were two halves of one guard that disagreed with each other.
+ *
+ * `block-self-pause` had the hardened matcher: it walks off runner prefixes and
+ * re-checks the shell-unescaped form, so `sudo failproofai …`, `npx failproofai
+ * …` and `fail\proofai …` do not get through. But it only ever looked for
+ * `config --pause`. `block-failproofai-commands` had the whole surface — any CLI
+ * call, plus package-manager uninstall — on a regex a single `sudo` defeated.
+ * Keeping the broad surface and dropping the weak matcher is the only
+ * combination stronger than either half.
+ *
+ * They also contradicted each other: `block-self-pause` deliberately ALLOWED
+ * `config --resume`, `config --status` and `policies --install`, while
+ * `block-failproofai-commands` denied them. Both were `defaultEnabled`, so the
+ * deny is what actually happened on every machine and the allow never ran. The
+ * merge keeps the behaviour users have.
+ */
 function blockFailproofaiCommands(ctx: PolicyContext): PolicyResult {
   if (ctx.toolName !== "Bash") return allow();
   const cmd = getCommand(ctx);
+  // The raw command AND its shell-unescaped form: a shell strips quotes and
+  // backslashes before running the binary, so `fail\proofai config --pause`
+  // reaches the pause CLI even though the literal name is broken.
+  const unescaped = stripShellQuoting(cmd);
+  const kind = classifySelfInvocation(cmd) ?? classifySelfInvocation(unescaped);
 
-  // Block direct failproofai CLI invocations
-  if (FAILPROOFAI_CLI_RE.test(cmd)) {
+  if (kind === "pause") {
+    return deny(
+      "Pausing failproofai enforcement is a human action, not an agent one. " +
+        "If a policy is blocking legitimate work, say so and let the operator decide.",
+    );
+  }
+  if (kind === "cli") {
     return deny("Running failproofai CLI commands is blocked");
   }
-
-  // Block package-manager uninstallation of failproofai
-  if (FAILPROOFAI_UNINSTALL_RE.test(cmd)) {
+  // Package-manager removal puts the manager in command position, not the
+  // binary, so the walk above never reaches it.
+  if (FAILPROOFAI_UNINSTALL_RE.test(cmd) || FAILPROOFAI_UNINSTALL_RE.test(unescaped)) {
     return deny("Uninstalling failproofai is blocked");
   }
-
+  // Deleting the state IS disabling enforcement, without ever naming the binary.
+  // `rm ~/.failproofai/policies/packs/installed.json` switched off every pack
+  // policy on the machine and fail-closed did NOT fire, because a missing store
+  // reads as a fresh machine rather than a broken one — so nothing anywhere
+  // reported it.
+  if (FAILPROOFAI_STATE_WRITE_RE.test(cmd) || FAILPROOFAI_STATE_WRITE_RE.test(unescaped)) {
+    return deny(
+      "Deleting or moving failproofai's own state would switch enforcement off. " +
+        "If a policy is blocking legitimate work, say so and let the operator decide.",
+    );
+  }
   return allow();
 }
 
@@ -2061,561 +2147,113 @@ function requireCiGreenBeforeStop(ctx: PolicyContext): PolicyResult {
 
 // -- Registry --
 
-export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
-  {
-    name: "sanitize-jwt",
-    description: "Stop Claude from reading JWTs in tool responses",
-    displayTitle: "Redacted JWT tokens from tool output",
-    impact: "Stops the agent from echoing auth tokens it saw in command output.",
-    fn: sanitizeJwt,
-    match: { events: ["PostToolUse"] },
-    defaultEnabled: true,
-    category: "Sanitize",
-  },
-  {
-    name: "sanitize-api-keys",
-    description: "Stop Claude from reading API keys (OpenAI, Anthropic, GitHub, AWS, Stripe, Google) in tool responses",
-    displayTitle: "Redacted API keys from tool output",
-    impact: "Catches OpenAI / Anthropic / GitHub / AWS / Stripe / Google keys before the model sees them.",
-    fn: sanitizeApiKeys,
-    match: { events: ["PostToolUse"] },
-    defaultEnabled: true,
-    category: "Sanitize",
-    params: {
-      additionalPatterns: {
-        type: "pattern[]",
-        description: "Additional API key patterns to scrub, each with { regex, label }",
-        default: [],
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "sanitize-connection-strings",
-    description: "Stop Claude from reading database connection strings with embedded credentials in tool responses",
-    displayTitle: "Redacted database connection strings from tool output",
-    impact: "Strips embedded DB credentials before they reach the model context.",
-    fn: sanitizeConnectionStrings,
-    match: { events: ["PostToolUse"] },
-    defaultEnabled: true,
-    category: "Sanitize",
-  },
-  {
-    name: "sanitize-private-key-content",
-    description: "Stop Claude from reading PEM private key content in tool responses",
-    displayTitle: "Redacted PEM private keys from tool output",
-    impact: "Prevents private key bodies from being echoed into chat context.",
-    fn: sanitizePrivateKeyContent,
-    match: { events: ["PostToolUse"] },
-    defaultEnabled: true,
-    category: "Sanitize",
-  },
-  {
-    name: "sanitize-bearer-tokens",
-    displayTitle: "Redacted bearer tokens from tool output",
-    impact: "Strips Authorization: Bearer values before they hit the model.",
-    description: "Stop Claude from reading Authorization Bearer tokens in tool responses",
-    fn: sanitizeBearerTokens,
-    match: { events: ["PostToolUse"] },
-    defaultEnabled: true,
-    category: "Sanitize",
-  },
-  {
-    name: "protect-env-vars",
-    displayTitle: "Tried to dump environment variables to chat",
-    impact: "Env vars often contain secrets; blocking `env` / `printenv` keeps them out of the model context.",
-    description: "Prevent commands that read environment variables",
-    fn: protectEnvVars,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: true,
-    category: "Environment",
-  },
-  {
-    name: "block-env-files",
-    displayTitle: "Tried to read or write a .env file",
-    impact: "`.env` files routinely contain API keys and DB credentials.",
-    description: "Block reading/writing .env files",
-    fn: blockEnvFiles,
-    match: { events: ["PreToolUse"] },
-    defaultEnabled: true,
-    category: "Environment",
-  },
-  {
-    name: "block-read-outside-cwd",
-    displayTitle: "Tried to read files outside your project directory",
-    impact: "Stops the agent from peeking at neighboring repos or your home directory.",
-    description: "Block file reads outside the session working directory",
-    fn: blockReadOutsideCwd,
-    match: { events: ["PreToolUse"], toolNames: ["Read", "Glob", "Grep", "Bash"] },
-    defaultEnabled: false,
-    category: "Environment",
-    params: {
-      allowPaths: {
-        type: "string[]",
-        description: "Absolute paths outside cwd that are allowed to be read",
-        default: [],
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "block-self-pause",
-    displayTitle: "Tried to pause failproofai enforcement",
-    impact: "An agent that can pause enforcement can switch off every other policy.",
-    description: "Block agents from pausing failproofai enforcement",
-    fn: blockSelfPause,
-    match: { events: ["PreToolUse", "PermissionRequest"], toolNames: ["Bash"] },
-    defaultEnabled: true,
-    category: "Dangerous Commands",
-  },
-  {
-    name: "block-sudo",
-    displayTitle: "Tried to run a command with sudo",
-    impact: "Sudo gives the agent root — blocked unless explicitly allow-listed.",
-    description: "Block sudo commands",
-    fn: blockSudo,
-    // PermissionRequest is Codex's escalation-approval event; fire the same
-    // sudo guard there so Codex sandbox bypasses are blocked too.
-    match: { events: ["PreToolUse", "PermissionRequest"], toolNames: ["Bash"] },
-    defaultEnabled: true,
-    category: "Dangerous Commands",
-    params: {
-      allowPatterns: {
-        type: "string[]",
-        description: "Sudo command patterns to allow, matched token-by-token (e.g. 'sudo systemctl status')",
-        default: [],
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "block-curl-pipe-sh",
-    displayTitle: "Tried to pipe a downloaded script straight to a shell",
-    impact: "`curl ... | sh` runs unverified remote code on your machine.",
-    description: "Block piping downloads to shell",
-    fn: blockCurlPipeSh,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: true,
-    category: "Dangerous Commands",
-  },
-  {
-    name: "block-rm-rf",
-    displayTitle: "Tried to recursively delete a system path",
-    impact: "Catches catastrophic `rm -rf /` and Windows equivalents.",
-    description: "Prevent catastrophic deletions",
-    fn: blockRmRf,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Dangerous Commands",
-    params: {
-      allowPaths: {
-        type: "string[]",
-        description: "Paths that are allowed to be recursively deleted",
-        default: [],
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "block-failproofai-commands",
-    displayTitle: "Tried to disable or modify failproofai itself",
-    impact: "Prevents the agent from turning off the policies that protect you.",
-    description: "Block failproofai CLI commands and uninstallation",
-    fn: blockFailproofaiCommands,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: true,
-    category: "Dangerous Commands",
-  },
-  {
-    name: "block-kubectl",
-    displayTitle: "Tried to run a Kubernetes command",
-    impact: "kubectl can change live cluster state — gated unless allow-listed.",
-    description: "Block kubectl commands (Kubernetes cluster mutations)",
-    fn: blockKubectl,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Infra Commands",
-    params: {
-      allowPatterns: {
-        type: "string[]",
-        description: "kubectl command patterns to allow, matched token-by-token (e.g. 'kubectl get *', 'kubectl describe *')",
-        default: [],
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "block-terraform",
-    displayTitle: "Tried to run a Terraform/OpenTofu command",
-    impact: "Terraform mutates real infrastructure — gated unless allow-listed.",
-    description: "Block terraform and tofu (OpenTofu) commands",
-    fn: blockTerraform,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Infra Commands",
-    params: {
-      allowPatterns: {
-        type: "string[]",
-        description: "terraform/tofu command patterns to allow (e.g. 'terraform plan', 'terraform validate')",
-        default: [],
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "block-aws-cli",
-    displayTitle: "Tried to run an AWS CLI command",
-    impact: "AWS CLI can spend money or break prod — gated.",
-    description: "Block aws CLI commands",
-    fn: blockAwsCli,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Infra Commands",
-    params: {
-      allowPatterns: {
-        type: "string[]",
-        description: "aws CLI command patterns to allow (e.g. 'aws s3 ls *', 'aws sts get-caller-identity')",
-        default: [],
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "block-gcloud",
-    displayTitle: "Tried to run a Google Cloud command",
-    impact: "gcloud can spend money or break prod — gated.",
-    description: "Block gcloud (Google Cloud) CLI commands",
-    fn: blockGcloud,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Infra Commands",
-    params: {
-      allowPatterns: {
-        type: "string[]",
-        description: "gcloud command patterns to allow (e.g. 'gcloud auth list', 'gcloud config list')",
-        default: [],
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "block-az-cli",
-    displayTitle: "Tried to run an Azure CLI command",
-    impact: "az can spend money or break prod — gated.",
-    description: "Block az (Azure) CLI commands",
-    fn: blockAzCli,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Infra Commands",
-    params: {
-      allowPatterns: {
-        type: "string[]",
-        description: "az CLI command patterns to allow (e.g. 'az account show', 'az group list')",
-        default: [],
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "block-helm",
-    displayTitle: "Tried to run a Helm command",
-    impact: "Helm releases mutate cluster state — gated.",
-    description: "Block helm commands",
-    fn: blockHelm,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Infra Commands",
-    params: {
-      allowPatterns: {
-        type: "string[]",
-        description: "helm command patterns to allow (e.g. 'helm list', 'helm status *')",
-        default: [],
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "block-gh-pipeline",
-    displayTitle: "Tried to run a privileged GitHub CLI pipeline command",
-    impact: "Catches `gh workflow run`, `gh pr merge`, `gh secret set`, etc.",
-    description: "Block gh CLI pipeline-trigger subcommands (workflow run, run rerun/cancel, pr merge, release create/delete, cache delete, secret set/delete)",
-    fn: blockGhPipeline,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Infra Commands",
-    params: {
-      allowPatterns: {
-        type: "string[]",
-        description: "gh pipeline command patterns to allow (e.g. specific scripted invocations); read-only gh subcommands like 'gh pr view' and 'gh run list' are not matched by this policy",
-        default: [],
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "block-secrets-write",
-    displayTitle: "Tried to write a secret-key file",
-    impact: "Stops the agent from creating `.pem`, `id_rsa`, `credentials.json`, etc.",
-    description: "Block writing secret key files",
-    fn: blockSecretsWrite,
-    match: { events: ["PreToolUse"], toolNames: ["Write"] },
-    defaultEnabled: false,
-    category: "Dangerous Commands",
-    params: {
-      additionalPatterns: {
-        type: "string[]",
-        description: "Additional filename patterns (substrings) to block",
-        default: [],
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "block-push-master",
-    displayTitle: "Tried to push directly to main/master",
-    impact: "Direct pushes to a protected branch bypass review.",
-    description: "Block pushing to main/master",
-    fn: blockPushMaster,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: true,
-    category: "Git",
-    params: {
-      protectedBranches: {
-        type: "string[]",
-        description: "Branch names to protect from direct pushes",
-        default: ["main", "master"],
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "block-force-push",
-    displayTitle: "Tried to force-push",
-    impact: "Force-pushes rewrite history and can clobber teammates' work.",
-    description: "Prevent force-pushing to any branch",
-    fn: blockForcePush,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Git",
-  },
-  {
-    name: "block-work-on-main",
-    displayTitle: "Tried to commit or merge on main/master",
-    impact: "Work should land via PR — direct commits skip review.",
-    description: "Block git commits and merges on main/master branch",
-    fn: blockWorkOnMain,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Git",
-    params: {
-      protectedBranches: {
-        type: "string[]",
-        description: "Branch names where commits/merges are blocked",
-        default: ["main", "master"],
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "warn-git-amend",
-    displayTitle: "Used git commit --amend",
-    impact: "Amending after a push rewrites history that others may have pulled.",
-    description: "Warns before amending git commits, which rewrites history",
-    fn: warnGitAmend,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Git",
-  },
-  {
-    name: "warn-git-stash-drop",
-    displayTitle: "Tried to drop or clear git stash",
-    impact: "Stash deletions are permanent and silent.",
-    description: "Warns before permanently deleting stashed changes",
-    fn: warnGitStashDrop,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Git",
-  },
-  {
-    name: "warn-all-files-staged",
-    displayTitle: "Staged all files with git add -A / .",
-    impact: "Wide stages routinely catch generated files or secrets you didn't intend to commit.",
-    description: "Warns before staging all working tree files with git add -A / . / --all",
-    fn: warnAllFilesStaged,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Git",
-  },
-  {
-    name: "warn-destructive-sql",
-    displayTitle: "Ran destructive SQL (DROP / TRUNCATE / DELETE without WHERE)",
-    impact: "Easy way to wipe a table by accident.",
-    description: "Warn before executing destructive SQL (DROP/TRUNCATE/DELETE without WHERE) via database clients",
-    fn: warnDestructiveSql,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Database",
-  },
-  {
-    name: "warn-schema-alteration",
-    displayTitle: "Altered a database schema column",
-    impact: "ALTER TABLE operations can lock tables and break readers.",
-    description: "Warns before SQL schema changes (ALTER TABLE with column or rename operations)",
-    fn: warnSchemaAlteration,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Database",
-  },
-  {
-    name: "warn-package-publish",
-    displayTitle: "Tried to publish a package",
-    impact: "Publishes are irreversible — `npm publish` / `cargo publish` shouldn't happen without intent.",
-    description: "Warn before publishing packages to public registries (npm, PyPI, crates.io, RubyGems, etc.)",
-    fn: warnPackagePublish,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Packages & System",
-  },
-  {
-    name: "warn-global-package-install",
-    displayTitle: "Installed a package globally",
-    impact: "`npm i -g`, `cargo install`, `pip --user` pollute your machine outside the project.",
-    description: "Warns before installing packages globally (npm -g, cargo install, etc.)",
-    fn: warnGlobalPackageInstall,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Packages & System",
-  },
-  {
-    name: "prefer-package-manager",
-    displayTitle: "Used a non-preferred package manager",
-    impact: "Mixing package managers creates lockfile churn for your team.",
-    description: "Blocks non-preferred package managers and tells Claude to use an allowed one (e.g., uv instead of pip)",
-    fn: preferPackageManager,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Packages & System",
-    params: {
-      allowed: {
-        type: "string[]",
-        description: "Allowed package manager names (e.g. ['uv', 'bun']). Any detected manager not in this list is blocked.",
-        default: [],
-      },
-      blocked: {
-        type: "string[]",
-        description: "Additional manager names to block beyond the built-in list (e.g. ['pdm', 'pipx']).",
-        default: [],
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "warn-large-file-write",
-    displayTitle: "Wrote a file larger than the configured threshold",
-    impact: "Catches accidentally large file writes (logs, binaries, model dumps).",
-    description: "Warn before writing files larger than 1MB (configurable via thresholdKb param)",
-    fn: warnLargeFileWrite,
-    match: { events: ["PreToolUse"], toolNames: ["Write"] },
-    defaultEnabled: false,
-    category: "Packages & System",
-    params: {
-      thresholdKb: {
-        type: "number",
-        description: "File size threshold in KB above which a warning is issued",
-        default: 1024,
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "warn-background-process",
-    displayTitle: "Started a long-lived background process",
-    impact: "Catches `nohup` / `&` / `screen` / `tmux` / `disown` patterns that the agent often forgets to clean up.",
-    description: "Warns before starting detached or background processes",
-    fn: warnBackgroundProcess,
-    match: { events: ["PreToolUse"], toolNames: ["Bash"] },
-    defaultEnabled: false,
-    category: "Packages & System",
-  },
-  {
-    name: "warn-repeated-tool-calls",
-    displayTitle: "Called the same tool 3+ times with identical arguments",
-    impact: "Usually a sign of a stuck loop burning tokens.",
-    description: "Warn when the same tool is called 3+ times with identical parameters",
-    fn: warnRepeatedToolCalls,
-    match: { events: ["PreToolUse"] },
-    defaultEnabled: false,
-    category: "AI Behavior",
-  },
-  {
-    name: "require-commit-before-stop",
-    displayTitle: "Stopped with uncommitted changes",
-    impact: "Work not in a commit is invisible to teammates and easy to lose.",
-    description: "Require all changes to be committed before Claude stops",
-    fn: requireCommitBeforeStop,
-    match: { events: ["Stop"] },
-    defaultEnabled: false,
-    category: "Workflow",
-  },
-  {
-    name: "require-push-before-stop",
-    displayTitle: "Stopped with unpushed commits",
-    impact: "Local-only commits won't trigger CI or be reviewable.",
-    description: "Require all commits to be pushed to remote before Claude stops",
-    fn: requirePushBeforeStop,
-    match: { events: ["Stop"] },
-    defaultEnabled: false,
-    category: "Workflow",
-    params: {
-      remote: {
-        type: "string",
-        description: "Remote name to push to (default: origin)",
-        default: "origin",
-      },
-      baseBranch: {
-        type: "string",
-        description: "Base branch to compare against (default: main)",
-        default: "main",
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "require-pr-before-stop",
-    displayTitle: "Stopped without a PR for the branch",
-    impact: "Branches without PRs don't get reviewed.",
-    description: "Require a pull request to exist for the current branch before Claude stops",
-    fn: requirePrBeforeStop,
-    match: { events: ["Stop"] },
-    defaultEnabled: false,
-    category: "Workflow",
-    params: {
-      baseBranch: {
-        type: "string",
-        description: "Base branch to compare against (default: main)",
-        default: "main",
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "require-no-conflicts-before-stop",
-    displayTitle: "Stopped with a branch that conflicts with main",
-    impact: "Conflicting branches can't merge — surface them early.",
-    description: "Require the current branch to merge cleanly with the base branch before Claude stops",
-    fn: requireNoConflictsBeforeStop,
-    match: { events: ["Stop"] },
-    defaultEnabled: false,
-    category: "Workflow",
-    params: {
-      baseBranch: {
-        type: "string",
-        description: "Base branch to check for conflicts against (default: main)",
-        default: "main",
-      },
-    } satisfies PolicyParamsSchema,
-  },
-  {
-    name: "require-ci-green-before-stop",
-    displayTitle: "Stopped with failing CI",
-    impact: "Failing CI blocks deploy.",
-    description: "Require CI checks to pass on the current HEAD commit before Claude stops (ignores stale runs on prior commits)",
-    fn: requireCiGreenBeforeStop,
-    match: { events: ["Stop"] },
-    defaultEnabled: false,
-    category: "Workflow",
-  },
-];
+/**
+ * Name → implementation. The other half of {@link POLICY_CATALOG}.
+ *
+ * Each value is the identical hoisted function object, never a wrapper. Two
+ * things depend on that and neither fails loudly: `audit/cache.ts` hashes
+ * `fn.toString()` into the audit cache's `engineVersion`, so wrapping every
+ * entry would collapse 39 distinct hashes into one and freeze the key — stale
+ * audit results would then be served for the full 30-day TTL with no symptom;
+ * and `gitBranchCache` is module-scoped, so a per-call factory would silently
+ * reset it on every hook event.
+ */
+const POLICY_IMPLEMENTATIONS: Record<string, PolicyFunction> = {
+  "sanitize-jwt": sanitizeJwt,
+  "sanitize-api-keys": sanitizeApiKeys,
+  "sanitize-connection-strings": sanitizeConnectionStrings,
+  "sanitize-private-key-content": sanitizePrivateKeyContent,
+  "sanitize-bearer-tokens": sanitizeBearerTokens,
+  "protect-env-vars": protectEnvVars,
+  "block-env-files": blockEnvFiles,
+  "block-read-outside-cwd": blockReadOutsideCwd,
+  "block-sudo": blockSudo,
+  "block-curl-pipe-sh": blockCurlPipeSh,
+  "block-rm-rf": blockRmRf,
+  "block-failproofai-commands": blockFailproofaiCommands,
+  "block-kubectl": blockKubectl,
+  "block-terraform": blockTerraform,
+  "block-aws-cli": blockAwsCli,
+  "block-gcloud": blockGcloud,
+  "block-az-cli": blockAzCli,
+  "block-helm": blockHelm,
+  "block-gh-pipeline": blockGhPipeline,
+  "block-secrets-write": blockSecretsWrite,
+  "block-push-master": blockPushMaster,
+  "block-force-push": blockForcePush,
+  "block-work-on-main": blockWorkOnMain,
+  "warn-git-amend": warnGitAmend,
+  "warn-git-stash-drop": warnGitStashDrop,
+  "warn-all-files-staged": warnAllFilesStaged,
+  "warn-destructive-sql": warnDestructiveSql,
+  "warn-schema-alteration": warnSchemaAlteration,
+  "warn-package-publish": warnPackagePublish,
+  "warn-global-package-install": warnGlobalPackageInstall,
+  "prefer-package-manager": preferPackageManager,
+  "warn-large-file-write": warnLargeFileWrite,
+  "warn-background-process": warnBackgroundProcess,
+  "warn-repeated-tool-calls": warnRepeatedToolCalls,
+  "require-commit-before-stop": requireCommitBeforeStop,
+  "require-push-before-stop": requirePushBeforeStop,
+  "require-pr-before-stop": requirePrBeforeStop,
+  "require-no-conflicts-before-stop": requireNoConflictsBeforeStop,
+  "require-ci-green-before-stop": requireCiGreenBeforeStop,
+};
+
+/**
+ * Catalog and implementations must be in BIJECTION, and this throws rather than
+ * warns because the failure is otherwise invisible in the worst direction: a
+ * name present here but not there yields `fn: undefined`, `registerPolicy`
+ * stores it unvalidated, and the `TypeError` at `await policy.fn(ctx)` is
+ * swallowed by `policy-evaluator.ts` (warn, count, `continue`). The hook then
+ * ALLOWS, exits 0, and still lists the policy in `matchedPolicies` — a machine
+ * reporting that a guard ran when it never did.
+ */
+function assertCatalogBijection(): void {
+  const implNames = new Set(Object.keys(POLICY_IMPLEMENTATIONS));
+  const missing = POLICY_CATALOG.filter((e) => !implNames.has(e.name)).map((e) => e.name);
+  if (missing.length > 0) {
+    throw new Error(
+      `failproofai: builtin policies missing an implementation: ${missing.join(", ")}`,
+    );
+  }
+  const catalogNames = new Set(POLICY_CATALOG.map((e) => e.name));
+  const orphaned = [...implNames].filter((n) => !catalogNames.has(n));
+  if (orphaned.length > 0) {
+    throw new Error(
+      `failproofai: policy implementations with no catalog entry: ${orphaned.join(", ")}`,
+    );
+  }
+}
+assertCatalogBijection();
+
+/**
+ * The joined view, and the shape every consumer has always seen.
+ *
+ * Deliberately a positional, spread-only, eager `.map()`: it preserves catalog
+ * order, adds no fields, fills no defaults, drops no rows and calls no factory.
+ * Each of those alternatives changes observable behaviour — see the rules on
+ * {@link POLICY_CATALOG} and the invariants in
+ * `__tests__/hooks/policy-catalog.test.ts`.
+ */
+export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = POLICY_CATALOG.map((entry) => ({
+  ...entry,
+  fn: POLICY_IMPLEMENTATIONS[entry.name] as PolicyFunction,
+}));
 
 export function registerBuiltinPolicies(enabledNames: string[]): void {
   // Tolerate both flat ("sanitize-jwt") and qualified ("failproofai/sanitize-jwt")
   // forms in the user's enabledPolicies config — canonicalize both sides.
   const enabledSet = new Set(enabledNames.map(normalizePolicyName));
   for (const policy of BUILTIN_POLICIES) {
-    if (enabledSet.has(normalizePolicyName(policy.name))) {
-      registerPolicy(policy.name, policy.description, policy.fn, policy.match);
+    // `alwaysOn` deliberately bypasses the enabled set, and the caller's three
+    // ways of producing an empty one with it: a policy the user never enabled,
+    // an active session pause (`handler.ts` passes `[]`), and a config file that
+    // failed to parse (`hooks-config.ts` soft-fails to `{enabledPolicies: []}`).
+    // A guard against the agent disabling failproofai that any of those can
+    // switch off is not a guard.
+    if (policy.alwaysOn || enabledSet.has(normalizePolicyName(policy.name))) {
+      registerPolicy(policy.name, policy.description, policy.fn, policy.match, 0, policy.params);
     }
   }
 }