メインコンテンツへスキップ
このドキュメントでは、failproofai の内部動作を説明します。フックシステムがエージェントのツール呼び出しをどのようにインターセプトするか、設定がどのように読み込まれてマージされるか、ポリシーがどのように評価されるか、そしてダッシュボードがエージェントの活動をどのように監視するかについて解説します。

​
概要

failproofai には2つの独立したサブシステムがあります。
  1. フックハンドラー - Claude Code がエージェントのすべてのツール呼び出し時に起動する高速な CLI サブプロセス。ポリシーを評価し、決定を返します。
  2. エージェントモニター（ダッシュボード） - エージェントセッションの監視とポリシー管理を行う Next.js ウェブアプリケーション。
どちらのサブシステムも ~/.failproofai/ およびプロジェクトの .failproofai/ ディレクトリにある設定ファイルを共有しますが、それぞれ独立したプロセスとして動作し、ファイルシステムを通じてのみ通信します。

​
フックハンドラー

​
Claude Code との統合

failproofai policies --install を実行すると、以下のようなエントリが ~/.claude/settings.json に書き込まれます。 
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "failproofai --hook PreToolUse"
          }
        ]
      }
    ],
    "PostToolUse": [ ... ]
  }
}
Claude Code は各ツール呼び出しの前に failproofai --hook PreToolUse をサブプロセスとして起動し、stdin に JSON ペイロードを渡します。

​
ペイロードの形式

{
  "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 イベントの場合、ペイロードにはツールの出力を含む tool_result も含まれます。 ハンドラーは stdin の上限を 1 MB に制限しています。これを超えるペイロードは破棄され、すべてのポリシーは暗黙的に allow となります。

​
レスポンスの形式

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 イベントの instruct:
  • 終了コード: 2
  • 理由は stdout ではなく stderr に書き込まれます
Allow:
  • 終了コード: 0
  • stdout は空
メッセージ付き Allow: allow(message) を使用することで、操作が許可されている場合でもポリシーが Claude に情報コンテキストを返せるようになりました。フックハンドラーは以下の JSON を stdout に書き込みます（設定ファイルではありません。上記の deny や instruct のレスポンスと同様に、Claude Code へのハンドラープロセスのレスポンスです）。 
// フックハンドラープロセスによって stdout に書き込まれます
{
  "hookSpecificOutput": {
    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
  }
}
  • 終了コード: 0（操作は許可されます）
  • 複数のポリシーがメッセージ付きで allow を返した場合、それらのメッセージは改行で結合されて単一の additionalContext 文字列になります
  • どのポリシーもメッセージを提供しない場合、stdout は空（従来と同じ）

​
処理パイプライン

src/hooks/handler.ts が完全なパイプラインを実装しています。 
stdin JSON
  → ペイロードのパース（最大 1 MB）
  → セッションメタデータの抽出（session_id、cwd、tool_name、tool_input など）
  → readMergedHooksConfig(cwd)    ← プロジェクト + ローカル + グローバル設定をマージ
  → 解決済みパラメーターで有効なビルトインポリシーを登録
  → customPoliciesPath からカスタムポリシーを読み込み（設定されている場合）
  → カスタムポリシーをポリシーレジストリに登録
  → すべてのポリシーを評価（ビルトインが先、次にカスタム）
      → 最初の deny で短絡
      → instruct の決定を蓄積
      → allow メッセージを蓄積
  → JSON 決定を stdout に書き込み
  → イベントを ~/.failproofai/hook-activity.jsonl に永続化
  → 終了
プロセス全体は、LLM 呼び出しなしで典型的なペイロードに対して 100ms 未満で実行されます。

​
設定の読み込み

src/hooks/hooks-config.ts が3スコープの設定読み込みを実装しています。 
[1] {cwd}/.failproofai/policies-config.json        ← プロジェクト（最高優先度）
[2] {cwd}/.failproofai/policies-config.local.json  ← ローカル
[3] ~/.failproofai/policies-config.json             ← グローバル（最低優先度）
マージロジック:
  • enabledPolicies - 3つのファイル全体で重複排除された和集合
  • policyParams - ポリシーごとのキー。最初に定義されたファイルが完全に優先
  • customPoliciesPath - 最初に定義されたファイルが優先
  • llm - 最初に定義されたファイルが優先
ウェブダッシュボードはプロジェクトの cwd で起動されないため、読み取りと書き込みには readHooksConfig()（グローバルのみ）を使用します。

​
ポリシー評価

src/hooks/policy-evaluator.ts がポリシーを順番に実行します。 各ポリシーについて:
  1. ポリシーの params スキーマを検索します（存在する場合）。
  2. マージされた設定から policyParams[policy.name] を読み取ります。
  3. スキーマのデフォルト値にユーザー提供の値をマージして ctx.params を生成します。
  4. 解決されたコンテキストと共に policy.fn(ctx) を呼び出します。
  5. 結果が deny の場合、即座に停止してその決定を返します。
  6. 結果が instruct の場合、メッセージを蓄積して続行します。
  7. 結果が allow の場合、次のポリシーに進みます。
すべてのポリシーの実行後:
  • deny が返された場合、deny レスポンスを出力します。
  • instruct の結果が収集された場合、すべてのメッセージを結合した単一の instruct レスポンスを出力します。
  • それ以外の場合、allow レスポンスを出力します（stdout 空、終了コード 0）。

​
ビルトインポリシー

src/hooks/builtin-policies.ts が BuiltinPolicyDefinition オブジェクトとして26個のビルトインポリシーをすべて定義しています。 
interface BuiltinPolicyDefinition {
  name: string;
  description: string;
  fn: (ctx: PolicyContext) => PolicyResult;
  match: {
    events: HookEventType[];
    tools?: string[];
  };
  defaultEnabled: boolean;
  category: string;
  beta?: boolean;
  params?: PolicyParamsSchema;
}
params を受け付けるポリシーは、各パラメーターの型とデフォルト値を含む PolicyParamsSchema を宣言します。ポリシーエバリュエーターは fn を呼び出す前に解決済みの値を ctx.params に注入します。デフォルト値は常に最初に適用されるため、ポリシー関数は null チェックなしで ctx.params を読み取ります。 ポリシー内のパターンマッチングは生の文字列マッチングではなく、パース済みのコマンドトークン（argv）を使用します。これにより、シェル演算子の挿入によるバイパスを防ぎます（例: sudo systemctl status * のパターンに ; rm -rf / を追加してもバイパスできません）。

​
カスタムポリシー

src/hooks/custom-hooks-registry.ts が globalThis バックのレジストリを実装しています。 
const REGISTRY_KEY = "__failproofai_custom_hooks__";

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

export function getCustomHooks(): CustomHook[] { ... }
export function clearCustomHooks(): void { ... }  // テストで使用
src/hooks/custom-hooks-loader.ts がユーザーのポリシーファイルを読み込みます。
  1. 設定から customPoliciesPath を読み取り、存在しない場合はスキップします。
  2. 絶対パスに解決し、ファイルの存在を確認します。
  3. customPolicies が同じ globalThis レジストリに解決されるよう、すべての from "failproofai" インポートを実際の dist パスに書き換えます。
  4. ESM 互換性を確保するため、推移的なローカルインポートを再帰的に書き換えます。
  5. 一時的な .mjs ファイルを書き込み、エントリファイルを import() します。
  6. getCustomHooks() を呼び出して登録済みフックを取得します。
  7. finally ブロックですべての一時ファイルを削除します。
エラー（ファイルが見つからない、構文エラー、インポートの失敗など）が発生した場合、エラーは ~/.failproofai/hook.log に記録され、ローダーは空の配列を返します。ビルトインポリシーには影響しません。 カスタムポリシーはすべてのビルトインポリシーの後に評価されます。カスタムポリシーの deny はそれ以降のカスタムポリシーの実行を短絡させますが（その時点ではすべてのビルトインはすでに実行済みです）。

​
アクティビティログ

各フックイベントの後、ハンドラーは ~/.failproofai/hook-activity.jsonl に 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
}
allow 以外の決定を下したポリシー1件につき1行。allow の決定はログに記録されません（ファイルサイズを小さく保つため）。

​
ダッシュボードのアーキテクチャ

ダッシュボードは、React Server Components と Server Actions を使用した App Router 採用の Next.js 16 アプリケーションです。 
app/
  layout.tsx                  ← ルートレイアウト（テーマ、テレメトリー、ナビゲーション）
  projects/page.tsx           ← サーバーコンポーネント: すべての Claude プロジェクトを一覧表示
  project/[name]/page.tsx     ← サーバーコンポーネント: プロジェクト内のセッションを一覧表示
  project/[name]/session/
    [sessionId]/page.tsx      ← サーバーコンポーネント: セッションビューアーを表示
  policies/page.tsx           ← クライアントコンポーネント: ポリシー管理 + アクティビティログ
  actions/
    get-hooks-config.ts       ← 設定とポリシーリストの読み取り
    update-hooks-config.ts    ← ポリシーのオン/オフ切り替え
    update-policy-params.ts   ← ポリシーパラメーターの更新
    get-hook-activity.ts      ← アクティビティログのページング/検索
    install-hooks-web.ts      ← ブラウザからのフックのインストール/削除
  api/
    download/[project]/[session]/route.ts   ← セッションを ZIP/JSONL としてエクスポート
データフロー:
  • ページコンポーネントは lib/projects.ts と lib/log-entries.ts を呼び出し、ファイルシステムからプロジェクト/セッションデータを直接読み取ります（読み取りに API レイヤーは不要）。
  • ポリシーページはすべての変更操作（切り替え、パラメーター更新、インストール/削除）に Server Actions を使用します。
  • セッションビューアーは Claude の JSONL トランスクリプト形式をパースし、メッセージとツール呼び出しのタイムラインをレンダリングします。
主要な設計上の決定事項:
  • データベースなし - すべての永続状態はプレーンファイル（~/.failproofai/、~/.claude/projects/）に保存されます。
  • 変更操作には Server Actions を使用 - CRUD 操作に REST API は不要。
  • 読み取りページには React Server Components を使用 - 初期ロードが高速で、データフェッチのクライアントバンドルが不要。
  • クライアントコンポーネントはインタラクティブ性が必要な場合のみ使用（ポリシーの切り替え、アクティビティ検索、ログビューアー）。

​
ファイル構成

failproofai/
├── bin/
│   └── failproofai.mjs           # CLI ルーター（フック / ダッシュボード / インストール など）
├── src/hooks/
│   ├── handler.ts                # フックイベントパイプライン
│   ├── builtin-policies.ts       # 26のポリシー定義
│   ├── policy-evaluator.ts       # ポリシー実行エンジン
│   ├── policy-registry.ts        # ポリシーの登録と検索
│   ├── policy-types.ts           # TypeScript インターフェース
│   ├── hooks-config.ts           # マルチスコープ設定読み込み
│   ├── custom-hooks-registry.ts  # globalThis バックのフックレジストリ
│   ├── custom-hooks-loader.ts    # ユーザー JS フック用の ESM ローダー
│   ├── manager.ts                # インストール / 削除 / 一覧操作
│   ├── install-prompt.ts         # インタラクティブなポリシー選択プロンプト
│   ├── hook-logger.ts            # hook.log へのロギング
│   ├── hook-activity-store.ts    # hook-activity.jsonl へのアクティビティの永続化
│   └── llm-client.ts             # LLM API クライアント（AI 搭載ポリシー用）
├── app/                          # Next.js ダッシュボード（ページ + サーバーアクション）
├── lib/                          # 共有ユーティリティ
│   ├── projects.ts               # ファイルシステムから Claude プロジェクトを列挙
│   ├── log-entries.ts            # Claude トランスクリプトの JSONL 形式をパース
│   ├── paths.ts                  # システムパスの解決
│   └── ...
├── components/                   # 共有 React UI コンポーネント
├── contexts/                     # React コンテキストプロバイダー（テーマ、自動更新、テレメトリー）
├── examples/                     # カスタムフックファイルの例
└── __tests__/                    # ユニットテストと E2E テスト