Claude Code フック
Claude Code フックとは、ユーザー定義のShellコマンドですClaude Codeのライフサイクルの特定のタイミングで自動的に実行されます。
フックを利用すると、Claude Codeの動作を正確に制御し、特定の操作(コードフォーマット、ログ記録など)を確実に実行させることができます。必ずトリガーされます、大規模モデルが実行するかどうかを自律的に選択するのではありません。
フックの代表的な使用例
フックを使うと多くの実用的な機能を実現できます。一般的な例は次のとおりです:
- メッセージ通知:Claude Codeが入力を待っているときや権限が必要なときに、デスクトップ通知/メールで自動的にリマインドを送信します
- 自動フォーマット:ファイル編集
.ts後に自動実行prettier、ファイル変更.go後に実行gofmt - 操作ログ:Claudeが実行したすべてのコマンドを記録し、コンプライアンス監査やデバッグ・トラブルシューティングに使用します
- コード規約チェック:Claudeが生成したコードがプロジェクトの規約(命名規則など)に適合しない場合、自動的にフィードバックを返します
- ファイル権限制御:Claudeによる本番環境の設定ファイルや機密ディレクトリの変更をブロックします(例:
.env、.git)
プロンプトでClaudeの動作を制約する方法と比較して、フックはアプリケーションレベルのハードルールです、対応するイベントがトリガーされれば強制実行されるため、安定性と信頼性がより高くなります。
重要なセキュリティ注意事項
フックの実行時には現在のシステム環境の認証情報を直接使用します(環境変数、ユーザー権限など)、一定のセキュリティリスクがあります:
- 悪意のあるフックコードが、APIキーやプロジェクトのソースコードなどの機密データを漏洩させる可能性があります
- 誤ったフックコマンドは、ファイルの誤削除やシステム異常を引き起こす可能性があります
必ず行うべき安全対策:
- フックを登録する前に、必ずコマンドのロジックと権限を1行ずつ確認してください
- フック内で出所不明のスクリプトを実行しないようにしてください
- 詳細なセキュリティのベストプラクティスは、公式ドキュメントの安全上の注意事項を参照してください
フックイベントタイプの説明
Claude Codeには複数のライフサイクルイベントが組み込まれており、異なるイベントにフックコマンドをバインドできます。各イベントは異なるコンテキストデータを渡し、Claudeの動作への影響の仕方も異なります。
| イベント名 | トリガーのタイミング | 主な機能 |
|---|---|---|
PreToolUse |
ツール呼び出し前 | ツールの実行をインターセプトでき(機密ファイルの変更を防ぐなど)、Claudeに調整提案をフィードバックします |
PermissionRequest |
権限リクエストダイアログが表示されたとき | 権限申請を自動承認または拒否します |
PostToolUse |
ツール呼び出し完了後 | 後続処理を実行します(コードのフォーマット、ログ記録など) |
UserPromptSubmit |
ユーザーがプロンプトを送信した後、Claudeが処理する前 | ユーザー入力を前処理します(コンテキスト情報の補完など) |
Notification |
Claudeが通知を送信するとき | 通知方法をカスタマイズします(デスクトップポップアップ、SMS通知など) |
Stop |
Claudeが応答を完了したとき | 後始末を実行します(一時ファイルのクリーンアップなど) |
SubagentStop |
サブエージェントのタスクが完了したとき | サブエージェントの実行結果を処理します |
PreCompact |
コンテキスト圧縮操作を実行しようとするとき | 圧縮ルールをカスタマイズします |
SessionStart |
新しいセッションを開始するか、以前のセッションを復元するとき | セッション環境を初期化します(プロジェクト設定の読み込みなど) |
SessionEnd |
セッションが終了するとき | セッションデータを保存し、環境をクリーンアップします |
クイックスタート:コマンドログの記録を実装する
以下では、Claudeが実行したすべてのBashコマンドの記録を例に、フックの設定と使用をステップバイステップで説明します。
事前準備
インストールjqツール(コマンドラインでJSONデータを解析するため)
- macOS:
brew install jq - Linux:
sudo apt install jq/sudo yum install jq - Windows:ダウンロードjq公式インストールパッケージ、またはWSL経由でインストールします
ステップ1:フック設定画面を開く
Claude Codeの対話画面でスラッシュコマンドを入力します/hooks、Enterキーを押してバインドするイベントを選択します —— ここではPreToolUse(ツール呼び出し前にトリガーされ、コマンド記録に適しています)を選択します。
ステップ2:イベントマッチャーを追加する
マッチャーの役割はフックのトリガー条件を限定することです、指定されたツールが呼び出されたときのみフックコマンドを実行します。
- 選択
+ Add new matcher… - マッチキーワードを入力
Bash、ClaudeがBashツールを呼び出したときのみフックがトリガーされることを意味しますヒント:
*を入力するとすべてのツールにマッチし、グローバルフックを実現できます
ステップ3:フックコマンドを追加する
選択+ Add new hook…、以下のコマンドを入力します(機能:コマンド内容と説明を抽出し、ログファイルに書き込む):
jq -r '"\(.tool_input.command) - \(.tool_input.description // "无描述信息")"' >> ~/.claude/bash-command-log.txt
コマンドの説明:
jq -r ...:JSON内のコマンド(command)と説明(description)を抽出し、説明がない場合は「説明なし」と表示します>> ~/.claude/...:内容をユーザーのホームディレクトリ下のログファイルに追記します
ステップ4:設定の保存場所を選択する
設定の保存場所によってフックの有効範囲が決まります:
- User settings:ユーザーレベル設定に保存(
~/.claude/settings.json),すべてのプロジェクトで有効 - Project settings:現在のプロジェクト設定に保存(
.claude/settings.local.json),現在のプロジェクトのみで有効
ここでは選択しますUser settings、グローバルなコマンドログ記録を実現します。選択後、Escキーを押して設定画面を終了すると、フックが登録完了します。
ステップ5:フック設定を検証する
- もう一度
/hooksコマンドを入力すると、設定済みのフックリストを確認できます - または設定ファイルを直接開きます
~/.claude/settings.json、以下の設定内容が表示されます:{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"无描述信息\")\"' >> ~/.claude/bash-command-log.txt" } ] } ] } }
ステップ6:フックの効果をテストする
- Claude Codeでコマンドを入力します:
帮我执行 ls 命令 - 実行完了後、ターミナルでログファイルを確認します:
cat ~/.claude/bash-command-log.txt
- ログに以下の内容が表示されていれば、フック設定は成功です:
ls - Lists files and directories
実用的なフックの例
以下に、よく使われるフック設定をいくつか紹介します。そのままコピーして使用するか、必要に応じて変更できます。
📌 完全なサンプルコードは公式リポジトリを参照してください:bashコマンドバリデータの例
例1:TypeScriptファイルを自動フォーマットする
機能:ファイルの編集/書き込み.ts後に、自動的にprettierコードをフォーマットします
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write", // 匹配“编辑”和“写入”工具
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
}
]
}
]
}
}
例2:Markdownファイルの形式を自動修正する
機能:言語タグのないコードブロックにタグを自動補完し、余分な空行を削除します
ステップ1:フック設定を追加する
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/markdown_formatter.py"
}
]
}
]
}
}
ステップ2:フォーマットスクリプトを作成する
プロジェクトディレクトリに新規ファイルを作成し.claude/hooks/markdown_formatter.py、以下のコードを貼り付けてください:
実例
"""
Markdownフォーマットツール:コードブロックの言語ラベルを自動補完、余分な空行を整理
"""
import json
import sys
import re
import os
def detect_language(code):
"""コード内容に基づいてプログラミング言語を自動検出"""
code = code.strip()
# JSONを検出
if re.search(r'^\s*[{\[]', code):
try:
json.loads(code)
return 'json'
except:
pass
# Pythonを検出
if re.search(r'^\s*def\s+\w+\s*\(', code, re.M) or re.search(r'^\s*(import|from)\s+\w+', code, re.M):
return 'python'
# JavaScript/TypeScriptを検出
if re.search(r'\b(function\s+\w+\s*\(|const\s+\w+\s*=)', code) or re.search(r'=>|console\.(log|error)', code):
return 'javascript'
# Bashを検出
if re.search(r'^#!.*\b(bash|sh)\b', code, re.M) or re.search(r'\b(if|then|fi|for|in|do|done)\b', code):
return 'bash'
# デフォルトのテキスト形式
return 'text'
def format_markdown(content):
"""Markdownコンテンツをフォーマット"""
# タグなしコードブロックに言語を補完
fence_pattern = r'(?ms)^([ \t]{0,3})```([^\n]*)\n(.*?)(\n\1```)\s*$'
def add_lang(match):
indent, info, body, closing = match.groups()
if not info.strip():
lang = detect_language(body)
return f"{indent}```{lang}\n{body}{closing}\n"
return match.group(0)
content = re.sub(fence_pattern, add_lang, content)
# 余分な空行を整理(コードブロック外のコンテンツのみ整理)
content = re.sub(r'\n{3,}', '\n\n', content)
return content.rstrip() + '\n'
if __name__ == "__main__":
try:
# Claudeから渡されたJSONデータを読み取る
input_data = json.load(sys.stdin)
file_path = input_data.get('tool_input', {}).get('file_path', '')
# .md/.mdxファイルのみ処理
if not file_path.endswith(('.md', '.mdx')):
sys.exit(0)
# ファイルを読み取ってフォーマット
if os.path.exists(file_path):
with open(file_path, 'r', encoding='utf-8') as f:
content = f.read()
formatted_content = format_markdown(content)
# コンテンツが変更された場合のみ書き込み
if formatted_content != content:
with open(file_path, 'w', encoding='utf-8') as f:
f.write(formatted_content)
print(f"Markdownファイルをフォーマットしました:{file_path}")
except Exception as e:
print(f"フォーマットに失敗しました:{e}", file=sys.stderr)
sys.exit(1)
ステップ3:スクリプトに実行権限を付与する
chmod +x .claude/hooks/markdown_formatter.py
例3:Claudeが入力を待っているときにデスクトップ通知を送信する
機能:Claudeがユーザー入力を必要とするとき、デスクトップ通知を自動的にポップアップ表示します(Linux/macOS対応)
{
"hooks": {
"Notification": [
{
"matcher": "", // 匹配所有通知事件
"hooks": [
{
"type": "command",
"command": "notify-send 'Claude Code 提示' '请你输入指令或确认权限'"
}
]
}
]
}
}
例4:機密ファイルの変更を禁止する
機能:Claudeによる編集をブロック(対象:.env、package-lock.jsonなどの機密ファイル)
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
}
]
}
]
}
}
説明:スクリプトがステータスコードを返すと2、Claude Codeはこのツール呼び出しをインターセプトし、ファイルの変更を阻止します。
Claude Code フックリファレンスマニュアル
設定ファイルのパス
| 設定レベル | ファイルパス | 有効範囲 |
|---|---|---|
| ユーザーレベル | ~/.claude/settings.json |
すべてのプロジェクト |
| プロジェクトレベル | .claude/settings.json |
現在のプロジェクト |
| ローカルプロジェクトレベル(コミットしない) | .claude/settings.local.json |
現在のプロジェクト、バージョン管理に含めない |
| 管理ポリシーレベル | 管理者指定のパス | 企業/チームの統一管理 |
コア設定構造
フックはイベント+マッチャーで組織され、command(シェルコマンドを実行)とprompt(LLMを呼び出して判断)の2種類をサポートします。
{
"hooks": {
"【钩子事件名】": [
{
"matcher": "【工具匹配规则】", // 部分事件可省略
"hooks": [
{
"type": "command/prompt",
"command": "【Shell 命令】", // type=command 时必填
"prompt": "【LLM 提示词】", // type=prompt 时必填
"timeout": 30 // 可选,超时时间(秒)
}
]
}
]
}
}
マッチャールール(ツール系イベントのみに適用)
| マッチングルール | 例 | 説明 |
|---|---|---|
| 完全一致 | Write |
のみに一致Writeツール |
| 複数ツール一致 | Edit | Write | に一致Edit 或 Writeツール |
| プレフィックス一致 | Notebook.* |
すべてのNotebookで始まるツールに一致 |
| 全一致 | */ 空文字列 |
すべてのツールに一致 |
特殊な設定テクニック
| シナリオ | 設定方法 | 例 |
|---|---|---|
| プロジェクト内のスクリプトを参照 | 環境変数を使用$CLAUDE_PROJECT_DIR |
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh" |
| プラグインフック | プラグイン内の設定hooks/hooks.json、${CLAUDE_PLUGIN_ROOT}[変数]を使用してプラグインファイルを参照 |
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh" |
| コンポーネントレベルのフック(Skill/Agent) | コンポーネントのfrontmatterで定義し、スコープはコンポーネントのライフサイクルに限定 | 以下の拡張設定の表を参照 |
拡張設定(Skill/Agent/スラッシュコマンド)
拡張設定では、Skill、Agent、またはカスタムスラッシュコマンドの定義にフック設定を直接埋め込むことができます。このようなフックは、対応するコンポーネントがアクティブ化されて実行されている間のみ有効で、コンポーネントの実行完了後に自動的にクリーンアップされ、グローバルセッションには影響しません。
サポートされるフックイベント
サポートされるのはPreToolUse、PostToolUse、Stopの3種類のイベントのみで、グローバルフックと機能は同じですが、スコープは現在のSkill/スラッシュコマンドのライフサイクルに限定されます。
専用設定項目
once: true(オプション):[値]に設定するとtrue、このフックはセッション全体で一度だけ実行され、初回の成功後に自動的に削除され、重複トリガーを防ぎます。
完全な設定例
---
# Skill/斜杠命令的基础信息
name: secure-operations
description: 执行Shell命令前先做安全校验的工具
# Hooks 配置段
hooks:
PreToolUse:
# 匹配器:仅拦截Bash工具调用
- matcher: "Bash"
hooks:
- type: "command"
# 要执行的安全校验脚本
command: "./scripts/security-check.sh"
# 会话内仅执行一次
once: true
# 超时时间(秒),避免脚本卡死
timeout: 15
---
Agent内のHooks設定
サポートされるフックイベント
同様にサポートされるのはPreToolUse、PostToolUse、Stopの3種類のイベントのみで、スコープはそのサブAgentのタスク実行サイクルに限定されます。
専用設定項目
追加の専用設定項目はなく、このオプションはサポートされませんonce: true(Agentがタスクを実行するたびにフックがトリガーされます)。
完全な設定例
---
# Agent 的基础信息
name: code-reviewer
description: 自动审查代码修改并运行代码检查的子代理
# Hooks 配置段
hooks:
PostToolUse:
# 匹配器:拦截Edit(编辑)或Write(写入)工具
- matcher: "Edit|Write"
hooks:
- type: "command"
# 代码检查脚本,执行lint校验
command: "./scripts/run-linter.sh"
# 超时时间(秒)
timeout: 30
---
注意事項:
- コンポーネント内フックのマッチャールールはグローバルフックと完全に同じです:完全一致(例:
"Write")、複数ツール一致(例:"Edit|Write")、ワイルドカード一致("*")をサポートし、大文字と小文字を区別します; - コンポーネント内フックとグローバルフックは並行して実行されます:グローバルとコンポーネント内で同じイベントに対するフックが同時に設定されている場合、トリガー時に両方のフックが一緒に実行され、互いに競合しません;
- 設定形式の要件:コンポーネント内フックはfrontmatter(
---で囲まれた領域)に記述する必要があり、YAML構文に従います。インデントエラーは設定を無効にします; - スクリプトパスの推奨:相対パス(例:
./scripts/xxx.sh)を優先的に使用するか、$CLAUDE_PROJECT_DIR環境変数を利用して絶対パスを指定し、コンポーネントが任意のディレクトリでスクリプトを見つけられるようにします。
フックイベント--ツール系イベント(マッチャー対応)
| イベント名 | トリガータイミング | 一般的なマッチャー | 主な役割 |
|---|---|---|---|
PreToolUse |
ツール呼び出し前 | Bash/Edit/Write/Read |
ツール実行のインターセプト、入力パラメータの変更、権限の自動承認/拒否 |
PermissionRequest |
権限リクエストダイアログがポップアップ表示されたとき | 同 PreToolUse |
権限申請を自動処理し、ユーザーの手動確認は不要 |
PostToolUse |
ツール呼び出し成功後 | 同 PreToolUse |
後処理を実行(コードフォーマット、ログ記録など) |
Notification |
Claudeが通知を送信するとき | permission_prompt/idle_prompt/auth_success |
通知方法をカスタマイズ(デスクトップポップアップ、メール通知など) |
PreCompact |
コンテキスト圧縮操作の実行前 | manual(手動トリガー)/auto(自動トリガー) |
圧縮ルールのカスタマイズ、重要なコンテキストのバックアップ |
フックイベント--セッション/タスク系イベント(マッチャーなし)
| イベント名 | トリガータイミング | 主な役割 |
|---|---|---|
UserPromptSubmit |
ユーザーがプロンプトを送信した後、Claudeが処理する前 | プロンプトの正当性を検証、コンテキスト情報を補足 |
Stop |
メインAgentが応答を完了したとき(ユーザーが中断した場合はトリガーされない) | タスクの実行を継続する必要があるかをインテリジェントに判断 |
SubagentStop |
サブAgentのタスク完了時 | サブタスクの結果を評価し、終了するかどうかを決定 |
SessionStart |
セッションの起動/復元時 | 環境の初期化、プロジェクト設定のロード、永続化環境変数の設定 |
SessionEnd |
セッション終了時 | 一時ファイルのクリーンアップ、セッションログの記録、作業状態の保存 |
フックタイプの比較
Claude Codeは2種類のフックタイプをサポートし、さまざまなシナリオのニーズに対応します。
| 特性 | commandタイプ(コマンドフック) |
promptタイプ(プロンプトフック) |
|---|---|---|
| 実行方法 | シェルコマンド/スクリプトを実行 | LLM(デフォルトでHaikuモデル)を呼び出してインテリジェントな判断を行う |
| 判断ロジック | コードロジックに基づく決定的な判断 | コンテキストに基づく柔軟な意味判断 |
| 設定の難易度 | スクリプトの作成が必要で、ハードルが高い | プロンプトを書くだけでよく、簡単で使いやすい |
| 応答速度 | 速い(ローカル実行) | 遅い(API呼び出しが必要) |
| 適用シナリオ | コードフォーマット、ログ記録、権限インターセプトなどの固定ルール | タスク完了度の評価、複雑な意図の判断などの柔軟なシナリオ |
| コア設定 | command + timeout |
prompt + timeout(参照可能:$ARGUMENTSプレースホルダー) |
入力と出力 -- フック入力(stdinでJSONを受け取る)
すべてのフックは共通フィールドを受け取り、一部のイベントには特定のフィールドが付属します。
| フィールドタイプ | 共通フィールド | 説明 |
|---|---|---|
| 基本情報 | session_id |
セッションの一意の識別子 |
transcript_path |
会話記録ファイルのパス | |
cwd |
フック実行時の現在の作業ディレクトリ | |
permission_mode |
現在の権限モード(default/plan/acceptEdits など) | |
hook_event_name |
現在トリガーされたフックイベント名 |
各イベント固有フィールドの例
| イベント名 | 固有フィールド | 例 |
|---|---|---|
PreToolUse |
tool_name/tool_input |
{"tool_name":"Write","tool_input":{"file_path":"/test.txt"}} |
UserPromptSubmit |
prompt |
{"prompt":"帮我写一个排序函数"} |
SessionEnd |
reason |
{"reason":"clear/logout/other"} |
フック出力(2つの方法)
方法1:終了コード(シンプルなシナリオ)
終了コードで実行状態を伝達し、stdout/stderrフィードバック情報に使用します。
| 終了コード | 意味 | 動作の説明 |
|---|---|---|
0 |
実行成功 | stdoutJSONを返して高度な制御が可能。一部のイベント(例:UserPromptSubmit)ではstdoutをコンテキストに追加します |
2 |
操作をブロック | のみをstderrエラーメッセージとしてClaudeにフィードバックし、現在のイベントの続行をブロックします |
| その他の非ゼロ値 | 非ブロッキングエラー | stderr詳細モード(ctrl+o)でのみ表示され、イベント実行には影響しません |
終了コード2の各イベントでの動作
| イベント名 | トリガー動作 |
|---|---|
PreToolUse |
ツール呼び出しをブロックし、Claudeに表示しますstderr |
UserPromptSubmit |
プロンプト処理をブロックし、ユーザー入力を消去します |
Stop |
Claudeの停止をブロックし、強制的に作業を続行させます |
PostToolUse/Notification |
のみ表示し、stderr、完了済みの操作には影響しません |
方法2:JSON出力(高度なシナリオ)
終了コードが0の場合、stdoutでJSONを返すことで詳細な制御を実現します。核心フィールドは以下の通りです:
| 共通JSONフィールド | 用途 |
|---|---|
continue: true/false |
イベントの続行を許可するかどうか(falseは他のルールより優先されます) |
stopReason |
continue=falseの場合、ユーザーに表示する理由 |
systemMessage |
ユーザーに表示する警告情報 |
イベント固有JSONフィールドの例
| イベント名 | 固有フィールド | 例 |
|---|---|---|
PreToolUse |
permissionDecision(allow/deny/ask) |
{"hookSpecificOutput":{"permissionDecision":"allow","updatedInput":{"file_path":"/new.txt"}}} |
UserPromptSubmit |
decision: block/undefined |
{"decision":"block","reason":"提示包含敏感信息"} |
PostToolUse |
additionalContext |
{"hookSpecificOutput":{"additionalContext":"文件已格式化完成"}} |
MCPツールのHooks設定
MCPツールはHooksとシームレスに統合でき、特定の命名規則でマッチングします。
MCPツールの命名規則
mcp__<服务器名>__<工具名>
例:mcp__github__search_repositories、mcp__filesystem__read_file
マッチング例
{
"hooks": {
"PreToolUse": [
{
"matcher": "mcp__memory__.*", // 匹配 memory 服务器的所有工具
"hooks": [{"type": "command", "command": "echo '内存操作日志' >> log.txt"}]
},
{
"matcher": "mcp__.*__write.*", // 匹配所有服务器的写操作工具
"hooks": [{"type": "command", "command": "./validate-write.py"}]
}
]
}
}セキュリティとデバッグ
セキュリティのベストプラクティス
| セキュリティの要点 | 具体的な操作 |
|---|---|
| 入力検証 | 厳格に検証tool_input内のファイルパス、コマンド引数を検証し、パストラバーサルを防止します(例:../) |
| 変数参照 | Shellコマンドでは"$VAR"ではなく$VARを使用してパラメータインジェクションを回避します |
| 権限の最小化 | フックスクリプトには必要な権限のみを付与し、sudoなどの高危険コマンドの使用を避けます |
| 機密ファイルの除外 | への操作、.env、.gitキーファイルへの操作をブロックします |
| コマンドレビュー | フックを登録する前に、コマンドを手動で実行してロジックを検証し、悪意のある動作がないことを確認します |
デバッグのテクニック
| 問題の種類 | 調査手順 |
|---|---|
| フックが有効にならない | 1./hooksコマンドを実行して設定が登録されているか確認<br>2. JSON構文が正しいか検証<br>3. マッチャールールがツール名と一致しているか確認(大文字小文字を区別) |
| コマンド実行失敗 | 1. フックコマンドを手動で実行し、正常に実行できるか確認<br>2. スクリプトに実行権限があるか確認(chmod +x script.sh)<br>3. 絶対パスでスクリプトを呼び出し、環境変数の問題を回避します |
| 詳細ログを確認 | Claude Code起動時に--debugパラメータを追加して、フック実行の全過程を確認します |
その他の拡張参考ドキュメント:フックの完全な機能説明を確認するには、公式のフック参考ドキュメントを参照してください。