claude-code-hooks

Claude Code フック

Claude Code のツール呼び出しの前後にカスタムスクリプトを実行します。

クイックリファレンス

イベント	タイミング	マッチャーあり
PreToolUse	ツール実行前	はい
PostToolUse	ツール完了後	はい
PermissionRequest	権限ダイアログの表示時	はい
Notification	通知の送信時	はい
UserPromptSubmit	ユーザーがプロンプトを送信した時	いいえ
Stop	エージェントの終了時	いいえ
SubagentStop	サブエージェントの終了時	いいえ
PreCompact	コンテキスト圧縮の前	いいえ
SessionStart	セッションの開始／再開時	いいえ
SessionEnd	セッションの終了時	いいえ

基本設定

~/.claude/settings.json または .claude/settings.local.json に追加します。

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "$CLAUDE_PROJECT_DIR/hooks/validate.sh",
        "timeout": 5000
      }]
    }]
  }
}

マッチャーパターン

パターン	マッチ対象
"Write"	Write ツールのみ
"*" または ""	すべてのツール
"mcp__*"	すべての MCP ツール
"Bash"	Bash コマンド

フックスクリプトの要件

#!/bin/bash
# Receives JSON via stdin: { "tool_name": "...", "tool_input": {...} }
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')

# Exit codes:
# 0 = Success (continue)
# 2 = Block with error (stderr shown to Claude)
# Other = Non-blocking error

よくあるユースケース

ユースケース	イベント	例
入力の検証	PreToolUse	危険なコマンドをブロック
監査ログ	PostToolUse	すべてのツール使用を記録
カスタム承認	PermissionRequest	Slack 通知
セッションの初期化	SessionStart	プロジェクトのコンテキストを読み込む

セキュリティチェックリスト

• すべての変数を引用符で囲みます。$VAR ではなく "$VAR" を使用します
• パスを検証します（.. によるトラバーサルがないこと）
• パスには $CLAUDE_PROJECT_DIR を使用します
• 適切なタイムアウトを設定します
• jq の解析エラーを処理します

トラブルシューティング

# Debug hook loading
claude --debug

# List registered hooks
/hooks

# Test script manually
echo '{"tool_name":"Bash"}' | ./hooks/validate.sh

公式ドキュメント

• https://code.claude.com/docs/en/hooks - フックのリファレンス
• https://code.claude.com/docs/en/settings - 設定

追加リソース

• ./references/hook-events.md - 入力／出力スキーマを含むすべてのイベント
• ./references/configuration.md - 高度な設定パターン
• ./references/security-ops.md - 本番環境のセキュリティ

---

関連項目： トラブルシューティングについては claude-code-debug、CLI 自動化については claude-code-headless を参照してください