Claude Code の hooks の matcher に書ける値一覧:イベント別の対象と書き方

settings.json に hooks を書くとき、matcher に何を書けばよいのか迷います。Bash のようなツール名が書けることは分かっても、正規表現が使えるのか、SessionStart では何と照合されるのかは、書いてみないと分かりません。

結論として、matcher は イベントごとに照合対象が違い、値の書き方によって完全一致か正規表現かが自動的に切り替わります。この記事では、その判定ルールとイベント別の対象を一覧にします。

値の書き方で判定方法が変わる

matcher は 3 つのモードのどれかで評価されます。どのモードになるかは、書いた文字で自動的に決まります。

書いた値	評価	例
"*"、""、または省略	すべてに一致	そのイベントのたびに実行
英数字・_・-・空白・,・| だけ	完全一致(複数可)	Bash、Edit|Write、Edit, Write
それ以外の文字を 1 つでも含む	JavaScript の正規表現(アンカーなし)	^Notebook、mcp__memory__.*

ここが最も間違えやすい点です。Bash は完全一致ですが、^Bash$ にはアンカー記号が含まれるため正規表現として扱われます。どちらも同じ結果になりますが、意識せずに . や * を含む名前を書くと、意図せず正規表現になります。

正規表現は RegExp.prototype.test() で評価されます。つまり アンカーなしの部分一致 です。Edit を正規表現として評価させると NotebookEdit にも一致します。完全一致させたいなら ^Edit$ と書いてください。

バージョンによる違いも 2 点あります。

• ハイフンを含む名前の完全一致は Claude Code v2.1.195 以降が必要です。それより前のバージョンでは code-reviewer のような名前はアンカーなしの正規表現として評価されるため、^code-reviewer$ と書きます
• カンマ区切りの列挙(Edit, Write)は v2.1.191 以降が必要です

イベント別:matcher は何と照合されるか

matcher はツール名専用ではありません。イベントごとに照合対象が変わります。

イベント	照合対象	値の例
PreToolUse / PostToolUse / PostToolUseFailure / PermissionRequest / PermissionDenied	ツール名	Bash、Edit|Write、mcp__.*
SessionStart	セッション開始の理由	startup、resume、clear、compact、fork
Setup	セットアップを起動した CLI フラグ	init、maintenance
SessionEnd	セッション終了の理由	clear、resume、logout、prompt_input_exit、other
Notification	通知の種類	permission_prompt、idle_prompt、auth_success など
SubagentStart / SubagentStop	エージェントの種類	general-purpose、Explore、Plan、独自の名前
PreCompact / PostCompact	圧縮のきっかけ	manual、auto
PreModelSwitch / PostModelSwitch	正規化されたモデル名	claude-opus-5
ConfigChange	設定のソース	user_settings、project_settings、local_settings、policy_settings、skills
DirectoryAdded	ディレクトリの追加方法	slash_command、register_repo_root
FileChanged	監視するファイル名(リテラル)	.envrc|.env
StopFailure	エラーの種類	rate_limit、overloaded、authentication_failed、server_error など
InstructionsLoaded	読み込みの理由	session_start、nested_traversal、path_glob_match、include、compact
UserPromptExpansion	コマンド名	自分のスキル名・コマンド名
Elicitation / ElicitationResult	MCP サーバー名	設定済みの MCP サーバー名

InstructionsLoaded を使った実例は InstructionsLoaded フックの使い方 にまとめています。

matcher を書いても無視されるイベント

次のイベントは matcher に対応していません。書いても エラーにはならず、黙って無視されます。

• UserPromptSubmit
• PostToolBatch
• Stop
• CwdChanged
• TeammateIdle
• TaskCreated
• TaskCompleted
• WorktreeCreate
• WorktreeRemove
• MessageDisplay

「フックが絞り込まれずに毎回動く」と感じたら、まずこの一覧を確認してください。エラーが出ないため気づきにくい種類の設定ミスです。

書き方の実例

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-bash.sh"
          }
        ]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/lint-check.sh"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "echo started >> ~/session.log"
          }
        ]
      }
    ]
  }
}

ツール名の正確な綴りは公式のツールリファレンスで確認してください。よく使うものは Bash、Read、Edit、Write、Glob、Grep、WebFetch、WebSearch、NotebookEdit、TodoWrite、Agent、Skill です。

MCP ツールを指定する

MCP サーバーのツールは mcp__<サーバー名>__<ツール名> という命名になります。

やりたいこと	matcher
あるサーバーのツールすべて	mcp__memory__.*
ハイフンを含むサーバー名	mcp__brave-search__.*
サーバー横断で特定のツール名	mcp__.*__write.*
プラグイン同梱のサーバー	mcp__plugin_my-plugin_db__.*

matcher で足りないときは if を使う

matcher はツール名までしか絞れません。「TypeScript ファイルの編集だけ」のようにパラメータで絞りたい場合は、フック側の if フィールドを使います。

{
  "matcher": "Edit",
  "hooks": [
    {
      "type": "command",
      "if": "Edit(*.ts)",
      "command": "./check-typescript.sh"
    }
  ]
}

if は permissions と同じルール記法で書きます(permissions を設計する)。ツールのイベントでのみ評価され、それ以外のイベントでは無視されます。

フック本体の書き方と終了コードの扱いは hooks で lint と format を自動実行する と hooks の終了コードの意味 を参照してください。

まとめ

• matcher は書いた文字で完全一致・正規表現・全一致が自動的に切り替わる
• 記号を含むと正規表現になり、アンカーなしの部分一致で評価される
• 大文字小文字は区別される。ハイフンの完全一致は v2.1.195 以降、カンマ区切りは v2.1.191 以降
• 照合対象はイベントごとに違う。ツール名とは限らない
• Stop や UserPromptSubmit など 10 個のイベントは matcher を黙って無視する
• MCP ツールをまとめて対象にするなら mcp__<サーバー名>__.* と末尾に .* を付ける