155 lines
8.4 KiB
Markdown
155 lines
8.4 KiB
Markdown
# Hook と Interceptor の責務分離
|
||
|
||
## レビュー状態
|
||
|
||
初回レビュー実施済み。[hook-interceptor-separation.review.md](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 のサマリ型に変更:
|
||
|
||
```rust
|
||
// 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 管理は別チケット
|