meta-hook-creator

フック作成ツール

概要

Claude Code のフックは、特定のライフサイクルのタイミングで自動的に実行される、ユーザー定義のシェルコマンド、LLM プロンプト、またはエージェントによる評価です。フックは標準入力経由で JSON コンテキストを受け取り、処理を行い、終了コード、標準出力、標準エラー出力を通じて結果を伝えます。

使用する場面： 危険なコマンドのブロック、書き込み後の自動フォーマット、機密ファイルの保護、カスタム通知、環境設定、プロジェクト規約の適用、安全なツールの自動承認、変更後のテスト実行。

使用しない場面： 静的なコンテキストの注入（CLAUDE.md を使用）、単純な権限ルール（許可リストの設定を使用）、一度限りの設定（シェルスクリプトを直接使用）。

クイックリファレンス

パターン	イベント	マッチャー	主なポイント
ツール呼び出しをブロック	PreToolUse	ツール名	終了コード 2、または JSON の permissionDecision: "deny"
ツールを自動承認	PreToolUse	ツール名	JSON の permissionDecision: "allow"
ツール入力を変更	PreToolUse	ツール名	変更したパラメーターを含む JSON の updatedInput
書き込み後にフォーマット	PostToolUse	Write|Edit	フォーマッターを実行し、終了コード 0 を返す
ツールの失敗を記録	PostToolUseFailure	ツール名	ツールがエラーをスローするか、失敗を返したときに実行される
権限リクエストを処理	PermissionRequest	ツール名	JSON の decision.behavior: "allow" または "deny"
ユーザープロンプトを検証	UserPromptSubmit	マッチャーなし	終了コード 2 でプロンプトをブロックし、標準出力でコンテキストを追加
デスクトップ通知	Notification	通知タイプ	permission_prompt、idle_prompt など
続行を強制	Stop	マッチャーなし	理由を含む JSON の decision: "block"
サブエージェントのライフサイクル	SubagentStop	エージェントタイプ	Stop と同じ決定制御
環境設定	SessionStart	ソースタイプ	CLAUDE_ENV_FILE に書き込んで環境変数を保持する
セッションのクリーンアップ	SessionEnd	終了理由	終了をブロックできない
圧縮前のコンテキスト	PreCompact	manual|auto	コンテキストの圧縮前に実行される
バックグラウンドタスク	任意のイベント後	任意	コマンドフックに async: true を設定する
LLM による評価	サポート対象のイベント	任意	単一ターンの LLM チェックには type: "prompt" を使用する
複数ターンの検証	サポート対象のイベント	任意	ツールにアクセスできるサブエージェントには type: "agent" を使用する

よくある間違い

間違い	正しいパターン
ツール呼び出しをブロックする目的で Exit 1 を使用する	PreToolUse と PermissionRequest でブロックするには exit 2 を使用します
exit 2 で JSON を出力する	JSON 出力が処理されるのは exit 0 の場合のみです。exit 2 では stderr が使用されます
settings.json に複雑な bash をインラインで記述する	スクリプトファイルに切り出し、$CLAUDE_PROJECT_DIR で参照します
時間のかかるフックにタイムアウトを設定しない	timeout フィールドを設定します。デフォルトはコマンドが 600s、プロンプトが 30s、エージェントが 60s です
$CLAUDE_PROJECT_DIR を引用符で囲まない	必ず引用符で囲みます："$CLAUDE_PROJECT_DIR"/.claude/hooks/script.sh
すべてのフックで CLAUDE_ENV_FILE を使用できると思い込む	SessionStart フックでのみ使用できます
Stop または UserPromptSubmit に matcher を追加する	これらのイベントは matcher を無視し、常に実行されます
PreToolUse のトップレベルで decision／reason を使用する	hookSpecificOutput.permissionDecision と permissionDecisionReason を使用します
Stop フックで stop_hook_active を確認しない	無限の継続ループを防ぐため、このフィールドを確認します
終了コードと JSON による判定を混在させる	フックごとに、終了コードのみを使う方法か、exit 0 と JSON を使う方法のどちらかを選びます

委任

• フックパターンの調査：Explore エージェントを使って、プロジェクト内の既存のフックを探します
• フックのテストと検証：Task エージェントを使って、フックの動作を検証します
• コードレビュー：code-reviewer エージェントにフックスクリプトのレビューを委任します

参考資料

• イベントの種類、matcher、入力スキーマ
• フックの設定、終了コード、JSON 出力、環境変数
• 一般的な自動化パターン向けのフックテンプレート