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

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";
@@ -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,
@@ -627,24 +644,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 +793,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 +1249,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/policy-evaluator.ts

@@ -51,6 +51,9 @@ export async function evaluatePolicies(
   let instructPolicyName: string | null = null;
   let instructReason: string | null = null;
 
+  // Track informational messages from allow decisions
+  const allowMessages: string[] = [];
+
   for (const policy of policies) {
     // Inject params: merge policyParams[policy.name] over schema defaults
     const schema = POLICY_PARAMS_MAP.get(policy.name);
@@ -133,6 +136,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) {
+      allowMessages.push(result.reason);
+    }
   }
 
   // No deny — check if we accumulated an instruct
@@ -166,6 +174,16 @@ export async function evaluatePolicies(
     };
   }
 
-  // All policies allowed
+  // All policies allowed — pass along any informational messages
+  if (allowMessages.length > 0) {
+    const combined = allowMessages.join("\n");
+    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" };
 }

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
+```
 
 ---