Hooks

Hook は、エージェントのランタイムが指定したライフサイクルイベントで呼ぶコールバックです。ツール実行前なら要求を拒否してファイルの変更を防げます。実行後なら結果を調べられますが、完了した操作を未実行にはできません。イベントとツールのマッチャーが両方一致したときだけ実行します。

検問を置く位置に似ています。ツールの前なら要求を止め、後なら結果を記録します。同じ問題を検出しても、位置によって防げることが変わります。

Hook の仕組み

操作を防ぐには実行前の検査を使います。完了した結果のログや編集後の整形には、実行後のコールバックを使います。イベントを配信してツールを実行する枠組みが harness です。

登録はイベント、マッチャー、コールバックを結びます。本例の h1 は check_release を PreToolUse または PostToolUse に登録し、ツールを Edit または Edit|Write で選びます。ディスパッチャーはイベント、次にツール名を照合します。両方が一致した後でコールバックが対象ファイルを調べます。

2 件の要求は事前に用意されています。モデルが追加判断で check_release の実行を決めるのではなく、harness が配信と実行を管理します。

保護対象は release.txt です。前置イベントでは試行を記録し、対象が保護ファイルなら deny、別ファイルなら no-decision を返します。harness は実行前にその結果を処理します。no-decision 自体は許可ではなく、本例の許可する基本ポリシーへ判断を戻します。

後置イベントでは成功結果を受け取り、完了した呼び出しを記録します。保護対象なら違反を報告しますが、補償書き込みは行いません。報告はツール結果に付随し、ファイルはツールが書いた状態を保ちます。

イベント名は Claude Code の hooks リファレンス に沿っています。前置 hook は実行前、成功後の hook は結果受信後に動き、マッチャーはツール名を選びます。イベントごとに出力形式は異なり、画面の短いラベルはその要約です。後置の阻止報告はフィードバックを加えても、過去の副作用を取り消しません。

Hooks のステップ

初期設定は check_release を PreToolUse、マッチャーを Edit|Write に登録します。notes.txt = draft、release.txt = locked から始めます。locked は本文であり OS のロックではありません。両ツールは呼ばれれば成功します。

1. c1 が編集を提案。 Edit("notes.txt", "draft", "reviewed") が置換を要求します。要求到着だけではファイルもツール回数も変わりません。
2. 前置イベントが h1 に一致。 イベントとツールが一致し、c1 の試行を記録します。保護対象ではないため no-decision。コールバック実行は必ずしも拒否を意味しません。
3. harness が c1 を実行。 基本ポリシーが許可し、Edit が draft を reviewed に変更。ツール回数は 1。成功後に PostToolUse が発生しますが、h1 は前置登録なので呼ばれません。
4. c2 が保護対象への書き込みを提案。 Write("release.txt", "published") が前置イベントへ来ます。Write も一致するため 2 件目の試行を記録し、deny を返します。
5. 拒否を処理。 harness が実行経路を閉じ、c2 を阻止済みにします。Write は呼ばれず、成功結果も後置成功イベントもありません。

結果は notes.txt = reviewed、release.txt = locked、hook 2 回、ツール 1 回です。コールバックの 2 記録は試行であり、c1 の実行を示すのは呼び出し台帳とツール結果です。保護ファイルが不変で要求が止まったことが、前置検査の効果を示します。

遅すぎる検査と対象漏れ

イベントだけを PostToolUse に変えると、両方とも前置段階を通り、基本ポリシーで実行されます。c2 が published を書いた後に違反を報告するため、ファイルはそのままです。監査記録は操作が完了した証拠であり、防止ではありません。

PreToolUse に戻し、マッチャーを Edit にすると、c1 は届きますが c2 の Write は一致しません。前置イベントは発生しても、コールバックは release.txt を検査する機会がありません。時機を早めても対象範囲の漏れは直りません。

各シナリオは c2 の要求時点で停止します。c1 は完了し、release.txt はまだ locked です。防げるか予測してから再生し、イベント、照合、ファイル効果を順に追ってください。Prevent the write と Check after execution は時機だけ、Miss the Write tool との比較は範囲だけを変えます。ファイルと要求は同じです。

後置 hook は成功ログや編集後の整形に使えます。自動整形の例 も参照できます。目的に合うイベントを選び、どのツールが処理器に届くかを確認します。

境界条件

• ツールは一致、イベントは不一致。 Write 対応でも、後置登録のコールバックは前置イベントでは動きません。
• イベントは一致、ツールは不一致。 c2 の前置イベント自体は発生します。Edit が Write を除外した状態は、コールバックが no-decision を返す状態とは別です。
• 一致しても無害な対象。 c1 はコールバックを通って実行します。マッチャーが候補を選び、コールバックが対象を判定します。
• 実行前に阻止。 c2 は拒否された要求であり、実行に失敗したツールではありません。成功結果と後置成功イベントも生じません。
• 実行後に全件一致。 2 件の成功呼び出しを監査できても、保護ファイルへの書き込みを未実行には戻せません。

よくある間違い

• イベント発生をコールバック実行の証拠にする。登録の一致と呼び出し回数も確認します。
• 試行ログを完了ログと読む。初期設定の hook は結果が出る前に動きます。
• no-decision を許可規則と読む。その後を決めるのは基本権限ポリシーです。
• 後置警告が元のファイルを復元すると思う。復元には別操作が必要で、この回復処理はありません。
• ツール名マッチャーへファイル名を書く。本例の Edit|Write はツールを選び、その後で release.txt を調べます。

モデルの簡略化

2 件の固定要求、2 個のメモリ上のファイル、1 個の同期コールバックを使う決定的な教材です。照合、コールバック、編集、書き込みはローカルで実行し、モデル出力を記録したり作り上げたりしていません。基本ポリシーは両ツールを許可し、hook の差を観察できるようにします。

実ランタイムにはパス処理、別の実行経路、複数コールバック、タイムアウト、非同期処理、入力変更、ほかのイベントがあります。hook 自体がモデルを使う種類もあります。本課は本番の権限制御実装や正式な訓練の代わりではありません。