3行でいうと

  • フックは、Claude Codeの動きの特定の場面（ファイルを編集した後、コマンドを実行する前、会話の開始時など）で、自分が書いたコマンドなどを実行する仕組みです。公式は、AIが実行するかどうかを選ぶ方式とは違い、決めた動作が必ず起きる点が利点だと説明しています。
  • 実行を止めたいときの約束事は、終了コードです。2 で止まり、1 では止まらない、と公式が強調しています。フックは複数あれば並列で動くため、設計には癖があります。
  • プラグインは、スキル、エージェント、フック、MCPサーバーを1つにまとめて入れる仕組みです。公式は、プラグインが利用者の権限でコードを実行できると明記し、入れる前に中身を確認するよう案内しています。

この記事は公式ドキュメントを2026年10月16日に読んでまとめたもので、実際に使って確かめた記録ではありません。運営者はClaude Codeを入れていますが、使い心地はこの記事には書いていません。設定のキー、イベント名、コマンドは公式に書かれたとおりに写したもので、動作確認はしていません。公式の文章は要約の形で取得したため、引用はせず言い換えています。

先に結論

フックとは：決まった場面で動く、自分のコマンド

フックは、利用者が定義したシェルコマンドなどを、Claude Codeのライフサイクルの決まった時点で実行する仕組みです。公式は、決まった動作が毎回起きること、つまり確実さを、AIに実行を任せる方式との違いとして挙げています。判断が要る場面には、モデルに条件を判定させる「prompt」型や、調査もする「agent」型（実験的）も使えます。

イベントの例（公式の表より）。

イベント 動く時点 止められるか
SessionStart 会話の開始・再開時 止められない
UserPromptSubmit プロンプトの送信後、処理の前 止められる
PreToolUse ツール実行の前 止められる
PermissionRequest 許可の判断が要るとき 終了コード2では止められない
PostToolUse ツールの成功後 止められない（実行済み）
Notification 通知が出るとき 止められない
Stop Claudeが応答を終えたとき 止められる（会話が続く）
ConfigChange 設定ファイルが変わったとき 止められる（policy_settings は除く）
SessionEnd セッションの終了時 止められない

ほかにも、SubagentStart、PreCompact、PostCompact、CwdChanged、FileChanged など、公式の一覧には30を超えるイベントがあります。

実行するものの種類。 type に指定します。command（シェルコマンド）、http（URLへPOST）、mcp_tool（MCPサーバーのツール）、prompt（1回のモデル判定）、agent（複数ターンの検証）です。

設定のしかた：JSONで、場所は7つ

設定は、設定ファイルの hooks の下に、イベント名、matcher（どのツールに反応するか）、hooks の配列、の順で書きます。公式ガイドの「保護したファイルの編集をブロックする」例は、次の形です。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

スクリプトは、標準入力のJSONから tool_input.file_path を読み、保護対象に当てはまれば、標準エラーに理由を書いて exit 2 で終わります。

置き場所は、公式の表で次のとおりです。~/.claude/settings.json（全プロジェクト、自分だけ）、.claude/settings.json（プロジェクト、共有可）、.claude/settings.local.json（プロジェクト、共有しない）、管理設定（組織）、プラグインの hooks/hooks.json、スキルの設定、サブエージェントの設定です。複数の場所のフックは混ぜ合わされ、一致したものは並列で動きます。登録したものは /hooks で確認できます。

入力と出力：終了コードで会話する

フックには、イベントごとのデータが、標準入力のJSONで渡されます（session_id、cwd、hook_event_name、ツールの前後なら tool_name と tool_input など）。結果は、終了コードで返すのが基本です。

終了コード 意味（公式の表）
0 成功。標準出力が1つのJSONなら、その内容が使われる。SessionStart など一部のイベントでは、文字がそのままClaudeの文脈に入る
2 止められるイベントでは、遮断。標準エラーが理由になる
それ以外 止めない通知付きエラー。1 もここに入る

公式は、方針の強制には exit 2 を使い、exit 1 だけでは止まらないと強調しています。細かい制御には、exit 0 でJSONを返します。たとえば PreToolUse では、hookSpecificOutput の中に permissionDecision（allow、deny、ask）を書きます。公式は、「終了コード2で止める」か「exit 0 でJSONを返す」かを、1つのフックでは片方に決めるよう書いています。

時間切れ、並列実行、特殊な動き（公式の記載）
  • 既定の時間切れは、command・http・mcp_tool が10分、prompt が30秒、agent が60秒です。UserPromptSubmit などは30秒に短縮され、SessionEnd は全体で1.5秒の枠を共有します。
  • 一致した複数のフックは、並列で、最後まで動きます。1つが deny を返しても、ほかのフックの実行は止まりません。PreToolUse の許可判断は、deny、defer、ask、allow の順で、厳しいものが採用されます。
  • 複数の PreToolUse フックが、同じツールの入力を updatedInput で書き換えると、最後に終わったものが有効です。順序は決まらないため、同じ入力を書き換えるフックは1つにするよう書かれています。
  • Stop フックは、続けて8回止めたあと、Claude Codeが上書きします。フックの側で、入力の stop_hook_active が true なら早めに終了するよう書かれています。上限は環境変数 CLAUDE_CODE_STOP_HOOK_BLOCK_CAP で上げられます。
  • PostToolUse は、ツールの実行後なので、取り消せません。

フックと権限の関係

公式は、ここを丁寧に書いています。

注意点：つまずきやすいところ

公式の「Limitations and troubleshooting」から、実際につまずきやすい点を選びます。

  1. シェルの設定ファイルが、JSONを壊す。 フックはシェルで起動されます。~/.zshrc などに、無条件の echo があると、その文字がフックの出力の前に混ざり、JSONとして読まれません。終了コード0なら、画面には何も出ない、と書かれています。対策は、echo を「対話シェルのときだけ」の条件に包むことです。
  2. JSONの置き場所を間違える。 permissionDecision や additionalContext は、hookSpecificOutput の中に書きます。最上位に書くと、読み込まれても無視され、エラーも出ません。
  3. スクリプトの実行権限とパス。 実行権限（chmod +x）の付け忘れや、相対パスが原因のエラーが挙げられています。$CLAUDE_PROJECT_DIR を使う、args で起動する、などが対策です。
  4. 効いているか分からない。 成功したフックは、画面に何も出ません。Ctrl+O で記録を見るか、claude --debug-file で出力先を指定して確認します。
  5. 信頼していないフォルダのフック。 公式の権限ページの表では、リポジトリの設定ファイルに入ったフックは、claude -p（画面なし）では、フォルダを信頼していなくても使われます。他人のリポジトリで実行する前の対策として、--bare や --settings '{"disableAllHooks": true}' が挙げられています。

プラグイン：まとめて配る箱

プラグインは、スキル、エージェント、フック、MCPサーバーなどの部品を、1つの単位で入れるためのフォルダです。部品は、skills/、agents/、hooks/hooks.json、.mcp.json に置き、名前や版は .claude-plugin/plugin.json に書きます。プラグインのスキルは /プラグイン名:スキル名 という名前で呼びます。

入れ方は、Claude Codeの中で /plugin install commit-commands@claude-plugins-official のように、プラグイン名と配布元（マーケットプレイス）を指定します。画面の中では、すぐには入れず、詳細画面が開いて範囲を選ぶ流れだと書かれています。シェルからは claude plugin install です。範囲は、ユーザー、プロジェクト、ローカルの3つから選びます。公式のマーケットプレイスは、対話画面で初めて起動したときに自動で追加されます（組織の管理設定で止められている場合を除く）。まだ一度も対話画面を開いていないパソコンでシェルから入れるときは、先に claude plugin marketplace add anthropics/claude-plugins-official が必要だと公式に書かれています。それ以外は、/plugin marketplace add owner/repo のように足します。

入れる前に確認すること（公式）。 公式は、入れたプラグインが、利用者の権限でパソコン上のコードを実行しうると書いています。フックはシェルコマンドとして、MCPサーバーは手元のプロセスとして動き、権限ルールとサンドボックスが守るのはClaudeのツール呼び出しで、フックやサーバーのプロセス自体は対象外です。確認の手順は、次のとおりです。

さらに、自動更新がオンの配布元では、確認したあとでも中身が変わりうると、公式は書いています。既定では、公式のマーケットプレイス（一部を除く）はオン、それ以外はオフです。入れたプラグインは、使わないセッションでも、説明文などが文脈に入り、MCPサーバーも動きます。claude plugin details <名前> で、その負担を見られます。

組織向けの設定（管理設定）。 allowManagedHooksOnly（管理設定以外のフックを止める）、disableAllHooks、allowedHttpHookUrls、httpHookAllowedEnvVars などがあります。プラグインでは、配布元の許可と拒否、プラグインの強制インストールができる、と書かれています。

僕らの見立て

見立てです。公式の整理から組み立てたもので、公式の推奨そのものではありません。最初の一歩は、通知のフックのように、失敗しても困らないものがよさそうです。止める系のフックは、/hooks で確認し、スクリプトを単体で動かしてから入れる、という順です（公式のトラブル対応にも、サンプルのJSONを流し込んで終了コードを見る手順があります）。プラグインは、配布元と、フックと .mcp.json の中身を読めるかどうかが、判断の材料になると考えます。

気をつけること

出典