Claude Code hook 必要性検証

2026年4月30日 22:30 更新

一言でいうと

Claude Code（コーディングAI）の自動処理レール（hook）28 本を棚卸し。4 本要改修・3 本不要・1 本（plan-impl-gate）が常態化していた回避ハックの元凶。

なぜこれが必要なのか

Claude Code には「ツール実行前後」「セッション開始終了時」などのタイミングで自動的に走るスクリプト群（hook = フック、引っかけ）がある。これらは便利な反面、設計を誤ると「正常な作業を勝手に止める」「危険な処理をすり抜けさせる」両方向に壊れる。

直近 4/26 〜 4/30 の運用で複数の hook エラーや誤動作が観測された。特に plan-impl-gate.sh の誤ブロックが原因で、Bash の heredoc（ヒアドキュメント、複数行をまとめて流し込む書き方）でファイル書き込みを回避するハック運用が常態化していた。今回はその全体像を整理して「何を残し、何を直し、何を捨てるか」を判定するのが目的。

何をしたのか

Claude Code 環境（~/.claude/settings.json 本体 + 各プラグイン側）の hook を全件読み込み、以下の観点で評価した。

目的（何のためにあるか）
発火条件（matcher = どのツール/イベントで動くか）
実害（既知の誤動作・運用上の歪み）
改修案 or 削除判断

件数サマリ

分類	件数	主な該当
必要	17	rate-limit-recovery、claude-stop、Permission 系、SessionStart 系、convert-plan、plan-write-marker、record-outbound、rm-rf-guard など
要改修	4	plan-impl-gate.sh、plan-viewer-stop-check.sh、settings 側の plan-viewer prompt、inject-datetime.sh
不要	3	plan-viewer plugin の重複 prompt、promo-video-compact-hook.sh、plugin-dev-prompt-hook.sh
未配線（デッドコード）	4	plan-bash-gate / plan-exitplan-gate / plan-html-gate / plan-sync-reminder

実害が大きかった hook 上位 3 つ

1. plan-impl-gate.sh（plan-viewer plugin / PreToolUse）

プラン（設計書）が更新されたあとに plan-viewer の HTML 同期を強制するためのフラグ番人。だが tool_input.file_path 取得失敗時に「警告だけ出して通す」フォールバックが致命的。

具体的には、Bash の cat <<EOF > path（heredoc）で書く場合は file_path フィールドが存在しないので、ガードがそのまま素通る。一方、正規の Write ツールでは file_path が取れるので発火 → CWD 比較ロジックの誤判定で通常作業を block する場面もある。両方向に壊れていて、結果として「heredoc で逃げる」運用が定着していた。

皮肉なことに、このレポート自体を Write ツールで書こうとしたら settings.json 側の prompt が .md に対して 2 回発火し、結局 heredoc 経由でのみ書けた。dispatch で指摘された現象が、検証中にリアルタイムで再現したことになる。

2. generic-convert-md.sh（hook 本体ではないが影響大）

launchd（macOS 標準のジョブ管理）の md-auto-publish 経由で ~/publish-md/ 配下の Markdown を ~/plan-viewer/ に publish する設計。ところが skip 判定が緩く、daily-report の出力 18 件が誤って plan-viewer に複製された。

j-20260430-001 で skip 判定の欠陥は修正済み。今回は再発防止のため周辺コンポーネントとして記録。

3. plan-viewer-stop-check.sh（plan-viewer plugin / Stop）

フラグが立ったまま会話を終了しようとすると exit 2 でブロックする防壁。dispatch ジョブの実行中など「プラン作成と無関係な作業」中でもフラグの隔離キー（CWD 比較）が誤判定すれば誤発火しうる。

plan-impl-gate と同じセッション隔離ロジックを共有しているので、A の改修と一緒に session_id ベースに切り替えるのが妥当。

改修案（別ジョブとして提案）

このジョブでは設計のみ。実装は以下の単位で別ジョブに切り出す。優先度は A > B > C > D > E。

A: plan-viewer フラグ機構の根本改修

対象: plan-impl-gate.sh, plan-viewer-stop-check.sh, フラグ作成側
スコープ: heredoc 抜け道塞ぎ + session_id ベース隔離 + 期待アクション type の追加
完了条件: heredoc 経由の Write が plans/ 更新後に block されること、heredoc 回避運用が不要になること

B: plan-viewer prompt の重複削除

対象: ~/.claude/settings.json の PreToolUse > Write(*/plan-viewer/*.html) ブロック
スコープ: 削除のみ（plan-viewer plugin 側に一本化）。同時に matcher パターンが .md にまで反応してしまう不具合も解消されるはず
完了条件: plan-viewer HTML 書き出し時に prompt が 1 回だけ発火し、.md ファイルへの Write が誤発火しない

C: 不要 hook の削除と settings.json クリーンアップ

対象: promo-video-compact-hook.sh, plugin-dev-prompt-hook.sh, settings.json の対応エントリ
スコープ: スクリプトと hook 登録を削除
完了条件: 削除後に SessionStart / UserPromptSubmit / PreCompact が想定どおり動くこと

D: inject-datetime の整理

対象: inject-datetime.sh（PreToolUse "" matcher）
スコープ: matcher を Bash 限定にするか、UserPromptSubmit 側に一本化して廃止
完了条件: 不要なコンテキストノイズが減る + 時刻参照が必要な場面では従来どおり機能

E: 未配線 plan-* hooks の整理

対象: plan-bash-gate.sh, plan-exitplan-gate.sh, plan-html-gate.sh, plan-sync-reminder.sh
スコープ: 意図確認 → アーカイブまたは削除
完了条件: 誤配線リスクの除去

主要 hook 一覧（settings.json 本体）

イベント	matcher	スクリプト	判定
InstructionsLoaded	""	`instructions-log.sh`	必要
PostToolUse	Write\|Edit	`convert-plan.sh`	必要
PostToolUse	Write\|Edit	`plan-write-marker.py`	必要
PostToolUse	telegram	`record-outbound.sh`	必要
PreToolUse	""	`inject-datetime.sh`	要改修
PreToolUse	Bash	`rm-rf-guard.sh`	必要
PreToolUse	AskUserQuestion	`notify-secretary-blocked.sh`	必要
PreToolUse	Write(plan-viewer/*.html)	prompt	不要（重複）
SessionStart	""	`compact-init.sh`	必要
SessionStart	""	`load-persona.sh`	必要
SessionStart	""	`session-bootstrap-hook.sh`	必要
Stop	""	`claude-stop.sh`	必要
PermissionRequest	Edit\|Write	`auto-approve-claude-dir.sh`	必要
PermissionRequest	""	`notify-secretary-permission.sh`	必要
PreCompact	""	`compact-counter.sh`	必要
PreCompact	""	`promo-video-compact-hook.sh`	不要
UserPromptSubmit	*	`inject-datetime-prompt.sh`	必要
UserPromptSubmit	*	`plugin-dev-prompt-hook.sh`	不要
UserPromptSubmit	*	`session-reminder.sh`	必要
Notification	idle_prompt	`notify-secretary.sh`	必要
PostToolUseFailure	""	`notify-secretary-failure.sh`	必要
SessionEnd	""	`notify-secretary-session-end.sh`	必要
StopFailure	""	`rate-limit-recovery.sh`	必要

plan-viewer plugin の hooks

イベント	matcher	スクリプト	判定
PreToolUse	Write\|Edit	`plan-impl-gate.sh`	要改修
PreToolUse	Write	prompt	不要（重複）
Stop	""	`plan-viewer-stop-check.sh`	要改修

codex plugin の hooks

イベント	スクリプト	判定
SessionStart	`session-lifecycle-hook.mjs SessionStart`	必要
SessionEnd	`session-lifecycle-hook.mjs SessionEnd`	必要
Stop	`stop-review-gate-hook.mjs` (timeout 900s)	必要

ポイント

このジョブで実装は行っていない。設計のみ。改修は A〜E の別ジョブで段階的に進める方針。

Markdown 版の詳細レポートは Second-Brain（個人ノート）の 2026-04-30_Claude_Code_hook_必要性検証.md に保存済み。改修着手時はそちらの「補足: なぜ plan-impl-gate.sh は壊れたのか」セクションを起点にすると、矯正方針が一気に見える。

関連: ADR-012（rate-limit 自動復帰）/ ADR-014（PermissionRequest hook 導入）/ ADR-015（telegram outbound 記録）/ j-20260430-001（generic-convert-md skip 欠陥修正、対応済み）。