最近、参画先でClaude Codeが配布されたので、改めてHooksについて調べたのでまとめてみました。
Hooksとは
hooksとはClaude Codeがプロンプトを実行する場合の一連のライフサイクルがあり、その中の特定のタイミング（Hooks）があり、その特定のタイミングでイベントを自動実行させる仕組みのことです。
以下、公式を日本語訳して抜粋
フックとは、Claude Code のライフサイクルの特定の時点で自動的に実行される、ユーザー定義のシェルコマンド、HTTP エンドポイント、MCP ツール呼び出し、LLM プロンプト、またはサブエージェントのことです。
ローカルのターミナルだけでなく、IDE拡張・デスクトップアプリ・クラウドセッションなど、Claude Codeが動くあらゆる環境で同じフックイベントが発火します。
※以下の公式サイトのイラストを見ると、イメージがつきやすいです。
フックの発火タイミング
イベントは大きく3つの頻度に分類されます。
- セッションごとに1回: SessionStart、SessionEnd
- ターンごとに1回: UserPromptSubmit、Stop、StopFailure
- ツール呼び出しのたびに: PreToolUse、PostToolUse
主要なイベント一覧はこちらです（全イベントは30種類近くありますが、まず押さえておきたいものを中心に抜粋しています）。
| イベント | 発火タイミング |
|---|---|
SessionStart |
セッション開始・再開時 |
UserPromptSubmit |
プロンプト送信時、Claudeが処理する前 |
PreToolUse |
ツール呼び出しの実行前（ブロック可能） |
PermissionRequest |
ツール呼び出しに権限確認が必要なとき |
PostToolUse |
ツール呼び出しが成功した後 |
PostToolUseFailure |
ツール呼び出しが失敗した後 |
Notification |
Claude Codeが通知を送るとき |
SubagentStart / SubagentStop
|
サブエージェントの起動時・終了時 |
Stop |
Claudeが応答を終える時 |
StopFailure |
APIエラーでターンが終わった時 |
PreCompact / PostCompact
|
コンテキスト圧縮の前後 |
SessionEnd |
セッション終了時 |
※このほかにもPermissionDenied、TaskCreated、ConfigChange、CwdChanged、FileChanged、PreModelSwitchなど多数のイベントがあります。詳細は公式リファレンスの全イベント表を参照してください。
覚えておいた方が良いhooks
数あるイベントの中でも、実運用で使う頻度が高いのは次の3つです。
PreToolUse — 危険な操作を未然にブロックする
ツール実行前に発火し、exit 2※を返すとツール呼び出しそのものをブロックできます。
rm -rfのような破壊的コマンドを機械的に止めるのに向いています。
※exit 2はUnixのプロセスが返す「終了コード（exit code）」の一つで、Claude Codeのhooksではブロックするという意味を持つ特別な値として扱われます。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
}
]
}
]
}
}
PostToolUse — 編集後の自動フォーマット・自動チェック
ファイル編集が終わった直後に走らせ、Prettierやlintなどを自動実行する定番の使い方です。ツールはすでに実行済みなのでブロックはできませんが、stderr※をClaudeに見せてフィードバックさせることは可能です。
※stderrは「standard error（標準エラー出力）」の略で、プログラムがエラーメッセージや診断情報を出力するための専用の出力先です。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh"
}
]
}
]
}
}
SessionStart — セッション開始時にコンテキストを注入
セッション開始・再開のたびに走り、現在のブランチ名やデプロイ対象など「環境の今の状態」をClaudeに教え込むのに使えます。
※ Notificationフックでデスクトップ通知を出す
Claudeが入力待ちになったときにOS標準の通知を飛ばせます。長時間タスクを裏で走らせているときの体験が大きく変わるので、地味に人気の高いフックです。
スキルとの連携例
hooksはsettings.jsonだけでなく、スキルのフロントマター内にも直接定義できます。
スキルが呼ばれたタイミングでフックが登録され、以降そのセッション中ずっと有効になる仕組みです。
例えば、「セキュアな操作」を行うスキルの中に、Bashコマンド実行前のセキュリティチェックを仕込む場合はこうなります。
---
name: secure-operations
description: セキュリティチェック付きで操作を行う
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/security-check.sh"
---
このスキルが一度呼ばれると、以降のBashコマンド実行にはすべてsecurity-check.shのチェックがかかるようになります。
一度きりのチェックで十分なら、フック側にonce: trueを付けることで初回成功時に自動的に登録解除されます
また、サブエージェント（.claude/agents/）のフロントマターにも同じ書式でフックを定義でき、そちらはそのサブエージェントが動いている間だけ有効という違いがあります。
最後に
hooksは「Claudeに頼む」のではなく「必ず実行される」仕組みを提供するもの。
PreToolUse、PostToolUse、SessionStartなどの発火のタイミングとスキルやシェルなどを組み合わせた自動化の仕組みである。
また、スキルやサブエージェントのフロントマターにフックを埋め込むことで、「その機能を使っている間だけ」有効な局所的なガードレールも作ることができる。