例を含むクイックスタートガイドについては、Claude Codeフックを始めるを参照してください。

設定

Claude Codeフックは設定ファイルで設定されます:

  • ~/.claude/settings.json - ユーザー設定
  • .claude/settings.json - プロジェクト設定
  • .claude/settings.local.json - ローカルプロジェクト設定(コミットされない)
  • エンタープライズ管理ポリシー設定

構造

フックはマッチャーによって整理され、各マッチャーは複数のフックを持つことができます:

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}
  • matcher: ツール名にマッチするパターン、大文字小文字を区別(PreToolUsePostToolUseにのみ適用)
    • 単純な文字列は完全一致:WriteはWriteツールのみにマッチ
    • 正規表現をサポート:Edit|WriteまたはNotebook.*
    • すべてのツールにマッチするには*を使用。空文字列("")を使用するか、matcherを空白のままにすることもできます。
  • hooks: パターンがマッチしたときに実行するコマンドの配列
    • type: 現在は"command"のみサポート
    • command: 実行するbashコマンド($CLAUDE_PROJECT_DIR環境変数を使用可能)
    • timeout: (オプション)特定のコマンドをキャンセルするまでの実行時間(秒)

UserPromptSubmitNotificationStopSubagentStopなどのマッチャーを使用しないイベントの場合、matcherフィールドを省略できます:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/prompt-validator.py"
          }
        ]
      }
    ]
  }
}

プロジェクト固有のフックスクリプト

環境変数CLAUDE_PROJECT_DIR(Claude Codeがフックコマンドを生成するときのみ利用可能)を使用して、プロジェクトに保存されたスクリプトを参照でき、Claudeの現在のディレクトリに関係なく動作することを保証できます:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/check-style.sh"
          }
        ]
      }
    ]
  }
}

フックイベント

PreToolUse

Claudeがツールパラメータを作成した後、ツール呼び出しを処理する前に実行されます。

一般的なマッチャー:

  • Task - エージェントタスク
  • Bash - シェルコマンド
  • Glob - ファイルパターンマッチング
  • Grep - コンテンツ検索
  • Read - ファイル読み取り
  • EditMultiEdit - ファイル編集
  • Write - ファイル書き込み
  • WebFetchWebSearch - Web操作

PostToolUse

ツールが正常に完了した直後に実行されます。

PreToolUseと同じマッチャー値を認識します。

Notification

Claude Codeが通知を送信するときに実行されます。通知は以下の場合に送信されます:

  1. Claudeがツールを使用する許可が必要な場合。例:「ClaudeがBashを使用する許可が必要です」
  2. プロンプト入力が少なくとも60秒間アイドル状態の場合。「Claudeがあなたの入力を待っています」

UserPromptSubmit

ユーザーがプロンプトを送信したとき、Claudeが処理する前に実行されます。これにより、プロンプト/会話に基づいて追加のコンテキストを追加したり、プロンプトを検証したり、特定のタイプのプロンプトをブロックしたりできます。

Stop

メインのClaude Codeエージェントが応答を完了したときに実行されます。ユーザーの中断による停止の場合は実行されません。

SubagentStop

Claude Codeサブエージェント(Taskツール呼び出し)が応答を完了したときに実行されます。

PreCompact

Claude Codeがコンパクト操作を実行しようとする前に実行されます。

マッチャー:

  • manual - /compactから呼び出し
  • auto - 自動コンパクトから呼び出し(コンテキストウィンドウが満杯のため)

フック入力

フックは、セッション情報とイベント固有のデータを含むJSONデータをstdinを介して受信します:

{
  // 共通フィールド
  session_id: string
  transcript_path: string  // 会話JSONへのパス
  cwd: string              // フックが呼び出されたときの現在の作業ディレクトリ

  // イベント固有のフィールド
  hook_event_name: string
  ...
}

PreToolUse入力

tool_inputの正確なスキーマはツールによって異なります。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  }
}

PostToolUse入力

tool_inputtool_responseの正確なスキーマはツールによって異なります。

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "success": true
  }
}

Notification入力

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Task completed successfully"
}

UserPromptSubmit入力

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "Write a function to calculate the factorial of a number"
}

StopとSubagentStop入力

stop_hook_activeは、Claude Codeがすでにストップフックの結果として継続している場合にtrueになります。この値をチェックするか、トランスクリプトを処理してClaude Codeが無限に実行されることを防いでください。

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "hook_event_name": "Stop",
  "stop_hook_active": true
}

PreCompact入力

manualの場合、custom_instructionsはユーザーが/compactに渡すものから来ます。autoの場合、custom_instructionsは空です。

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": ""
}

フック出力

フックがClaude Codeに出力を返す方法は2つあります。出力は、ブロックするかどうかと、Claudeとユーザーに表示すべきフィードバックを伝達します。

シンプル:終了コード

フックは終了コード、stdout、stderrを通じてステータスを伝達します:

  • 終了コード0: 成功。stdoutはトランスクリプトモード(CTRL-R)でユーザーに表示されますが、UserPromptSubmitの場合は例外で、stdoutがコンテキストに追加されます。
  • 終了コード2: ブロッキングエラー。stderrがClaudeに自動的にフィードバックされ処理されます。以下のフックイベント別の動作を参照してください。
  • その他の終了コード: 非ブロッキングエラー。stderrがユーザーに表示され、実行が継続されます。

注意:Claude Codeは終了コードが0の場合stdoutを見ませんが、UserPromptSubmitフックの場合は例外で、stdoutがコンテキストとして注入されます。

終了コード2の動作

フックイベント動作
PreToolUseツール呼び出しをブロックし、stderrをClaudeに表示
PostToolUsestderrをClaudeに表示(ツールは既に実行済み)
NotificationN/A、stderrをユーザーのみに表示
UserPromptSubmitプロンプト処理をブロックし、プロンプトを消去し、stderrをユーザーのみに表示
Stop停止をブロックし、stderrをClaudeに表示
SubagentStop停止をブロックし、stderrをClaudeサブエージェントに表示
PreCompactN/A、stderrをユーザーのみに表示

高度:JSON出力

フックは、より洗練された制御のためにstdoutで構造化JSONを返すことができます:

共通JSONフィールド

すべてのフックタイプは、これらのオプションフィールドを含むことができます:

{
  "continue": true, // フック実行後にClaudeが継続すべきかどうか(デフォルト:true)
  "stopReason": "string" // continueがfalseの場合に表示されるメッセージ
  "suppressOutput": true, // トランスクリプトモードからstdoutを隠す(デフォルト:false)
}

continueがfalseの場合、Claudeはフック実行後に処理を停止します。

  • PreToolUseの場合、これは"permissionDecision": "deny"とは異なり、特定のツール呼び出しのみをブロックしてClaudeに自動フィードバックを提供します。
  • PostToolUseの場合、これは"decision": "block"とは異なり、Claudeに自動フィードバックを提供します。
  • UserPromptSubmitの場合、これはプロンプトが処理されることを防ぎます。
  • StopSubagentStopの場合、これは任意の"decision": "block"出力よりも優先されます。
  • すべての場合において、"continue" = falseは任意の"decision": "block"出力よりも優先されます。

stopReasoncontinueに伴い、ユーザーに表示される理由を提供しますが、Claudeには表示されません。

PreToolUse決定制御

PreToolUseフックは、ツール呼び出しが進行するかどうかを制御できます。

  • "allow"は許可システムをバイパスします。permissionDecisionReasonはユーザーに表示されますが、Claudeには表示されません。(非推奨の"approve"値 + reasonも同じ動作をします。
  • "deny"はツール呼び出しの実行を防ぎます。permissionDecisionReasonはClaudeに表示されます。("block"値 + reasonも同じ動作をします。
  • "ask"はユーザーにUIでツール呼び出しを確認するよう求めます。permissionDecisionReasonはユーザーに表示されますが、Claudeには表示されません。
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow" | "deny" | "ask",
    "permissionDecisionReason": "My reason here (shown to user)"
  },
  "decision": "approve" | "block" | undefined, // PreToolUseでは非推奨だが、まだサポートされている
  "reason": "Explanation for decision" // PreToolUseでは非推奨だが、まだサポートされている
}

PostToolUse決定制御

PostToolUseフックは、ツール呼び出しが進行するかどうかを制御できます。

  • "block"は自動的にClaudeにreasonでプロンプトします。
  • undefinedは何もしません。reasonは無視されます。
{
  "decision": "block" | undefined,
  "reason": "Explanation for decision"
}

UserPromptSubmit決定制御

UserPromptSubmitフックは、ユーザープロンプトが処理されるかどうかを制御できます。

  • "block"はプロンプトが処理されることを防ぎます。送信されたプロンプトはコンテキストから消去されます。"reason"はユーザーに表示されますが、コンテキストには追加されません。
  • undefinedはプロンプトが正常に進行することを許可します。"reason"は無視されます。
  • "hookSpecificOutput.additionalContext"は、ブロックされていない場合に文字列をコンテキストに追加します。
{
  "decision": "block" | undefined,
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here"
  }
}

Stop/SubagentStop決定制御

StopSubagentStopフックは、Claudeが継続しなければならないかどうかを制御できます。

  • "block"はClaudeが停止することを防ぎます。Claudeがどのように進行すべきかを知るためにreasonを入力する必要があります。
  • undefinedはClaudeが停止することを許可します。reasonは無視されます。
{
  "decision": "block" | undefined,
  "reason": "Must be provided when Claude is blocked from stopping"
}

終了コード例:Bashコマンド検証

#!/usr/bin/env python3
import json
import re
import sys

# 検証ルールを(正規表現パターン、メッセージ)タプルのリストとして定義
VALIDATION_RULES = [
    (
        r"\bgrep\b(?!.*\|)",
        "Use 'rg' (ripgrep) instead of 'grep' for better performance and features",
    ),
    (
        r"\bfind\s+\S+\s+-name\b",
        "Use 'rg --files | rg pattern' or 'rg --files -g pattern' instead of 'find -name' for better performance",
    ),
]


def validate_command(command: str) -> list[str]:
    issues = []
    for pattern, message in VALIDATION_RULES:
        if re.search(pattern, command):
            issues.append(message)
    return issues


try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})
command = tool_input.get("command", "")

if tool_name != "Bash" or not command:
    sys.exit(1)

# コマンドを検証
issues = validate_command(command)

if issues:
    for message in issues:
        print(f"• {message}", file=sys.stderr)
    # 終了コード2はツール呼び出しをブロックし、stderrをClaudeに表示
    sys.exit(2)

JSON出力例:コンテキスト追加と検証のためのUserPromptSubmit

UserPromptSubmitフックの場合、どちらの方法でもコンテキストを注入できます:

  • 終了コード0とstdout:Claudeがコンテキストを見る(UserPromptSubmitの特別なケース)
  • JSON出力:動作をより詳細に制御
#!/usr/bin/env python3
import json
import sys
import re
import datetime

# stdinから入力を読み込み
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

prompt = input_data.get("prompt", "")

# 機密パターンをチェック
sensitive_patterns = [
    (r"(?i)\b(password|secret|key|token)\s*[:=]", "Prompt contains potential secrets"),
]

for pattern, message in sensitive_patterns:
    if re.search(pattern, prompt):
        # JSON出力を使用して特定の理由でブロック
        output = {
            "decision": "block",
            "reason": f"Security policy violation: {message}. Please rephrase your request without sensitive information."
        }
        print(json.dumps(output))
        sys.exit(0)

# 現在時刻をコンテキストに追加
context = f"Current time: {datetime.datetime.now()}"
print(context)

"""
以下も同等です:
print(json.dumps({
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": context,
  },
}))
"""

# 追加コンテキストでプロンプトの進行を許可
sys.exit(0)

JSON出力例:承認付きPreToolUse

#!/usr/bin/env python3
import json
import sys

# stdinから入力を読み込み
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})

# 例:ドキュメントファイルのファイル読み取りを自動承認
if tool_name == "Read":
    file_path = tool_input.get("file_path", "")
    if file_path.endswith((".md", ".mdx", ".txt", ".json")):
        # JSON出力を使用してツール呼び出しを自動承認
        output = {
            "decision": "approve",
            "reason": "Documentation file auto-approved",
            "suppressOutput": True  # トランスクリプトモードで表示しない
        }
        print(json.dumps(output))
        sys.exit(0)

# その他の場合、通常の許可フローを進行させる
sys.exit(0)

MCPツールとの連携

Claude CodeフックはModel Context Protocol (MCP) ツールとシームレスに連携します。MCPサーバーがツールを提供する場合、フックでマッチできる特別な命名パターンで表示されます。

MCPツールの命名

MCPツールはmcp__<server>__<tool>のパターンに従います。例:

  • mcp__memory__create_entities - Memoryサーバーのcreate entitiesツール
  • mcp__filesystem__read_file - Filesystemサーバーのread fileツール
  • mcp__github__search_repositories - GitHubサーバーの検索ツール

MCPツール用のフック設定

特定のMCPツールまたはMCPサーバー全体をターゲットにできます:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
          }
        ]
      },
      {
        "matcher": "mcp__.*__write.*",
        "hooks": [
          {
            "type": "command",
            "command": "/home/user/scripts/validate-mcp-write.py"
          }
        ]
      }
    ]
  }
}

コードフォーマット、通知、ファイル保護を含む実用的な例については、開始ガイドのその他の例を参照してください。

セキュリティ考慮事項

免責事項

自己責任で使用してください:Claude Codeフックは、システム上で任意のシェルコマンドを自動的に実行します。フックを使用することで、以下を認めることになります:

  • 設定するコマンドについて、あなたが単独で責任を負う
  • フックは、あなたのユーザーアカウントがアクセスできる任意のファイルを変更、削除、またはアクセスできる
  • 悪意のあるまたは不適切に書かれたフックは、データ損失やシステム損傷を引き起こす可能性がある
  • Anthropicは保証を提供せず、フック使用による損害について一切の責任を負わない
  • 本番環境で使用する前に、安全な環境でフックを十分にテストすべきである

設定に追加する前に、常にフックコマンドを確認し理解してください。

セキュリティのベストプラクティス

より安全なフックを書くための主要な実践方法:

  1. 入力を検証し無害化する - 入力データを盲目的に信頼しない
  2. 常にシェル変数を引用符で囲む - $VARではなく"$VAR"を使用
  3. パストラバーサルをブロックする - ファイルパスで..をチェック
  4. 絶対パスを使用する - スクリプトの完全パスを指定(プロジェクトパスには$CLAUDE_PROJECT_DIRを使用)
  5. 機密ファイルをスキップする - .env.git/、キーなどを避ける

設定の安全性

設定ファイルでのフックの直接編集は、すぐには有効になりません。Claude Codeは:

  1. 起動時にフックのスナップショットを取得
  2. セッション全体でこのスナップショットを使用
  3. フックが外部で変更された場合に警告
  4. 変更を適用するために/hooksメニューでの確認が必要

これにより、悪意のあるフック変更が現在のセッションに影響することを防ぎます。

フック実行の詳細

  • タイムアウト:デフォルトで60秒の実行制限、コマンドごとに設定可能。
    • 個別のコマンドのタイムアウトは他のコマンドに影響しません。
  • 並列化:マッチするすべてのフックが並列で実行
  • 環境:Claude Codeの環境で現在のディレクトリで実行
    • CLAUDE_PROJECT_DIR環境変数が利用可能で、プロジェクトルートディレクトリの絶対パスが含まれます
  • 入力:stdinを介したJSON
  • 出力
    • PreToolUse/PostToolUse/Stop:トランスクリプト(Ctrl-R)で進行状況表示
    • Notification:デバッグのみにログ(--debug

デバッグ

基本的なトラブルシューティング

フックが動作しない場合:

  1. 設定を確認 - /hooksを実行してフックが登録されているかを確認
  2. 構文を検証 - JSON設定が有効であることを確認
  3. コマンドをテスト - まずフックコマンドを手動で実行
  4. 権限を確認 - スクリプトが実行可能であることを確認
  5. ログを確認 - claude --debugを使用してフック実行の詳細を確認

一般的な問題:

  • 引用符がエスケープされていない - JSON文字列内で\"を使用
  • 間違ったマッチャー - ツール名が完全に一致することを確認(大文字小文字を区別)
  • コマンドが見つからない - スクリプトの完全パスを使用

高度なデバッグ

複雑なフックの問題の場合:

  1. フック実行を検査 - claude --debugを使用して詳細なフック実行を確認
  2. JSONスキーマを検証 - 外部ツールでフック入力/出力をテスト
  3. 環境変数を確認 - Claude Codeの環境が正しいことを確認
  4. エッジケースをテスト - 異常なファイルパスや入力でフックを試す
  5. システムリソースを監視 - フック実行中のリソース枯渇をチェック
  6. 構造化ログを使用 - フックスクリプトでログを実装

デバッグ出力例

claude --debugを使用してフック実行の詳細を確認:

[DEBUG] Executing hooks for PostToolUse:Write
[DEBUG] Getting matching hook commands for PostToolUse with query: Write
[DEBUG] Found 1 hook matchers in settings
[DEBUG] Matched 1 hooks for query "Write"
[DEBUG] Found 1 hook commands to execute
[DEBUG] Executing hook command: <Your command> with timeout 60000ms
[DEBUG] Hook command completed with status 0: <Your stdout>

進行状況メッセージはトランスクリプトモード(Ctrl-R)に表示され、以下を示します:

  • 実行中のフック
  • 実行されるコマンド
  • 成功/失敗ステータス
  • 出力またはエラーメッセージ