failproofai 0.0.2-beta.2 → 0.0.2-beta.3

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);
@@ -653,22 +669,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 +773,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) {
@@ -1102,6 +1239,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 +1304,7 @@ async function evaluatePolicies(eventType, payload, session, config) {
   };
   let instructPolicyName = null;
   let instructReason = null;
+  const allowMessages = [];
   for (const policy of policies) {
     const schema = POLICY_PARAMS_MAP.get(policy.name);
     let ctx;
@@ -1195,6 +1376,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) {
+      allowMessages.push(result.reason);
+    }
   }
   if (instructPolicyName && instructReason) {
     if (eventType === "Stop") {
@@ -1222,6 +1406,17 @@ async function evaluatePolicies(eventType, payload, session, config) {
       decision: "instruct"
     };
   }
+  if (allowMessages.length > 0) {
+    const combined = allowMessages.join(`
+`);
+    const response = {
+      hookSpecificOutput: {
+        hookEventName: eventType,
+        additionalContext: combined
+      }
+    };
+    return { exitCode: 0, stdout: JSON.stringify(response), stderr: "", policyName: null, reason: combined, decision: "allow" };
+  }
   return { exitCode: 0, stdout: "", stderr: "", policyName: null, reason: null, decision: "allow" };
 }
 var POLICY_PARAMS_MAP;
@@ -1536,7 +1731,7 @@ var init_hook_activity_store = __esm(() => {
 });
 
 // package.json
-var version2 = "0.0.2-beta.2";
+var version2 = "0.0.2-beta.3";
 var init_package = () => {};
 
 // src/posthog-key.ts
@@ -2762,7 +2957,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.3";
 
 // 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