OMP Hook 拡張の概念：意思決定ポイントのヒント、ハードブロック、ステータス橋渡し

このページは、Hook をどこに置き、何を変え、どう動作を証明するかを答える。要点はツール呼び出し直前の意思決定ポイントである。sendMessage は低リスクなヒントに適し、{ block, reason } が拒否チャネルであり、ctx.ui.setStatus は状態を見える UI へ公開するだけで、提案をセキュリティ強制へ変えるものではない。

コアメカニズム

1. イベント全集、判断点、出力チャネル

flowchart LR
  A[tool_call イベント] --> B[toolName/input を読む]
  B --> C{ヒントか拒否か?}
  C -- ヒント --> D[pi.sendMessage<br/>custom message]
  D --> E[return void<br/>呼び出し継続]
  C -- 明示的拒否 --> F[return {block, reason}]
  F --> G[呼び出し拒否、呼び出し元が再試行]
  H[ライフサイクル/ツールイベント] --> I[ctx.ui.setStatus]
  I --> J[Hook 状態 map] --> K[ステータス行/任意 segment]

固定した OMP 17.2.15 の HookAPI.on() が明示するイベントは：

• 会話とツリー：session_start, session_before_switch, session_switch, session_before_branch, session_branch, session_before_compact, session.compacting, session_compact, session_shutdown, session_before_tree, session_tree。
• 文脈と Agent ターン：context, before_agent_start, agent_start, agent_end, turn_start, turn_end。
• 自動回復と通知：auto_compaction_start, auto_compaction_end, auto_retry_start, auto_retry_end, ttsr_triggered, todo_reminder。
• ツール境界：tool_call, tool_result。tool_call は toolName、toolCallId、input を持ち、handler は阻止結果を返せる。

これは v17.2.15 の型上の全集であり、全バージョン・ロード方法・会話で全てが発火する保証ではない。

チャネル	最小契約	確認できる効果	仮定できない効果
LLM へのヒント	pi.sendMessage({ customType, content, display, attribution }) の後 void	LLM 文脈の CustomMessageEntry を作る。現在のツールは継続	必ず従うこと、危険操作の阻止
Hook 状態・会話記録	pi.appendEntry(...)	公式説明では LLM に送らない Hook state を記録	自動 UI 表示、阻止・権限検査の代用
ハード阻止	return { block: true, reason }（現行型を確認）	現在の呼び出しを拒否し、呼び出し側が結果を処理	誤判定なし、サーバー権限・書き込みゲートの代用
UI 状態	ctx.ui.setStatus(key, text)	描画可能な状態に入る。undefined で消去	必ず上段に出ること、長文が省略されないこと

2. 拡張ライフサイクルと状態ブリッジ

• loader は capability API と明示設定のパスで Hook を発見する。v17.2.15 の証拠には hooks/pre・hooks/post の自動走査がなく、既定の規約とはしない。
• session_start は探針、ルートのキャッシュ、状態初期化に使う。tool_call は高速で失敗に耐える分類に留める。
• setStatus はイベント → 状態 map → renderer の橋。v17.2.15 の statusLine segment ID は 24 項目の閉じた union で、hook はない。設定で segment を追加できない。公開 PR #2001 は closed・未マージで主線機能ではない。
• 可視性と強制性を分ける。状態行は観測、阻止結果は一回の呼び出し制御、実際の安全境界は独立した権限・書き込みゲートである。

3. HookCommandContext のデッドロック安全境界

拡張コマンド context は newSession、branch、navigateTree を提供し、switchSession、reload、compact、getContextUsage を意図的に省く。tool_call や context の handler 内で呼ぶとデッドロックの可能性がある。欠落は安全境界であり、追加すべき API ではない。必要なら handler 外へ要求を移し、新しい会話で確認する。

4. 安定した信号で検出する

自然言語 pattern より toolName、入力のパス範囲、プロジェクトルートを使う。例外を捕捉・記録または静かに縮退し、通常フローを壊さない fail-soft にする。重複排除や抑制でハード阻止の意味を変えない。

適用条件

• Agent が特定の意思決定ポイントで弱いデフォルトツールを繰り返し選び、代替案を即時に知らせたい。
• gate、圧縮、インデックス、実行状態を UI に投影して観測したい。業務結果を偽装するためではない。
• ホストプログラムを変更せず、プロジェクトまたはグローバルなセッションにイベントハンドラーを登録したい。
• まず合成イベントでロジックを証明し、その後新しいセッションでロードと配送を証明したい。

非適用とリスク

境界	失敗の兆候	正しい対応
ソフトヒントはセキュリティ制御ではない	Agent が sendMessage を無視し、危険な呼び出しが続く	取り返しのつかない操作にはテスト済みの hard gate またはサーバー認可を使い、ヒントを保証とみなさない
Hook API はバージョン依存	型は通るがイベントフィールドやロード場所が変わる	現行型宣言を確認し、新しいセッションで実イベントを観測する
mock は実行時証拠ではない	合成 handler は通るが拡張がロードまたは描画されない	mock の後に実 tool_call と TUI 検証を行う
状態行とトップ segment は別	setStatus にデータがあるが期待位置に出ない	status gate、segment union/preset、renderer 経路を別々に確認する
UI の長さと更新予算がある	文が省略、border が overflow、状態が古い	segment は短くし、完全な状態は独立行に残し、実端末サイズで試す
検出が重い、または throw する	ツールが遅くなり、正常呼び出しにも影響する	高速な path/field 判定、throttling、fail-soft try/catch を使う

最小検証

型/契約確認
  → mock pi に handler を登録し、正・負・エラーイベントを発火
  → 新しいセッション：実 tool_call を発火し、ヒントと通常結果を確認
  → 新しいセッション：hard-block 例を実行し、block/reason を確認
  → tmux または実端末：setStatus と目的の statusline 経路を観測

mock 探針では少なくとも、対象外ツールが静かであること、対象ツールが一度または throttling 規則どおりにヒントされること、エラーが外へ漏れないこと、hard 分岐が拒否を返すことを断言する。実行時の証拠にはメッセージ／状態の到達と、実際のツールまたは UI の結果の両方が必要である。ソースの export や関数の戻り値を見るだけでは不十分だ。

証拠と不確実性

• 出典の事実：legacy-omp-hook-extension-guide は初期イベント、HookAPI.sendMessage、ToolCallEventResult、ctx.ui.setStatus、mock-pi、tmux の検証を記録する。omp-17-2-15-runtime-contract は最初の固定 tag、omp-17-2-15-runtime-contract-correction は ExtensionRunner、全イベント群、sendMessage/appendEntry の分離、HookCommandContext の安全な省略、hook を含まない statusline union を補足する。
• 総合：イベント、LLM メッセージ・状態記録、判断介入、可視性を分け、観測を強制的な安全性と誤報しない。
• 版と未確認事項：公式事実は OMP 17.2.15 の固定 tag のみ。発火、display/triggerTurn の既定、状態行スイッチ、ロードパス、hot reload はインストール版と新会話で再確認する。hooks/pre/post 自動走査は確認していない。

関連ページ

• Headroom 単一ポート移行
• OMP 設定の階層
• Headroom ルート永続化
• LLM wiki pattern

出典と関連文書

• legacy-omp-hook-extension-guide
• omp-17-2-15-runtime-contract
• omp-17-2-15-runtime-contract-correction
• Headroom 単一ポートの総合：入口、動的上流、検証の境界
• OMP 設定の階層：モデルロール、Agent オーバーライド、フォールバックチェーン
• Headroom ルート永続化の総合：Named Profile、model_cache、復旧
• LLM-Wiki パターン：LLM で蓄積する個人 AI ナレッジベース
• Headroom 0.34 圧縮・取得契約：フィールド、モード、実エンドポイント検証