Chuyển đến nội dung chính

​
title: Kiến trúc description: “Cách hook handler, config loading, và policy evaluation hoạt động nội bộ” icon: sitemap

Tài liệu này giải thích cách failproofai hoạt động nội bộ: cách hệ thống hook chặn các lệnh gọi công cụ của agent, cách cấu hình được tải và hợp nhất, cách các chính sách được đánh giá, và cách dashboard theo dõi hoạt động của agent.

​
Tổng quan

failproofai có hai hệ thống con độc lập:
  1. Hook handler - Một CLI subprocess nhanh mà Claude Code gọi trên mỗi lệnh gọi công cụ agent. Đánh giá các chính sách và trả về một quyết định.
  2. Agent Monitor (Dashboard) - Một ứng dụng web Next.js để theo dõi các phiên làm việc của agent và quản lý các chính sách.
Cả hai hệ thống con chia sẻ các tệp cấu hình trong ~/.failproofai/ và thư mục .failproofai/ của dự án, nhưng chúng chạy dưới dạng các quy trình riêng biệt và chỉ giao tiếp thông qua hệ thống tệp.

​
Hook handler

​
Tích hợp với Claude Code

Khi bạn chạy failproofai policies --install, nó ghi các mục như thế này vào ~/.claude/settings.json: 
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "failproofai --hook PreToolUse"
          }
        ]
      }
    ],
    "PostToolUse": [ ... ]
  }
}
Claude Code sau đó gọi failproofai --hook PreToolUse như một subprocess trước mỗi lệnh gọi công cụ, truyền một payload JSON trên stdin.

​
Định dạng 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" }
}
Đối với các sự kiện PostToolUse, payload cũng chứa tool_result với kết quả của công cụ. Handler thực thi giới hạn 1 MB cho stdin. Các payload vượt quá giới hạn này sẽ bị loại bỏ và tất cả các chính sách ngầm cho phép.

​
Định dạng phản hồi

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 (bất kỳ sự kiện nào ngoại trừ Stop): 
{
  "hookSpecificOutput": {
    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
  }
}
Instruct sự kiện Stop:
  • Exit code: 2
  • Lý do được ghi vào stderr (không phải stdout)
Allow:
  • Exit code: 0
  • stdout trống
Allow với thông báo: allow(message) cho phép một chính sách gửi ngữ cảnh thông tin trở lại Claude ngay cả khi hoạt động được phép. Hook handler ghi JSON sau đây vào stdout (không phải một tệp cấu hình — đây là phản hồi của handler đối với Claude Code, giống như các phản hồi deny và instruct ở trên): 
// Written to stdout by the hook handler process
{
  "hookSpecificOutput": {
    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
  }
}
  • Exit code: 0 (hoạt động được phép)
  • Khi nhiều chính sách trả về allow với một thông báo, các thông báo của chúng được nối với dòng mới thành một chuỗi additionalContext duy nhất
  • Nếu không có chính sách nào cung cấp một thông báo, stdout sẽ trống (giống như trước đây)

​
Pipeline xử lý

src/hooks/handler.ts thực hiện toàn bộ 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
Toàn bộ quy trình chạy dưới 100ms cho các payload điển hình mà không có các lệnh gọi LLM.

​
Config loading

src/hooks/hooks-config.ts thực hiện config loading ba phạm vi. 
[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)
Logic hợp nhất:
  • enabledPolicies - hợp nhất được khử trùng lặp trên cả ba tệp
  • policyParams - mỗi chính sách, tệp đầu tiên xác định nó sẽ thắng toàn bộ
  • customPoliciesPath - tệp đầu tiên xác định nó sẽ thắng
  • llm - tệp đầu tiên xác định nó sẽ thắng
Dashboard web sử dụng readHooksConfig() (chỉ toàn cầu) để đọc và ghi, vì nó không được gọi với một project cwd.

​
Policy evaluation

src/hooks/policy-evaluator.ts chạy các chính sách theo thứ tự. Đối với mỗi chính sách:
  1. Tra cứu lược đồ params của chính sách (nếu có).
  2. Đọc policyParams[policy.name] từ config đã hợp nhất.
  3. Hợp nhất các giá trị do người dùng cung cấp vào các giá trị mặc định của lược đồ để tạo ctx.params.
  4. Gọi policy.fn(ctx) với ngữ cảnh đã được giải quyết.
  5. Nếu kết quả là deny, dừng lại ngay lập tức và trả về quyết định đó.
  6. Nếu kết quả là instruct, tích lũy thông báo và tiếp tục.
  7. Nếu kết quả là allow, tiếp tục với chính sách tiếp theo.
Sau khi tất cả các chính sách chạy:
  • Nếu bất kỳ deny nào được trả về, phát hành phản hồi deny.
  • Nếu bất kỳ kết quả instruct nào được thu thập, phát hành một phản hồi instruct duy nhất với tất cả các thông báo được nối.
  • Ngoài ra, phát hành phản hồi allow (stdout trống, exit 0).

​
Builtin policies

src/hooks/builtin-policies.ts định nghĩa tất cả 39 chính sách tích hợp sẵn như các đối tượng BuiltinPolicyDefinition: 
interface BuiltinPolicyDefinition {
  name: string;
  description: string;
  fn: (ctx: PolicyContext) => PolicyResult;
  match: {
    events: HookEventType[];
    tools?: string[];
  };
  defaultEnabled: boolean;
  category: string;
  beta?: boolean;
  params?: PolicyParamsSchema;
}
Các chính sách chấp nhận params khai báo PolicyParamsSchema với các loại và giá trị mặc định cho mỗi tham số. Policy evaluator tiêm các giá trị đã được giải quyết vào ctx.params trước khi gọi fn. Các hàm chính sách đọc ctx.params mà không cần null-guarding vì các giá trị mặc định luôn được áp dụng trước. Pattern matching bên trong các chính sách sử dụng các token lệnh được phân tích (argv), không phải so khớp chuỗi thô. Điều này ngăn chặn bypass thông qua shell operator injection (ví dụ: một mẫu cho sudo systemctl status * không thể bị bypass bằng cách thêm ; rm -rf / vào lệnh).

​
Custom policies

src/hooks/custom-hooks-registry.ts thực hiện một registry được hỗ trợ bởi globalThis: 
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 tải tệp chính sách của người dùng:
  1. Đọc customPoliciesPath từ config; bỏ qua nếu không có.
  2. Giải quyết đến đường dẫn tuyệt đối; kiểm tra tệp tồn tại.
  3. Viết lại tất cả from "failproofai" imports đến đường dẫn dist thực tế để customPolicies giải quyết đến cùng một registry globalThis.
  4. Viết lại một cách đệ quy các import local chuyên cần để đảm bảo tương thích ESM.
  5. Ghi các tệp .mjs tạm thời và import() tệp mục nhập.
  6. Gọi getCustomHooks() để truy xuất các hook đã đăng ký.
  7. Dọn dẹp tất cả các tệp tạm thời trong một khối finally.
Nếu xảy ra bất kỳ lỗi nào (tệp không tìm thấy, lỗi cú pháp, lỗi import), lỗi sẽ được ghi vào ~/.failproofai/hook.log và loader sẽ trả về một mảng trống. Các chính sách tích hợp sẵn không bị ảnh hưởng. Các chính sách tùy chỉnh được đánh giá sau tất cả các chính sách tích hợp sẵn. Một chính sách tùy chỉnh deny vẫn ngắn mạch các chính sách tùy chỉnh tiếp theo (nhưng tất cả các builtins đã chạy ở thời điểm này).

​
Activity logging

Sau mỗi sự kiện hook, handler thêm một dòng JSONL vào ~/.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
}
Một dòng cho mỗi chính sách đưa ra quyết định không phải allow. Các quyết định Allow không được ghi vào nhật ký (để giữ tệp nhỏ).

​
Kiến trúc Dashboard

Dashboard là một ứng dụng Next.js 16 sử dụng App Router với React Server Components và 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)
Luồng dữ liệu:
  • Các thành phần trang gọi lib/projects.ts và lib/log-entries.ts để đọc dữ liệu dự án/phiên trực tiếp từ hệ thống tệp (không có lớp API để đọc).
  • Trang Policies sử dụng Server Actions cho tất cả các thay đổi (toggle, cập nhật params, install/remove).
  • Trình xem phiên phân tích định dạng transcript JSONL của Claude và hiển thị một dòng thời gian của các tin nhắn và lệnh gọi công cụ.
Các quyết định thiết kế chính:
  • Không có cơ sở dữ liệu - tất cả trạng thái liên tục nằm trong các tệp thuần (~/.failproofai/, ~/.claude/projects/).
  • Server Actions cho các thay đổi - không cần REST API cho các hoạt động CRUD.
  • React Server Components cho các trang đọc - tải ban đầu nhanh hơn, không có client bundle cho việc tìm nạp dữ liệu.
  • Các thành phần client chỉ khi cần tương tác (toggles chính sách, tìm kiếm hoạt động, trình xem nhật ký).

​
Bố cục tệp

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