Architecture

מסמך זה מסביר כיצד failproofai עובד באופן פנימי: כיצד מערכת ה-Hook מיירטת קריאות Tool של Agent, כיצד Config נטען ומוזג, כיצד Policies מוערכות, וכיצד ה-Dashboard עוקב אחרי פעילות Agent.

Overview

ל-failproofai יש שתי תת-מערכות עצמאיות:

Hook handler - CLI subprocess מהיר שClaude Code קורא לו בכל קריאת Tool של Agent. מעריך Policies ומחזיר החלטה.
Agent Monitor (Dashboard) - אפליקציית Next.js לעקיבה אחרי סשנים של Agent וניהול Policies.

שתי התת-מערכות משתפות קבצי Config ב-~/.failproofai/ ובתיקייה .failproofai/ של הפרויקט, אך הן רצות כתהליכים נפרדים ותקשרו רק דרך מערכת הקבצים.

Hook handler

Integration עם Claude Code

כאשר אתה מריץ failproofai policies --install, הוא כותב entries כמו זה ל-~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "failproofai --hook PreToolUse"
          }
        ]
      }
    ],
    "PostToolUse": [ ... ]
  }
}

Claude Code קורא אחר כך ל-failproofai --hook PreToolUse כ-subprocess לפני כל קריאת Tool, ומעביר JSON payload על stdin.

פורמט Payload

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.claude/projects/myproject/sessions/abc123.jsonl",
  "cwd": "/home/user/myproject",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "sudo apt install nodejs" }
}

עבור אירועי PostToolUse, ה-payload גם כולל tool_result עם Output של ה-Tool. ה-Handler אוכף מגבלת stdin של 1 MB. Payloads החוצים זאת מושלכים וכל Policies באופן implicit מאפשרים.

Response format

Deny (PreToolUse):

{
  "hookSpecificOutput": {
    "permissionDecision": "deny",
    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
  }
}

Deny (PostToolUse):

{
  "hookSpecificOutput": {
    "additionalContext": "Blocked by failproofai because: API key detected in output"
  }
}

Instruct (כל אירוע למעט Stop):

{
  "hookSpecificOutput": {
    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
  }
}

Stop event instruct:

Exit code: 2
Reason כתוב ל-stderr (לא stdout)

Allow:

Exit code: 0
stdout ריק

Allow עם Message: allow(message) מאפשר לPolicy לשלוח Context informational חזרה ל-Claude גם כאשר הפעולה מותרת. ה-Hook Handler כותב את ה-JSON הבא ל-stdout (לא קובץ Config — זה ה-Response של ה-Handler ל-Claude Code, בדיוק כמו Deny ו-Instruct responses למעלה):

// Written to stdout by the hook handler process
{
  "hookSpecificOutput": {
    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
  }
}

Exit code: 0 (הפעולה מותרת)
כאשר multiple Policies מחזירות allow עם Message, ה-Messages שלהם מצורפות עם newlines לתוך string additionalContext יחיד
אם אף Policy לא מספק Message, stdout ריק (כמו קודם)

Processing pipeline

src/hooks/handler.ts מיישם את כל ה-Pipeline:

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

כל התהליך רץ בפחות מ-100ms עבור Payloads טיפוסיים בלי LLM calls.

Configuration loading

src/hooks/hooks-config.ts מיישם שלוש-scope Config loading.

[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 על כל שלושת הקבצים
policyParams - per-policy key, הקובץ הראשון שמגדיר אותו מנצח לחלוטין
customPoliciesPath - הקובץ הראשון שמגדיר אותו מנצח
llm - הקובץ הראשון שמגדיר אותו מנצח

ה-Web Dashboard משתמש ב-readHooksConfig() (global only) לקריאה וכתיבה, מכיוון שהוא לא קרוא עם Project cwd.

Policy evaluation

src/hooks/policy-evaluator.ts מריץ Policies בסדר. עבור כל Policy:

חפש את ה-params schema של ה-Policy (אם יש לו).
קרא policyParams[policy.name] מה-Merged Config.
Merge user-provided values על schema defaults לייצור ctx.params.
קרא policy.fn(ctx) עם ה-Resolved Context.
אם ה-Result הוא deny, עצור מיד וחזור בהחלטה זו.
אם ה-Result הוא instruct, צבור את ה-Message והמשך.
אם ה-Result הוא allow, המשך ל-Policy הבא.

לאחר שכל Policies רצים:

אם כל deny חזר, emit את ה-Deny Response.
אם כל instruct returns נאספו, emit Response instruct יחיד עם כל Messages מצורפות.
אחרת, emit Allow Response (stdout ריק, exit 0).

Builtin policies

src/hooks/builtin-policies.ts מגדיר את כל 39 ה-Builtin Policies כ-BuiltinPolicyDefinition objects:

interface BuiltinPolicyDefinition {
  name: string;
  description: string;
  fn: (ctx: PolicyContext) => PolicyResult;
  match: {
    events: HookEventType[];
    tools?: string[];
  };
  defaultEnabled: boolean;
  category: string;
  beta?: boolean;
  params?: PolicyParamsSchema;
}

Policies שמקבלות params מכריזות PolicyParamsSchema עם Types וDefaults עבור כל Parameter. ה-Policy Evaluator משדר Resolved Values ל-ctx.params לפני קריאה ל-fn. Policy Functions קוראות ctx.params בלי Null-Guarding כי Defaults תמיד מיושמות ראשון. Pattern Matching בתוך Policies משתמש בParsed Command Tokens (argv), לא Raw String Matching. זה מונע Bypass דרך Shell Operator Injection (למשל Pattern עבור sudo systemctl status * לא יכול להיות bypassed על ידי Appending ; rm -rf / לפקודה).

Custom policies

src/hooks/custom-hooks-registry.ts מיישם globalThis-backed Registry:

const REGISTRY_KEY = "__failproofai_custom_hooks__";

export const customPolicies = {
  add(hook: CustomHook): void { ... }
};

export function getCustomHooks(): CustomHook[] { ... }
export function clearCustomHooks(): void { ... }  // used in tests

src/hooks/custom-hooks-loader.ts טוען את Policy File של ה-User:

קרא customPoliciesPath מ-Config; דלג אם חסר.
Resolve ל-Absolute Path; בדוק אם הקובץ קיים.
כתוב מחדש את כל from "failproofai" Imports ל-Actual Dist Path כדי שה-customPolicies יתמוקד ל-globalThis Registry אותו.
כתוב מחדש באופן Recursive Transitive Local Imports כדי להבטיח ESM Compatibility.
כתוב Temporary .mjs Files ו-import() את Entry File.
קרא getCustomHooks() כדי לאחזר Registered Hooks.
נקה את כל Temp Files בבלוק finally.

בכל Error (File not found, Syntax Error, Import Failure), ה-Error נרשם ל-~/.failproofai/hook.log ו-Loader מחזיר Array ריק. Builtin Policies לא מושפעות. Custom Policies מוערכות לאחר כל Builtin Policies. Custom Policy deny עדיין Short-Circuits Further Custom Policies (אבל כל ה-Builtins כבר רצו בנקודה זו).

Activity logging

לאחר כל Hook Event, ה-Handler Appends JSONL Line ל-~/.failproofai/hook-activity.jsonl:

{
  "timestamp": "2026-04-06T12:34:56.789Z",
  "sessionId": "abc123",
  "eventType": "PreToolUse",
  "toolName": "Bash",
  "policyName": "block-sudo",
  "decision": "deny",
  "reason": "sudo command blocked by failproofai",
  "durationMs": 12
}

שורה אחת לכל Policy שעשה Decide שאינו Allow. Allow Decisions לא נרשמות (כדי לשמור את הקובץ קטן).

Dashboard architecture

ה-Dashboard היא אפליקציית Next.js 16 באמצעות App Router עם React Server Components ו-Server Actions.

app/
  layout.tsx                  ← Root layout (theme, telemetry, nav)
  projects/page.tsx           ← Server component: list all Claude projects
  project/[name]/page.tsx     ← Server component: list sessions in a project
  project/[name]/session/
    [sessionId]/page.tsx      ← Server component: render session viewer
  policies/page.tsx           ← Client component: policy management + activity log
  actions/
    get-hooks-config.ts       ← Read config + policy list
    update-hooks-config.ts    ← Toggle policy on/off
    update-policy-params.ts   ← Update policy parameters
    get-hook-activity.ts      ← Paginate/search activity log
    install-hooks-web.ts      ← Install/remove hooks from the browser
  api/
    download/[project]/[session]/route.ts   ← Per-CLI session export (JSONL or JSON)

Data flow:

Page Components קוראים ל-lib/projects.ts ו-lib/log-entries.ts כדי לקרוא Project/Session Data ישירות מ-Filesystem (אין API Layer עבור Reads).
ה-Policies Page משתמשת ב-Server Actions עבור כל Mutations (Toggle, Params Update, Install/Remove).
ה-Session Viewer מנתח Claude’s JSONL Transcript Format ומרנדר Timeline של Messages וTool Calls.

Key Design Decisions:

No Database - כל Persistent State נמצא בקבצים רגילים (~/.failproofai/, ~/.claude/projects/).
Server Actions לMutations - אין צורך ב-REST API עבור CRUD Operations.
React Server Components לRead Pages - Fast Initial Load, לא Client Bundle עבור Data Fetching.
Client Components רק כאשר Interactivity נדרשת (Policy Toggles, Activity Search, Log Viewer).

File layout

failproofai/
├── bin/
│   └── failproofai.mjs           # CLI router (hook / dashboard / install / etc.)
├── src/hooks/
│   ├── handler.ts                # Hook event pipeline
│   ├── builtin-policies.ts       # 39 policy definitions
│   ├── policy-evaluator.ts       # Policy execution engine
│   ├── policy-registry.ts        # Policy registration and lookup
│   ├── policy-types.ts           # TypeScript interfaces
│   ├── hooks-config.ts           # Multi-scope config loading
│   ├── custom-hooks-registry.ts  # globalThis-backed hook registry
│   ├── custom-hooks-loader.ts    # ESM loader for user JS hooks
│   ├── manager.ts                # install / remove / list operations
│   ├── install-prompt.ts         # Interactive policy selection prompt
│   ├── hook-logger.ts            # Logging to hook.log
│   ├── hook-activity-store.ts    # Persist activity to hook-activity.jsonl
│   └── llm-client.ts             # LLM API client (for AI-powered policies)
├── app/                          # Next.js dashboard (pages + server actions)
├── lib/                          # Shared utilities
│   ├── projects.ts               # Enumerate Claude projects from filesystem
│   ├── log-entries.ts            # Parse Claude transcript JSONL format
│   ├── paths.ts                  # Resolve system paths
│   └── ...
├── components/                   # Shared React UI components
├── contexts/                     # React context providers (theme, auto-refresh, telemetry)
├── examples/                     # Example custom hook files
└── __tests__/                    # Unit and E2E tests

תחילת עבודה

מושגי יסוד

CLI

כלים

מתקדם

דוגמאות

Overview

Hook handler

Integration עם Claude Code

פורמט Payload

Response format

Processing pipeline

Configuration loading

Policy evaluation

Builtin policies

Custom policies

Activity logging

Dashboard architecture

File layout

​Overview

​Hook handler

​Integration עם Claude Code

​פורמט Payload

​Response format

​Processing pipeline

​Configuration loading

​Policy evaluation

​Builtin policies

​Custom policies

​Activity logging

​Dashboard architecture

​File layout

Overview

Hook handler

Integration עם Claude Code

פורמט Payload

Response format

Processing pipeline

Configuration loading

Policy evaluation

Builtin policies

Custom policies

Activity logging

Dashboard architecture

File layout