フックシステム

​

フックが存在する理由

​

フックが接続される場所

​

フックと命令のどちらを使うか

​

フックコントラクト

class ReadOnlyGuard(PreToolUseHook):
    name = "readonly_guard"
    priority = 5                          # lower runs earlier

    def should_trigger(self, ctx: HookContext) -> bool:
        return ctx.tool_name.startswith("sql_")

    async def execute(self, ctx: HookContext) -> HookResult:
        if org_is_readonly(ctx.metadata["org_id"]):
            return HookResult(
                allow=False,
                error="Org is in read-only mode — write blocked.",
                side_effects=["readonly_guard: blocked sql write"],
            )
        return HookResult()               # default: allow=True, no mutation

• allow: bool = True — ツール呼び出しが進行するかどうか（PostToolUse / SessionStart では無視されます）
• error: str | None — 人間が読める理由で、ブロックされた場合は観測値として LLM に表示されます
• modified_args: dict | None — 設定されている場合、実行前にツール引数を置き換えます
• modified_result: Any | None — 設定されている場合（PostToolUse）、LLM に返される前に観測値を置き換えます
• side_effects: list[str] — フックが実行した内容の監査証跡で、エージェントのトレースにマージされます

​

ケーススタディ: FeishuGateHook

• ツール呼び出しは本当に一時停止します。 エージェントの SSE ストリームは「oa__purchase_pay を呼び出します」と観察の間で一時停止します。ユーザーはエージェントが待機しているのを見ます。これは内部で起きていることと一致します。
• 承認はプロセス再起動後も保持されます。 保留中の行はデータベースにあり、メモリにはありません。カードが未処理の状態でバックエンドが再起動した場合、次のポーリングは中断したところから再開します。
• 決定は監査されます。 ConfirmationRequest は payload、responded_at、responded_by_open_id、および最終ステータスを保持します。誰が何をいつ承認したかの監査可能な記録です。
• 決定ループに LLM はありません。 モデルはツール呼び出しを生成します。人間は判定を生成します。フックは決定論的なブリッジです。

​

候補となるフック（予定なし）

​

Hooks vs. Channels

​

現状（v0.8.4）

• ✅ HookRegistry、HookContext、HookResult のプリミティブを ReAct と DAG の両方に組み込み済み
• ✅ PreToolUseHook / PostToolUseHook / SessionStartHook の抽象基底クラス
• ✅ FeishuGateHook — ConfirmationRequest テーブル、ポーリングループ、タイムアウト／期限切れ処理、コールバック駆動の状態更新を含めて実装完了
• ✅ card.action.trigger をデコードし、保留中の行を更新する Feishu チャネルコールバックエンドポイント
• ✅ エージェントレベルのフック宣言：agent.model_config_json.hooks.class_hooks により、すべての ReAct/DAG セッションでインスタンス化された HookRegistry を解決
• ✅ すべての実行経路でフックが実行されます：メインチャット経路（Portal、API、DAG）、委譲されたサブエージェント（CallAgentTool）、Workflow の AGENT ノード。Eval Center では意図的にフックをバイパスします（自動評価が人間の承認待ちでブロックされないようにするため）。 委譲先のエージェントは呼び出し元のレジストリを引き継がず、自身の model_config_json から独自のレジストリを構築します。確認ゲートはすべてのエージェントに自動でアタッチされるため、再構築では継承時より多くのフックが含まれます。委譲先には確認ゲートに加えて、委譲先自身が宣言したフックが適用され、確認ゲートは呼び出し元ではなく委譲先の require_confirmation_for_all を参照します。どちらの経路もフェイルクローズで動作します。フックを構築できないエージェントは実行されません。
• ❌ AuditLogHook、ReadOnlyGuard、ResultTruncateHook、ConnectorRateLimitHook（計画なし）
• ❌ ユーザー定義の YAML フック宣言（計画なし）