failproofai 0.0.2 → 0.0.3

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

@@ -8,11 +8,20 @@ import { BUILTIN_POLICIES } from "./builtin-policies";
 import { getPoliciesForEvent } from "./policy-registry";
 import { hookLogInfo, hookLogWarn } from "./hook-logger";
 
+function appendHint(baseReason: string, hint: unknown): string {
+  const base = baseReason.trim();
+  const normalizedHint = typeof hint === "string" ? hint.trim() : "";
+  if (!normalizedHint) return base;
+  if (!base) return normalizedHint;
+  return `${base}. ${normalizedHint}`;
+}
+
 export interface EvaluationResult {
   exitCode: number;
   stdout: string;
   stderr: string;
   policyName: string | null;
+  policyNames?: string[];
   reason: string | null;
   decision: "allow" | "deny" | "instruct";
 }
@@ -47,9 +56,11 @@ export async function evaluatePolicies(
     session,
   };
 
-  // Track the first instruct result (accumulated, does not short-circuit)
-  let instructPolicyName: string | null = null;
-  let instructReason: string | null = null;
+  // Track all instruct results (accumulated, does not short-circuit)
+  const instructEntries: Array<{ policyName: string; reason: string }> = [];
+
+  // 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
@@ -76,7 +87,10 @@ export async function evaluatePolicies(
     }
 
     if (result.decision === "deny") {
-      const reason = result.reason ?? `Blocked by policy: ${policy.name}`;
+      const reason = appendHint(
+        result.reason ?? `Blocked by policy: ${policy.name}`,
+        config?.policyParams?.[policy.name]?.hint,
+      );
       hookLogInfo(`deny by "${policy.name}": ${reason}`);
 
       const displayTool = ctx.toolName ?? "unknown tool";
@@ -120,32 +134,44 @@ export async function evaluatePolicies(
       return {
         exitCode: 2,
         stdout: "",
-        stderr: "",
+        stderr: reason,
         policyName: policy.name,
         reason,
         decision: "deny",
       };
     }
 
-    // Accumulate first instruct (does not short-circuit — later policies can still deny)
-    if (result.decision === "instruct" && !instructPolicyName) {
-      instructPolicyName = policy.name;
-      instructReason = result.reason ?? `Instruction from policy: ${policy.name}`;
-      hookLogInfo(`instruct by "${policy.name}": ${instructReason}`);
+    // Accumulate all instruct results (does not short-circuit — later policies can still deny)
+    if (result.decision === "instruct") {
+      const reason = appendHint(
+        result.reason ?? `Instruction from policy: ${policy.name}`,
+        config?.policyParams?.[policy.name]?.hint,
+      );
+      instructEntries.push({ policyName: policy.name, reason });
+      hookLogInfo(`instruct by "${policy.name}": ${reason}`);
+    }
+
+    // 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
-  if (instructPolicyName && instructReason) {
+  // No deny — check if we accumulated any instructs
+  if (instructEntries.length > 0) {
+    const combined = instructEntries.map((e) => e.reason).join("\n");
+    const policyNames = instructEntries.map((e) => e.policyName);
+
     if (eventType === "Stop") {
       // Stop hook: exitCode 2 blocks Claude from stopping.
       // Reason goes to stderr so Claude Code receives it as context.
       return {
         exitCode: 2,
         stdout: "",
-        stderr: instructReason,
-        policyName: instructPolicyName,
-        reason: instructReason,
+        stderr: combined,
+        policyName: policyNames[0],
+        policyNames,
+        reason: combined,
         decision: "instruct",
       };
     }
@@ -153,19 +179,32 @@ export async function evaluatePolicies(
     const response = {
       hookSpecificOutput: {
         hookEventName: eventType,
-        additionalContext: `Instruction from failproofai: ${instructReason}`,
+        additionalContext: `Instruction from failproofai: ${combined}`,
       },
     };
     return {
       exitCode: 0,
       stdout: JSON.stringify(response),
       stderr: "",
-      policyName: instructPolicyName,
-      reason: instructReason,
+      policyName: policyNames[0],
+      policyNames,
+      reason: combined,
       decision: "instruct",
     };
   }
 
-  // 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

@@ -13,23 +13,25 @@
 [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai)
 [![License](https://img.shields.io/badge/license-MIT%20%2B%20Commons%20Clause-blue?style=flat-square)](LICENSE)
 [![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)
+[![Slack](https://img.shields.io/badge/Slack-join%20us-4A154B?style=flat-square&logo=slack)](https://join.slack.com/t/failproofai/shared_invite/zt-3v63b7k5e-O3NBHmj8X6n9gZSGDx6ggQ)
 
-Open-source hooks, policies, and project visualization for **Claude Code** & the **Agents SDK**.
+**Translations**: [简体中文](docs/i18n/README.zh.md) | [日本語](docs/i18n/README.ja.md) | [한국어](docs/i18n/README.ko.md) | [Español](docs/i18n/README.es.md) | [Português](docs/i18n/README.pt-br.md) | [Deutsch](docs/i18n/README.de.md) | [Français](docs/i18n/README.fr.md) | [Русский](docs/i18n/README.ru.md) | [हिन्दी](docs/i18n/README.hi.md) | [Türkçe](docs/i18n/README.tr.md) | [Tiếng Việt](docs/i18n/README.vi.md) | [Italiano](docs/i18n/README.it.md) | [العربية](docs/i18n/README.ar.md) | [עברית](docs/i18n/README.he.md)
 
-- **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.
+The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously - for **Claude Code** & the **Agents SDK**.
 
-Everything runs locally — no data leaves your machine.
+- **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.
 
 ---
 
 ## 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 +61,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
 
@@ -111,10 +113,12 @@ Policy configuration lives in `~/.failproofai/policies-config.json` (global) or
   ],
   "policyParams": {
     "block-sudo": {
-      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"],
+      "hint": "Use apt-get directly without sudo."
     },
     "block-push-master": {
-      "protectedBranches": ["main", "release", "prod"]
+      "protectedBranches": ["main", "release", "prod"],
+      "hint": "Try creating a fresh branch instead."
     },
     "sanitize-api-keys": {
       "additionalPatterns": [
@@ -128,7 +132,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 +140,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 +201,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 +218,22 @@ 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.
+
+### Convention-based policies (v0.0.2-beta.7+)
+
+Drop `*policies.{js,mjs,ts}` files into `.failproofai/policies/` and they're automatically loaded — no `--custom` flag or config changes needed. Works like git hooks: drop a file, it just works.
+
+```text
+# Project level — committed to git, shared with the team
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# User level — personal, applies to all projects
+~/.failproofai/policies/my-policies.mjs
+```
+
+Both levels load (union). Files are loaded alphabetically within each directory. Prefix with `01-`, `02-`, etc. to control order. See [examples/convention-policies/](examples/convention-policies/) for ready-to-use examples.
 
 ---
 
@@ -233,17 +253,39 @@ 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
+```
 
 ---
 
+## Note for failproofai contributors
+
+This repo's `.claude/settings.json` uses `bun ./bin/failproofai.mjs --hook <EventType>` instead of the standard `npx -y failproofai` command. This is because running `npx -y failproofai` inside the failproofai project itself creates a self-referencing conflict.
+
+For all other repos, the recommended approach is `npx -y failproofai`, installed via:
+
+```bash
+failproofai policies --install --scope project
+```
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).
@@ -253,3 +295,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 ## License
 
 See [LICENSE](LICENSE).
+
+---
+
+Built and Maintained by **ExosphereHost: Reliability Research Lab for Your Agents**. We help enterprises and startups improve the reliability of their AI agents through our own agents, software, and expertise. Learn more at [exosphere.host](https://exosphere.host).

package/bin/failproofai.mjs

@@ -97,6 +97,11 @@ COMMANDS
   --version, -v                  Print version and exit
   --help, -h                     Show this help message
 
+CONVENTION POLICIES
+  Drop *policies.{js,mjs,ts} files into .failproofai/policies/ for auto-loading.
+  Works at project level (.failproofai/policies/) and user level (~/.failproofai/policies/).
+  No --custom flag or config changes needed — just drop files and they're picked up.
+
 EXAMPLES
   failproofai policies
   failproofai policies --install