05 フック — イベント駆動の自動実行

フックとは

フックは 特定のイベント発生時に自動実行されるシェルスクリプト。Claude Codeの動作を拡張・制御する。

ユーザーがツールを実行
  │
  ▼
PreToolUse フックが発火 ──→ チェックOK → ツール実行
  │                          └─ チェックNG → ブロック
  ▼
ツールが実行される
  │
  ▼
PostToolUse フックが発火 ──→ ログ記録・後処理

主要4種のフック

SessionStart

セッション開始時に実行。

PreToolUse

ツール実行前に実行。最も重要なフック。

ブロックされるコマンドの例:

• bash -x（デバッグ出力でシークレット露出の恐れ）
• cat -A（特殊文字表示でシークレット露出の恐れ）
• マスクなしの grep（APIキーを含むファイルの検索）
• フィルタなしの env（全環境変数の表示）

PostToolUse

ツール実行後に実行。

Stop

セッション終了時に実行。

Notification / PostToolUseFailure

エラー・ブロック時（Notification）、ツール失敗時（PostToolUseFailure）に実行。Discord通知等の異常系ハンドリングに使用。

設定方法

フックは settings.json の hooks セクションに定義する。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/scripts/security/check-command-safety.py"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "source ~/.secrets.env"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/scripts/session/save-session-log.sh",
            "timeout": 5000
          },
          {
            "type": "command",
            "command": "~/.claude/scripts/session/generate-handoff.sh",
            "timeout": 3000
          },
          {
            "type": "command",
            "command": "~/.claude/scripts/session/queue-guide-updates.sh",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

matcherについて

• matcher はツール名を指定（例: "Bash", "Edit", "Read"）
• 空文字 "" は全ツールにマッチ
• 複数のフックを設定可能（配列で定義）

現在のフック構成（実態）

state日付管理による日次自動発動パターン（再利用可能）

check-ssot-sync-staleness.sh が実装する「stateファイルの日付で1日1回を制御」する汎用パターン。CronCreateは REPL idle時しか発火しないが、SessionStart hookはセッション開始で確実に走るため、この組合せで「忘れない」を担保する。

STATE="$HOME/.claude/state/<task>-last-run"
TODAY=$(date +%Y-%m-%d)
LAST=$(cat "$STATE" 2>/dev/null)
if [ "$LAST" != "$TODAY" ]; then
  # stdout がプロンプトとして注入される → CCが自律実行
  echo "[<task> 日次実行トリガー] ...を実行してください"
fi

実行側スキルは完了後 date +%Y-%m-%d > "$STATE" で再発火を抑制する。

自律タスクループ（Stop Hook 応用）

概要

GitHub Issue を順番に自動実装するイベント駆動ループ。
CronCreate が時間トリガーのみなのに対し、Stop Hook を使うことで「前のタスク完了後に次を起動」が実現できる。

ファイル構成

~/.claude/scripts/auto-dev/
├── state.json       # キュー状態（永続）
├── start.sh         # 手動起動エントリポイント
├── next-issue.py    # Stop Hook 本体
└── loop.log         # 実行ログ（自動生成）

使い方

# WSL で実行（Issue #76 → #75 の順で自律実行）
bash ~/.claude/scripts/auto-dev/start.sh 76 75

# 状態確認
cat ~/.claude/scripts/auto-dev/state.json

# ログ確認
tail -f ~/.claude/scripts/auto-dev/loop.log

緊急停止

python3 -c "
import json
p='/home/<USER>/.claude/scripts/auto-dev/state.json'
s=json.load(open(p))
s['active']=False
json.dump(s,open(p,'w'),indent=2)
print('停止しました')
"

誤爆防止

• state.active == false の時は next-issue.py が即 exit(0) — 通常の会話終了では何も起きない
• except 節で必ず exit(0) — Stop Hook がセッション終了をブロックすることはない

動作フロー

start.sh 76 75
  → state.json: active=true / pending=[76,75]
  → claude --print "Issue #76 を実装して..."
  → [セッション終了]
  → Stop Hook → next-issue.py
      → completed=[76] / pending=[75]
      → claude --print "Issue #75 を実装して..."
      → [セッション終了]
  → Stop Hook → next-issue.py
      → completed=[76,75] / pending=[] → active=false → 完了

デバッグ方法

フックが期待通りに動かない場合:

1. フックのログを確認 — エラーメッセージが表示される
2. 手動でスクリプトを実行 — ターミナルで直接実行して動作確認
3. /config で設定確認 — hooks セクションの内容を確認
4. 一時的に無効化 — settings.json で該当フックをコメントアウト

💡 やさしい補足（初心者向け）

• 「フック」= 特定のタイミングで自動で動く番人: 「作業開始時」「命令実行前」「終了時」などに、自動で決まった処理を走らせる仕組み
• 代表例: 危険な命令を止める（セキュリティ）・操作を記録する（ログ）・終了時にメモを残す
• 設定ファイルで管理: 何をいつ動かすかは設定ファイルに書く。小さなプログラム（スクリプト）を組み合わせる
• 地味だけど強力: 手動で毎回やる作業をフックに任せると、ミスが減って楽になる