Claude Code Hooksの使い方｜全33イベント表と設定例・止め方

Claude Code の Hooks（フック）は、ツールの実行前後やプロンプトの送信時など、決まったタイミングで自分のコマンドを必ず実行させる仕組みです。settings.json の hooks に「イベント名 → matcher → 実行するコマンド」を書き、コマンドが終了コード 2 で終わると、その操作（ツールの実行など）を止められます。

CLAUDE.md に書いた指示は「守ってほしいお願い」ですが、Hooks は毎回必ず動く処理です。危険なコマンドの停止や、編集後の自動フォーマットのように、毎回確実に行いたいことに向いています。いちばん小さな例は次のとおりです。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous.sh" }
        ]
      }
    ]
  }
}

確認環境：Claude Code 2.1.301（npm の latest。stable タグは 2.1.292）・jq 1.7・Prettier 3.9.10・Node.js 22.22.2（Linux）。イベント・入力・出力の仕様は公式ドキュメント（Hooks reference と hooks ガイド）と、同じ版番号の Agent SDK（@anthropic-ai/claude-agent-sdk 0.3.301）の型定義で確かめました。この記事のフックのスクリプトは、ドキュメントの入力 JSON を自分で作って標準入力に流し、終了コードと出力を確かめました。さらに、決まった順にツール呼び出しを返す検証用の API サーバーに Claude Code 2.1.301 をつなぎ、claude -p で実際にフックを発火させて、フックの実行記録（--include-hook-events）と Claude 側に返った文言を確かめています。出力中のパスは /home/you/... に置き換えています（確認日 2026年10月16日）。

Hooksとは：CLAUDE.md・Skillsとの違い

「毎回必ず」なら Hooks、「Claude に判断してほしい方針や手順」なら CLAUDE.md や Skills です。CLAUDE.md と Skills の使い分けは、関連記事「CLAUDE.mdとSkillsの違い｜使い分け判断表と移し替え手順」で扱っています。権限ルールの書き方や設定の優先順位は、関連記事「Claude Code settings.json設定一覧｜権限の雛形と優先順位」で扱っています。なお、Git の pre-commit などのフックは別の仕組みで、関連記事「Git hooks・husky v9の設定方法｜実行結果とlefthook比較」で扱っています。

Hooksの全イベント一覧（2026年10月・33イベント）

公式ドキュメントのイベント表と、Agent SDK の型定義（HOOK_EVENTS）はどちらも 33 イベントでした。「止められるか」は、ドキュメントの「exit 2 のときの動き」の表に従っています。主な入力項目は、全イベント共通の項目（後述）を除いたものです。

セッション・プロンプトのイベント

ツール実行のイベント

応答・エージェント・タスクのイベント

設定・ファイル・その他のイベント

覚えておきたいのは「止めたいなら Pre 系、後処理なら Post 系」です。 PostToolUse はツールがすでに実行された後なので、取り消せません。

設定の書き方：イベント・matcher・ハンドラーの3段

{
  "hooks": {
    "イベント名": [
      {
        "matcher": "対象の絞り込み（ツール名など）",
        "hooks": [
          { "type": "command", "command": "実行するコマンド", "timeout": 60 }
        ]
      }
    ]
  }
}

同じイベントに当たったハンドラーは、すべて並列に実行されます（ドキュメント）。PreToolUse の判断が分かれたときは、より厳しいもの（deny → defer → ask → allow の順）が優先されます。

設定ファイルの場所

ドキュメントでは、フックは上書きではなく、すべての置き場所のものが合わさって（マージされて）動きます。 設定ファイルを直接書き換えると、通常はファイルの監視で自動的に読み直されます。

ハンドラーの種類（type）

UserPromptSubmit・PreModelSwitch・PostModelSwitch では command・http・mcp_tool の既定が 30 秒、MessageDisplay では 10 秒に下がります。SessionEnd のフックは全体で 1.5 秒の持ち時間を共有します（ドキュメント）。

ハンドラーに書ける項目

matcher の書き方

matcher は大文字・小文字を区別します。書き方で「完全一致」か「正規表現」かが自動で切り替わります（ドキュメント）。

正規表現は部分一致なので、Edit.* は NotebookEdit にも当たります。全体で一致させるなら ^Edit$ と書きます。matcher に対応しないイベント（UserPromptSubmit・Stop など）に書いた matcher は無視されます。

さらに引数で絞るなら if を使います。matcher でツールを選び、if で引数を絞ると整理できます。ドキュメントの Bash の判定例は次のとおりです。

実際に、後述の設定（deny-git-push.sh に "if": "Bash(git *)"）で動かすと、rm -rf ./tmpdir のときは Bash 用のフックが2つ、git push origin main のときは3つ起動しました。if は最善努力の絞り込みなので、確実に禁止したいものは権限ルールと組み合わせます。

入力：標準入力に届くJSON

command のフックには、標準入力（stdin）に JSON が1つ届きます（http では POST の本文）。全イベントに共通の項目は次のとおりです。

claude -p で実際に届いた JSON を、フックの中でそのまま保存したものです（ID は伏せています）。まず PreToolUse（Bash）です。

{
  "session_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "transcript_path": "/home/you/.claude/projects/-home-you-hooks-lab/xxxxxxxx.jsonl",
  "cwd": "/home/you/hooks-lab",
  "prompt_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "permission_mode": "auto",
  "effort": { "level": "medium" },
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "ls src", "description": "t6" },
  "tool_use_id": "toolu_msg_6"
}

PostToolUse には tool_response（実行結果）と duration_ms が加わります。Bash では標準出力・標準エラー出力が入っていました（共通項目は省略）。

{
  "hook_event_name": "PostToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "ls -1 src && echo rewritten-by-hook", "description": "rewritten" },
  "tool_response": { "stdout": "a.txt\nrewritten-by-hook", "stderr": "", "interrupted": false, "isImage": false, "noOutputExpected": false },
  "tool_use_id": "toolu_msg_6",
  "duration_ms": 12
}

Bash なら .tool_input.command、Edit・Write・Read なら .tool_input.file_path を取り出すのが基本です。

終了コードの意味（exit 0・exit 2・それ以外）

exit 1 では止まりません。 ドキュメントも「方針を強制するフックは exit 2 を使う」と注意しています。実際に PreToolUse のフックが stderr に something broke を出して exit 1 で終わると、フックの記録は "exit_code": 1, "outcome": "error" でしたが、Bash は実行されました。デバッグログには次の行が残りました。

[ERROR] "Hook PreToolUse:Bash (PreToolUse) error: status code 1\nstderr:\nsomething broke"

標準出力と終了コードの組み合わせで、結果は次のように決まります（ドキュメント）。

JSON出力の早見表（decision・additionalContext など）

exit 0 で、標準出力に JSON を1つだけ出すと、細かい制御ができます。全イベント共通の項目は次のとおりです。

イベントごとの「判断」の書き方は3通りに分かれます。

permissionDecision や additionalContext は hookSpecificOutput の中に書きます。 トップレベルに書くと、エラーにならずに無視されます。実際に {"permissionDecision":"deny",...} をトップレベルで返すとコマンドは実行され、claude --debug-file のログに次の行が残りました。

[DEBUG] Hook JSON output had unrecognized keys (ignored): permissionDecision, permissionDecisionReason.

additionalContext・systemMessage・テキストの stdout は、それぞれ 10,000 文字までです。超えた分はファイルに保存され、先頭 2,000 文字とファイルのパスに置き換わります（ドキュメント）。hookSpecificOutput を使うときは hookEventName にイベント名を入れます。

PreToolUse の allow を返しても、settings の deny ルールは越えられません。ドキュメントでは、フックは制限を強めることはできても、権限ルールより緩めることはできないと説明されています。逆に、PreToolUse の deny は bypassPermissions モードでも効きます。

すぐ使える設定例（settings.json 全文）

次の settings.json と .claude/hooks/ のスクリプトで、危険なコマンドの停止、git push の拒否、秘密ファイルの保護、編集後のフォーマット、コマンドの記録、日付の追加、通知、テストが通るまで終わらせない、圧縮後の再注入、をまとめて設定できます。プロジェクト直下の .claude/settings.json に置きます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/log-bash.sh" },
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous.sh" },
          { "type": "command", "if": "Bash(git *)", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/deny-git-push.sh" }
        ]
      },
      {
        "matcher": "Read|Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.sh", "statusMessage": "Prettier で整形中" }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/add-date.sh" }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/notify.sh" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stop-check.sh", "timeout": 120 }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          { "type": "command", "command": "echo '再確認：パッケージ管理は npm。コミット前に npm test を実行する。'" }
        ]
      }
    ]
  }
}

スクリプトには実行権限を付けます（chmod +x .claude/hooks/*.sh）。$CLAUDE_PROJECT_DIR はプロジェクトのルートで、作業ディレクトリが変わっても同じ場所を指します。パスに空白が入ることがあるため、ダブルクォートで囲んでいます。

例1：危険なコマンドを exit 2 で止める（PreToolUse）

#!/bin/bash
# .claude/hooks/block-dangerous.sh
# PreToolUse(Bash)：危険なコマンドを exit 2 で止める
INPUT=$(cat)
CMD=$(jq -r '.tool_input.command // empty' <<<"$INPUT")
if grep -Eq '(^|[;&|[:space:]])rm[[:space:]]+-[a-zA-Z]*(rf|fr)[a-zA-Z]*([[:space:]]|$)|git[[:space:]]+push[[:space:]].*(--force|-f)([[:space:]]|$)' <<<"$CMD"; then
  echo "Blocked by hook: '$CMD' は禁止しています。削除や強制 push は人が実行します。" >&2
  exit 2
fi
exit 0

ドキュメントの入力 JSON（tool_name: "Bash"・tool_input.command）を作って標準入力に流した結果です。

$ jq -nc '{hook_event_name:"PreToolUse",tool_name:"Bash",tool_input:{command:"rm -rf ./tmpdir"}}' \
    | .claude/hooks/block-dangerous.sh; echo "exit=$?"
Blocked by hook: 'rm -rf ./tmpdir' は禁止しています。削除や強制 push は人が実行します。
exit=2

claude -p で Claude が rm -rf ./tmpdir を実行しようとしたとき、Claude に返ったツールの結果は次のとおりで、tmpdir は消えずに残りました。--allowedTools で Bash を許可していても止まります。

PreToolUse:Bash hook error: ["$CLAUDE_PROJECT_DIR"/.claude/hooks/block-dangerous.sh]: Blocked by hook: 'rm -rf ./tmpdir' は禁止しています。削除や強制 push は人が実行します。

正規表現での禁止は、書き方を変えるとすり抜けます。 同じスクリプトに次のコマンドを流すと、どれも exit 0 でした。

フックは多層防御の1枚と考え、権限ルールの deny やサンドボックスと組み合わせます。

例2：git push を JSON で拒否する（理由つき）

#!/bin/bash
# .claude/hooks/deny-git-push.sh
# PreToolUse(Bash)：git push を JSON で deny（理由つき）
INPUT=$(cat)
CMD=$(jq -r '.tool_input.command // empty' <<<"$INPUT")
if grep -Eq '(^|[;&|[:space:]])git[[:space:]]+push([[:space:]]|$)' <<<"$CMD"; then
  jq -n --arg cmd "$CMD" '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: ("git push はレビュー後に人が実行します（hook で拒否）: " + $cmd)
    }
  }'
fi
exit 0

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "git push はレビュー後に人が実行します（hook で拒否）: git push origin main"
  }
}

claude -p では、Claude に次の結果が返りました。JSON の permissionDecisionReason がそのまま理由になっています。

PreToolUse:Bash hook error: git push はレビュー後に人が実行します（hook で拒否）: git push origin main

permissionDecision の値は4つです。allow は許可の確認を省く（ただし deny ルールは越えない）、deny は拒否して理由を Claude に渡す、ask は利用者に確認する、defer は -p の実行でツール呼び出しを保留して後で再開できるようにする、です。JSON は文字列の連結ではなく jq -n --arg で作ると、引用符や改行が正しくエスケープされます。

claude -p の最終結果（"type": "result"）の permission_denials には、exit 2 で止めた rm -rf、JSON で止めた git push、例3で止めた .env の読み取りの3件が並んで記録されていました。CI で「何を止めたか」を集計するときに使えます。

例3：.env や鍵ファイルを守る

#!/bin/bash
# .claude/hooks/protect-files.sh
# PreToolUse(Read|Edit|Write)：.env や鍵ファイルへのアクセスを止める
INPUT=$(cat)
FILE=$(jq -r '.tool_input.file_path // empty' <<<"$INPUT")
case "$FILE" in
  *.env|*.env.*|*/.git/*|*.pem|*id_rsa*)
    echo "Blocked by hook: $FILE は保護対象のファイルです" >&2
    exit 2 ;;
esac
exit 0

matcher に Read も入れているのは、書き込みだけでなく読み取りも止めるためです。claude -p で Claude が .env を Read しようとすると、PreToolUse:Read hook error: [...protect-files.sh]: Blocked by hook: /home/you/hooks-lab/.env は保護対象のファイルです が返りました。Bash の cat .env は別の経路なので、権限ルールの Read(./.env) の deny などと組み合わせます。

例4：編集後に Prettier で整形する（PostToolUse）

#!/bin/bash
# .claude/hooks/format.sh
# PostToolUse(Edit|Write)：編集したファイルを Prettier で整形
INPUT=$(cat)
FILE=$(jq -r '.tool_input.file_path // empty' <<<"$INPUT")
case "$FILE" in
  *.js|*.jsx|*.ts|*.tsx|*.json|*.css|*.md)
    cd "$CLAUDE_PROJECT_DIR" && npx --no-install prettier --write "$FILE" >&2 ;;
esac
exit 0

Prettier の出力（src/app2.js 44ms）は stderr に出したので、フックの記録に残るだけで会話には入りません。一方、フックがファイルを書き換えたことは、Claude Code が Claude に伝えていました。 次の要求に、この文が入っていました。

PostToolUse:Write hook additional context: PostToolUse hook modified /home/you/hooks-lab/src/app2.js after your edit (likely a formatter). Your next Edit will not fail with a stale-file error, but if its old_string targets a region the hook reformatted, Read the file first.

ドキュメントの例どおり1行で書くなら "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" です。Bash のコマンドがファイルを書き換えた場合も整形したいときは、FileChanged イベントを使う方法がドキュメントで案内されています。

例5：許可待ち・入力待ちを通知する（Notification）

#!/bin/bash
# .claude/hooks/notify.sh
# Notification：デスクトップ通知（OS ごとのコマンド）と端末への通知シーケンス
INPUT=$(cat)
MSG=$(jq -r '.message // "Claude Code が入力を待っています"' <<<"$INPUT")
if command -v osascript >/dev/null; then
  osascript -e "display notification \"$MSG\" with title \"Claude Code\"" >/dev/null 2>&1
elif command -v notify-send >/dev/null; then
  notify-send "Claude Code" "$MSG" >/dev/null 2>&1
fi
SEQ=$(printf '\033]777;notify;%s;%s\007' "Claude Code" "$MSG")
jq -nc --arg seq "$SEQ" '{terminalSequence: $seq}'

{"hook_event_name":"Notification","message":"Claude needs your permission to use Bash","notification_type":"permission_prompt"} を流すと、{"terminalSequence":"\u001b]777;notify;Claude Code;Claude needs your permission to use Bash\u0007"} が出力されました。ドキュメントでは、フックは端末を持たずに動くため /dev/tty に直接書けず、通知の端末シーケンスは terminalSequence で Claude Code に出してもらいます（対話モードのときだけ）。

macOS の osascript は、スクリプトエディタに通知の許可がないと何も出ません。Linux の notify-send は通知デーモンがない環境（SSH・コンテナ）では使えません（ドキュメント）。

例6：実行されたコマンドを記録する

#!/bin/bash
# .claude/hooks/log-bash.sh
# PreToolUse(Bash)：実行されようとしたコマンドを JSON Lines で記録
jq -c '{time: (now | todate), session: .session_id, cwd: .cwd, command: .tool_input.command}' \
  >> "$CLAUDE_PROJECT_DIR/.claude/bash-commands.log"
exit 0

{"time":"2026-10-16T07:33:08Z","session":"xxxxxxxx-...","cwd":"/home/you/hooks-lab","command":"rm -rf ./tmpdir"}
{"time":"2026-10-16T07:33:08Z","session":"xxxxxxxx-...","cwd":"/home/you/hooks-lab","command":"git push origin main"}
{"time":"2026-10-16T07:33:09Z","session":"xxxxxxxx-...","cwd":"/home/you/hooks-lab","command":"ls src"}

例1・例2で止めた rm -rf と git push も記録されています。同じイベントのフックは並列にすべて走るため、ほかのフックが拒否しても記録のフックは動きます。 ログのファイルは .gitignore に入れておきます。

例7：プロンプトに日付とブランチを足す（UserPromptSubmit）

#!/bin/bash
# .claude/hooks/add-date.sh
# UserPromptSubmit：プロンプトに今日の日付とブランチを足す
BRANCH=$(git -C "$CLAUDE_PROJECT_DIR" branch --show-current 2>/dev/null)
jq -n --arg d "$(date '+%Y-%m-%d (%a) %H:%M %Z')" --arg b "${BRANCH:-unknown}" '{
  hookSpecificOutput: {
    hookEventName: "UserPromptSubmit",
    additionalContext: ("現在の日時は " + $d + "。作業中のブランチは " + $b + "。")
  }
}'

claude -p では、Claude への要求に次の1行が入っていました。

UserPromptSubmit hook additional context: 現在の日時は 2026-10-16 (Fri) 16:33 JST。作業中のブランチは master。

UserPromptSubmit は、JSON を使わずに echo したテキストも文脈に入ります。ドキュメントは、additionalContext は命令ではなく事実として書くよう勧めています（命令調だとプロンプトインジェクションの防御に引っかかることがあるため）。--resume で再開すると、過去のターンの値は再実行されずに保存済みのものが使われます。

例8：テストが通るまで終わらせない（Stop）

#!/bin/bash
# .claude/hooks/stop-check.sh
# Stop：テストが通るまで終わらせない（無限ループ防止つき）
INPUT=$(cat)
if [ "$(jq -r '.stop_hook_active' <<<"$INPUT")" = "true" ]; then
  exit 0   # すでに一度続行させている
fi
cd "$CLAUDE_PROJECT_DIR" || exit 0
if ! OUT=$(npm test --silent 2>&1); then
  jq -n --arg out "$(tail -n 20 <<<"$OUT")" '{decision: "block", reason: ("npm test が失敗しています。失敗を直してから応答を終えること。\n" + $out)}'
fi
exit 0

claude -p では、1回目の Stop で会話が続き、Claude には Stop hook feedback: に続けて理由の文が渡されました。2回目の Stop は stop_hook_active: true だったため、そのまま終わりました。stop_hook_active を見ないと、Stop フックが止め続けます。 ドキュメントでは、ツール呼び出しを挟まずに8回続けて止めると Claude Code が上書きして終わらせ、上限は CLAUDE_CODE_STOP_HOOK_BLOCK_CAP で変えられます。

例9：圧縮（compact）の後に大事な文脈を入れ直す

settings.json の SessionStart の "matcher": "compact" がこの例です。SessionStart はテキストの stdout が文脈に入るため、echo だけで足せます。git log --oneline -5 のような動的な出力にも置き換えられます（ドキュメントの例）。毎回のセッション開始で入れたい固定の内容は、CLAUDE.md に書くほうが簡単です。

例10：コマンドを書き換える（updatedInput）

PreToolUse の hookSpecificOutput.updatedInput で、ツールの引数を実行前に置き換えられます。ls src を書き換えるフックで試しました。

jq -n '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "allow",
  updatedInput: {command: "ls -1 src && echo rewritten-by-hook", description: "rewritten"}}}'

Claude に返った結果は a.txt と rewritten-by-hook で、書き換えたコマンドが実行されていました。デバッグログには modified tool input keys: [command, description] と記録されました。ドキュメントでは、複数のフックが同じツールの updatedInput を返すと、最後に終わったものが使われ、順番は決まりません。

デバッグ方法：動いたか・何を返したかを確かめる

まずはスクリプト単体で確かめます。

echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./.claude/hooks/block-dangerous.sh
echo $?   # 0 なら止めない、2 なら止める

--include-hook-events では、フックごとに次のような記録が出ました（ID は省略）。

{"type":"system","subtype":"hook_response","hook_name":"PreToolUse:Bash","hook_event":"PreToolUse","stdout":"","stderr":"Blocked by hook: 'rm -rf ./tmpdir' は禁止しています。削除や強制 push は人が実行します。\n","exit_code":2,"outcome":"error"}

デバッグログ（--debug-file）で役に立った行です。

よくあるつまずきと直し方

いくつかは claude -p で実際に起こしました。

• パスの誤り：存在しないスクリプトを登録すると、記録は "exit_code": 127, "outcome": "error" で、Bash はそのまま実行されました
• onFailure: "block"：同じく存在しないスクリプトに "onFailure": "block" を付けると、ツールは止まり、Claude に PreToolUse:Bash hook error: [node ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js]: failed; blocking because onFailure is "block" と Error: Cannot find module ... が返りました
• プロファイルの出力：JSON の前に Shell ready on arm64 を出すと、deny の JSON は読まれず、コマンドは実行されました
• タイムアウト："timeout": 2 のフックで 5 秒待つと、記録は "outcome": "cancelled" で、exit 2 を返す前に打ち切られ、Bash は実行されました

シェルのプロファイルの echo は、ドキュメントの方法で対話シェルのときだけ出すようにします。

# ~/.zshrc や ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

止め方・無効化

--settings '{"disableAllHooks": true}' と --bare の両方で claude -p を動かすと、プロジェクトの .claude/settings.json のフックは1つも起動しませんでした。ドキュメントでは、disableAllHooks は設定の優先順位を適用した後の値で決まるため、ユーザー設定の true はプロジェクトの false で上書きされます。--settings で渡したものはプロジェクトやローカルの設定より優先されます。

管理ポリシー（managed settings）で配られたフックは、ユーザー・プロジェクト・ローカルの disableAllHooks では止まりません。 管理側の設定でだけ止められます。管理側で allowManagedHooksOnly が設定されていると、ユーザー・プロジェクト・ローカル・プラグインのフックは動かず、/hooks には Only hooks from managed settings run here と表示されます（ドキュメント）。

セキュリティ上の注意

フックは、あなたのユーザー権限で、確認なしにコマンドを実行します。

• 他人のリポジトリの .claude/settings.json を確かめてから使う：今回、まだ信頼（trust）の確認をしていないフォルダーで claude -p を実行しても、プロジェクトの .claude/settings.json のフックは動きました。CI などで読み込む範囲を絞るなら、--bare や --setting-sources を使います
• 変数はダブルクォートで囲む："$FILE" のようにしないと、空白や記号を含むパスで想定外の動きになります。パスの置き換えを使うなら、args を付けたシェルを通さない形（exec form）がドキュメントで勧められています
• 入力を eval しない：標準入力の JSON は Claude が組み立てた値です。判定に使い、コマンドとして実行しないようにします
• 正規表現での禁止はすり抜けを前提にする：例1の表のとおりです。権限ルール（deny）やサンドボックスと組み合わせます
• .env や鍵は読み取りも守る：Edit・Write だけでなく Read、Bash の cat にも目を配ります
• HTTP フックのヘッダーに入れる環境変数は allowedEnvVars に書いたものだけ展開されます。秘密情報は設定ファイルに直接書きません
• additionalContext に外部の内容をそのまま入れない：Claude の文脈に入るため、外部の文に仕込まれた指示が混ざる危険があります

よくある質問

Q. claude hooks（Claude Code の Hooks）とは何ですか？ A. Claude Code の決まったタイミング（ツールの実行前後、プロンプトの送信、応答の終了など33のイベント）で、自分のコマンド・HTTP・MCP ツールなどを必ず実行させる仕組みです。settings.json の hooks に書きます。

Q. hooks は Claude Code のどこに設定しますか？ A. 全プロジェクト共通なら ~/.claude/settings.json、チームで共有するなら .claude/settings.json、自分だけの実験なら .claude/settings.local.json です。すべて合わさって動きます。設定後は /hooks で確かめます。

Q. Claude Code の hook が動きません。 A. /hooks に出るか、イベント名と matcher の大文字小文字、スクリプトの実行権限（chmod +x）、パス（"$CLAUDE_PROJECT_DIR"/...）を確かめます。サンプル JSON をパイプで流して単体で動くかを見て、それでも分からなければ claude --debug-file のログを見ます。

Q. PreToolUse で exit 0 を返せば、そのツールは許可されますか？ A. いいえ。exit 0 は「フックとしては反対しない」という意味で、通常の許可判定に進みます。確認を省きたいときは JSON で permissionDecision: "allow" を返します。ただし settings の deny ルールは越えられません。

Q. PostToolUse でテストが失敗したら、編集を取り消せますか？ A. 取り消せません。ツールは実行済みです。トップレベルの "decision": "block" と reason を返すか exit 2 で stderr を渡して Claude に直させるか、事前に止めたいなら PreToolUse で判断します。

Q. Hooks は有料プランでないと使えませんか？ A. Hooks は Claude Code の機能で、設定ファイルに書けば使えます。type: "prompt" と type: "agent" はモデルを呼ぶため、その分の利用量がかかります。

Q. Windows でも使えますか？ A. 使えます。ドキュメントでは、シェルの形のコマンドは Git Bash（なければ PowerShell）で動き、"shell": "powershell" で PowerShell を選べます。npx などの .cmd は、args を付けた形では直接起動できないため、シェルの形で書くか node からスクリプトを起動します。

まとめ

• Hooks は33のイベントで必ず動く処理。止めたいなら Pre 系、後処理なら Post 系
• 設定は イベント → matcher → ハンドラー の3段。matcher は大文字小文字を区別し、記号を含むと正規表現。引数は if で絞る
• 止めるなら exit 2 ＋ stderr。exit 1 では止まらない
• 理由つきの拒否・確認・書き換えは exit 0 ＋ JSON。項目は hookSpecificOutput の中
• フックは並列にすべて走る。拒否されても記録のフックは動く
• PostToolUse のフォーマッターの変更は Claude に伝えられる
• 動かないときは サンプル JSON のパイプ実行 → /hooks → --debug-file
• 止めるなら disableAllHooks（1回なら --settings）か --bare。管理ポリシーのフックは管理側でしか止まらない
• フックは自分の権限で動く。他人の設定を確かめ、正規表現のすり抜けを前提に多層で守る

参考・出典

確認日はいずれも 2026年10月16日です。

• Claude Code ドキュメント「Hooks reference」：https://code.claude.com/docs/en/hooks
• Claude Code ドキュメント「Automate actions with hooks」（hooks ガイド）：https://code.claude.com/docs/en/hooks-guide
• Claude Code ドキュメントの一覧：https://code.claude.com/docs/en/claude_code_docs_map.md
• @anthropic-ai/claude-code（npm）：https://www.npmjs.com/package/@anthropic-ai/claude-code
• @anthropic-ai/claude-agent-sdk（npm、フックの入力・出力の型定義）：https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk
• Bash command validator のサンプル（GitHub）：https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。