Hooks (フック)

LLM が実行を選ぶかどうかに頼らず、決まった処理を毎回実行させる決定的な制御に使います。プロジェクトの規則の徹底、繰り返し作業の自動化、既存のツールとの連携に向いています。

Hooks は、Claude Code がライフサイクルの特定の時点で実行するユーザー定義の処理です。イベントが発火すると、該当するフックを並列に実行します。

• フックは stdin・stdout・stderr と終了コードで Claude Code とやり取りし、イベントごとのデータを JSON で stdin から受け取ります。終了コードでできるのはブロックするか何もしないかだけで、より細かく制御するときは終了コード 0 で終わり、stdout に JSON オブジェクトを出力します。
• matcher を指定しないフックは、そのイベントが起きるたびに発火します。matcher で発火の対象を絞れます。if フィールドは permission rule syntax でツール名と引数を合わせて絞り込む仕組みで、ツールのイベントでだけ使えます。
• 多くのフックは "type": "command" でシェルコマンドを実行します。ほかに http・mcp_tool・prompt・agent の型があります。HTTP フックはイベントのデータを HTTP エンドポイントに POST し、command フックと同じ形式の JSON で結果を受け取ります。
• prompt フックは、プロンプトとフックの入力データを Claude モデルに送って判断させます。agent フックはサブエージェントを起動し、ファイルの読み取りやコード検索などのツールで条件を確かめてから判断を返します。
• 実現したい内容を CLI で説明して、Claude にフックを書かせることもできます。

• 複数の PreToolUse フックが許可の判断を返したときは、deny・defer・ask・allow の順で、最も制限の強い判断が適用されます。
• permissionDecision: "deny" を返すフックは、bypassPermissions モードや --dangerously-skip-permissions の指定があってもツールをブロックします。
• PermissionRequest フックが "behavior": "allow" を返すと、Claude Code が利用者に代わって許可要求に応答します。PermissionRequest では agent 型のフックは実行されず、command または http フックを案内するエラーが表示されます。
• PreToolUse と PermissionRequest フックが返す updatedInput は、Claude 自身の入力と同じように検証されます。未知のキーは除去され、ツールが受け付けない入力の場合は呼び出しが拒否されます。
• command と HTTP フックに onFailure: "block" を指定すると、フックが起動できない・タイムアウトする・想定外の終了コードで終わる場合に、操作を通さずにブロックします。
• PostToolUse フックはツールの実行後に動くため、実行済みの操作を取り消せません。

• フックを追加する場所で、そのフックの適用範囲が決まります。/hooks を実行すると、設定済みのフックをイベントごとにまとめた 1 つのリストで確認できます。
• フックを無効にするには、設定ファイルで "disableAllHooks": true を指定します。managed settings のフックは、managed settings 側にも同じ指定をしない限り実行されます。
• allowManagedHooksOnly を設定しているとき、管理設定で強制的に有効化されたプラグインのフックは実行されます。
• VS Code ではコマンドメニューの Hooks (フック) ダイアログで、user・project・local 設定のフックを表示・追加・編集・削除できます。managed・plugin・session のフックは読み取り専用です。
• prompt フックと agent フックは、サブエージェントを含めてセッションあたり同時に最大 24 個まで実行され、これに加えてイベントのタイムアウトより長く待ったものが最大 12 個実行されます。
• 5 万文字を超えるフックの出力は、コンテキストに直接挿入されず、ファイルパスとプレビュー付きでディスクに保存されます。
• フックの実行結果は、Ctrl+O で transcript view (会話記録の表示) を開いて確認できます。

1. ~/.claude/settings.json を開き、Notification フックを追加します。ファイルが無い場合は作成します。
2. Claude Code のプロンプトで /hooks と入力して hooks browser (フックの一覧) を開き、追加したフックが Notification の下に表示されていることを確認します。
3. Esc で CLI に戻り、ステータスバーに ⏸ manual mode on が表示されるまで Shift+Tab を押します。
4. 許可が必要な作業を Claude に頼み、ターミナルから別の画面に切り替えます。デスクトップ通知が届けば設定は動いています。