failproofai 0.0.2-beta.2 → 0.0.2-beta.4

package/.next/standalone/src/hooks/builtin-policies.ts

@@ -3,7 +3,7 @@
  */
 import { resolve, join } from "node:path";
 import { readFile, writeFile, stat, open } from "node:fs/promises";
-import { execSync } from "node:child_process";
+import { execSync, execFileSync } from "node:child_process";
 import { homedir } from "node:os";
 import type { BuiltinPolicyDefinition, PolicyContext, PolicyResult, PolicyParamsSchema } from "./policy-types";
 import { allow, deny, instruct } from "./policy-helpers";
@@ -86,7 +86,7 @@ const PUBLISH_CMD_RE = /(?:npm\s+publish|bun\s+publish|pnpm\s+publish|yarn\s+npm
 
 // protectEnvVars
 const ENV_PRINTENV_RE = /(?:^|\s|;|&&|\|\|)(?:env|printenv)(?:\s|$|;|&&|\|)/;
-const ECHO_ENV_RE = /echo\s+.*\$[A-Za-z_]/;
+const ECHO_ENV_RE = /echo\s+.*\$\{?[A-Za-z_]/;
 const EXPORT_RE = /(?:^|\s|;|&&|\|\|)export\s+\w+/;
 const PS_ENV_VAR_RE = /\$env:[A-Za-z_]/i;
 const PS_CHILDITEM_ENV_RE = /(?:Get-ChildItem|dir|gci|ls)\s+Env:/i;
@@ -103,7 +103,7 @@ const PS_ELEVATION_RE = /Start-Process\s+.*-Verb\s+RunAs/i;
 const RUNAS_RE = /(?:^|;|&&|\|\|)\s*runas\s/i;
 
 // blockCurlPipeSh
-const CURL_PIPE_SH_RE = /(?:curl|wget)\s.*\|\s*(?:sh|bash|zsh)/;
+const CURL_PIPE_SH_RE = /(?:curl|wget)\s.*\|\s*(?:sh|bash|zsh|dash|ksh|csh|tcsh|fish|ash)\b/;
 const PS_WEB_PIPE_RE = /(?:Invoke-WebRequest|iwr|Invoke-RestMethod|irm)\s+.*\|\s*(?:Invoke-Expression|iex)/i;
 
 // blockForcePush
@@ -145,12 +145,29 @@ const TMUX_DETACH_RE = /\btmux\s+(?:new-session|new)\b[^|&;]*-d\b/;
 const DISOWN_RE = /\bdisown\b/;
 const BACKGROUND_AMPERSAND_RE = /(?<![&|])\s?&\s*(?:$|#|;)/;
 
-// blockWorkOnMain: caches the current branch per cwd to avoid repeated execSync calls.
+// Caches the current branch per cwd to avoid repeated execSync calls.
 // Trade-off: if the user switches branches externally mid-session, the cache serves
 // the stale value until the process restarts. This is acceptable since branch switches
 // during an active Claude session are rare.
 const gitBranchCache = new Map<string, string>();
 
+function getCurrentBranch(cwd: string): string | null {
+  try {
+    let branch = gitBranchCache.get(cwd);
+    if (branch === undefined) {
+      branch = execSync("git rev-parse --abbrev-ref HEAD", {
+        cwd,
+        encoding: "utf8",
+        timeout: 3000,
+      }).trim();
+      gitBranchCache.set(cwd, branch);
+    }
+    return branch || null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Check if a command matches an allow pattern using token-by-token comparison.
  * The "*" token is a wildcard. Extra command tokens beyond the pattern are allowed,
@@ -423,7 +440,8 @@ function rmTargetIsAllowed(cmd: string, allowPaths: string[]): boolean {
     if (rmIdx < 0) continue;
     // Only validate recursive rm segments — non-recursive rm has no catastrophic-deletion risk
     const flagTokens = tokens.slice(rmIdx + 1).filter((t) => /^-[^-]/.test(t));
-    if (!/r/i.test(flagTokens.join(""))) continue;
+    const longFlagsInSeg = tokens.slice(rmIdx + 1).filter((t) => /^--/.test(t));
+    if (!/r/i.test(flagTokens.join("")) && !longFlagsInSeg.some(f => /^--recursive$/i.test(f))) continue;
     const pathArgs = tokens.slice(rmIdx + 1).filter((t) => !t.startsWith("-"));
     for (const target of pathArgs) {
       const normalized = target.replace(/\/\*$/, "").replace(/\/+$/, "") || "/";
@@ -448,7 +466,10 @@ function rmTargetIsAllowed(cmd: string, allowPaths: string[]): boolean {
 function blockRmRf(ctx: PolicyContext): PolicyResult {
   if (ctx.toolName !== "Bash") return allow();
   const cmd = getCommand(ctx);
-  const hasDestructivePath = /(?:\/\s*$|\/\*|~)/.test(cmd);
+  const hasDestructivePath = parseArgvTokens(cmd).some((token) => {
+    const normalized = token.replace(/\/\*$/, "").replace(/\/+$/, "") || (token.startsWith("/") ? "/" : "");
+    return normalized === "/" || normalized === "~" || /^\/[A-Za-z_][\w.-]*$/.test(normalized);
+  });
 
   // Combined flags in one token: rm -rf /, rm -fr /
   if (hasDestructivePath && (
@@ -464,7 +485,10 @@ function blockRmRf(ctx: PolicyContext): PolicyResult {
   if (hasDestructivePath && /\brm\b/.test(cmd)) {
     const tokens = parseArgvTokens(cmd);
     const shortFlags = tokens.filter((t) => /^-[^-]/.test(t)).join("");
-    if (/r/i.test(shortFlags) && /f/.test(shortFlags)) {
+    const longFlags = tokens.filter((t) => /^--/.test(t));
+    const hasRecursive = /r/i.test(shortFlags) || longFlags.some(f => /^--recursive$/i.test(f));
+    const hasForce = /f/.test(shortFlags) || longFlags.some(f => /^--force$/i.test(f));
+    if (hasRecursive && hasForce) {
       const allowPaths = ((ctx.params?.allowPaths ?? []) as string[]);
       if (rmTargetIsAllowed(cmd, allowPaths)) return allow();
       return deny("Catastrophic deletion blocked");
@@ -627,24 +651,14 @@ function blockWorkOnMain(ctx: PolicyContext): PolicyResult {
   const cwd = ctx.session?.cwd;
   if (!cwd) return allow();
 
-  try {
-    let branch = gitBranchCache.get(cwd);
-    if (branch === undefined) {
-      branch = execSync("git rev-parse --abbrev-ref HEAD", {
-        cwd,
-        encoding: "utf8",
-        timeout: 3000,
-      }).trim();
-      gitBranchCache.set(cwd, branch);
-    }
-    const protectedBranches = ((ctx.params?.protectedBranches ?? ["main", "master"]) as string[]);
-    if (protectedBranches.includes(branch)) {
-      return deny(
-        `Git ${cmd.match(/git\s+(\S+)/)?.[1] ?? "operation"} on ${branch} is blocked. Create a feature branch first.`,
-      );
-    }
-  } catch {
-    return allow();
+  const branch = getCurrentBranch(cwd);
+  if (!branch) return allow();
+
+  const protectedBranches = ((ctx.params?.protectedBranches ?? ["main", "master"]) as string[]);
+  if (protectedBranches.includes(branch)) {
+    return deny(
+      `Git ${cmd.match(/git\s+(\S+)/)?.[1] ?? "operation"} on ${branch} is blocked. Create a feature branch first.`,
+    );
   }
   return allow();
 }
@@ -786,6 +800,195 @@ function warnBackgroundProcess(ctx: PolicyContext): PolicyResult {
   return allow();
 }
 
+// -- Workflow (Stop event) policies --
+
+function requireCommitBeforeStop(ctx: PolicyContext): PolicyResult {
+  const cwd = ctx.session?.cwd;
+  if (!cwd) return allow("No working directory available, skipping commit check.");
+
+  try {
+    const status = execSync("git status --porcelain", {
+      cwd,
+      encoding: "utf8",
+      timeout: 5000,
+    }).trim();
+
+    if (status.length > 0) {
+      return deny(
+        "You have uncommitted changes in the working directory. Commit all changes before stopping.",
+      );
+    }
+    return allow("All changes are committed.");
+  } catch {
+    return allow("Not a git repository, skipping commit check.");
+  }
+}
+
+function requirePushBeforeStop(ctx: PolicyContext): PolicyResult {
+  const cwd = ctx.session?.cwd;
+  if (!cwd) return allow("No working directory available, skipping push check.");
+
+  try {
+    const remotes = execSync("git remote", {
+      cwd,
+      encoding: "utf8",
+      timeout: 3000,
+    }).trim();
+
+    if (!remotes) return allow("No git remote configured, skipping push check.");
+
+    const remote = (ctx.params?.remote as string) ?? "origin";
+
+    const branch = getCurrentBranch(cwd);
+    if (!branch || branch === "HEAD") return allow("Detached HEAD, skipping push check.");
+
+    // Check if remote tracking branch exists
+    let hasTracking = false;
+    try {
+      execFileSync("git", ["rev-parse", "--verify", `${remote}/${branch}`], {
+        cwd,
+        encoding: "utf8",
+        timeout: 3000,
+      });
+      hasTracking = true;
+    } catch {
+      // Remote tracking branch does not exist
+    }
+
+    if (!hasTracking) {
+      return deny(
+        `Branch "${branch}" has not been pushed to remote "${remote}". ` +
+        `Push your branch with: git push -u ${remote} ${branch}`,
+      );
+    }
+
+    // Check for unpushed commits
+    const unpushed = execFileSync("git", ["log", `${remote}/${branch}..HEAD`, "--oneline"], {
+      cwd,
+      encoding: "utf8",
+      timeout: 5000,
+    }).trim();
+
+    if (unpushed.length > 0) {
+      const commitCount = unpushed.split("\n").length;
+      return deny(
+        `You have ${commitCount} unpushed commit${commitCount > 1 ? "s" : ""} on branch "${branch}". ` +
+        `Push your changes with: git push`,
+      );
+    }
+
+    return allow(`All commits pushed to "${remote}".`);
+  } catch {
+    return allow("Could not check push status, skipping.");
+  }
+}
+
+function requirePrBeforeStop(ctx: PolicyContext): PolicyResult {
+  const cwd = ctx.session?.cwd;
+  if (!cwd) return allow("No working directory available, skipping PR check.");
+
+  try {
+    // Check if gh CLI is available
+    try {
+      execSync("gh --version", { cwd, encoding: "utf8", timeout: 3000 });
+    } catch {
+      return allow("GitHub CLI (gh) not installed, skipping PR check.");
+    }
+
+    const branch = getCurrentBranch(cwd);
+    if (!branch || branch === "HEAD") return allow("Detached HEAD, skipping PR check.");
+
+    // Check if a PR exists for this branch
+    let prJson: string;
+    try {
+      prJson = execSync("gh pr view --json number,url,state", {
+        cwd,
+        encoding: "utf8",
+        timeout: 15000,
+      }).trim();
+    } catch {
+      // gh pr view exits non-zero when no PR exists
+      return deny(
+        `No pull request found for branch "${branch}". ` +
+        `Create one with: gh pr create`,
+      );
+    }
+
+    const pr = JSON.parse(prJson) as { number: number; url: string; state: string };
+
+    if (pr.state === "OPEN") {
+      return allow(`PR #${pr.number} exists: ${pr.url}`);
+    }
+
+    return deny(
+      `Pull request for branch "${branch}" is ${pr.state.toLowerCase()}. Create a new PR with: gh pr create`,
+    );
+  } catch {
+    return allow("Could not check PR status, skipping.");
+  }
+}
+
+function requireCiGreenBeforeStop(ctx: PolicyContext): PolicyResult {
+  const cwd = ctx.session?.cwd;
+  if (!cwd) return allow("No working directory available, skipping CI check.");
+
+  try {
+    // Check if gh CLI is available
+    try {
+      execSync("gh --version", { cwd, encoding: "utf8", timeout: 3000 });
+    } catch {
+      return allow("GitHub CLI (gh) not installed, skipping CI check.");
+    }
+
+    const branch = getCurrentBranch(cwd);
+    if (!branch || branch === "HEAD") return allow("Detached HEAD, skipping CI check.");
+
+    const runsJson = execFileSync(
+      "gh",
+      ["run", "list", "--branch", branch, "--limit", "5", "--json", "status,conclusion,name"],
+      {
+        cwd,
+        encoding: "utf8",
+        timeout: 15000,
+      },
+    ).trim();
+
+    if (!runsJson || runsJson === "[]") return allow(`No CI runs found for branch "${branch}".`);
+
+    const runs = JSON.parse(runsJson) as Array<{
+      status: string;
+      conclusion: string;
+      name: string;
+    }>;
+
+    if (runs.length === 0) return allow(`No CI runs found for branch "${branch}".`);
+
+    const failing = runs.filter(
+      (r) => r.status === "completed" && r.conclusion !== "success" && r.conclusion !== "skipped",
+    );
+    if (failing.length > 0) {
+      const names = failing.map((r) => `"${r.name}"`).join(", ");
+      return deny(
+        `CI checks are failing on branch "${branch}": ${names}. Fix the failing checks before stopping.`,
+      );
+    }
+
+    const pending = runs.filter(
+      (r) => r.status === "in_progress" || r.status === "queued" || r.status === "waiting",
+    );
+    if (pending.length > 0) {
+      const names = pending.map((r) => `"${r.name}"`).join(", ");
+      return deny(
+        `CI checks are still running on branch "${branch}": ${names}. Wait for all checks to complete and verify they pass.`,
+      );
+    }
+
+    return allow(`All CI checks passed on branch "${branch}".`);
+  } catch {
+    return allow("Could not check CI status, skipping.");
+  }
+}
+
 // -- Registry --
 
 export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
@@ -1053,6 +1256,49 @@ export const BUILTIN_POLICIES: BuiltinPolicyDefinition[] = [
     defaultEnabled: false,
     category: "AI Behavior",
   },
+  {
+    name: "require-commit-before-stop",
+    description: "Require all changes to be committed before Claude stops",
+    fn: requireCommitBeforeStop,
+    match: { events: ["Stop"] },
+    defaultEnabled: false,
+    category: "Workflow",
+    beta: true,
+  },
+  {
+    name: "require-push-before-stop",
+    description: "Require all commits to be pushed to remote before Claude stops",
+    fn: requirePushBeforeStop,
+    match: { events: ["Stop"] },
+    defaultEnabled: false,
+    category: "Workflow",
+    beta: true,
+    params: {
+      remote: {
+        type: "string",
+        description: "Remote name to push to (default: origin)",
+        default: "origin",
+      },
+    } satisfies PolicyParamsSchema,
+  },
+  {
+    name: "require-pr-before-stop",
+    description: "Require a pull request to exist for the current branch before Claude stops",
+    fn: requirePrBeforeStop,
+    match: { events: ["Stop"] },
+    defaultEnabled: false,
+    category: "Workflow",
+    beta: true,
+  },
+  {
+    name: "require-ci-green-before-stop",
+    description: "Require CI checks to pass on the current branch before Claude stops",
+    fn: requireCiGreenBeforeStop,
+    match: { events: ["Stop"] },
+    defaultEnabled: false,
+    category: "Workflow",
+    beta: true,
+  },
 ];
 
 export function registerBuiltinPolicies(enabledNames: string[]): void {

package/.next/standalone/src/hooks/handler.ts

@@ -134,6 +134,7 @@ export async function handleHookEvent(eventType: string): Promise<number> {
       eventType,
       toolName: (parsed.tool_name as string) ?? null,
       policyName: result.policyName,
+      policyNames: result.policyNames,
       decision: result.decision,
       reason: result.reason,
       durationMs,

package/.next/standalone/src/hooks/hook-activity-store.ts

@@ -43,6 +43,7 @@ export interface HookActivityEntry {
   eventType: string;
   toolName: string | null;
   policyName: string | null;
+  policyNames?: string[];
   decision: "allow" | "deny" | "instruct";
   reason: string | null;
   durationMs: number;
@@ -186,7 +187,11 @@ function updateStats(entry: HookActivityEntry): void {
   const s = readStoredStats();
   s.totalEvents += 1;
   if (entry.decision === "deny") s.denyCount += 1;
-  if (entry.policyName) {
+  if (entry.policyNames && entry.policyNames.length > 0) {
+    for (const name of entry.policyNames) {
+      s.policyMap[name] = (s.policyMap[name] ?? 0) + 1;
+    }
+  } else if (entry.policyName) {
     s.policyMap[entry.policyName] = (s.policyMap[entry.policyName] ?? 0) + 1;
   }
   // Write atomically: write to a PID-unique temp file then rename — prevents partial reads.

package/.next/standalone/src/hooks/policy-evaluator.ts

@@ -13,6 +13,7 @@ export interface EvaluationResult {
   stdout: string;
   stderr: string;
   policyName: string | null;
+  policyNames?: string[];
   reason: string | null;
   decision: "allow" | "deny" | "instruct";
 }
@@ -51,6 +52,9 @@ export async function evaluatePolicies(
   let instructPolicyName: string | null = null;
   let instructReason: string | null = null;
 
+  // Track informational messages from allow decisions (with policy attribution)
+  const allowEntries: Array<{ policyName: string; reason: string }> = [];
+
   for (const policy of policies) {
     // Inject params: merge policyParams[policy.name] over schema defaults
     const schema = POLICY_PARAMS_MAP.get(policy.name);
@@ -120,7 +124,7 @@ export async function evaluatePolicies(
       return {
         exitCode: 2,
         stdout: "",
-        stderr: "",
+        stderr: reason,
         policyName: policy.name,
         reason,
         decision: "deny",
@@ -133,6 +137,11 @@ export async function evaluatePolicies(
       instructReason = result.reason ?? `Instruction from policy: ${policy.name}`;
       hookLogInfo(`instruct by "${policy.name}": ${instructReason}`);
     }
+
+    // Accumulate informational messages from allow decisions
+    if (result.decision === "allow" && result.reason) {
+      allowEntries.push({ policyName: policy.name, reason: result.reason });
+    }
   }
 
   // No deny — check if we accumulated an instruct
@@ -166,6 +175,18 @@ export async function evaluatePolicies(
     };
   }
 
-  // All policies allowed
+  // All policies allowed — pass along any informational messages
+  if (allowEntries.length > 0) {
+    const combined = allowEntries.map((e) => e.reason).join("\n");
+    const policyNames = allowEntries.map((e) => e.policyName);
+    const supportsHookSpecificOutput = eventType === "PreToolUse" || eventType === "PostToolUse" || eventType === "UserPromptSubmit";
+    const response = supportsHookSpecificOutput
+      ? { hookSpecificOutput: { hookEventName: eventType, additionalContext: `Note from failproofai: ${combined}` } }
+      : { reason: combined };
+    const stderrMsg = allowEntries
+      .map((e) => `[failproofai] ${e.policyName}: ${e.reason}`)
+      .join("\n");
+    return { exitCode: 0, stdout: JSON.stringify(response), stderr: stderrMsg + "\n", policyName: policyNames[0], policyNames, reason: combined, decision: "allow" };
+  }
   return { exitCode: 0, stdout: "", stderr: "", policyName: null, reason: null, decision: "allow" };
 }

package/.next/standalone/src/hooks/policy-helpers.ts

@@ -3,8 +3,8 @@
  */
 import type { PolicyResult } from "./policy-types";
 
-export function allow(): PolicyResult {
-  return { decision: "allow" };
+export function allow(reason?: string): PolicyResult {
+  return reason ? { decision: "allow", reason } : { decision: "allow" };
 }
 
 export function deny(reason: string): PolicyResult {

package/.next/standalone/vitest.config.e2e.mts

@@ -17,5 +17,8 @@ export default defineConfig({
     // forks pool: true process isolation — tests spawn subprocesses,
     // thread workers share globalThis which can interfere.
     pool: "forks",
+    env: {
+      FAILPROOFAI_TELEMETRY_DISABLED: "1",
+    },
   },
 });

package/.next/standalone/vitest.config.mts

@@ -16,5 +16,8 @@ export default defineConfig({
     include: ["__tests__/**/*.test.{ts,tsx}"],
     exclude: ["__tests__/e2e/**"],
     css: false,
+    env: {
+      FAILPROOFAI_TELEMETRY_DISABLED: "1",
+    },
   },
 });

package/README.md

@@ -15,21 +15,21 @@
 [![CI](https://img.shields.io/github/actions/workflow/status/exospherehost/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/exospherehost/failproofai/actions)
 [![Discord](https://img.shields.io/discord/1234567890?style=flat-square&label=Discord&color=5865F2)](https://discord.com/invite/zT92CAgvkj)
 
-Open-source hooks, policies, and project visualization for **Claude Code** & the **Agents SDK**.
+The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously - for **Claude Code** & the **Agents SDK**.
 
-- **Hooks & Policies** — 35+ built-in security policies that run as Claude Code hooks. Block dangerous commands, sanitize secrets, restrict file access, and more.
-- **Custom Policies** — Write your own policies in JavaScript. Same `allow`/`deny`/`instruct` API as built-in policies, with full async support.
-- **Policy Parameters** — Tune built-in policies without writing code: configure allowlists, protected branches, thresholds, and custom patterns.
-- **Session Viewer** — Browse Claude Code projects and sessions locally. Inspect tool calls, messages, and per-session hook activity side-by-side.
+- **30 Built-in Policies** - Catch common agent failure modes out of the box. Block destructive commands, prevent secret leakage, keep agents inside project boundaries, detect loops, and more.
+- **Custom Policies** - Write your own reliability rules in JavaScript. Use the `allow`/`deny`/`instruct` API to enforce conventions, prevent drift, gate operations, or integrate with external systems.
+- **Easy Configuration** - Tune any policy without writing code. Set allowlists, protected branches, thresholds per-project or globally. Three-scope config merges automatically.
+- **Agent Monitor** - See what your agents did while you were away. Browse sessions, inspect every tool call, and review exactly where policies fired.
 
-Everything runs locally — no data leaves your machine.
+Everything runs locally - no data leaves your machine.
 
 ---
 
 ## Requirements
 
 - Node.js >= 20.9.0
-- Bun >= 1.3.0 (optional — only needed for development / building from source)
+- Bun >= 1.3.0 (optional - only needed for development / building from source)
 
 ---
 
@@ -59,7 +59,7 @@ Writes hook entries into `~/.claude/settings.json`. Claude Code will now invoke
 failproofai
 ```
 
-Opens `http://localhost:8020` — browse sessions, inspect logs, manage policies.
+Opens `http://localhost:8020` - browse sessions, inspect logs, manage policies.
 
 ### 3. Check what's active
 
@@ -128,7 +128,7 @@ Policy configuration lives in `~/.failproofai/policies-config.json` (global) or
 }
 ```
 
-**Three config scopes** are merged automatically (project → local → global). See [docs/configuration.md](docs/configuration.md) for full merge rules.
+**Three config scopes** are merged automatically (project → local → global). See [docs/configuration.mdx](docs/configuration.mdx) for full merge rules.
 
 ---
 
@@ -136,40 +136,40 @@ Policy configuration lives in `~/.failproofai/policies-config.json` (global) or
 
 | Policy | Description | Configurable |
 |--------|-------------|:---:|
-| `block-sudo` | Block sudo commands | `allowPatterns` |
-| `block-rm-rf` | Block recursive deletions | `allowPaths` |
-| `block-curl-pipe-sh` | Block curl\|bash and wget\|bash | |
+| `block-sudo` | Prevent agents from running privileged system commands | `allowPatterns` |
+| `block-rm-rf` | Prevent accidental recursive file deletion | `allowPaths` |
+| `block-curl-pipe-sh` | Prevent agents from piping untrusted scripts to shell | |
 | `block-failproofai-commands` | Prevent self-uninstallation | |
-| `sanitize-jwt` | Redact JWT tokens from tool output | |
-| `sanitize-api-keys` | Redact API keys from tool output | `additionalPatterns` |
-| `sanitize-connection-strings` | Redact database credentials from tool output | |
-| `sanitize-private-key-content` | Redact PEM private key blocks | |
-| `sanitize-bearer-tokens` | Redact Authorization Bearer tokens | |
-| `block-env-files` | Block access to .env files | |
-| `protect-env-vars` | Block commands that print environment variables | |
-| `block-read-outside-cwd` | Block reading files outside the project | `allowPaths` |
-| `block-secrets-write` | Block writes to private key and certificate files | `additionalPatterns` |
-| `block-push-master` | Block pushing to main/master | `protectedBranches` |
-| `block-work-on-main` | Block checking out main/master | `protectedBranches` |
-| `block-force-push` | Block `git push --force` | |
-| `warn-git-amend` | Warn on `git commit --amend` | |
-| `warn-git-stash-drop` | Warn on `git stash drop` | |
-| `warn-all-files-staged` | Warn on `git add -A` | |
-| `warn-destructive-sql` | Warn on DROP/DELETE SQL statements | |
-| `warn-schema-alteration` | Warn on ALTER TABLE statements | |
-| `warn-large-file-write` | Warn on large file writes | `thresholdKb` |
-| `warn-package-publish` | Warn on `npm publish` | |
-| `warn-background-process` | Warn on background process launches | |
-| `warn-global-package-install` | Warn on global package installs | |
+| `sanitize-jwt` | Stop JWT tokens from leaking into agent context | |
+| `sanitize-api-keys` | Stop API keys from leaking into agent context | `additionalPatterns` |
+| `sanitize-connection-strings` | Stop database credentials from leaking into agent context | |
+| `sanitize-private-key-content` | Redact PEM private key blocks from output | |
+| `sanitize-bearer-tokens` | Redact Authorization Bearer tokens from output | |
+| `block-env-files` | Keep agents from reading .env files | |
+| `protect-env-vars` | Prevent agents from printing environment variables | |
+| `block-read-outside-cwd` | Keep agents inside project boundaries | `allowPaths` |
+| `block-secrets-write` | Prevent writes to private key and certificate files | `additionalPatterns` |
+| `block-push-master` | Prevent accidental pushes to main/master | `protectedBranches` |
+| `block-work-on-main` | Keep agents off protected branches | `protectedBranches` |
+| `block-force-push` | Prevent `git push --force` | |
+| `warn-git-amend` | Remind agents before amending commits | |
+| `warn-git-stash-drop` | Remind agents before dropping stashes | |
+| `warn-all-files-staged` | Catch accidental `git add -A` | |
+| `warn-destructive-sql` | Catch DROP/DELETE SQL before execution | |
+| `warn-schema-alteration` | Catch ALTER TABLE before execution | |
+| `warn-large-file-write` | Catch unexpectedly large file writes | `thresholdKb` |
+| `warn-package-publish` | Catch accidental `npm publish` | |
+| `warn-background-process` | Catch unintended background process launches | |
+| `warn-global-package-install` | Catch unintended global package installs | |
 | …and more | | |
 
-Full policy details and parameter reference: [docs/built-in-policies.md](docs/built-in-policies.md)
+Full policy details and parameter reference: [docs/built-in-policies.mdx](docs/built-in-policies.mdx)
 
 ---
 
 ## Custom policies
 
-Create a `.js` file with your own policies:
+Write your own policies to keep agents reliable and on-task:
 
 ```js
 import { customPolicies, allow, deny, instruct } from "failproofai";
@@ -197,8 +197,9 @@ failproofai policies --install --custom ./my-policies.js
 
 | Function | Effect |
 |----------|--------|
-| `allow()` | Permit the tool call |
-| `deny(message)` | Block the tool call; message shown to Claude |
+| `allow()` | Permit the operation |
+| `allow(message)` | Permit and send informational context to Claude *(beta)* |
+| `deny(message)` | Block the operation; message shown to Claude |
 | `instruct(message)` | Add context to Claude's prompt; does not block |
 
 ### Context object (`ctx`)
@@ -213,7 +214,7 @@ failproofai policies --install --custom ./my-policies.js
 | `session.sessionId` | `string` | Session identifier |
 | `session.transcriptPath` | `string` | Path to the session transcript file |
 
-Custom hooks support transitive local imports, async/await, and access to `process.env`. Errors in custom hooks are fail-open (logged to `~/.failproofai/hook.log`, built-in policies continue). See [docs/custom-hooks.md](docs/custom-hooks.md) for the full guide.
+Custom hooks support transitive local imports, async/await, and access to `process.env`. Errors are fail-open (logged to `~/.failproofai/hook.log`, built-in policies continue). See [docs/custom-hooks.mdx](docs/custom-hooks.mdx) for the full guide.
 
 ---
 
@@ -233,14 +234,26 @@ FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai
 
 | Guide | Description |
 |-------|-------------|
-| [Getting Started](docs/getting-started.md) | Installation and first steps |
-| [CLI Reference](docs/cli-reference.md) | All commands and flags |
-| [Configuration](docs/configuration.md) | Config file format and scope merging |
-| [Built-in Policies](docs/built-in-policies.md) | All 35+ policies with parameters |
-| [Custom Hooks](docs/custom-hooks.md) | Write your own policies |
-| [Dashboard](docs/dashboard.md) | Session viewer and policy management |
-| [Architecture](docs/architecture.md) | How the hook system works |
-| [Testing](docs/testing.md) | Running tests and writing new ones |
+| [Getting Started](docs/getting-started.mdx) | Installation and first steps |
+| [Built-in Policies](docs/built-in-policies.mdx) | All 30 built-in policies with parameters |
+| [Custom Policies](docs/custom-policies.mdx) | Write your own policies |
+| [Configuration](docs/configuration.mdx) | Config file format and scope merging |
+| [Dashboard](docs/dashboard.mdx) | Monitor sessions and review policy activity |
+| [Architecture](docs/architecture.mdx) | How the hook system works |
+| [Testing](docs/testing.mdx) | Running tests and writing new ones |
+
+### Run docs locally
+
+```bash
+docker build -f Dockerfile.docs -t failproofai-docs .
+docker run --rm -p 3000:3000 failproofai-docs
+```
+
+Opens the Mintlify docs site at `http://localhost:3000`. The container watches for changes if you mount the docs directory:
+
+```bash
+docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs
+```
 
 ---