Architecture

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 giám sát hoạt động của agent.

Tổng quan

failproofai có hai hệ thống con độc lập:

Hook handler - Một quy trình CLI nhanh mà Claude Code gọi trên mỗi lệnh gọi công cụ của agent. Đánh giá các chính sách và trả về một quyết định.
Agent Monitor (Dashboard) - Một ứng dụng web Next.js để giám sát 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 đều 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 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ó sẽ 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 quy trình con trước mỗi lệnh gọi công cụ, truyền một payload JSON vào 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 đầu ra của công cụ. Handler áp dụng giới hạn stdin 1 MB. Các payload vượt quá giới hạn này 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

Từ chối (PreToolUse):

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

Từ chối (PostToolUse):

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

Hướng dẫn (bất kỳ sự kiện nào trừ Stop):

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

Hướng dẫn sự kiện Stop:

Mã thoát: 2
Lý do được ghi vào stderr (không phải stdout)

Cho phép:

Mã thoát: 0
stdout rỗng

Cho phép với tin nhắn: allow(message) cho phép một chính sách gửi bối cảnh thông tin quay 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 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 từ chối và hướng dẫn ở trên):

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

Mã thoát: 0 (hoạt động được phép)
Khi nhiều chính sách trả về allow với một tin nhắn, các tin nhắn của chúng được nối với các 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 tin nhắn, stdout trống (giống như trước đây)

Đường ống xử lý

src/hooks/handler.ts triển khai đầy đủ đường ống:

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ộ quá trình chạy dưới 100ms cho các payload điển hình không có lệnh gọi LLM.

Tải cấu hình

src/hooks/hooks-config.ts triển khai tải cấu hình 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 - liên kết không trùng lặp trên cả ba tệp
policyParams - mỗi khóa chính sách, tệp đầu tiên xác định nó sẽ thắng hoàn toàn
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() (toàn cầu duy nhất) để đọc và ghi, vì nó không được gọi với cwd của dự án.

Đánh giá chính sách

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:

Tra cứu lược đồ params của chính sách (nếu nó có).
Đọc policyParams[policy.name] từ cấu hình đã hợp nhất.
Hợp nhất các giá trị do người dùng cung cấp trên các giá trị mặc định của lược đồ để tạo ra ctx.params.
Gọi policy.fn(ctx) với bối cảnh đã được giải quyết.
Nếu kết quả là deny, dừng ngay lập tức và trả về quyết định đó.
Nếu kết quả là instruct, tích lũy thông báo và tiếp tục.
Nếu kết quả là allow, tiếp tục đến 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 ra phản hồi từ chối.
Nếu có bất kỳ phản hồi instruct nào được thu thập, phát ra một phản hồi hướng dẫn duy nhất với tất cả các thông báo được nối lại.
Nếu không, phát ra phản hồi cho phép (stdout trống, thoát 0).

Chính sách tích hợp sẵn

src/hooks/builtin-policies.ts định nghĩa tất cả 39 chính sách tích hợp sẵn dưới dạng 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 một PolicyParamsSchema với các kiểu và giá trị mặc định cho mỗi tham số. Người đánh giá chính sách 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 bảo vệ null vì các giá trị mặc định luôn được áp dụng trước. So khớp mẫu bên trong các chính sách sử dụng các token lệnh được phân tích cú pháp (argv), không phải so khớp chuỗi thô. Điều này ngăn chặn việc vượt qua thông qua tiêm toán tử shell (ví dụ: một mẫu cho sudo systemctl status * không thể bị vượt qua bằng cách nối thêm ; rm -rf / vào lệnh).

Chính sách tùy chỉnh

src/hooks/custom-hooks-registry.ts triển khai một sổ đăng ký đượ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:

Đọc customPoliciesPath từ cấu hình; bỏ qua nếu không có.
Giải quyết đến đường dẫn tuyệt đối; kiểm tra tệp tồn tại.
Viết lại tất cả các mục nhập from "failproofai" thành đường dẫn dist thực tế để customPolicies phân giải thành cùng một sổ đăng ký globalThis.
Viết lại một cách đệ quy các mục nhập cục bộ chuyên qua để đảm bảo khả năng tương thích ESM.
Ghi các tệp .mjs tạm thời và import() tệp entry.
Gọi getCustomHooks() để lấy các hook đã đăng ký.
Dọn sạch tất cả các tệp tạm thời trong khối finally.

Trong trường hợp có lỗi (tệp không tìm thấy, lỗi cú pháp, lỗi nhập), lỗi được ghi vào ~/.failproofai/hook.log và loader 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 làm ngắn mạch các chính sách tùy chỉnh tiếp theo (nhưng tất cả các chính sách tích hợp sẵn đã chạy tại thời điểm đó).

Ghi nhật ký hoạt động

Sau mỗi sự kiện hook, handler nối 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 cho phép. Các quyết định cho phép không được ghi 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 làm việc trực tiếp từ hệ thống tệp (không có lớp API cho các lần đọc).
Trang Policies sử dụng Server Actions cho tất cả các thay đổi (bật/tắt, cập nhật tham số, cài đặt/xóa).
Trình xem phiên làm việc phân tích định dạng bảng điểm JSONL của Claude và hiển thị dòng thời gian của các thông báo 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 là trong các tệp thô (~/.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ó gói máy khách cho tìm nạp dữ liệu.
Các thành phần máy khách chỉ khi cần tương tác (bật/tắt 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

Bắt đầu

Khái niệm cốt lõi

CLI

Công cụ

Nâng cao

Ví dụ

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

Tổng quan

Hook handler

Tích hợp với Claude Code

Định dạng payload

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

Đường ống xử lý

Tải cấu hình

Đánh giá chính sách

Chính sách tích hợp sẵn

Chính sách tùy chỉnh

Ghi nhật ký hoạt động

Kiến trúc dashboard

Bố cục tệp

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

​Tổng quan

​Hook handler

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

​Định dạng payload

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

​Đường ống xử lý

​Tải cấu hình

​Đánh giá chính sách

​Chính sách tích hợp sẵn

​Chính sách tùy chỉnh

​Ghi nhật ký hoạt động

​Kiến trúc dashboard

​Bố cục tệp

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

Tổng quan

Hook handler

Tích hợp với Claude Code

Định dạng payload

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

Đường ống xử lý

Tải cấu hình

Đánh giá chính sách

Chính sách tích hợp sẵn

Chính sách tùy chỉnh

Ghi nhật ký hoạt động

Kiến trúc dashboard

Bố cục tệp