概要

Claude Codeの hooks は、ユーザー定義のシェルコマンドで動作制御を自動化 通知やフォーマット、権限制御など 多様なユースケース に対応 設定ファイルで 柔軟に管理 でき、MCPツールとの連携も可能 JSON入出力 やexit codeでClaudeと連携し、詳細な制御が可能 セキュリティリスクもあるため、 安全な運用 が重要

Claude Code Hooksの概要

• Claude Code hooks は、ユーザーが任意のシェルコマンドをライフサイクルの各ポイントで自動実行
• LLMの判断に依存せず、確実な動作・自動化ルールの実装
• 代表的な用途
  • 通知 ：入力待ちや実行許可などのカスタム通知
  • 自動フォーマット ：ファイル編集後にprettierやgofmt等を自動実行
  • ログ記録 ：実行コマンドのトラッキングや監査
  • フィードバック ：コード規約違反時の自動指摘
  • 権限制御 ：本番ファイルや機密ディレクトリの変更ブロック

クイックスタート：コマンド実行ログフックの追加

• 前提条件 ：jq（JSON処理ツール）のインストール
• 手順
  • /hooksコマンドでPreToolUseイベントを選択
    • PreToolUseはツール実行前に動作、ブロックやフィードバックが可能
  • • Add new matcher…でBashツールのみ対象に設定
  • • Add new hook…で任意のシェルコマンドを登録
  • 保存先はUser settingsを選択（全プロジェクト共通で適用）
  • 設定を保存しREPLに戻ればフック登録完了
  • /hooksや~/.claude/settings.jsonで設定確認

設定ファイルと構造

• 設定ファイル一覧
  • ~/.claude/settings.json ：ユーザー全体設定
  • .claude/settings.json ：プロジェクト単位
  • .claude/settings.local.json ：ローカル設定（非コミット）
  • Enterprise managed policy settings ：企業管理用
• 構成
  • matcher ：ツール名やパターン指定（PreToolUse/PostToolUseのみ適用）
    • 例：Write（完全一致）、Edit|Write（正規表現）、Notebook.*（プレフィックス）
    • 空欄の場合は全イベント対象
  • hooks ：一致時に実行するコマンド配列
    • typeは現状"command"のみ
    • commandでbashコマンド指定

フックイベントの種類

• PreToolUse ：ツールパラメータ生成後、実行前に動作
  • 代表matcher：Task, Bash, Glob, Grep, Read, Edit, Write, WebFetch, WebSearch
• PostToolUse ：ツール実行後、即時動作
• Notification ：Claude Codeからの通知時に動作
• Stop ：Claude Codeの応答完了時に動作

フックの入出力仕様

• 入力 ：stdinでJSON形式のセッション・イベント固有データ受け取り
  • PreToolUse, PostToolUse, Notification, Stopごとにスキーマが異なる
• 出力 ：Claude Codeへの戻り値は2方式
  • シンプル方式 ：exit code, stdout, stderrで状態通知
    • 0：正常、stdoutはユーザー表示
    • 2：ブロック、stderrはClaudeへ自動返却
    • その他：非ブロックエラー、stderrはユーザー表示
  • JSON方式 ：stdoutで構造化JSON返却
    • continue（falseで以降処理停止）、stopReason（ユーザー向け理由）
    • PreToolUse/PostToolUse/Stopごとにdecision（approve/block/undefined）指定可

MCPツールとの連携

• MCPツール名のパターン ：mcp__<server>__<tool>
  • 例：mcp__memory__create_entities, mcp__github__search_repositories
• 特定MCPツールやサーバー単位でフック設定可能

代表的なフック例

• 自動フォーマット ：ファイル編集後に自動整形
• カスタム通知 ：許可要求やアイドル時の通知内容変更

セキュリティに関する注意点

• 自己責任 ：任意コマンド自動実行のため、データ損失やシステム破壊リスクあり
• 安全対策
  • 入力検証・サニタイズ
  • シェル変数は必ずダブルクォートで囲む
  • パストラバーサル防止（..のチェック）
  • 絶対パス指定
  • 機密ファイルの除外（.env, .git/, 鍵ファイル等）
• 設定反映のタイミング
  • 起動時にhooksのスナップショット取得、セッション中は変更反映なし
  • 外部変更時は/hookメニューでレビュー必須

フック実行の詳細

• タイムアウト ：60秒
• 並列実行 ：一致する全フックを並列で実行
• 実行環境 ：カレントディレクトリ、Claude Codeの環境を継承
• 入出力 ：stdinでJSON受信、stdout/stderrで結果返却
• 進捗表示 ：transcriptモード（Ctrl-R）でフック進捗を表示

デバッグ方法

• /hooksメニュー で設定確認
• 設定ファイルのJSON構文チェック
• コマンドを手動実行し挙動確認
• exit codeやstdout/stderr出力形式の確認
• シェルのクォートやエスケープミスの検証
• transcriptモードで実行中フック、コマンド、出力・エラー内容を確認