hooks-configuration

Claude Code フックの設定

ワークフローを自動化し、ベストプラクティスを徹底するための Claude Code フックの設定と開発に関する専門知識です。

このスキルを使用する場面

このスキルを使用する場面...	別の方法を使用する場面...
フックのライフサイクルイベント（PreToolUse、PostToolUse など）を設定する場合	フックと関係のない一般的なシェルスクリプトを作成する場合
危険なコマンドをブロックしたり、パターンを徹底したりする場合	CI/CD パイプラインを設定する場合（CI ツールを使用してください）
編集後にファイルを自動フォーマットする場合	フックと関係のない Claude Code の設定を行う場合
セッションまたはサブエージェントの開始時にコンテキストを注入する場合	独立した自動化スクリプトを作成する場合
PermissionRequest の自動承認／拒否を設定する場合	settings.json を直接使ってプロジェクトの権限を管理する場合
判断に基づく決定を行うプロンプトフックまたはエージェントフックを開発する場合	MCP サーバーやカスタムツール連携を構築する場合

主な概念

フックとは何ですか？ フックは、Claude Code のライフサイクルの特定のタイミングで実行される、ユーザー定義のシェルコマンドです。Claude が何かを実行する「判断」に依存するのとは異なり、フックは確実で保証された実行を提供します。

フックを使用する理由

• コードのフォーマットを自動的に徹底する
• 実行前に危険なコマンドをブロックする
• セッション開始時にコンテキストを注入する
• 監査証跡のためにコマンドを記録する
• タスク完了時に通知を送信する

フックのライフサイクルイベント

イベント	発生するタイミング	主な用途
SessionStart	セッションの開始時／再開時	環境のセットアップ、コンテキストの読み込み
SessionEnd	セッションの終了時	クリーンアップ、状態の永続化
UserPromptSubmit	ユーザーがプロンプトを送信したとき	入力の検証、コンテキストの挿入
PreToolUse	ツールの実行前	権限の制御、危険な操作のブロック
PostToolUse	ツールの実行後	自動フォーマット、ログ記録、検証
PostToolUseFailure	ツールの実行が失敗した後	再試行の判断、エラー処理
PermissionRequest	Claude がツールの使用許可を要求したとき	ユーザーへの確認なしで自動的に許可／拒否
Stop	メインエージェントが応答を完了したとき	通知、Git のリマインダー
SubagentStart	サブエージェント（Task ツール）の開始直前	入力の変更、コンテキストの挿入
SubagentStop	サブエージェントの完了時	タスクごとの完了評価
WorktreeCreate	EnterWorktree によって新しい Git ワークツリーが作成されたとき	ワークツリーのセットアップ、依存関係のインストール
WorktreeRemove	セッション終了後にワークツリーが削除されたとき	クリーンアップ、未コミット変更の警告
TeammateIdle	エージェントチームのチームメイトがアイドル状態になったとき	チームメイトへの追加タスクの割り当て
TaskCompleted	共有タスクリストでタスクが完了としてマークされたとき	タスク受け入れ前の検証ゲート
PreCompact	コンテキストの圧縮前	トランスクリプトのバックアップ
Notification	Claude が通知を送信したとき	カスタムアラート
ConfigChange	Claude Code の設定が実行中に変更されたとき	設定変更の監査、検証

Stop と SubagentStop の違い：Stop は、メインエージェントが応答ターンを完了したときにセッションレベルで発生します。SubagentStop は、個々のサブエージェント（Task ツールによって起動）が完了したときに発生します。セッションレベルの通知には Stop を、タスクごとの品質ゲートには SubagentStop を使用します。

各イベントの完全なスキーマ、例、タイムアウトの推奨事項については、.claude/rules/hooks-reference.md を参照してください。

設定

ファイルの場所

フックは設定ファイルで設定します。

• ~/.claude/settings.json - ユーザーレベル（すべての場所に適用）
• .claude/settings.json - プロジェクトレベル（リポジトリにコミット）
• .claude/settings.local.json - プロジェクトのローカル設定（コミットしない）

Claude Code は、すべてのファイルから条件に一致するフックをマージします。

フロントマターのフック（スキルとコマンド）

スキルやコマンドのフロントマターで hooks フィールドを使用して、フックを直接定義することもできます。

---
name: my-skill
description: A skill with hooks
allowed-tools: Bash, Read
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "echo 'Pre-tool hook from skill'"
          timeout: 10
---

基本構造

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

マッチャーパターン

• 完全一致：「Bash」ツールに完全一致する "Bash"
• 正規表現パターン：いずれかのツールに一致する "Edit|Write"
• ワイルドカード：「Notebook」で始まるツールに一致する "Notebook.*"
• すべてのツール：すべてに一致する "*"
• MCP ツール：MCP サーバーのツールを対象とする "mcp__server__tool"

入力／出力スキーマの概要

フックは、共通フィールド（session_id、transcript_path、cwd、permission_mode、hook_event_name）を含む JSON を stdin 経由で受け取ります。イベント固有のフィールドには、PreToolUse の tool_name と tool_input、PostToolUse の tool_response、SubagentStart の subagent_type／subagent_prompt があります。

終了コード：0 = 許可、2 = ブロック（stderr の内容が Claude に表示されます）、その他 = ブロックを伴わないエラー。

JSON レスポンスはイベントごとに異なります。PreToolUse は permissionDecision を含む hookSpecificOutput を使用し、Stop／SubagentStop は decision／reason を使用し、SubagentStart は updatedPrompt を使用し、SessionStart は additionalContext を含む hookSpecificOutput を使用します。

フックの詳細なスキーマと例については、REFERENCE.md を参照してください。

よくあるフックのパターン

危険なコマンドをブロックする（PreToolUse）

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block rm -rf /
if echo "$COMMAND" | grep -Eq 'rm\s+(-rf|-fr)\s+/'; then
    echo "BLOCKED: Refusing to run destructive command on root" >&2
    exit 2
fi

exit 0

編集後に自動フォーマットする（PostToolUse）

#!/bin/bash
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if [[ "$FILE" == *.py ]]; then
    ruff format "$FILE" 2>/dev/null
    ruff check --fix "$FILE" 2>/dev/null
elif [[ "$FILE" == *.ts ]] || [[ "$FILE" == *.tsx ]]; then
    prettier --write "$FILE" 2>/dev/null
fi

exit 0

組み込みツールを使うよう促す（PreToolUse）

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if echo "$COMMAND" | grep -Eq '^\s*cat\s+[^|><]'; then
    echo "REMINDER: Use the Read tool instead of 'cat'" >&2
    exit 2
fi

exit 0

セッション開始時にコンテキストを読み込む（SessionStart）

#!/bin/bash
GIT_STATUS=$(git status --short 2>/dev/null | head -5)
BRANCH=$(git branch --show-current 2>/dev/null)

CONTEXT="Current branch: $BRANCH\nPending changes:\n$GIT_STATUS"
jq -n --arg ctx "$CONTEXT" '{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": $ctx
  }
}'

その他のパターン（サブエージェントへの挿入、デスクトップ通知、監査ログ、自動承認、worktree のセットアップ、タスクのゲーティング）については、REFERENCE.md を参照してください。

プロンプトベースおよびエージェントベースのフック

フックの種類は 4 つあります。command（シェルスクリプト、終了コード）、http（HTTPS エンドポイント）、prompt（単一ターンの LLM 呼び出し）、agent（ツールアクセスを伴う複数ターン）です。決定論的なルールには command を、判断を伴う決定には prompt／agent を使用してください。バックグラウンドで実行して結果を待たない場合は async: true を、セッションごとに一度だけ実行する場合は once: true を追加します。

プロンプトフックとエージェントフックは、PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest、Stop、SubagentStop、TaskCompleted、UserPromptSubmit で動作します。その他のすべてのイベントでサポートされるのは command フックのみです。

フックの種類の詳細、CLAUDE_ENV_FILE、設定例については、REFERENCE.md および .claude/rules/prompt-agent-hooks.md を参照してください。

ブロックされたコマンドへの対処

PreToolUse フックがコマンドをブロックした場合：

状況	対応
フックが代替案を提示する	提案されたツール／方法を使用する
代替案が機能しない	ユーザーにコマンドを手動で実行してもらう
ユーザーが「続行」と言う	それでもブロックされます。理由を説明し、手動実行用のコマンドを提示してください

重要：ユーザーの許可によってフックを回避することはできません。ブロックされたコマンドを再試行しても、再び失敗します。

コマンドが正当に必要な場合：

1. コマンドが必要な理由を説明する
2. 検討した代替案と、それらが機能しない理由を説明する
3. ユーザーが手動で実行するための正確なコマンドを提示する
4. ユーザーの判断に任せる

タイムアウトのガイドライン

Claude Code 2.1.50 以降では、フックのデフォルトのタイムアウトは 600s（10 分）です。意図を明確にし、「Hook cancelled」エラーを防ぐため、タイムアウトを明示的に設定してください。

フックの種類	推奨タイムアウト	用途
SessionStart	120–300s	テスト、リンター、依存関係のチェック
SessionEnd	60–120s	ログ記録、クリーンアップ、状態の保存
Stop / SubagentStop	30–60s	Git の状態チェック、簡単な検証
PreToolUse	10–30s	簡単な検証
PostToolUse	30–120s	ログ記録、通知
PermissionRequest	5–15s	快適なユーザー体験のため、迅速に処理

バックグラウンドサブシェルパターン（推奨）

ブロックせずに時間のかかる処理（ログ記録、API 呼び出し）をフックで実行する必要がある場合は、バックグラウンドサブシェルで実行します。

#!/bin/bash
# Exits instantly; slow work continues in background
(
  echo "$(date): Session ended" >> ~/.claude/session.log
  # Any other slow work...
) &>/dev/null &
exit 0

この方法が機能する理由：( ) はサブシェルを作成し、& はバックグラウンドで実行し、&>/dev/null は stdout／stderr によるブロックを防ぎ、exit 0 は直ちに成功を返します。

ベストプラクティス

領域	主なポイント
スクリプト	cat で stdin を読み込み、jq で解析します。すべての変数を引用符で囲みます。ブロックする場合は終了コード 2、許可する場合は 0 を返します。メッセージは stderr に出力し、5 秒未満で完了させます
設定	移植可能なパスには $CLAUDE_PROJECT_DIR を使用します。タイムアウトを明示し、ワイルドカードより具体的なマッチャーを使います。有効にする前にテストします
セキュリティ	すべての入力を検証します。絶対パスを使用します。.env や .git/ を直接使用しないでください。デプロイ前に確認します

デバッグ

エラー	原因	対処方法
フックがキャンセルされた	タイムアウトを超過しました	"timeout" フィールドを追加するか、バックグラウンドのサブシェルパターンを使用します
フックが失敗した	スクリプトエラーです	終了コードを確認し、エラー処理を追加します
コマンドが見つからない	スクリプトがありません	スクリプトのパスと権限を確認します
アクセスが拒否された	スクリプトに実行権限がありません	chmod +x ~/.claude/script.sh

/hooks で登録を確認し、詳細なログには claude --debug を使用します。手動でテストするには、echo '{"tool_input":{"command":"..."}}' | bash your-hook.sh を実行します。終了コードは $? で確認できます。プラグインフックのドキュメントについては、hooks/README.md を参照してください。