yoi/tickets/hook-interceptor-separation.md

Hook と Interceptor の責務分離

レビュー状態

初回レビュー実施済み。hook-interceptor-separation.review.md を参照。 要件全項目達成。無条件で受け入れ可。

背景

Worker の実行ループへの介入手段として Interceptor trait (llm-worker crate) と Hook trait (pod crate) が存在するが、現状では Hook が Interceptor と同じ権限を持っており、責務の分離が成立していない。

現状の構造

Worker
  └── Interceptor trait (llm-worker)
        ↑ implements
  HookInterceptor (pod)
        └── HookRegistry
              └── Vec<Box<dyn Hook<E>>>

• Interceptor は &mut Vec<Item> (context)、&mut ToolResultInfo (tool result) 等を直接受け取る。context の書き換え、history への干渉、tool result の改変が自由にできる
• HookInterceptor は Interceptor を実装し、各メソッドで Hook を順に呼ぶブリッジ
• Hook<E> の call(&self, input: &mut E::Input) が受け取る E::Input は Vec<Item> や ToolCallInfo そのもの
• 結果として Hook からも Interceptor と同じ全権限で context を操作できてしまっている

問題

• Hook を将来スクリプト言語（Rhai, Wasm 等）に公開したとき、ユーザースクリプトが context を自由に書き換えられてしまう
• 内部機構（compaction トリガー、notification 注入、tool output truncation）と外部公開 hook が同じ権限レベルで動いており、何が安全に公開できるかが型で表現されていない
• Interceptor のドキュメントには「upper layers (e.g. Pod) implement」とあるが、Pod が直接実装するのではなく Hook 経由で間接実装しているため、設計意図と実態がずれている

ゴール

Interceptor と Hook の責務を明確に分離し、型レベルで権限の境界を表現する。

方針

Interceptor（内部実装用）

• llm-worker crate に留まる。Pod / Worker の内部機構が直接実装する
• context / history の直接操作が可能（&mut Vec<Item> 等を受け取る）
• 外部に公開しない。pub(crate) または Pod crate 内でのみ利用
• 用途:
  • compaction トリガー（PreLlmRequest で context サイズを見て Yield を返す）
  • notification 注入（PreLlmRequest で pending notifications を context に flush）
  • tool output truncation（PostToolCall で content を書き換え）
  • 将来の内部機構

Hook（公開 API 用）

• Pod crate で定義。将来スクリプト言語やプラグインに公開する前提
• イベントの観測と制御フロー判断（continue / skip / abort / pause）のみ
• context の直接操作はできない。受け取るのは:
  • 読み取り専用の情報（ツール名、引数の概要、ターン番号、etc.）
  • 制御フロー判断の返却値（continue / skip / abort）
• 安全に sandbox 可能

実行順序

同じ決定点（例: pre_tool_call）で Interceptor と Hook の両方が登録されている場合:

[Interceptor: 内部機構の処理（context 操作等）]
  ↓
[Hook: 外部の判断（observe + continue/skip/abort）]
  ↓
Worker が次のステップに進む

Interceptor が先に走って context を整え、Hook はその結果を観測する。Hook の判断が Interceptor の操作を覆すことはない（abort 等で中断は可能）。

必要な変更

Hook の Input 型を制限する

現状の Hook<PreLlmRequest> の Input は Vec<Item> だが、これを read-only のサマリ型に変更:

// Before: Hook が context を直接操作できる
impl HookEventKind for PreLlmRequest {
    type Input = Vec<Item>;       // &mut Vec<Item> が渡される
    type Output = PreRequestAction;
}

// After: Hook は read-only の情報だけ受け取る
impl HookEventKind for PreLlmRequest {
    type Input = PreRequestInfo;  // context のサマリ（item 数、token 推定等）
    type Output = PreRequestAction;
}

同様に各イベントの Input を「観測に必要な最小限の read-only 情報」に絞る。

ToolCallInfo / ToolResultInfo の分離

現状は Interceptor と Hook で同じ ToolCallInfo を共有している。分離:

• Interceptor 用: ToolCallInfo { call: &mut ToolCall, meta: ToolMeta, tool: Arc<dyn Tool> } — call の書き換え可能
• Hook 用: ToolCallSummary { name: String, arguments_preview: String } — 読み取りのみ、tool instance へのアクセスなし

HookInterceptor の解体

現在の HookInterceptor（Hook を Interceptor にブリッジする層）は不要になる。代わりに:

• Worker が Interceptor を呼ぶ（内部機構の処理）
• Worker が Hook を呼ぶ（外部判断の問い合わせ）
• これらは Worker の実行ループ内で別々のステップとして呼ばれる

Worker が Hook を直接知るか、Pod 層が Worker に Hook callback を注入するかは設計時に判断。

llm-worker 側の変更

• Interceptor trait はそのまま（内部実装用として健全）
• Worker の実行ループに「Hook 呼び出しポイント」を追加（Interceptor とは別系統）
• Hook の呼び出しインターフェースは Fn ベースのコールバックか、新しい trait か

pod 側の変更

• Hook<E> の E::Input を read-only サマリ型に置き換え
• HookInterceptor を削除
• 内部機構（compaction 等）は Interceptor を直接実装する形に移行
• HookRegistry は外部公開 API として残り、将来のスクリプト公開の基盤になる

設計で決めること

• Hook の Input 型の具体設計: 各イベントで何を read-only として渡すか（ツール名? 引数の先頭 N 文字? token 数?）
• Worker が Hook をどう呼ぶか: Interceptor と同じ trait 方式か、コールバック登録方式か、別の trait か
• Interceptor の複数登録: 現状 Worker は1つの Interceptor しか持てない。内部機構が複数（compaction + notification + truncation）になると、Chain of Responsibility 的に複数の Interceptor を合成する仕組みが要る
• Hook の実行順序保証: 複数の Hook が登録されている場合の評価順序と short-circuit 規則（現行と同じ「登録順 + 最初の non-Continue で打ち切り」を維持するか）
• 既存の Pod 層 hook ユーザーの移行: compact_interceptor 等が現在 HookInterceptor 経由で動いている場合の移行パス

完了条件

• Interceptor は context / history の直接操作が可能な内部 API として存続し、compaction / notification 注入 / tool output truncation 等が Interceptor を直接利用する
• Hook は read-only のサマリ情報のみを受け取り、制御フロー判断（continue / skip / abort / pause）を返す公開 API になる
• Hook から &mut Vec<Item> や &mut ToolCallInfo 等の context 直接操作パスが型レベルで存在しない
• HookInterceptor ブリッジは削除される
• Worker の実行ループ内で Interceptor → Hook の順序で呼ばれ、それぞれの責務が分離されている
• 既存の Pod 層 hook（compaction トリガー等）が Interceptor 直接実装に移行し、動作が壊れていない
• 単体テストで Hook が context を操作できないことが検証される

他チケットとの関係

• tickets/method-notify.md: notification の context 注入は Interceptor の責務。Hook ではない
• tickets/pod-orchestration.md: spawned Pod のツール実行制御（permission）は Hook として公開しうる
• tickets/permission-extension-point.md: パーミッション制御は Hook の代表的ユースケース。ツール実行の approve/deny を外部から制御する
• tickets/bash-tool.md: Bash ツールの Permission 層は Hook (pre_tool_call) で実装される想定

範囲外

• スクリプト言語バインディングの実装: Hook を Rhai / Wasm に公開する仕組み自体は別チケット。本チケットは公開可能な型境界を作るところまで
• Hook の動的ロード / アンロード: 起動時に登録して freeze する現行モデルを維持。動的な Hook 管理は別チケット