active: true
derived: false
gherkin: |
  Feature: Cache Hooks
    Scenario: Triggering custom logic during cache lifecycle events
      Given a cache operation (hit, miss, or pre-execute)
      When the corresponding hook method is triggered
      Then the registered hooks execute sequentially and thread-safely
groups:
- HOOK
header: |
  HookBase / ThreadSafeHookBase
level: 2.19
links:
- ARCH009: QB3oa3wODbrEiWMPJXf1o-YHfM7CoQRgkyg-ERzIA6U=
normative: true
ref: ''
reviewed: e-W5wTf8ilWYE7X-LM-5reO_a5TTmzJlwiX18teLx3k=
text: |
  ## インターフェース

  ```python
  class HookBase:
      def pre_execute(self, ctx: PreExecuteContext) -> None: ...
      def on_cache_hit(self, ctx: CacheHitContext) -> None: ...
      def on_cache_miss(self, ctx: CacheMissContext) -> None: ...
  ```

  ## 振る舞い

  1. **フック呼出**: キャッシュエンジンの各ステート（実行前、ヒット、ミス）で登録されたフックを順番に実行する
  2. **スレッド安全化**: `ThreadSafeHookBase` を継承した場合、メタクラスが自動的に各メソッドを `with self._lock:` で包む

  ## パラメータ詳細 (Context)

  | コンテキスト | 保持データ |
  |---|---|
  | `PreExecuteContext` | `func`, `args`, `kwargs`, `cache_key` |
  | `CacheHitContext` | `cache_key`, `result`, `metadata` |
  | `CacheMissContext` | `cache_key`, `result`, `execution_time` |

  ## エラーハンドリング

  - **フック内例外**: フックの実行中に発生した例外はキャッチされ、エラーログとして出力されるが、主処理（関数の実行結果）は中断されない。

  ## エッジケース

  - **フックの順序**: `hooks=[h1, h2]` と指定した場合、`h1` -> `h2` の順で実行される。

  ## 設計判断

  キャッシュヒット時のログ出力や、LLMのトークン消費量の集計など、メインのビジネスロジックに手を加えずにカスタム処理を介入させるための、安全な拡張ポイント（フック）を提供するため。
