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

package/.next/standalone/app/policies/hooks-client.tsx

@@ -83,7 +83,7 @@ function SessionCell({ sessionId, transcriptPath }: { sessionId?: string; transc
 
 // -- Badge Components --
 
-function DecisionBadge({ decision }: { decision: "allow" | "deny" | "instruct" }) {
+function DecisionBadge({ decision, hasMessage }: { decision: "allow" | "deny" | "instruct"; hasMessage?: boolean }) {
   if (decision === "deny") {
     return (
       <span className="inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-[0.65rem] font-semibold tracking-wide uppercase bg-red-500/10 text-red-400 border border-red-500/20">
@@ -100,6 +100,15 @@ function DecisionBadge({ decision }: { decision: "allow" | "deny" | "instruct" }
       </span>
     );
   }
+  if (decision === "allow" && hasMessage) {
+    return (
+      <span className="inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-[0.65rem] font-semibold tracking-wide uppercase bg-sky-500/10 text-sky-400 border border-sky-500/20">
+        <ShieldCheck className="h-3 w-3" />
+        Allow
+        <span className="text-[0.55rem] font-normal normal-case">(note)</span>
+      </span>
+    );
+  }
   return (
     <span className="inline-flex items-center gap-1 rounded px-1.5 py-0.5 text-[0.65rem] font-semibold tracking-wide uppercase bg-emerald-500/10 text-emerald-400 border border-emerald-500/20">
       <ShieldCheck className="h-3 w-3" />
@@ -270,6 +279,12 @@ function DetailPanel({
               </span>
             </div>
           </div>
+          {item.policyNames && item.policyNames.length > 1 && (
+            <div>
+              <span className="text-muted-foreground">Policies: </span>
+              <span className="font-mono text-foreground">{item.policyNames.join(", ")}</span>
+            </div>
+          )}
           {item.reason && (
             <div>
               <span className="text-muted-foreground">Full reason: </span>
@@ -469,6 +484,7 @@ function ActivityTab({
                   const isDeny = item.decision === "deny";
                   const isExpanded = expandedRow === i;
                   const isInstruct = item.decision === "instruct";
+                  const isAllowWithMessage = item.decision === "allow" && !!item.reason;
                   return (
                     <React.Fragment key={`${item.timestamp}-${i}`}>
                       <tr
@@ -478,9 +494,11 @@ function ActivityTab({
                             ? "bg-red-500/[0.03] hover:bg-red-500/[0.07] border-l-2 border-l-red-500/40"
                             : isInstruct
                               ? "bg-amber-500/[0.03] hover:bg-amber-500/[0.07] border-l-2 border-l-amber-500/40"
-                              : i % 2 === 0
-                                ? "hover:bg-muted/30"
-                                : "bg-muted/[0.04] hover:bg-muted/30"
+                              : isAllowWithMessage
+                                ? "bg-sky-500/[0.02] hover:bg-sky-500/[0.05] border-l-2 border-l-sky-500/30"
+                                : i % 2 === 0
+                                  ? "hover:bg-muted/30"
+                                  : "bg-muted/[0.04] hover:bg-muted/30"
                         } ${isExpanded ? "bg-muted/20" : ""}`}
                       >
                         <td className="px-4 py-2">
@@ -491,7 +509,7 @@ function ActivityTab({
                           />
                         </td>
                         <td className="px-3 py-2">
-                          <DecisionBadge decision={item.decision} />
+                          <DecisionBadge decision={item.decision} hasMessage={isAllowWithMessage} />
                         </td>
                         <td className="px-3 py-2">
                           <EventTypeBadge eventType={item.eventType} />
@@ -500,7 +518,14 @@ function ActivityTab({
                           {item.toolName ?? "\u2014"}
                         </td>
                         <td className="px-3 py-2 font-mono text-foreground">
-                          {item.policyName ?? "\u2014"}
+                          {item.policyNames && item.policyNames.length > 1 ? (
+                            <span title={item.policyNames.join(", ")}>
+                              {item.policyNames[0]}
+                              <span className="text-muted-foreground text-[0.6rem]"> +{item.policyNames.length - 1}</span>
+                            </span>
+                          ) : (
+                            item.policyName ?? "\u2014"
+                          )}
                         </td>
                         <td
                           className="px-3 py-2 text-muted-foreground truncate max-w-[240px]"

package/.next/standalone/dist/cli.mjs

@@ -179,8 +179,8 @@ var init_hooks_config = __esm(() => {
 });
 
 // src/hooks/policy-helpers.ts
-function allow() {
-  return { decision: "allow" };
+function allow(reason) {
+  return reason ? { decision: "allow", reason } : { decision: "allow" };
 }
 function deny(reason) {
   return { decision: "deny", reason };
@@ -248,7 +248,7 @@ var REGISTRY_KEY = "__FAILPROOFAI_POLICY_REGISTRY__", INDEX_CACHE_KEY = "__FAILP
 // src/hooks/builtin-policies.ts
 import { resolve as resolve2, join as join2 } from "node:path";
 import { readFile, writeFile } from "node:fs/promises";
-import { execSync } from "node:child_process";
+import { execSync, execFileSync } from "node:child_process";
 import { homedir as homedir3 } from "node:os";
 function isClaudeInternalPath(resolved2) {
   const claudeDir = join2(homedir3(), ".claude");
@@ -266,6 +266,22 @@ function getFilePath(ctx) {
 function parseArgvTokens(cmd) {
   return cmd.trim().split(/\s+/).map((t) => t.replace(/^['"]|['"]$/g, ""));
 }
+function getCurrentBranch(cwd) {
+  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;
+  }
+}
 function matchesAllowedPattern(cmd, pattern) {
   const cmdTokens = parseArgvTokens(cmd);
   const patTokens = parseArgvTokens(pattern);
@@ -480,7 +496,8 @@ function rmTargetIsAllowed(cmd, allowPaths) {
     if (rmIdx < 0)
       continue;
     const flagTokens = tokens.slice(rmIdx + 1).filter((t) => /^-[^-]/.test(t));
-    if (!/r/i.test(flagTokens.join("")))
+    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) {
@@ -505,7 +522,10 @@ function blockRmRf(ctx) {
   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);
+  });
   if (hasDestructivePath && (/rm\s+-[^\s]*r[^\s]*f[^\s]*/.test(cmd) || /rm\s+-[^\s]*f[^\s]*r[^\s]*/.test(cmd))) {
     const allowPaths = ctx.params?.allowPaths ?? [];
     if (rmTargetIsAllowed(cmd, allowPaths))
@@ -515,7 +535,10 @@ function blockRmRf(ctx) {
   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 ?? [];
       if (rmTargetIsAllowed(cmd, allowPaths))
         return allow();
@@ -653,22 +676,12 @@ function blockWorkOnMain(ctx) {
   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"];
-    if (protectedBranches.includes(branch)) {
-      return deny(`Git ${cmd.match(/git\s+(\S+)/)?.[1] ?? "operation"} on ${branch} is blocked. Create a feature branch first.`);
-    }
-  } catch {
+  const branch = getCurrentBranch(cwd);
+  if (!branch)
     return allow();
+  const protectedBranches = ctx.params?.protectedBranches ?? ["main", "master"];
+  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();
 }
@@ -767,6 +780,137 @@ function warnBackgroundProcess(ctx) {
   }
   return allow();
 }
+function requireCommitBeforeStop(ctx) {
+  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) {
+  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 ?? "origin";
+    const branch = getCurrentBranch(cwd);
+    if (!branch || branch === "HEAD")
+      return allow("Detached HEAD, skipping push check.");
+    let hasTracking = false;
+    try {
+      execFileSync("git", ["rev-parse", "--verify", `${remote}/${branch}`], {
+        cwd,
+        encoding: "utf8",
+        timeout: 3000
+      });
+      hasTracking = true;
+    } catch {}
+    if (!hasTracking) {
+      return deny(`Branch "${branch}" has not been pushed to remote "${remote}". ` + `Push your branch with: git push -u ${remote} ${branch}`);
+    }
+    const unpushed = execFileSync("git", ["log", `${remote}/${branch}..HEAD`, "--oneline"], {
+      cwd,
+      encoding: "utf8",
+      timeout: 5000
+    }).trim();
+    if (unpushed.length > 0) {
+      const commitCount = unpushed.split(`
+`).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) {
+  const cwd = ctx.session?.cwd;
+  if (!cwd)
+    return allow("No working directory available, skipping PR check.");
+  try {
+    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.");
+    let prJson;
+    try {
+      prJson = execSync("gh pr view --json number,url,state", {
+        cwd,
+        encoding: "utf8",
+        timeout: 15000
+      }).trim();
+    } catch {
+      return deny(`No pull request found for branch "${branch}". ` + `Create one with: gh pr create`);
+    }
+    const pr = JSON.parse(prJson);
+    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) {
+  const cwd = ctx.session?.cwd;
+  if (!cwd)
+    return allow("No working directory available, skipping CI check.");
+  try {
+    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);
+    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.");
+  }
+}
 function registerBuiltinPolicies(enabledNames) {
   const enabledSet = new Set(enabledNames);
   for (const policy of BUILTIN_POLICIES) {
@@ -802,7 +946,7 @@ var init_builtin_policies = __esm(() => {
   SCHEMA_ALTER_RE = /\bALTER\s+TABLE\b[\s\S]*\b(?:DROP\s+COLUMN|ADD\s+COLUMN|RENAME\s+(?:COLUMN|TO)|MODIFY\s+COLUMN)\b/i;
   PUBLISH_CMD_RE = /(?:npm\s+publish|bun\s+publish|pnpm\s+publish|yarn\s+npm\s+publish|twine\s+upload|poetry\s+publish|cargo\s+publish|gem\s+push)\b/;
   ENV_PRINTENV_RE = /(?:^|\s|;|&&|\|\|)(?:env|printenv)(?:\s|$|;|&&|\|)/;
-  ECHO_ENV_RE = /echo\s+.*\$[A-Za-z_]/;
+  ECHO_ENV_RE = /echo\s+.*\$\{?[A-Za-z_]/;
   EXPORT_RE = /(?:^|\s|;|&&|\|\|)export\s+\w+/;
   PS_ENV_VAR_RE = /\$env:[A-Za-z_]/i;
   PS_CHILDITEM_ENV_RE = /(?:Get-ChildItem|dir|gci|ls)\s+Env:/i;
@@ -813,7 +957,7 @@ var init_builtin_policies = __esm(() => {
   SUDO_RE = /(?:^|;|&&|\|\|)\s*sudo\s/;
   PS_ELEVATION_RE = /Start-Process\s+.*-Verb\s+RunAs/i;
   RUNAS_RE = /(?:^|;|&&|\|\|)\s*runas\s/i;
-  CURL_PIPE_SH_RE = /(?:curl|wget)\s.*\|\s*(?:sh|bash|zsh)/;
+  CURL_PIPE_SH_RE = /(?:curl|wget)\s.*\|\s*(?:sh|bash|zsh|dash|ksh|csh|tcsh|fish|ash)\b/;
   PS_WEB_PIPE_RE = /(?:Invoke-WebRequest|iwr|Invoke-RestMethod|irm)\s+.*\|\s*(?:Invoke-Expression|iex)/i;
   FORCE_PUSH_RE = /(?:--force|-f\b)/;
   SECRET_FILE_RE = /\.(?:pem|key)$/;
@@ -1102,6 +1246,49 @@ var init_builtin_policies = __esm(() => {
       match: { events: ["PreToolUse"] },
       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"
+        }
+      }
+    },
+    {
+      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
     }
   ];
 });
@@ -1124,6 +1311,7 @@ async function evaluatePolicies(eventType, payload, session, config) {
   };
   let instructPolicyName = null;
   let instructReason = null;
+  const allowEntries = [];
   for (const policy of policies) {
     const schema = POLICY_PARAMS_MAP.get(policy.name);
     let ctx;
@@ -1184,7 +1372,7 @@ async function evaluatePolicies(eventType, payload, session, config) {
       return {
         exitCode: 2,
         stdout: "",
-        stderr: "",
+        stderr: reason,
         policyName: policy.name,
         reason,
         decision: "deny"
@@ -1195,6 +1383,9 @@ async function evaluatePolicies(eventType, payload, session, config) {
       instructReason = result.reason ?? `Instruction from policy: ${policy.name}`;
       hookLogInfo(`instruct by "${policy.name}": ${instructReason}`);
     }
+    if (result.decision === "allow" && result.reason) {
+      allowEntries.push({ policyName: policy.name, reason: result.reason });
+    }
   }
   if (instructPolicyName && instructReason) {
     if (eventType === "Stop") {
@@ -1222,6 +1413,17 @@ async function evaluatePolicies(eventType, payload, session, config) {
       decision: "instruct"
     };
   }
+  if (allowEntries.length > 0) {
+    const combined = allowEntries.map((e) => e.reason).join(`
+`);
+    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(`
+`);
+    return { exitCode: 0, stdout: JSON.stringify(response), stderr: stderrMsg + `
+`, policyName: policyNames[0], policyNames, reason: combined, decision: "allow" };
+  }
   return { exitCode: 0, stdout: "", stderr: "", policyName: null, reason: null, decision: "allow" };
 }
 var POLICY_PARAMS_MAP;
@@ -1516,7 +1718,11 @@ function updateStats(entry) {
   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;
   }
   const tmpPath = join3(storeDir, `stats.json.${process.pid}.tmp`);
@@ -1536,7 +1742,7 @@ var init_hook_activity_store = __esm(() => {
 });
 
 // package.json
-var version2 = "0.0.2-beta.2";
+var version2 = "0.0.2-beta.4";
 var init_package = () => {};
 
 // src/posthog-key.ts
@@ -1745,6 +1951,7 @@ async function handleHookEvent(eventType) {
       eventType,
       toolName: parsed.tool_name ?? null,
       policyName: result.policyName,
+      policyNames: result.policyNames,
       decision: result.decision,
       reason: result.reason,
       durationMs,
@@ -2762,7 +2969,7 @@ import { realpathSync as realpathSync2 } from "fs";
 import { dirname as dirname5, resolve as resolve8 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 // package.json
-var version = "0.0.2-beta.2";
+var version = "0.0.2-beta.4";
 
 // bin/failproofai.mjs
 if (!process.env.FAILPROOFAI_PACKAGE_ROOT) {

package/.next/standalone/dist/index.js

@@ -69,8 +69,8 @@ function clearCustomHooks() {
   g[REGISTRY_KEY] = [];
 }
 // src/hooks/policy-helpers.ts
-function allow() {
-  return { decision: "allow" };
+function allow(reason) {
+  return reason ? { decision: "allow", reason } : { decision: "allow" };
 }
 function deny(reason) {
   return { decision: "deny", reason };

package/.next/standalone/docs/{architecture.md → architecture.mdx}

@@ -4,7 +4,7 @@ description: "How the hook handler, config loading, and policy evaluation work i
 icon: sitemap
 ---
 
-This document explains how failproofai works internally: how the hook system processes events, how configuration is loaded and merged, how policies are evaluated, and how the dashboard fits in.
+This document explains how failproofai works internally: how the hook system intercepts agent tool calls, how configuration is loaded and merged, how policies are evaluated, and how the dashboard monitors agent activity.
 
 ---
 
@@ -12,8 +12,8 @@ This document explains how failproofai works internally: how the hook system pro
 
 failproofai has two independent subsystems:
 
-1. **Hook handler** — A fast CLI subprocess that Claude Code invokes on every tool call. Evaluates policies and returns a decision.
-2. **Dashboard** — A Next.js web application for browsing sessions and managing policies.
+1. **Hook handler** - A fast CLI subprocess that Claude Code invokes on every agent tool call. Evaluates policies and returns a decision.
+2. **Agent Monitor (Dashboard)** - A Next.js web application for monitoring agent sessions and managing policies.
 
 Both subsystems share configuration files in `~/.failproofai/` and the project's `.failproofai/` directory, but they run as separate processes and communicate only through the filesystem.
 
@@ -23,7 +23,7 @@ Both subsystems share configuration files in `~/.failproofai/` and the project's
 
 ### Integration with Claude Code
 
-When you run `failproofai --install-policies`, it writes entries like this into `~/.claude/settings.json`:
+When you run `failproofai policies --install`, it writes entries like this into `~/.claude/settings.json`:
 
 ```json
 {
@@ -60,7 +60,7 @@ Claude Code then invokes `failproofai --hook PreToolUse` as a subprocess before
 }
 ```
 
-For `PostToolUse` events, the payload additionally contains `tool_result` with the tool's output.
+For `PostToolUse` events, the payload also contains `tool_result` with the tool's output.
 
 The handler enforces a 1 MB stdin limit. Payloads exceeding this are discarded and all policies implicitly allow.
 
@@ -102,21 +102,38 @@ The handler enforces a 1 MB stdin limit. Payloads exceeding this are discarded a
 - Exit code: `0`
 - Empty stdout
 
+**Allow with message (beta):**
+
+Since v0.0.2-beta.3, `allow(message)` lets a policy send informational context back to Claude even when the operation is permitted. The hook handler writes the following JSON to **stdout** (not a config file — this is the handler's response to Claude Code, just like deny and instruct responses above):
+
+```json
+// Written to stdout by the hook handler process
+{
+  "hookSpecificOutput": {
+    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
+  }
+}
+```
+- Exit code: `0` (operation is allowed)
+- When multiple policies return `allow` with a message, their messages are joined with newlines into a single `additionalContext` string
+- If no policy provides a message, stdout is empty (same as before)
+
 ### Processing pipeline
 
 `src/hooks/handler.ts` implements the full pipeline:
 
-```
+```text
 stdin JSON
   → parse payload (max 1 MB)
   → extract session metadata (session_id, cwd, tool_name, tool_input, etc.)
   → readMergedHooksConfig(cwd)    ← merges project + local + global config
   → register enabled builtin policies with resolved params
-  → load custom hooks from customPoliciesPath (if set)
-  → register custom hooks into policy registry
+  → load custom policies from customPoliciesPath (if set)
+  → register custom policies into policy registry
   → evaluate all policies (builtins first, then custom)
       → first deny short-circuits
       → instruct decisions accumulate
+      → allow messages accumulate
   → write JSON decision to stdout
   → persist event to ~/.failproofai/hook-activity.jsonl
   → exit
@@ -130,17 +147,17 @@ The entire process runs in under 100ms for typical payloads with no LLM calls.
 
 `src/hooks/hooks-config.ts` implements three-scope config loading.
 
-```
+```text
 [1] {cwd}/.failproofai/policies-config.json        ← project  (highest priority)
 [2] {cwd}/.failproofai/policies-config.local.json  ← local
 [3] ~/.failproofai/policies-config.json             ← global   (lowest priority)
 ```
 
 Merge logic:
-- `enabledPolicies` — deduplicated union across all three files
-- `policyParams` — per-policy key, first file that defines it wins entirely
-- `customPoliciesPath` — first file that defines it wins
-- `llm` — first file that defines it wins
+- `enabledPolicies` - deduplicated union across all three files
+- `policyParams` - per-policy key, first file that defines it wins entirely
+- `customPoliciesPath` - first file that defines it wins
+- `llm` - first file that defines it wins
 
 The web dashboard uses `readHooksConfig()` (global only) for reading and writing, since it is not invoked with a project cwd.
 
@@ -169,7 +186,7 @@ After all policies run:
 
 ## Builtin policies
 
-`src/hooks/builtin-policies.ts` defines all 35+ built-in policies as `BuiltinPolicyDefinition` objects:
+`src/hooks/builtin-policies.ts` defines all 26 built-in policies as `BuiltinPolicyDefinition` objects:
 
 ```typescript
 interface BuiltinPolicyDefinition {
@@ -193,7 +210,7 @@ Pattern matching inside policies uses parsed command tokens (argv), not raw stri
 
 ---
 
-## Custom hooks
+## Custom policies
 
 `src/hooks/custom-hooks-registry.ts` implements a `globalThis`-backed registry:
 
@@ -208,7 +225,7 @@ export function getCustomHooks(): CustomHook[] { ... }
 export function clearCustomHooks(): void { ... }  // used in tests
 ```
 
-`src/hooks/custom-hooks-loader.ts` loads the user's hooks file:
+`src/hooks/custom-hooks-loader.ts` loads the user's policy file:
 
 1. Read `customPoliciesPath` from config; skip if absent.
 2. Resolve to absolute path; check file exists.
@@ -220,7 +237,7 @@ export function clearCustomHooks(): void { ... }  // used in tests
 
 On any error (file not found, syntax error, import failure), the error is logged to `~/.failproofai/hook.log` and the loader returns an empty array. Built-in policies are unaffected.
 
-Custom hooks are evaluated after all built-in policies. A custom hook `deny` still short-circuits further custom hooks (but all built-ins have already run by that point).
+Custom policies are evaluated after all built-in policies. A custom policy `deny` still short-circuits further custom policies (but all built-ins have already run by that point).
 
 ---
 
@@ -249,7 +266,7 @@ One line per policy that made a non-allow decision. Allow decisions are not logg
 
 The dashboard is a **Next.js 16** application using the App Router with React Server Components and Server Actions.
 
-```
+```text
 app/
   layout.tsx                  ← Root layout (theme, telemetry, nav)
   projects/page.tsx           ← Server component: list all Claude projects
@@ -275,22 +292,22 @@ app/
 
 **Key design decisions:**
 
-- No database — all persistent state is in plain files (`~/.failproofai/`, `~/.claude/projects/`).
-- Server Actions for mutations — no REST API needed for CRUD operations.
-- React Server Components for read pages — faster initial load, no client bundle for data fetching.
+- No database - all persistent state is in plain files (`~/.failproofai/`, `~/.claude/projects/`).
+- Server Actions for mutations - no REST API needed for CRUD operations.
+- React Server Components for read pages - faster initial load, no client bundle for data fetching.
 - Client components only where interactivity is needed (policy toggles, activity search, log viewer).
 
 ---
 
 ## File layout
 
-```
+```text
 failproofai/
 ├── bin/
 │   └── failproofai.mjs           # CLI router (hook / dashboard / install / etc.)
 ├── src/hooks/
 │   ├── handler.ts                # Hook event pipeline
-│   ├── builtin-policies.ts       # 35+ policy definitions
+│   ├── builtin-policies.ts       # 26 policy definitions
 │   ├── policy-evaluator.ts       # Policy execution engine
 │   ├── policy-registry.ts        # Policy registration and lookup
 │   ├── policy-types.ts           # TypeScript interfaces