Hooksリファレンス

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

設定

Claude Code hooksは設定ファイルで設定されます：

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

構造

Hooksはマッチャーで整理され、各マッチャーは複数のhooksを持つことができます：

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

matcher: ツール名にマッチするパターン、大文字小文字を区別（PreToolUseとPostToolUseにのみ適用）
- 単純な文字列は完全にマッチします：WriteはWriteツールのみにマッチします
- 正規表現をサポート：Edit|WriteまたはNotebook.*
- *を使用してすべてのツールにマッチさせます。空の文字列（""）を使用することもできます、またはmatcherを空白のままにします。
hooks: パターンがマッチしたときに実行するコマンドの配列
- type: 現在のところ"command"のみがサポートされています
- command: 実行するbashコマンド（$CLAUDE_PROJECT_DIR環境変数を使用できます）
- timeout: （オプション）コマンドがキャンセルされるまでの実行時間（秒単位）。

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

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

プロジェクト固有のHookスクリプト

環境変数CLAUDE_PROJECT_DIR（Claude Codeがhookコマンドをスポーンするときのみ利用可能）を使用して、プロジェクトに保存されているスクリプトを参照し、Claudeの現在のディレクトリに関係なく動作することを確認できます：

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

プラグインhooks

プラグインは、ユーザーおよびプロジェクトhooksとシームレスに統合するhooksを提供できます。プラグインhooksは、プラグインが有効になると、自動的に設定とマージされます。 プラグインhooksの動作方法：

プラグインhooksはプラグインのhooks/hooks.jsonファイル、またはhooksフィールドへのカスタムパスで指定されたファイルで定義されます。
プラグインが有効になると、そのhooksはユーザーおよびプロジェクトhooksとマージされます
異なるソースからの複数のhooksが同じイベントに応答できます
プラグインhooksは${CLAUDE_PLUGIN_ROOT}環境変数を使用してプラグインファイルを参照します

プラグインhook設定の例：

{
  "description": "自動コードフォーマット",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

プラグインhooksは通常のhooksと同じ形式を使用し、hookの目的を説明するオプションのdescriptionフィールドを持ちます。

プラグインhooksはカスタムhooksと並行して実行されます。複数のhooksがイベントにマッチする場合、すべてが並行して実行されます。

プラグイン用の環境変数：

${CLAUDE_PLUGIN_ROOT}: プラグインディレクトリへの絶対パス
${CLAUDE_PROJECT_DIR}: プロジェクトルートディレクトリ（プロジェクトhooksと同じ）
すべての標準環境変数が利用可能です

プラグインhooksの作成の詳細については、プラグインコンポーネントリファレンスを参照してください。

Hook イベント

PreToolUse

Claudeがツールパラメータを作成した後、ツール呼び出しを処理する前に実行されます。 一般的なマッチャー：

Task - サブエージェントタスク（サブエージェントドキュメントを参照）
Bash - シェルコマンド
Glob - ファイルパターンマッチング
Grep - コンテンツ検索
Read - ファイル読み取り
Edit - ファイル編集
Write - ファイル書き込み
WebFetch、WebSearch - Web操作

PostToolUse

ツールが正常に完了した直後に実行されます。 PreToolUseと同じマッチャー値を認識します。

Notification

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

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

UserPromptSubmit

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

Stop

メインのClaude Codeエージェントが応答を完了したときに実行されます。ユーザーの割り込みが原因で停止が発生した場合は実行されません。

SubagentStop

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

PreCompact

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

manual - /compactから呼び出された
auto - 自動コンパクトから呼び出された（コンテキストウィンドウが満杯のため）

SessionStart

Claude Codeが新しいセッションを開始するか、既存のセッションを再開するときに実行されます（現在のところ、内部的には新しいセッションを開始します）。既存の問題や最近のコードベースの変更などの開発コンテキストをロードしたり、依存関係をインストールしたり、環境変数を設定したりするのに役立ちます。 マッチャー：

startup - スタートアップから呼び出された
resume - --resume、--continue、または/resumeから呼び出された
clear - /clearから呼び出された
compact - 自動または手動コンパクトから呼び出された。

環境変数の永続化

SessionStart hooksはCLAUDE_ENV_FILE環境変数にアクセスでき、後続のbashコマンド用に環境変数を永続化できるファイルパスを提供します。 例：個別の環境変数を設定する

#!/bin/bash

if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export API_KEY=your-api-key' >> "$CLAUDE_ENV_FILE"
  echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
fi

exit 0

例：hookからのすべての環境変更を永続化する セットアップが環境を変更する場合（例：nvm use）、環境をdiffして、すべての変更をキャプチャして永続化します：

#!/bin/bash

ENV_BEFORE=$(export -p | sort)

# 環境を変更するセットアップコマンドを実行します
source ~/.nvm/nvm.sh
nvm use 20

if [ -n "$CLAUDE_ENV_FILE" ]; then
  ENV_AFTER=$(export -p | sort)
  comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
fi

exit 0

このファイルに書き込まれた変数は、セッション中にClaude Codeが実行するすべての後続のbashコマンドで利用可能になります。

CLAUDE_ENV_FILEはSessionStart hooksでのみ利用可能です。他のhookタイプはこの変数にアクセスできません。

SessionEnd

Claude Codeセッションが終了するときに実行されます。クリーンアップタスク、セッション統計のログ、またはセッション状態の保存に役立ちます。 hook入力のreasonフィールドは以下のいずれかになります：

clear - /clearコマンドでセッションがクリアされた
logout - ユーザーがログアウトした
prompt_input_exit - プロンプト入力が表示されている間にユーザーが終了した
other - その他の終了理由

Hook入力

Hooksはstdinを介してセッション情報とイベント固有のデータを含むJSONデータを受け取ります：

{
  // 共通フィールド
  session_id: string
  transcript_path: string  // 会話JSONへのパス
  cwd: string              // hookが呼び出されるときの現在の作業ディレクトリ
  permission_mode: string  // 現在の許可モード："default"、"plan"、"acceptEdits"、または"bypassPermissions"

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

PreToolUse入力

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

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

PostToolUse入力

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

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

StopおよびSubagentStop入力

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

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "permission_mode": "default",
  "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",
  "permission_mode": "default",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": ""
}

SessionStart入力

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "permission_mode": "default",
  "hook_event_name": "SessionStart",
  "source": "startup"
}

SessionEnd入力

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SessionEnd",
  "reason": "exit"
}

Hook出力

Hooksがoutputをclaude Codeに返す方法は2つあります。出力は、ブロックするかどうか、およびClaudeとユーザーに表示されるべきフィードバックを通信します。

シンプル：終了コード

Hooksは終了コード、stdout、およびstderrを通じてステータスを通信します：

終了コード0：成功。stdoutはトランスクリプトモード（CTRL-R）でユーザーに表示されます。ただし、UserPromptSubmitとSessionStartの場合は、stdoutがコンテキストに追加されます。
終了コード2：ブロッキングエラー。stderrはClaudeに自動的に処理されるようにフィードバックされます。hook固有のイベント動作については以下を参照してください。
その他の終了コード：ブロッキングなしのエラー。stderrはユーザーに表示され、実行は続行されます。

リマインダー：Claude Codeは終了コードが0の場合、stdoutを表示しません。ただし、UserPromptSubmit hookの場合は例外で、stdoutがコンテキストとして注入されます。

終了コード2の動作

Hook イベント	動作
`PreToolUse`	ツール呼び出しをブロック、stderrをClaudeに表示
`PostToolUse`	stderrをClaudeに表示（ツールはすでに実行済み）
`Notification`	N/A、stderrをユーザーのみに表示
`UserPromptSubmit`	プロンプト処理をブロック、プロンプトを消去、stderrをユーザーのみに表示
`Stop`	停止をブロック、stderrをClaudeに表示
`SubagentStop`	停止をブロック、stderrをClaudeサブエージェントに表示
`PreCompact`	N/A、stderrをユーザーのみに表示
`SessionStart`	N/A、stderrをユーザーのみに表示
`SessionEnd`	N/A、stderrをユーザーのみに表示

高度な：JSON出力

Hooksは、より高度な制御のためにstdoutで構造化されたJSONを返すことができます：

共通JSONフィールド

すべてのhookタイプは、これらのオプションフィールドを含めることができます：

{
  "continue": true, // hookの実行後にClaudeが続行するかどうか（デフォルト：true）
  "stopReason": "string", // continueがfalseの場合に表示されるメッセージ

  "suppressOutput": true, // トランスクリプトモードからstdoutを非表示にする（デフォルト：false）
  "systemMessage": "string" // ユーザーに表示されるオプションの警告メッセージ
}

continueがfalseの場合、hooksが実行された後、Claudeは処理を停止します。

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

stopReasonはcontinueに付随し、ユーザーに表示される理由を示し、Claudeには表示されません。

`PreToolUse`決定制御

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

"allow"は許可システムをバイパスします。permissionDecisionReasonはユーザーに表示されますが、Claudeには表示されません。
"deny"はツール呼び出しの実行を防ぎます。permissionDecisionReasonはClaudeに表示されます。
"ask"はユーザーにUIでツール呼び出しを確認するよう求めます。permissionDecisionReasonはユーザーに表示されますが、Claudeには表示されません。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow" | "deny" | "ask",
    "permissionDecisionReason": "My reason here"
  }
}

decisionとreasonフィールドはPreToolUse hooksでは非推奨です。代わりにhookSpecificOutput.permissionDecisionと hookSpecificOutput.permissionDecisionReasonを使用してください。非推奨フィールド "approve"と"block"は"allow"と"deny"にマップされます。

`PostToolUse`決定制御

PostToolUse hooksはツール実行後にClaudeにフィードバックを提供できます。

"block"は自動的にreasonでClaudeにプロンプトを表示します。
undefinedは何もしません。reasonは無視されます。
"hookSpecificOutput.additionalContext"はClaudeが考慮するコンテキストを追加します。

{
  "decision": "block" | undefined,
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude"
  }
}

`UserPromptSubmit`決定制御

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

"block"はプロンプトが処理されるのを防ぎます。送信されたプロンプトはコンテキストから消去されます。"reason"はユーザーに表示されますが、コンテキストに追加されません。
undefinedはプロンプトが通常通り進行することを許可します。"reason"は無視されます。
"hookSpecificOutput.additionalContext"はブロックされていない場合、文字列をコンテキストに追加します。

{
  "decision": "block" | undefined,
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here"
  }
}

`Stop`/`SubagentStop`決定制御

StopとSubagentStop hooksはClaudeが続行する必要があるかどうかを制御できます。

"block"はClaudeが停止するのを防ぎます。Claudeが進行方法を知るためにreasonを入力する必要があります。
undefinedはClaudeが停止することを許可します。reasonは無視されます。

{
  "decision": "block" | undefined,
  "reason": "Must be provided when Claude is blocked from stopping"
}

`SessionStart`決定制御

SessionStart hooksはセッションの開始時にコンテキストをロードできます。

"hookSpecificOutput.additionalContext"は文字列をコンテキストに追加します。
複数のhooksのadditionalContext値は連結されます。

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "My additional context here"
  }
}

`SessionEnd`決定制御

SessionEnd hooksはセッションが終了するときに実行されます。セッション終了をブロックすることはできませんが、クリーンアップタスクを実行できます。

終了コード例：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 hooksの場合、次のいずれかの方法を使用してコンテキストを注入できます：

終了コード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 hooksはModel Context Protocol（MCP）ツールとシームレスに動作します。MCPサーバーがツールを提供する場合、hooksでマッチできる特別な命名パターンで表示されます。

MCPツール命名

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

mcp__memory__create_entities - メモリサーバーのエンティティ作成ツール
mcp__filesystem__read_file - ファイルシステムサーバーのファイル読み取りツール
mcp__github__search_repositories - GitHubサーバーの検索ツール

MCPツール用のhooksの設定

特定の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 hooksはシステム上で任意のシェルコマンドを自動的に実行します。hooksを使用することで、あなたは以下を認めます：

設定したコマンドについて、あなたのみが責任を負います
Hooksはユーザーアカウントがアクセスできるファイルを変更、削除、またはアクセスできます
悪意のある、または不適切に書かれたhooksはデータ損失またはシステム損害を引き起こす可能性があります
Anthropicは保証を提供せず、hook使用から生じるいかなる損害についても責任を負いません
本番環境で使用する前に、安全な環境でhooksを徹底的にテストする必要があります

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

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

より安全なhooksを書くための重要なプラクティスは以下の通りです：

入力を検証およびサニタイズする - 入力データを盲目的に信頼しないでください
常にシェル変数をクォートする - $VARではなく"$VAR"を使用してください
パストラバーサルをブロックする - ファイルパスで..をチェックしてください
絶対パスを使用する - スクリプトの完全なパスを指定してください（プロジェクトパスには"$CLAUDE_PROJECT_DIR"を使用）
機密ファイルをスキップする - .env、.git/、キーなどを避けてください

設定の安全性

設定ファイルのhooksへの直接編集は即座には有効になりません。Claude Codeは：

スタートアップ時にhooksのスナップショットをキャプチャします
セッション全体でこのスナップショットを使用します
hooksが外部で変更された場合に警告します
変更を適用するために/hooksメニューでレビューが必要です

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

Hook実行の詳細

タイムアウト：デフォルトでは60秒の実行制限、コマンドごとに設定可能。
- 個別のコマンドのタイムアウトは他のコマンドに影響しません。
並列化：マッチするすべてのhooksが並行して実行されます
重複排除：同一のhookコマンドは自動的に重複排除されます
環境：現在のディレクトリでClaude Codeの環境で実行されます
- CLAUDE_PROJECT_DIR環境変数が利用可能で、プロジェクトルートディレクトリへの絶対パスが含まれます（Claude Codeが開始された場所）
- CLAUDE_CODE_REMOTE環境変数は、hookがリモート（web）環境で実行されているかどうかを示します（"true"）またはローカルCLI環境（設定されていないか空）。実行コンテキストに基づいて異なるロジックを実行するために使用してください。
入力：stdinを介したJSON
出力：
- PreToolUse/PostToolUse/Stop/SubagentStop：トランスクリプトに進行状況を表示（Ctrl-R）
- Notification/SessionEnd：デバッグのみにログ（--debug）
- UserPromptSubmit/SessionStart：stdoutをClaudeのコンテキストとして追加

デバッグ

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

hooksが機能していない場合：

設定を確認する - /hooksを実行してhookが登録されているかどうかを確認します
構文を確認する - JSON設定が有効であることを確認します
コマンドをテストする - hookコマンドを最初に手動で実行します
権限を確認する - スクリプトが実行可能であることを確認します
ログを確認する - claude --debugを使用してhook実行の詳細を確認します

一般的な問題：

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

高度なデバッグ

複雑なhook問題の場合：

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

デバッグ出力例

claude --debugを使用してhook実行の詳細を確認します：

[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）に表示され、以下を示します：

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

はじめに

Claude Codeで構築

Claude Agent SDK

デプロイ

管理

設定

リファレンス

リソース

​設定

​構造

​プロジェクト固有のHookスクリプト

​プラグインhooks

​Hook イベント

​PreToolUse

​PostToolUse

​Notification

​UserPromptSubmit

​Stop

​SubagentStop

​PreCompact

​SessionStart

​環境変数の永続化

​SessionEnd

​Hook入力

​PreToolUse入力

​PostToolUse入力

​Notification入力

​UserPromptSubmit入力

​StopおよびSubagentStop入力

​PreCompact入力

​SessionStart入力

​SessionEnd入力

​Hook出力

​シンプル：終了コード

​終了コード2の動作

​高度な：JSON出力

​共通JSONフィールド

​PreToolUse決定制御

​PostToolUse決定制御

​UserPromptSubmit決定制御

​Stop/SubagentStop決定制御

​SessionStart決定制御

​SessionEnd決定制御

​終了コード例：Bashコマンド検証

​JSON出力例：コンテキストと検証を追加するUserPromptSubmit

​JSON出力例：承認を伴うPreToolUse

​MCPツールの操作

​MCPツール命名

​MCPツール用のhooksの設定

​例

​セキュリティに関する考慮事項

​免責事項

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

​設定の安全性

​Hook実行の詳細

​デバッグ

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

​高度なデバッグ

​デバッグ出力例

設定

構造

プロジェクト固有のHookスクリプト

プラグインhooks

Hook イベント

PreToolUse

PostToolUse

Notification

UserPromptSubmit

Stop

SubagentStop

PreCompact

SessionStart

環境変数の永続化

SessionEnd

Hook入力

PreToolUse入力

PostToolUse入力

Notification入力

UserPromptSubmit入力

StopおよびSubagentStop入力

PreCompact入力

SessionStart入力

SessionEnd入力

Hook出力

シンプル：終了コード

終了コード2の動作

高度な：JSON出力

共通JSONフィールド

`PreToolUse`決定制御

`PostToolUse`決定制御

`UserPromptSubmit`決定制御

`Stop`/`SubagentStop`決定制御

`SessionStart`決定制御

`SessionEnd`決定制御

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

JSON出力例：コンテキストと検証を追加するUserPromptSubmit

JSON出力例：承認を伴うPreToolUse

MCPツールの操作

MCPツール命名

MCPツール用のhooksの設定

例

セキュリティに関する考慮事項

免責事項

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

設定の安全性

Hook実行の詳細

デバッグ

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

高度なデバッグ

デバッグ出力例