アーキテクチャ

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

概要

failproofai には独立した 2 つのサブシステムがあります。

フックハンドラー — エージェントのすべてのツール呼び出しに対して Claude Code が呼び出す高速な CLI サブプロセスです。ポリシーを評価して判定結果を返します。
エージェントモニター（ダッシュボード） — エージェントセッションの監視とポリシー管理のための 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 をサブプロセスとして起動し、JSON ペイロードを stdin に渡します。

ペイロードの形式

{
  "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 を返した場合、各メッセージは改行で結合されて 1 つの 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 がポリシーを順番に実行します。各ポリシーに対して:

ポリシーの params スキーマを参照します（存在する場合）。
マージ済み設定から policyParams[policy.name] を読み取ります。
ユーザー指定の値をスキーマのデフォルト値にマージして ctx.params を生成します。
解決済みコンテキストで policy.fn(ctx) を呼び出します。
結果が deny の場合、直ちに処理を停止してその判定を返します。
結果が instruct の場合、メッセージを蓄積して次のポリシーに進みます。
結果が allow の場合、次のポリシーに進みます。

すべてのポリシーの実行後:

deny が返された場合、deny レスポンスを出力します。
instruct が収集された場合、すべてのメッセージを結合した単一の instruct レスポンスを出力します。
それ以外の場合、allow レスポンスを出力します（stdout 空、終了コード 0）。

組み込みポリシー

src/hooks/builtin-policies.ts が 39 個の組み込みポリシーをすべて BuiltinPolicyDefinition オブジェクトとして定義しています。

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 がユーザーのポリシーファイルを読み込みます。

設定から customPoliciesPath を読み取り、未設定の場合はスキップします。
絶対パスに解決し、ファイルの存在を確認します。
すべての from "failproofai" インポートを実際の dist パスに書き換え、customPolicies が同じ globalThis レジストリに解決されるようにします。
ESM 互換性を確保するため、推移的なローカルインポートも再帰的に書き換えます。
一時的な .mjs ファイルを生成し、エントリファイルを import() します。
getCustomHooks() を呼び出して登録済みフックを取得します。
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 行記録されます。ファイルサイズを抑えるため、allow の判定はログに記録されません。

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

ダッシュボードは、App Router・React Server Components・Server Actions を使用した 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   ← CLI セッションごとのエクスポート（JSONL または JSON）

データフロー:

ページコンポーネントは lib/projects.ts と lib/log-entries.ts を呼び出し、ファイルシステムから直接プロジェクト/セッションデータを読み取ります（読み取りに API レイヤーは不要）。
Policies ページはすべての変更操作（切り替え、パラメーター更新、インストール/削除）に Server Actions を使用します。
セッションビューアーは Claude の JSONL トランスクリプト形式をパースし、メッセージとツール呼び出しのタイムラインを表示します。

主な設計上の判断:

データベースなし — すべての永続状態はプレーンファイル（~/.failproofai/、~/.claude/projects/）に保存されます。
変更操作には Server Actions を使用 — CRUD 操作に REST API は不要です。
読み取りページには React Server Components を使用 — 初期ロードが高速で、データフェッチのクライアントバンドルが不要です。
クライアントコンポーネントはインタラクティブな操作が必要な箇所のみ使用（ポリシーの切り替え、アクティビティ検索、ログビューアー）。

ファイル構成

failproofai/
├── bin/
│   └── failproofai.mjs           # CLI ルーター（hook / dashboard / install など）
├── src/hooks/
│   ├── handler.ts                # フックイベントパイプライン
│   ├── builtin-policies.ts       # 39 個のポリシー定義
│   ├── 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 ダッシュボード（ページ + Server Actions）
├── lib/                          # 共有ユーティリティ
│   ├── projects.ts               # ファイルシステムから Claude プロジェクトを列挙
│   ├── log-entries.ts            # Claude トランスクリプト JSONL 形式のパース
│   ├── paths.ts                  # システムパスの解決
│   └── ...
├── components/                   # 共有 React UI コンポーネント
├── contexts/                     # React コンテキストプロバイダー（テーマ、自動更新、テレメトリー）
├── examples/                     # カスタムフックのサンプルファイル
└── __tests__/                    # ユニットテストおよび E2E テスト

はじめに

基本概念

CLI

ツール

上級

例

アーキテクチャ

概要

フックハンドラー

Claude Code との統合

ペイロードの形式

レスポンスの形式

処理パイプライン

設定の読み込み

ポリシー評価

組み込みポリシー

カスタムポリシー

アクティビティログ

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

ファイル構成

​概要

​フックハンドラー

​Claude Code との統合

​ペイロードの形式

​レスポンスの形式

​処理パイプライン

​設定の読み込み

​ポリシー評価

​組み込みポリシー

​カスタムポリシー

​アクティビティログ

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

​ファイル構成

概要

フックハンドラー

Claude Code との統合

ペイロードの形式

レスポンスの形式

処理パイプライン

設定の読み込み

ポリシー評価

組み込みポリシー

カスタムポリシー

アクティビティログ

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

ファイル構成