フックシステム

​

フックが存在する理由

​

フックが接続される場所

​

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

​

フックコントラクト

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 はありません。 モデルはツール呼び出しを生成します。人間は判定を生成します。フックは決定論的なブリッジです。

​

計画中のフック (v0.9)

​

Hooks vs. Channels

​

Current state (v0.8.4)

• ✅ HookRegistry、HookContext、HookResult プリミティブが ReAct と DAG の両方に統合
• ✅ PreToolUseHook / PostToolUseHook / SessionStartHook 抽象基底クラス
• ✅ FeishuGateHook — 完全実装。ConfirmationRequest テーブル、ポーリングループ、タイムアウト/有効期限、コールバック駆動の状態遷移を含む
• ✅ Feishu チャネルコールバックエンドポイント。card.action.trigger をデコードして保留中の行を更新
• ✅ エージェントレベルのフック宣言：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 ではなく委譲先の require_confirmation_for_all を解決する。両方のサーフェスは安全側で失敗：フックを構築できないエージェントは実行されない。
• ❌ AuditLogHook、ReadOnlyGuard、ResultTruncateHook、ConnectorRateLimitHook（v0.9）
• ❌ ユーザー定義 YAML フック宣言（v0.9）