Hooks設定リファレンス

概要

Hooksはツールの実行前後に自動的に実行されるカスタムコマンドです。settings.json の hooks ブロックで設定します。コードのフォーマット、型チェック、セキュリティスキャンなどを自動化できます。

イベント種別

基本イベント

イベント	タイミング	Matcher
PreToolUse	ツール実行前	ツール名（正規表現対応）
PostToolUse	ツール実行後	ツール名（正規表現対応）
Notification	通知送信時	なし
UserPromptSubmit	ユーザー入力送信時	なし
Stop	メインエージェント完了時	なし
SubagentStop	サブエージェント完了時	なし
PreCompact	Compact実行前	manual / auto
SessionStart	セッション開始時	startup / resume / clear / compact
SessionEnd	セッション終了時	なし
InstructionsLoaded	CLAUDE.md/rules読み込み時	session_start, nested_traversal 等

拡張イベント

必要に応じて使用する高度なフックイベントです。

イベント	タイミング	Matcher
TaskCreated	サブタスク生成時	なし
CwdChanged	作業ディレクトリ変更時	なし
FileChanged	ファイル変更検出時	ファイルパス（正規表現対応）
PermissionDenied	権限拒否時	ツール名（正規表現対応）

設定構造

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx tsc --noEmit"
          }
        ]
      }
    ]
  }
}

条件付き実行（if フィールド）

if フィールドを使うと、Hook の実行条件を細かく制御できます。条件式が true を返す場合のみ Hook が実行されます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "if": "toolInput.command.includes('git push')",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Push detected - reviewing changes...'"
          }
        ]
      }
    ]
  }
}

利用可能なコンテキスト変数

イベント	変数	説明
PreToolUse	toolInput	ツールへの入力パラメータ
PreToolUse	toolName	実行されるツール名
PostToolUse	toolInput	ツールへの入力パラメータ
PostToolUse	toolOutput	ツールの出力結果
PostToolUse	toolName	実行されたツール名

使用例

{
  "matcher": "Edit|Write",
  "if": "toolInput.file_path.endsWith('.ts') || toolInput.file_path.endsWith('.tsx')",
  "hooks": [
    {
      "type": "command",
      "command": "npx tsc --noEmit"
    }
  ]
}

if フィールドを省略した場合、matcher に一致するすべてのイベントで Hook が実行されます。

非同期実行

Hookを非ブロッキングで実行できます。長時間の処理に適しています。

{
  "hooks": [
    {
      "type": "command",
      "command": "long-running-check.sh",
      "async": true,
      "timeout": 60
    }
  ]
}

オプション	説明	デフォルト
async	非ブロッキング実行	false
timeout	タイムアウト秒数	600

終了コード

Hookの終了コードによってClaudeの動作が変わります。

終了コード	動作
0	成功。stdoutがユーザーに表示される
2	ブロック。stderrがClaudeにフィードバックとして返される
その他	非ブロッキングエラー。stderrがユーザーに表示される

終了コード 2 は強力な安全メカニズムです。例えば、機密ファイルの編集をブロックできます。

#!/bin/bash
# secret-guard.sh
if echo "$CLAUDE_FILE_PATH" | grep -q ".env"; then
  echo ".env files must not be edited by AI" >&2
  exit 2
fi

InstructionsLoadedペイロード

InstructionsLoaded イベントのHookには以下の情報が渡されます。

フィールド	説明
file_path	読み込まれたファイルの絶対パス
memory_type	スコープ: User, Project, Local, Managed
load_reason	理由: session_start, nested_traversal 等
globs	Frontmatterのglobパターン（省略可）

実用的なHook例

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "grep -rn 'console.log' --include='*.ts' --include='*.tsx' src/ && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}