Hooks とは

Hooks（フック）は、Claude Code の決まったタイミングで、自分で用意したコマンドを自動で動かす仕組みです。

たとえば次のようなことができます。

  • ツールを使う前に中身を調べて、危ないものは止める
  • ファイルを書き換えたあとに、lint やテストを自動で走らせる
  • Claude が止まったら、通知を出す

CLAUDE.md に書いたルールは「お願い」なので、守られないことがあります。 Hooks は Claude Code 自身が毎回動かすので、守らせたいことを機械的に守らせられるのが違いです。

いつ動くか（主なイベント）

イベントは 30 以上ありますが、よく使うのは次のものです。「止められる」は、そのイベントで処理を止められるかどうかです。

イベント 動くとき 止められる
SessionStart セッションの開始・再開 いいえ
UserPromptSubmit プロンプトを送った直後（Claude が読む前） はい
PreToolUse ツールを使う直前 はい
PermissionRequest ツールの使用に許可が要るとき 許可・拒否を JSON で返す（終了コード 2 では止まらない）
PostToolUse ツールが成功したあと いいえ
PostToolUseFailure ツールが失敗したあと いいえ
Notification Claude Code が通知を出すとき いいえ
Stop Claude が応答を終えたとき はい（※）
SubagentStop サブエージェントが終わったとき はい（※）
PreCompact 会話の圧縮の前 はい
SessionEnd セッションの終了 いいえ

※ Stop と SubagentStop で「止める」と、終わるのを止めて、作業を続けさせる意味になります。ほかのイベントとは逆なので注意してください。

全部の一覧は 公式ドキュメント にあります。

設定の書き方

設定は settings.json の hooks に書きます。主な置き場所は次の 3 つで、内容は合わさって効きます（上書きではありません）。ほかに、組織の管理設定・プラグイン・スキルにも書けます。

  • ~/.claude/settings.json: 自分のすべてのプロジェクト
  • .claude/settings.json: そのプロジェクト（リポジトリに入れて共有する）
  • .claude/settings.local.json: そのプロジェクトで自分だけ（共有しない）

Bash を使う前にスクリプトを動かす例です。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-bash.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}
  • matcher: どのツールで動かすか。"Bash"、"Edit|Write" のように書く。省略するとすべてに当たる
  • type: ふつうは "command"（コマンドを動かす）。ほかに "http"、"prompt" などがある
  • timeout: 秒。省略すると、コマンドは 600 秒（UserPromptSubmit では 30 秒）

フックには、何が起きたかが JSON で標準入力に渡されます（ツール名、ツールへの入力 tool_input など）。

止める・通すの決まり

フックの結果は、終了コードか、標準出力の JSON で伝えます。

終了コード

終了コード 意味
0 成功。標準出力が JSON なら読まれる
2 止める（止められるイベントのとき）。標準エラーの文が理由として Claude に渡る
それ以外 通常は止めない。エラーの表示だけ出て、処理は続く（下の onFailure: "block" を付けたフックなどは例外）

よくある勘違い: 終了コード 1 では止まりません。 止めたいときは 2 を返します。

JSON で返す（PreToolUse の例）

ツールの使用を止めるとき:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": ".env は読まない決まりです"
  }
}

permissionDecision は allow（許可）・deny（拒否）・ask（人に聞く）などを返せます。updatedInput を返すと、ツールへの入力を書き換えられます。

フック自体が失敗したら止める（onFailure）

2.1.295 から、command と http のフックに "onFailure": "block" を書けます。 スクリプトが見つからない・時間切れなど、フック自体が失敗したときにも止める設定です。書かないと、フックが失敗しても処理は続きます。

よく使われる使い方

Hiroba に集まった記事から、実例を紹介します。

危ないファイルを開かせない .env などを読む前に PreToolUse で止める。permissions.deny（拒否のルール）と 2 段構えにするのが定番です。

→ Claude Code が .env を開く前に止める—deny ルールと PreToolUse フックの最小構成

書き換えのたびに検査する PostToolUse で、ファイルを書き換えたら lint・型チェック・テストを走らせる。CI やテストとの役割分担も考える。

→ Claude Code で品質を担保する仕組みを設計する — Hooks・CI・テストの役割分担

止まったことに気づく Notification や Stop で、許可待ち・入力待ちなどの理由ごとに通知を出し分ける。

→ Claude Code が止まった理由ごとに通知を出し分ける hooks レシピと、効かないときの確認リスト

受託開発で安全側に倒す CLAUDE.md・権限設定・Hooks の 3 層で、指示していないファイルの変更を防ぐ。

→ 受託開発で Claude Code を安全側に倒す設定

気をつけること

フック自体の間違いに気づきにくい。 検査する側のスクリプトが間違っていると、誰も気づけません。フックにもテストを書く、という考え方の記事があります。

→ Claude Code の Hook を「誰が検査するのか」問題 ― 観点・テスト・変異テストで品質を育てる

増やしすぎない。 70 本あったフックを 6 本に減らしてトークンを 71% 減らした、という記録もあります。

→ Claude Code の常駐エージェントを再構築：トークン71%削減も、根本的な誤りパターンは改善されず

書き換え（updatedInput）が不正だと止まる。 ツールが受け付けない形に書き換えると、実行前に止まります。Hiroba 編集部で旧版と比べて試しました。

→ Claude Code 2.1.300 のフック updatedInput 検証を旧版と比べた

PermissionRequest は、許可の要らない操作では呼ばれなかった。 Hiroba 編集部の試験では echo では呼ばれず、mkdir で呼ばれました（公式ドキュメントに明記はありません）。すべてのツールの使用を見たいなら PreToolUse を使います。

最近の変更

この記事は Hiroba 編集部（Koji）が、Claude Code の公式ドキュメント（Hooks）と Hiroba に集まった記事をもとにまとめました（2026-10-21 時点）。