Hooks システム

学ぶこと

Hooks は Claude Code ライフサイクルの定義された時点で deterministic automation を実行します。活動の監査、context の追加、ファイル整形、実行前の操作ブロックに利用できます。

現行の settings schema は nested 構造です。

hooks
└── event name
    └── matcher group
        └── hooks
            └── handler

古い flat event-to-command 形式は使用しないでください。

Hook を設定する

必要な scope に応じて user、project、local settings に hooks を置きます。この project hook は Bash コマンドを実行前に検査します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

外側の key が event を選び、matcher group がその event を絞り込み、内側の hooks array が一つ以上の handlers を保持します。現在の handler types は command、http、mcp_tool、prompt と、実験的な agent hooks です。

/hooks で有効な設定とその出所を確認できます。メニューは読み取り専用なので、変更には該当 settings file を編集します。

主なライフサイクルイベント

Hooks のイベントは四種類だけではありません。判断がまだ有効な、正確な時点の event を選びます。

フェーズ	主なイベント	一般的な用途
Session	SessionStart, SessionEnd	context の読み込み、初期化、アーカイブ
User turn	UserPromptSubmit, Stop, StopFailure	入力検証、完了条件の強制、失敗記録
Tool call	PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure	tools のブロック、承認、監査、後処理
Workers と teams	SubagentStart, SubagentStop, TeammateIdle, TaskCreated, TaskCompleted	workers の観測と quality gates
Context と設定	PreCompact, PostCompact, ConfigChange, InstructionsLoaded	context 遷移と設定変更の保護
Worktrees	WorktreeCreate, WorktreeRemove	分離環境の作成・削除のカスタマイズ

Reference には追加 events と正確な matchers があります。その一覧はバージョン付きドキュメントとして扱い、自分の enum へ永久にコピーしないでください。

Command Hook の入力

Command hooks は stdin から JSON を受け取ります。共通 fields は session_id、cwd、hook_event_name で、各 event が固有 fields を追加します。たとえば PreToolUse には tool_name、tool_input、tool_use_id があります。

#!/usr/bin/env bash
set -euo pipefail

payload=$(< /dev/stdin)
command=$(jq -r '.tool_input.command // ""' <<< "$payload")

if [[ "$command" == rm\ * ]]; then
  echo "Blocked by project policy" >&2
  exit 2
fi

exit 0

Hook scripts は小さく、deterministic かつ高速に保ちます。Event ごとに payload が異なるため、fields がない場合を検証してください。

出力とブロック規則

Command hooks では：

• exit 0：成功。Claude Code は stdout の JSON を解析できる
• exit 2：まだブロック可能な events では blocking error。feedback は stderr から渡る
• その他の non-zero code：ほとんどの events では non-blocking error
• WorktreeCreate は重要な例外で、すべての non-zero exit が作成を中止する

「ブロック」の意味は event が決めます。PreToolUse は tool 実行前に停止できますが、PostToolUse は実行済み tool を元に戻せません。Stop は agent に作業を続けさせられますが、SessionEnd は終了中の session を止められません。

PreToolUse を structured control するには exit 0 で JSON を返します。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database writes are not allowed"
  }
}

Decision fields は event 固有です。ある event の schema を全 hooks に一般化せず、その event の公式 reference から取得してください。

安全規則

• variables を quote し、本物の JSON parser を使う
• Project scripts は absolute paths または ${CLAUDE_PROJECT_DIR} で参照する
• secrets や完全な environment を hook output に出さない
• 予防には PreToolUse を優先し、post events は観測と後処理に使う
• 一致する hooks は並列実行され得る。同じ input を複数 hooks で競合して書き換えない
• 代表的な stdin JSON で scripts をテストし、/hooks で登録を確認する

Hooks は寛容なモードでもポリシーを厳しくできますが、allow response はより強い deny rule を上書きできません。Permissions bypass ではなく enforcement layer として設計してください。

公式情報源

• Hooks リファレンス
• Hooks でアクションを自動化する

次のセッション

次は private transcript structures を解析せず、サポートされた commands と IDs で session の継続性を管理します。