Hare/yoi
1
1
Fork 0
Code Actions Packages Releases Activity

Interceptorの責務分離完了

Browse Source
This commit is contained in:
Keisuke Hirata 2026-04-18 17:27:22 +09:00
parent 84a8bd099b
commit b538c2f1ea
3 changed files with 0 additions and 227 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
TODO.md
View File

@ -4,7 +4,6 @@
- [ ] Compact の改善（要約品質 + 挙動詳細） → [tickets/compact-improvements.md](tickets/compact-improvements.md)
- [ ] Protocol の設計 → [tickets/protocol-design.md](tickets/protocol-design.md)
- [ ] パーミッション: パターンベースのツール実行制御 → [tickets/permission-extension-point.md](tickets/permission-extension-point.md)
- [ ] Hook と Interceptor の責務分離 → [tickets/hook-interceptor-separation.md](tickets/hook-interceptor-separation.md)
- [ ] Method::Notify: システム起点のコンテキスト注入 → [tickets/method-notify.md](tickets/method-notify.md)
- [ ] Pod オーケストレーション: LLM によるマルチエージェント分業 → [tickets/pod-orchestration.md](tickets/pod-orchestration.md)
- [ ] ネイティブ GUI クライアント MVP → [tickets/native-gui-mvp.md](tickets/native-gui-mvp.md)

154
tickets/hook-interceptor-separation.md
View File

@ -1,154 +0,0 @@
# 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 管理は別チケット

72
tickets/hook-interceptor-separation.review.md
View File

@ -1,72 +0,0 @@
# レビュー: Hook と Interceptor の責務分離
対象差分: `crates/pod/src/{hook,pod,lib,pod_interceptor}.rs`、削除: `compact_interceptor.rs` / `hook_interceptor.rs`（staged、未コミット）
## 要件達成状況
| 要件 | 状態 |
|---|---|
| Hook の Input が read-only サマリ型になる | ✅ `PromptSubmitInfo` / `PreRequestInfo` / `ToolCallSummary` / `ToolResultSummary` / `TurnEndInfo` / `AbortInfo` を新設。`Hook::call(&self, input: &E::Input)` で `&mut` が消えた |
| Hook から context / history の直接操作パスが型レベルで存在しない | ✅ `Vec<Item>` / `ToolCallInfo` / `ToolResultInfo` が Hook の Input から消え、サマリ型に置換 |
| Interceptor は context / history の直接操作が可能なまま | ✅ `PodInterceptor` が `Interceptor` を実装し `&mut Vec<Item>` / `&mut ToolCallInfo` 等を受け取る |
| Interceptor → Hook の実行順序（内部が先、公開が後） | ✅ `PodInterceptor` の各メソッドが: 内部ロジック（compaction check 等）→ サマリ構築 → Hook 呼び出し の順 |
| HookInterceptor ブリッジの削除 | ✅ `hook_interceptor.rs` deleted |
| CompactInterceptor の統合 | ✅ `compact_interceptor.rs` deleted。compaction check は `PodInterceptor::pre_llm_request` に統合 |
| 既存の compaction 動作が壊れない | ✅ `compact_state` を `PodInterceptor` に渡し、`exceeds_turn()` で Yield する同じロジック |
| 単体テストで Hook が context を操作できないことが検証される | ✅ テストの Hook が `&PreRequestInfo`（read-only）を受け取る形で書かれている。`&mut` パスは型レベルで不可能 |
## アーキテクチャ
### 良い点
**`PodInterceptor` が single composite interceptor として全責務を統合**:
- compaction check (内部) → サマリ構築 → Hook 呼び出しを1つの `pre_llm_request` 内で制御
- Worker 側は単一の `set_interceptor` で完結（`Vec<Box<dyn Interceptor>>` 不要）
- `compact_interceptor.rs` の decorator パターン（inner HookInterceptor をラップ）が消え、フラットな構造に
**Hook の `call` シグネチャが `&self, input: &E::Input` に**:
- `&mut E::Input` → `&E::Input` への変更で、Hook 実装者が context を書き換える経路が型レベルで消えた
- 将来スクリプトに公開するとき、`&T` だけ渡せば良い（sandbox の粒度が明確）
**サマリ型の設計**:
- `ToolCallSummary::arguments` が `serde_json::Value` clone — 構造的アクセスが可能で permission 判断に使える
- `ToolResultSummary::output` が `ToolOutput` clone — summary + content 両方にアクセス可能
- `PreRequestInfo` が item_count / estimated_tokens / turn_index / tool_calls_this_turn を集約 — compaction 判断に必要十分
- `TurnEndInfo::final_text_preview` が 512 byte 制限 + UTF-8 boundary — Pod orchestration で spawned Pod の結果要約に使える
**ターン追跡の統合**:
- `next_turn_index` / `tool_calls_this_turn` が `PodInterceptor` 内の `AtomicUsize` で管理
- `on_prompt_submit` でリセット、`pre_tool_call` でインクリメント
- Hook が受け取るサマリにこの情報が反映される
### テスト
4 ケース:
- `pre_llm_request_yields_and_skips_hooks_when_compact_threshold_exceeded` — 内部機構（compaction）が Hook より先に short-circuit することを検証
- `pre_llm_request_runs_hooks_when_under_threshold` — 通常時は Hook が走ることを検証
- `pre_llm_request_runs_hooks_when_no_compact_state` — compaction 無効時も Hook が走ることを検証
- `pre_llm_request_short_circuits_on_first_non_continue` — 複数 Hook の短絡評価を検証
特に 1 つ目が**設計の核心（Interceptor が先、Hook が後。内部が short-circuit したら Hook は走らない）**を lock-in している。
## 指摘事項
### 1. 🟢 `pod.rs` の `ensure_interceptor_installed` が少しすっきりした
旧: `CompactInterceptor::new(hook_interceptor, state)` で decorator をネスト → 新: `PodInterceptor::new(registry, compact_state)` でフラットに構築。`compact_state` の有無で分岐していた `set_interceptor` 呼び出しが1箇所に統合。
### 2. 🟢 `HookEventKind::Input` に `Send + Sync` バウンドが追加
```rust
type Input: Send + Sync;
```
`&E::Input` を async メソッドで受け取るために必要。正しい追加。
### 3. 🟢 `extract_message_text` / `preview` がユーティリティとして分離
`PodInterceptor` 内の private function として切り出し。`preview` は UTF-8 boundary を考慮した切断で、`truncate_content`（tool output truncation）と同じパターン。
## 結論
**無条件で受け入れ可**。チケットの要件を完全に達成。特に「型レベルで Hook から context 操作が不可能」という核心的な保証が `&E::Input` (not `&mut`) + サマリ型で実現されている。テストも設計意図を正確にカバー。