
「コミット前にテストを回す」とCLAUDE.mdに書いても、Claude Codeが毎回そのとおりに動くとは限りません。Hooksは、決まった時点でClaude Codeが毎回自動で実行する処理です。
この記事では、仕組み・書き方・設定例・確認方法・安全上の注意を解説します。

Hooksは、Claudeの判断に任せず、決まった時点でClaude Code自身が実行する機能です。「ファイルを保存したら整形する」「このコマンドは実行前に止める」といったルールを、毎回同じように働かせたいときに使います。
Claude Code全体の使い方は「Claude Codeの使い方——インストールから基本操作・つまずき対処を解説」で、製品の概要は「Claude Codeとは——コードだけじゃない「AI業務エージェント」」で解説しています。
Hooksは、ユーザーが定義したシェルコマンドなどを、Claude Codeの動作の決まった時点で自動実行する機能です。決まった時点は「イベント」と呼ばれ、ファイルの編集前後やセッションの開始など、節目ごとに用意されたものです。
ターミナル・IDE拡張・デスクトップアプリ・クラウドのセッションのどこで使っても、同じイベントが発火します。
CLAUDE.mdの内容は、強制される設定ではなく、コンテキスト(Claudeが参照する情報)として渡されるものです。Claudeは読んで従おうとしますが、厳密な遵守は保証されません。
毎回必ず実行したい処理の置き場所は、フックです。公式ドキュメントも、この分け方を示しています。詳しくは「CLAUDE.mdとは?書き方・置き場所・ベストプラクティスを解説」を参照してください。
判断が要らず、毎回同じ動きにしたい処理が、Hooksに向いています。保存のたびの整形、rm -rf /のような危険コマンドの拒否、入力待ちの通知などがあります。
Claudeに考えて適用させたい作業はスキル、毎回同じにしたい処理はHooksが基本の分け方です。
出典:Claude Code Docs「Memory」(冒頭の説明)/Claude Code Docs「Features overview」(Hook vs Skill)

フックイベントは、Claude Codeが決まった節目で出す合図です。フックは、この合図を受けて動きます。
イベントは追加が続いているため、全体は現行のドキュメントで確認してください(2026年11月時点で33種類)。
イベントは、発生の周期で3つに分かれます。1つ目は、セッションごとのSessionStartとSessionEndです。
2つ目は、1回のやり取り(ターン)ごとのUserPromptSubmit・Stop・StopFailureです。3つ目は、Claudeがツールを呼び出すたびに発火するPreToolUseとPostToolUseで、作業の途中で何度も繰り返されます。
下の表は、主要なイベントを選んだものです。Stopが発火するのは、タスクが完了したときではなく、Claudeの応答が1回終わるごとです。ユーザーが割り込んだときは発火しません。
TaskCompleted・PostToolUseFailure・FileChangedなど、ほかにも多数あるため、全体は公式の一覧で確認してください。
| イベント | 動くタイミング | 業務での使いどころ |
|---|---|---|
| PreToolUse | ツール実行の前 | 危険なコマンドや機密ファイルの編集を、実行前に止める |
| PostToolUse | ツール呼び出しが成功した直後 | 編集後の自動フォーマット、実行したコマンドの記録 |
| UserPromptSubmit | プロンプトの送信後、Claudeが処理する前 | プロンプトの検査、追加情報の付与 |
| Stop | Claudeが応答を終えるたび(ユーザーの割り込みでは発火しない) | 応答の後に毎回走らせる確認処理 |
| SubagentStop | サブエージェントが応答を終えたとき | サブエージェントの作業後の処理 |
| SessionStart | セッションの開始時と再開時 | 開発の状況や直近の変更の読み込み |
| SessionEnd | セッションの終了時 | 後片づけ、セッション情報のログ記録 |
| Notification | Claude Codeが通知を送るとき | デスクトップ通知 |
| PreCompact | コンテキストの圧縮(コンパクション)の前 | 圧縮の前に走らせたい処理 |
ツール呼び出しのように、まだ実行されていない動作は止められますが、すでに起きたことは止められません。可否はイベントごとに違います。
Stopの「止められる」は、Claudeが止まるのを妨げて、会話を続けさせる意味です。PermissionRequestは終了コード2が効かず、JSONのdecisionで拒否します。
| イベント | 止められるか | 終了コード2で起きること |
|---|---|---|
| PreToolUse | 止められる | ツール呼び出しをブロックする |
| UserPromptSubmit | 止められる | プロンプトがClaudeに届かない |
| Stop | 止められる | Claudeが止まるのを妨げ、会話を続ける |
| SubagentStop | 止められる | サブエージェントが止まるのを妨げる |
| PreCompact | 止められる | コンパクションをブロックする |
| PostToolUse | 止められない | ツールは実行済み。stderrがClaudeに表示される |
| Notification | 止められない | 終了コードとstderrは無視される |
| SessionStart・SessionEnd | 止められない | stderrはユーザーにだけ表示される |
| PermissionRequest | 終了コード2は効かない | 権限の確認はそのまま進む。decisionオブジェクトで拒否する |
出典:Claude Code Docs「Hooks reference」(Hook lifecycle/Exit code 2 behavior per event)

Hooksの設定は、イベント、matcher、ハンドラー(実行する処理)の3階層で書きます。settings.jsonのhooksキーの下にイベント名を置き、その下にmatcherのグループ、さらにその下にハンドラーを並べる構造です。
すでにhooksキーがある設定ファイルでは、置き換えずに同じhooksの中へイベントを足します。
公式ガイドの最小構成は、Claudeが入力を待つたびにmacOSの通知を出す設定です。Notificationがイベント、空のmatcherがすべての通知への一致、typeのcommandがシェルコマンドの実行を表します。
typeは主にcommandを使い、ほかにhttp・mcp_tool・prompt・agentがあります。実験的な機能のagentは、変更される場合があるので注意してください。
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}
matcherは、フックを動かす対象を絞る条件です。判定のしかたを決めるのは、書いた値の文字の種類です。
| matcherの値 | 判定のしかた |
|---|---|
空欄、または* |
すべてに一致する |
英数字・_・-・空白・,・|だけで書いた値 |
完全一致。|か,で区切ると、区切った名前のどれかに一致する(Edit|WriteならEditかWrite) |
| それ以外の文字を含む値 | 正規表現として扱う |
大文字小文字は区別されます。UserPromptSubmitやStopなど、matcherが効かず毎回発火するイベントもあります。
イベント別の対象は次の表です。
| イベント | matcherが見る対象 | 値の例 |
|---|---|---|
| PreToolUse・PostToolUse | ツール名 | Bash、Edit|Write |
| SessionStart | セッションの始まり方 | startup、resume、clear、compact、fork |
| SessionEnd | 終了の理由 | clear、resume、logout、prompt_input_exit、other |
| Notification | 通知の種類 | permission_prompt、idle_promptなど |
| PreCompact | 圧縮のきっかけ | manual、auto |
標準入力(stdin)は、プログラムが外から受け取るデータの入り口です。コマンドフックには、session_id、cwd(作業ディレクトリ)、tool_name、tool_inputなどがJSONで渡されます。
シェルスクリプトでは、編集対象のパスをjq -r '.tool_input.file_path'で取り出します(jqは別途インストールが必要)。下は、PreToolUseの入力例です。
{
"session_id": "abc123",
"cwd": "/home/user/my-project",
"permission_mode": "default",
"hook_event_name": "PreToolUse",
"tool_name": "Bash",
"tool_input": {
"command": "npm test"
},
"tool_use_id": "toolu_01ABC123..."
}
出典:Claude Code Docs「Hooks reference」(Configuration/Matcher patterns/Common input fields)/Claude Code Docs「Hooks guide」(Get notified when Claude needs input)

終了コードは、スクリプトが終わるときに返す数字で、結果の種類をClaude Codeに伝えます。フックが結果を返す方法は、終了コードと、標準出力へのJSON出力の2つです。
どのイベントで止められるかは前章の表のとおりで、ここでは返し方そのものを扱います。
0は成功で、処理はそのまま進みます。2はブロックを表す終了コードです。
ブロックできるイベントでは、Claude Codeが動作を止めます。それ以外の終了コードは、動作を原則として続行させる「ブロックしないエラー」です。
慣習では1が失敗を表しますが、Claude Codeではexit 1でもブロックになりません。ポリシーを強制したいフックには、exit 2を使ってください。
終了コード2のとき、ブロックに添えるメッセージは、フックの標準エラー出力(stderr)です。Claudeはその理由を受け取り、別の方法を考えられます。
終了コード0で出力したstderrは、Claudeには見えません。次の2行が公式の例です。
echo "Blocked: rm commands are not allowed" >&2
exit 2
終了コード0でJSONを標準出力に出すと、許可・拒否・確認を細かく選べます。JSONの形はイベントによって違い、下の表のとおりです。
終了コードとJSONは、どちらか一方で使い、標準出力にはJSON以外を混ぜないでください。階層を間違えると、エラーも出ずにフィールドが無視されます。
| イベント | JSONでの返し方 |
|---|---|
| PreToolUse | hookSpecificOutputの中のpermissionDecision(allow・deny・ask・defer)とpermissionDecisionReason |
| UserPromptSubmit・PostToolUse・Stop・PreCompactなど | トップレベルの"decision": "block"とreason |
| Notification・SessionEndなど | 判断の制御はなく、ログや後片づけなどの副作用に使う |
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Use rg instead of grep for better performance"
}
}
出典:Claude Code Docs「Hooks reference」(Exit code output/Exit code 2 behavior per event/JSON output)

スコープは、その設定が効く範囲のことです。
Claude Code全体の設定は、「Claude Codeの使い方——インストールから基本操作・つまずき対処を解説」を参照してください。なお、インストールしただけでは設定ファイルは作られません。
Claude Codeが読む設定ファイルは、次の4種類です。
| 設定ファイル | 効く範囲 | チームと共有できるか |
|---|---|---|
ユーザー:~/.claude/settings.json |
自分のすべてのプロジェクト | できない(自分のマシンだけ) |
プロジェクト共有:.claude/settings.json |
そのプロジェクト | できる(リポジトリにコミットして共有) |
プロジェクトローカル:.claude/settings.local.json |
自分の、そのプロジェクトのみ | できない(Claude Codeが作る場合はgit管理から外される) |
| 管理者ポリシー(managed settings) | 組織全体 | できる(管理者が管理) |
Windowsでは、~/.claudeが%USERPROFILE%\.claudeにあたります。クラウドセッションは手元の~/.claude/settings.jsonを読みません。このほか、プラグインやスキル、サブエージェントの定義も、フックを書ける場所です。
設定ファイルのフックは、サブエージェントの中でも同じように動きます。
同じキーが複数の場所にあるときは、最も上位のレベルの値が採用されます。高い順に、管理者ポリシー、コマンドライン、プロジェクトローカル、プロジェクト共有、ユーザーです。
フックは上書きではなく結合され、各レベルのフックがすべて動きます。同じハンドラーを複数の設定ファイルに書いても、動くのは1回です。プラグインやスキルにある同じハンドラーは、別に動きます。管理者ポリシーのフックは、ユーザー側のdisableAllHooksでは無効にできません。
現在のセッションで読み込まれた設定ファイルを確かめる場所は、/statusのStatusタブにあるSetting sourcesの行です。ただし、この行で分かるのは読み込まれたファイルまでです。
どのファイルがどのキーを出したかは分かりません。登録されたフックの確認には、別のコマンド/hooksを使います。
出典:Claude Code Docs「Settings」(Settings files and who they affect/Settings precedence)/Claude Code Docs「Hooks reference」(Hook locations/Disable or remove hooks)

ここから紹介する4つの設定例は、公式のHooks guideとHooks referenceに載っている例です。そのまま貼って終わりにせず、自分の環境で試してから使ってください。
①〜③の例はjqを使うため、jqのインストールが前提です。
rm -rfのような削除コマンドを止める例で、PreToolUseのBashに登録するフックです。スクリプトは、コマンドがrmで始まると、理由をstderrに書いてexit 2で止めます。
検出できるのは先頭がrmのコマンドで、sudo rmやecho x && rmは通ります。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"if": "Bash(rm *)",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
"args": []
}
]
}
]
}
}
設定のifは、ツール名と引数を合わせて対象をさらに絞る条件です。判定は完全ではない(best-effort)ため、確実に拒否したい操作は、permissionsのルールにも書いてください。
#!/bin/bash
# Reads JSON input from stdin, checks the command
input=$(cat)
command=$(jq -r '.tool_input.command' <<<"$input")
if [[ "$command" == rm* ]]; then
echo "Blocked: rm commands are not allowed" >&2
exit 2 # Blocking error: tool call is prevented
fi
exit 0 # No decision: the normal permission flow applies
スクリプトには、chmod +x .claude/hooks/block-rm.shで実行権限を付けておきます。
EditとWriteで、編集先のパスが保護パターン(.env・package-lock.json・.git/)に当てはまればexit 2で止める例です。スクリプトには実行権限を付けておきます。
EditとWriteの呼び出しは止まりますが、Claudeがシェルコマンドで書き換える場合は止まりません。permissions.denyにEdit(/.env)のようなルールを足して、補ってください。
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
}
]
}
]
}
}
#!/bin/bash
# protect-files.sh
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
# Normalize Windows backslash separators so the patterns below match
FILE_PATH="${FILE_PATH//\\//}"
PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")
for pattern in "${PROTECTED_PATTERNS[@]}"; do
if [[ "$FILE_PATH" == *"$pattern"* ]]; then
echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
exit 2
fi
done
exit 0
chmod +x .claude/hooks/protect-files.sh
PostToolUseのEdit|Writeで、編集されたファイルのパスをjqで取り出し、フォーマッタのPrettierに渡して整形します。Bashでファイルが書き換えられた場合、この設定は動きません。その場合は、ディスク上のファイルの変更をきっかけに動くイベントFileChangedを使ってください。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown \"$f\""
}
]
}
]
}
}
動作を確かめるには、JavaScriptのファイルにシングルクォートの文字列を足させます。Prettierの既定設定なら、ダブルクォートに変われば成功です。
Notificationは、Claudeが入力や許可を待つときに発火し、先に示した最小構成のcommandを入れ替えるだけで使える設定です。Windowsの例は通知ではなくダイアログで、ターミナルの後ろに隠れることがあります。
下の表はシェルで実行するコマンドそのものです。settings.jsonのcommandに入れるときは、先の最小構成の例のように、文字列の中の"を\"と書きます。
| OS | commandに書く内容(公式の例) | 注意点 |
|---|---|---|
| macOS | osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"' |
Script Editorに通知の権限がないと、何も表示されずに失敗する |
| Linux | notify-send 'Claude Code' 'Claude Code needs your attention' |
デスクトップ通知デーモンが必要で、ヘッドレスのサーバー・SSH接続・多くのコンテナでは動かない |
| Windows(PowerShell) | powershell.exe -Command "[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')" |
通知ではなくダイアログで、ターミナルの後ろに隠れることがある。WSLではpowershell.exeをPATHに通しておく必要がある |
出典:Claude Code Docs「Hooks guide」(Automate actions with hooks)/Claude Code Docs「Hooks reference」(How a hook resolves/Exit code 2)

ここで取り上げる例は、セッション開始時に情報を渡す設定と、コマンドのログの2つです。スクリプトの要らない固定の内容は、CLAUDE.mdに書けば足ります。
スクリプトで中身を作りたい場合や、コンパクション後に渡し直したい場合は、フックが役立ちます。
コンパクションは、会話の履歴を要約に置き換えて、コンテキストの空きを作る処理です。実行のきっかけは、上限に近づいたときの自動と、/compactによる手動です。
要約では、会話の早い段階にあった詳細な指示が失われることがあります。失いたくない注意書きは、matcherをcompactにしたSessionStartで標準出力に書けば渡し直せます。処理は短時間で終わるものにしてください。
{
"hooks": {
"SessionStart": [
{
"matcher": "compact",
"hooks": [
{
"type": "command",
"command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
}
]
}
]
}
}
PostToolUseは成功したツール呼び出しの後に発火するため、Bashに絞ると、成功したコマンドが1つずつファイルに追記されます。失敗したコマンドは別のイベントPostToolUseFailureの対象で、このフックには記録されません。
PowerShellツールのコマンドも残すなら、BashとPowerShellの両方に一致するBash|PowerShellがmatcherです。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
}
]
}
]
}
}
出典:Claude Code Docs「Hooks guide」(Re-inject context after compaction/Log successful Bash commands)/Claude Code Docs「Hooks reference」(How a hook resolves)

成功したフックは、会話に何も表示しません。動いたかどうかを確かめる手がかりは、目に見える効果です。
確認は、登録されているか、スクリプトが単体で動くか、実際の操作で効くかの順に進めると、切り分けやすくなります。
/hooksは、設定済みのフックを閲覧する読み取り専用の画面です。追加したフックは該当するイベントの下に表示され、ユーザー設定・プロジェクト設定・プラグインなど、どこから来たフックかも分かります。
一覧に出ないフックは、Claude Codeが読み込んでいない状態です。スキルのフロントマターに書いたフックは、そのスキルを起動した後に登録されます。
サンプルのJSONをパイプで流し、echo $?で終了コードを見る手順です。流したJSONはPreToolUseの最小形で、実際の入力はもっと多くの項目を持ちます。
Stopのように別の項目を使うフックは、その項目を足したJSONを自分で作ってください。
echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
echo $? # Check the exit code
| 症状 | 対処 |
|---|---|
| スクリプトがまったく動かない | chmod +xで実行権限を付ける |
| 「command not found」と出る | 絶対パスか${CLAUDE_PROJECT_DIR}でスクリプトを指定する |
| 「jq: command not found」と出る | jqをインストールするか、PythonやNode.jsでJSONを解析する |
フックの結果を見る場所は、Ctrl+Oで開くトランスクリプト表示です。成功したフックは何も表示せず、ほとんどのイベントではブロックされるとメッセージが、ブロックしないエラーでは「hook error」の通知が出ます。自動整形はファイルを開いて変化を確かめ、通知はShift+Tabで権限確認を求めるモード(manual mode)に切り替えて、許可が必要な操作を頼んで試します。
Notificationのように、失敗しても通知が出ないイベントには注意してください。
動かないときの見直し点は、次の表のとおりです。
| 症状 | 見直す点 |
|---|---|
/hooksに出ない |
設定ファイルに構文エラーがないか(起動時にSettings Errorとして報告される) |
| 出ているのに動かない | matcherがツール名と完全に一致しているか(大文字小文字を区別する) |
| JSON出力が効かない | 標準出力にJSON以外が混ざっていないか(シェルのプロファイルの出力など)。デバッグログでHook output does not start with {を探す |
| 原因が分からない | claude --debug-file <path>でログを書き出して読む。起動後なら/debugでも有効にできる |
claude --debugはログを端末に出さず、~/.claude/debug/<session-id>.txtに書き込みます。ログの場所を決めたいときは、claude --debug-file <path>を使ってください。
出典:Claude Code Docs「Hooks guide」(Limitations and troubleshooting/Check what a hook did)/Claude Code Docs「Hooks reference」(The /hooks menu)

CLAUDE.mdとHooksの違いは前述のとおりです。ここでは、何をどこに書くかの判断、フックとpermissionsの重ね使い、チームへの配り方を扱います。
スキルの作り方は、「Claude Code Skillsとは?仕組みと作り方を解説」で解説しています。
下の表は、公式ドキュメントの使い分けをまとめたものです。
| 仕組み | 何を書くか | 守られ方 | 向いているもの |
|---|---|---|---|
| CLAUDE.md | 考え方・前提・方針 | コンテキストとして読まれる。遵守は保証されない | プロジェクトの前提や方針を伝える |
| skills | Claudeに考えて適用してほしい手順・知識 | Claudeが解釈して適用するため、結果は変わりうる | 再利用する作業手順 |
| permissions | 許可・拒否のルール | 設定による技術的な強制 | ツールやファイルの許可・拒否 |
| Hooks | 判断が要らず毎回同じにしたい処理 | イベントごとに、Claudeの判断なしで実行される | 整形・通知・ブロック・ログ記録 |
「.envを編集しない」という規則は、CLAUDE.mdやスキルに書いても依頼にとどまり、必ず守られる保証はありません。守らせたい規則は、フックかpermissionsに置いてください。
PreToolUseフックのdenyは、bypassPermissionsや--dangerously-skip-permissionsを含むすべての権限モードで効き、ユーザーが権限モードを変えても回避できないポリシーを強制できます。一方、フックがallowや終了コード0を返したときの扱いは、下の表のとおりです。
フックとpermissionsのルールは働き方が違うため、併用してください。
| フックの返答 | 結果 |
|---|---|
allow |
設定側のdenyルールは破れない |
| 終了コード0 | 承認にならず、通常の権限確認に進む |
チームには、.claude/settings.jsonをリポジトリにコミットして配ります。組織全体には管理者ポリシーで配り、管理者はallowManagedHooksOnlyで、ユーザー・プロジェクト・ローカル・プラグインのフックを止められます。
出典:Claude Code Docs「Features overview」(Hook vs Skill)/Claude Code Docs「Hooks guide」(Hooks and permission modes/Configure hook location)

コマンドフックは、自分のユーザー権限のまま実行されるシェルコマンドで、アカウントがアクセスできるファイルを変更・削除・参照できます。導入前に中身を読み、動作を確認することが前提です。
Hooksだけで安全が保証されるわけではなく、止められる範囲には限りがあります。
フックのコマンドは、ユーザー自身の全権限で実行されます。自分で書いたフックも、共有されたリポジトリの.claude/settings.jsonに入っていたフックも、実行される権限は同じです。
他人が書いた設定は、中身を読まずに取り込まないでください。
対話型セッションでは、フォルダの信頼ダイアログを承諾するまで、自分の設定ファイルを含むすべてのフックが動きません。-pやSDKのセッションでは信頼ダイアログが出ず、リポジトリの.claude/settings.jsonにあるフックが確認なしで動きます。自分が書いていないリポジトリでclaude -pを使う前に、.claude/の設定ファイルを確認してください。
フックが動かない、または止まらない場面は、次の4つです。
| 場面 | 起きること | 補う方法 |
|---|---|---|
| プロンプトで@参照したファイル(既定) | ツール呼び出しなしで読み込まれるため、Read対象を含むPreToolUseのフックが動かない | Readのdenyルールをpermissionsに書く |
| PreToolUseのタイムアウト | 止まらず、通常の権限確認に進む | "onFailure": "block"を指定する(v2.1.295以降) |
| 終了コード1 | ブロックにならない | 強制したいときはexit 2を使う |
| Bash経由のファイル変更 | Edit・Writeを対象にしたフックは動かない | permissions.denyのルールを併用する |
どの場面も、フックだけに頼らず、permissionsのルールで補う前提で組んでください。タイムアウトの既定値は、command・http・mcp_toolで600秒で、UserPromptSubmitなどでは30秒に短縮されます(2026年11月時点)。
書くときの基本は、次の5点です。
| 注意点 | 書き方 |
|---|---|
| 入力を信用しない | 標準入力のJSONの値は、検証してから使う |
| 変数は引用符で囲む | "$VAR"と書き、$VARは避ける |
..を弾く |
ファイルパスに..が含まれていれば止める(上位のフォルダへ抜ける指定を防ぐ) |
| 絶対パスで指定する | スクリプトは絶対パスで指定する。${CLAUDE_PROJECT_DIR}を使い、シェル形式では二重引用符で囲む |
| 機密ファイルを避ける | .env・.git/・鍵などは対象にしない |
出典:Claude Code Docs「Hooks reference」(Security considerations)
設定ファイルに"disableAllHooks": trueを書くと、削除せずにすべてのフックを一時的に無効にできます。個別のフックだけを無効にする方法はなく、無効化は全フックが対象です。1回の実行だけ無効にしたいときは、claude --settings '{"disableAllHooks": true}'で渡してください。
Git Bashは必須ではありませんが、入っているかどうかでフックの既定のシェルが変わります。Git Bashがないと、シェル形式のフックはPowerShellで動き、PreToolUseとPermissionRequestでは0と2以外の終了コードが失敗として扱われ、ツール呼び出しがブロックされます。PowerShellで書くフックには"shell": "powershell"を指定し、$CLAUDE_PROJECT_DIRをそのまま書かないでください(${CLAUDE_PROJECT_DIR}か$env:CLAUDE_PROJECT_DIRと書きます)。
一致したフックは、順番に動くのではなく並列で動きます。1つのフックがdenyを返しても、ほかのフックの実行は止まらない仕様です。PreToolUseの判断が食い違うときは、最も厳しい答えが採用されます(厳しい順にdeny、defer、ask、allow)。
ツール呼び出しを挟まずに8回連続でブロックすると、Claude CodeがStopフックの指示を上書きします。入力JSONのstop_hook_activeがtrueなら早めに終了させるのが、公式の例の書き方です。既定ではこの上限があるため、無限には続きません。上限を引き上げる手段は、環境変数CLAUDE_CODE_STOP_HOOK_BLOCK_CAPです。
コメントは書けません。settings.jsonは厳密なJSONのため、//のコメントや末尾のカンマは構文エラーです。エラーは、次回の起動時にSettings Errorとして報告されます。
不明なイベント名のような個別の項目の誤りは、警告にとどまり、無視されるのはその値だけです。
出典:Claude Code Docs「Hooks reference」(Disable or remove hooks/Stop)/Claude Code Docs「Settings」
CLAUDE.mdは強制ではなくコンテキストのため、毎回必ず実行したい処理はHooksに書きます。ただし、どのイベントでも止められるわけではない点に注意してください。設定はsettings.jsonに「イベント→matcher→フック」の3階層で書き、ブロックには終了コード2を使います。
確認は/hooks、単体実行、実際の操作の順です。Bash経由の変更、既定での@参照、タイムアウトでは止まらないため、permissionsのルールも併用します。
まず通知や自動整形など影響の小さい例を試し、危険コマンドのブロックは自分の環境で確認してから入れましょう。

Claude CodeのHooks設計からチーム展開まで伴走しますパンハウスは、Claude Codeを日々の業務で使い倒しているAI開発会社です。どこまでClaude Codeに任せ、どこを人が確認するかの線引きから、Hooksやpermissionsの設計、ビジネス職・開発組織向けの研修まで、実務に即して支援します。まずはお気軽にご相談ください。詳しくはこちら