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

フックとは

フックは 特定のイベント発生時に自動実行されるシェルユーザーとOSの間に入って、コマンド入力を受け付けて実行する程序。ターミナルで打つコマンドを実際に処理する部分スクリプト自動実行できる小さなプログラム。手順を書いたテキストファイルの形をしている。Claude Codeの動作を拡張・制御する。

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

主要4種のフック

<a id="sessionstart"></a>SessionStart

セッションClaude Codeの1回の対話単位。起動から終了までの会話と作業状態のこと。長く使うと内容が混ざるため、トピックの区切りで新セッションに引き継ぐ運用をする開始時に実行。

バナー集約パターン（startup-banner.sh）

複数のSessionStart hookClaude Codeの特定のタイミング（ツール実行前後・セッション開始時等）で自動処理を差し込む仕組み。「保存前にチェック」「終了時に記録」等を機械的に強制できるが各自 stdout を出すと出力が散らかるため、各hookは /tmp/claude-startup/<名前>.status にステータスを書くだけにし、最後の1本 startup-banner.sh が集約して1枚のバナーにする設計。

• 集計: ステータスファイルの行頭マーク ✅/⚠️/❌ を数えて「フック: N/M 正常 | 要確認: <名前>」形式でサマリー
• 表示内容: CCバージョンソフトウェアやファイルの「どの時点の状態か」を示す番号。v1.2等。更新のたびに番号が上がる（hook検知時は「✅最新版！」フラグ）・前回handoff・本日セッション数・スキルClaude Codeで「特定の作業手順」をパッケージ化したもの。SKILL.mdに手順を書いておくと、対応する場面でAIがその手順を読み込んで従う。経験を再利用する仕組みトリガーマップ（各SKILL.mdの「トリガーワード」欄を自動抽出）
• 層1読込検証（@取り込み実働チェック）: CLAUDE.md の @rules/ 参照ファイルの存在確認に加え、LLMへ「特定行の見出しを返答冒頭で引用せよ」という引用チャレンジを出す（中身は表示しない=引用できれば読込証明・echo捏造では成立しない）
• Desktop App対応: /dev/tty は使わず stdout に出力（Desktop Appでは /dev/tty が使用不可のため）

<a id="pretooluse"></a>PreToolUse

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

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

• bash -x（デバッグ不具合の原因を特定して直すこと。ログや実行の跡を辿って、どこで期待と違う動きをしたかを突き止める作業出力でシークレット露出の恐れ）
• cat -A（特殊文字表示でシークレット露出の恐れ）
• マスクなしの grep（APIApplication Programming Interface（エーピーアイ）の略。あるプログラムの機能を、別のプログラムから呼び出せるようにした「窓口」キーを含むファイルの検索）
• フィルタなしの env（全環境変数値を入れておく名前付きの箱。x = 1 のように名前に値を紐付けて、後で使い回すの表示）

<a id="posttooluse"></a>PostToolUse

ツール実行後に実行。

<a id="stop"></a>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

Windows Desktop版とWSL側のSessionStartフック差分に注意（2026-07-10）

Windows Desktop版とWSL CLI版の settings.json は別ファイル（C:\Users\yn441\.claude\settings.json と ~/.claude/settings.json）のため、片方だけにフックを追加登録してもう片方に反映し忘れることがある。check-proxy-compat.sh・check-ssot-sync-staleness.sh はWSL側にのみ登録されWindows側で約1日分未同期だった実例あり。フック追加・変更時は両方の settings.json を確認すること。

登録スクリプトの $HOME に依存する処理（例: sync-secrets-to-settings.sh）は要注意。wsl bash 経由で実行しても $HOME は常にWSL側 /home/<USER> に解決されるため、Windows側のsettings.json自体を対象にしたい処理はwsl bash経由では実現できない（対象が常にWSL側ファイルになる）。逆に状態ファイル（~/.claude/state/）を使った日次発動制御のような「WSL・Windows間で共有したい」ロジックは、この同一解決先という性質を逆手に取って安全に両環境へ登録できる。

Windows側でフックコマンド文字列をスクリプト経由（例: python の json.dump）で新規追加する際、path-rewrite.py が Bash ツールに送るコマンド文字列内の /home/<USER> を検知してUNC形式に書き換えてしまうため、文字列を "/" + "home/<USER>" のように分割して結合し検知パターンを回避する必要がある。

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

WSL側settings.jsonのフックはWindows Desktopでも発火する（uname判定分岐パターン・2026-07-11）

Windows Desktop版のセッションは作業ディレクトリがWSLホーム（\\wsl.localhost\Ubuntu\home\<USER>）のため、WSL側 ~/.claude/settings.json をプロジェクト設定として読み込み、そのフックがGit Bash上で発火する。python3 /home/<USER>/bin/xxx.py のようなWSLパス直書きコマンドは Git Bash が /home/<USER> を C:\Program Files\Git\home\<USER> に解決して毎回エラーになる（archive-backlog-done.py で実例あり）。

共有されるフックコマンドは uname -s 判定で両環境に分岐させる:

if [ "$(uname -s)" = "Linux" ]; then python3 /home/<USER>/bin/xxx.py; else wsl bash -c "python3 /home/<USER>/bin/xxx.py"; fi

なお、フック設定はセッション起動時にスナップショットある瞬間の状態のコピー。後で比較・復元するために取っておくもの取込されるため、settings.json修正後も既存セッションでは旧コマンドが発火し続ける（反映には再起動が必要）。 → バックログhookのWindows環境判定分岐修正

自律タスクループ（Stop HookClaude Codeの特定のタイミング（ツール実行前後・セッション開始時等）で自動処理を差し込む仕組み。「保存前にチェック」「終了時に記録」等を機械的に強制できる 応用）

概要

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 → 完了

PreToolUseでのコマンド書き換え（updatedInputパターン）

PreToolUseフックはブロック（{"decision": "block", ...}）だけでなく、ツールの実行直前にその入力を書き換えることもできる。以下のJSONをexit code 0で標準出力プログラムが結果を書き出す標準的な出口。画面表示や次のプログラムへの受け渡しに使われる。ちなみにエラー情報は「標準エラー出力」という別の出口に出るに書くと、updatedInputで指定した内容が実際の実行に反映される（セッション再起動不要・live反映）。

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "updatedInput": { "command": "書き換え後のコマンド文字列" }
  }
}

実例（Windows Desktop版限定）: path-rewrite.pyは、Bashコマンド文字列内の既知WSLホームパスプレフィックス（~/projects/・~/.claude/・/home/<USER>/projects/・/home/<USER>/.claude/の4種のみ＝ホワイトリスト）をUNCパス（//wsl.localhost/Ubuntu/home/<USER>/...）に単純文字列置換する。これにより、WSL CLI版で書かれた共有ファイル（handoff/SKILL.md/SSOT）内のパスをWindows Desktop版でも変換なしで実行できる。

デバッグ方法

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

1. フックのログを確認 — エラーメッセージが表示される
2. 手動でスクリプトを実行 — ターミナル文字だけでパソコンと対話する画面。コマンドを打ち込むと結果が文字で返ってくる。Claude Code CLIはここで動くで直接実行して動作確認
3. /config で設定確認 — hooks セクションの内容を確認
4. 一時的に無効化 — settings.json で該当フックをコメントアウト

guard-settings-write（Task6 α C'案・✅実装済 2026-07-31）

settings.json への TOKEN 書込を PostToolUse 内容ベース差分検知で防御する hook。Bash 経由（jq / sed / リダイレクト / python3 -c / MCP / hooks 設定）の本体 settings.json 書換も完全スルーする guard-config-secrets.sh の盲点を塞ぐ。

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

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