この手順は、Claude Code にフックを追加するものである。フックとは、Claude Code がライフサイクルの特定の時点で実行する、ユーザー定義のハンドラー（多くの場合はシェルコマンド）であり、これによってあるアクションが、モデルがそれを実行すると選ぶかどうかに左右されず、必ず行われるようになる（エージェントフック を参照）。Anthropic のガイドは、Claude がユーザーの入力を待っているときに毎回発火するデスクトップ通知を例に、この手順を順を追って説明している。
前提条件
- Claude Code と、フックを記述できる設定ファイルのいずれかへの書き込み権限。すべてのプロジェクトに適用するなら
~/.claude/settings.json、プロジェクト単位でリポジトリを通じて共有するなら.claude/settings.json、プロジェクト単位で共有しないなら.claude/settings.local.jsonである。フックは、管理ポリシー設定、プラグインのhooks/hooks.json、あるいはスキルやサブエージェントのフロントマターから提供されることもある。 - フックの JSON 入力を解析するガイドのコマンド例を使う場合は
jq。 - コマンドから呼び出すフックスクリプトは、macOS と Linux では実行可能になっていなければならない（
chmod +x）。
手順
- 目的のスコープの設定ファイルを開き、
hooksブロックを追加する。各イベント名は単一のhooksオブジェクト内のキーであり、省略可能なmatcherと実行するハンドラーを持つグループのリストを保持する。通知の例では、空のマッチャーと、プラットフォームの通知コマンド（macOS ではosascript、Linux ではnotify-send、Windows では PowerShell のダイアログ）を呼び出すcommandハンドラーを持つNotificationイベントとなる。ファイルにすでにhooksキーがある場合は、オブジェクトを置き換えるのではなく、新しいイベントを兄弟要素として追加する。フックを書くよう Claude に依頼することもできる。 - 必要に応じて、発火する条件を絞り込む。マッチャーがなければ、フックはそのイベントが発生するたびに発火する。マッチャーは、イベントによって異なるフィールドで絞り込む。ツールイベントではツール名（たとえば
Edit|Write）、Notificationでは通知の種類、SessionStartではセッションの開始方法である。ツールイベントでは、Bash(git *)のようなパーミッションルールの構文を用いるifフィールドによって、ツール名と引数を組み合わせて絞り込める。 /hooksと入力してフックブラウザーを開き、イベントを選択して、新しいフックがそのマッチャー、種類、ソースファイル、コマンドとともに表示されることを確認する。このメニューは読み取り専用であり、変更は設定の JSON で行う。- イベントを発生させてテストする。通知の例では、
Shift+Tabで Claude Code を手動モードに切り替え、権限が必要なことを依頼し、ターミナルから別のウィンドウに切り替えて、通知が届くのを待つ。
補足
- コマンドフックはイベントのデータを JSON として stdin で受け取り、終了コードと出力によって応答する。終了コード 0 は異議なしを意味する（
PreToolUseの場合、呼び出しを承認するわけではなく、通常のパーミッションフローが引き続き適用される）。終了コード 2 はアクションをブロックし、stderr がその理由となる。あるいは、フックは 0 で終了したうえで JSON オブジェクトを出力し、構造化された制御を行うこともできる。たとえばhookSpecificOutputの中にネストした、allow、deny、askのいずれかのPreToolUseのpermissionDecisionである。 - フックの
typeには、commandのほかに、http（イベントデータを URL に POST する）、mcp_tool、prompt（Claude モデルによる単一ターンの評価で、デフォルトは Haiku）、agent（ツールを使って条件を検証できるサブエージェントで、実験的とされている）を指定できる。 - ガイドの実例には、
PostToolUseフックによる編集後のファイルの自動整形、2 で終了するPreToolUseスクリプトによる保護対象ファイルへの編集のブロック、compactマッチャーを指定したSessionStartフックによる コンパクション 後の重要なコンテキストの再注入、設定変更のログ記録、作業ディレクトリが変わったときの環境変数の再読み込み、そしてPermissionRequestフックによる特定の権限プロンプトの自動承認が含まれる。最後のものについて、ガイドはマッチ対象を狭く保つよう警告している。 - 1 つのイベントに複数のフックが一致した場合、それらはすべて並列に実行され、その後で結果が統合される。
PreToolUseでは最も制限の厳しい判定が優先される。PreToolUseの deny は、bypassPermissionsを含むあらゆる パーミッションモード の設定でツールをブロックするが、allowを返すフックが設定の deny ルールを上書きすることはできない。つまりフックは制限を強めることはできても、緩めることはできない。 - フックが発火しない場合は、
/hooksで正しいイベントの下に表示されているか、マッチャーがツール名と正確に一致しているか（マッチャーは大文字と小文字を区別する）を確認する。JSON 出力が効かない場合は、シェルプロファイルのecho行が stdout の先頭に付け加えられていないか、フィールドが誤った階層に置かれていないかを調べる。ブロックし続けるStopフックは、進展のないまま 8 回連続でブロックすると無視されるため、入力フィールドstop_hook_activeが true のときは早めに終了するようにすべきである。