この文書は、doc_bug を「Issue番号」ではなく「確定で再現する条件」で整理し直したものです。
同じ問題の重複カウントを避けるため、頻度順に条件を取り出して、取り出した分を除外しながら再分類しています。
- 対象データ: フック期待値と実測結果を1ケース単位で記録した全件データ
- 総ケース数:
5076 doc_bug:2470doc_expected:2606- 集計時刻:
2026-03-05T20:28:58Z - 実行ログ上の Claude Code バージョン（過去集計）:
2.1.69 - 検証時点の Claude Code バージョン（2026-03-11時点）:
2.1.72
補足: この文書の結論は 5076 ケースの実測ログに基づきます。Issue状態は 2026-03-11 に再取得しました。
project_local: プロジェクト内に直接置いた設定plugin_dir:--plugin-dirで読み込む方式marketplace: Marketplace 経由で入れる方式frontmatter_*: スキル/エージェント定義ファイル先頭（YAML）に書くフックsettings_*:settings.json側に書くフックinteractive: 対話モードprint: 単発実行モードsession: セッション継続モードagent_flag_fork: 入口から別エージェントとして分岐起動する実行経路slash_fork: スキル/コマンド経由で fork 実行
install_mode:project_local / plugin_dir / marketplaceinvoke_mode:interactive / print / sessionenv_mode:inherit / unset_nested / env_ientry_mode:plain_prompt / slash_inline / slash_ops / slash_fork / agent_flag_forkoperation:plain / bash / write / sub / subsubhook_surface:settings_stop / settings_subagentstop / settings_sessionend / settings_pretooluse / settings_posttooluse / frontmatter_skill_stop / frontmatter_agent_stopblock_mode:allow / denydepth:main / sub / subsub
ユーザー指定の手順をそのまま機械化しています。
- 未分類の
doc_bugから、「条件に入ったケースが100% doc_bug」の条件の中で、件数最大を1つ選ぶ。 - その条件を「確定再現条件」として記録する。
- その条件で説明できたケースを未分類集合から取り除く。
- 1に戻る。未分類が尽きるまで繰り返す。
出力:
- 非重複ルール一覧（頻度順）
- 本文で扱う上位条件: 新規件数
10以上（17条件）
hookずれ は hook_fired_mismatch 件数、blockずれ は block_observed_mismatch 件数です（同一ケースが両方に入ることがあります）。
| 順位 | 新規件数 | 累積 | hookずれ | blockずれ | 再現条件（やさしい説明） |
|---|---|---|---|---|---|
| 1 | 864 | 864 (35.0%) | 864 | 432 | plugin_dir または marketplace で入れた状態で、frontmatter の Stop フック（frontmatter_agent_stop / frontmatter_skill_stop）を使うと、必ず doc_bug。 |
| 2 | 276 | 1140 (46.2%) | 16 | 266 | plugin_dir または project_local で、settings_sessionend を deny、実行が interactive または -p のとき、必ず doc_bug。 |
| 3 | 207 | 1347 (54.5%) | 56 | 207 | marketplace で settings_stop=deny のとき、必ず doc_bug。 |
| 4 | 162 | 1509 (61.1%) | 162 | 81 | --agent 分岐実行で settings_subagentstop を使い、操作が plain/bash/write のとき、必ず doc_bug。 |
| 5 | 99 | 1608 (65.1%) | 39 | 99 | marketplace で settings_subagentstop=deny のとき、必ず doc_bug。 |
| 6 | 96 | 1704 (69.0%) | 96 | 48 | interactive かつ inherit / unset_nested 環境で frontmatter Stop を使うと、必ず doc_bug。 |
| 7 | 92 | 1796 (72.7%) | 0 | 92 | plugin_dir / project_local で env_i / unset_nested、settings_sessionend=deny のとき、必ず doc_bug。 |
| 8 | 70 | 1866 (75.5%) | 70 | 35 | slash_fork で frontmatter_skill_stop を使うと、必ず doc_bug。 |
| 9 | 42 | 1908 (77.2%) | 42 | 21 | --agent 分岐実行で frontmatter agent_stop を使い、plain/bash/write のとき、必ず doc_bug。 |
| 10 | 36 | 1944 (78.7%) | 36 | 18 | plugin_dir で --agent 分岐実行し、settings_subagentstop を使うと、必ず doc_bug。 |
| 11 | 36 | 1980 (80.2%) | 36 | 0 | plugin_dir で --agent 分岐実行し、PreToolUse/PostToolUse を使うと、必ず doc_bug。 |
| 12 | 30 | 2010 (81.4%) | 0 | 30 | plugin_dir / project_local で分岐実行系（agent_flag_fork / slash_fork / slash_ops）かつ settings_sessionend=deny のとき、必ず doc_bug。 |
| 13 | 30 | 2040 (82.6%) | 30 | 15 | project_local で -p 単発、slash_fork 経由、settings_stop を使うと、必ず doc_bug。 |
| 14 | 20 | 2060 (83.4%) | 20 | 20 | env_i / unset_nested で frontmatter_skill_stop=deny、操作が plain 以外（bash/sub/subsub/write）のとき、必ず doc_bug。 |
| 15 | 18 | 2078 (84.1%) | 18 | 0 | plugin_dir / marketplace で --agent 分岐実行、PreToolUse/PostToolUse=deny のとき、必ず doc_bug。 |
| 16 | 12 | 2090 (84.6%) | 12 | 0 | plugin_dir / marketplace で --agent 分岐実行、interactive / session で settings_subagentstop を使うと、必ず doc_bug。 |
| 17 | 10 | 2100 (85.0%) | 10 | 3 | interactive で slash_inline 実行し、frontmatter Stop を使うと、必ず doc_bug。 |
残件:
- 上位17条件で
2100件（85.0%）を説明 - 残り
370件（15.0%）はロングテール
- 対応条件: 1, 6, 8, 9, 14, 17
- 代表事実:
plugin_dir/marketplace+ frontmatterStopは今回実測で大半が未発火
- 対応条件: 2, 7, 12
- 代表事実:
settings_sessionend=deny条件でblockずれが集中的に発生
- 対応条件: 3（および 13 の一部）
- 代表事実:
settings_stop=denyでblockずれが高頻度
- 対応条件: 4, 5, 10, 16
- 代表事実:
agent_flag_forkでsettings_subagentstopが未発火になりやすい
- 対応条件: 11, 15
- 代表事実:
plugin_dir/marketplaceではPreToolUse/PostToolUseが未発火になりやすい
- A（frontmatter Stop）: #17688, #16288, #9354, #24115, #24529, #27153, #16803, #19213, #19220
- B（SessionEnd + deny）: #30217, #24571, #27244
- C（settings_stop + deny）: #11947, #27521
- D（SubagentStop + --agent）: #27755, #27423, #20221, #22087, #33049
- E（Pre/PostToolUse + --agent）: #6305, #26923, #21460, #24788, #33073
- 追加で近接: #25655
| Issue | 状態 | state_reason | タイトル |
|---|---|---|---|
| #17688 | open | - | [BUG] Skill-scoped hooks defined in SKILL.md frontmatter are not triggered within plugins |
| #16288 | open | - | Plugin hooks not loaded from external hooks.json file |
| #9354 | open | - | [BUG] Fix ${CLAUDE_PLUGIN_ROOT} in command markdown OR support local project plugin installation |
| #24115 | open | - | Plugin hooks fire twice: marketplace source + cache both loaded |
| #24529 | open | - | Hook executor doesn't set CLAUDE_PLUGIN_ROOT environment variable |
| #27153 | open | - | [BUG] Agent frontmatter hooks: changelog (v2.1.0) says 3, official docs say "all", but only 6 of 16 actually fire |
| #16803 | open | - | feat: context: fork in skill frontmatter doesn't work - skill still runs inline |
| #19213 | closed | completed | [BUG] Agent frontmatter hooks (PreToolUse, PostToolUse, Stop) not executing |
| #19220 | open | - | [BUG] Agent Stop hook receives "SubagentStop" instead of "Stop" as hook_event_name |
| #30217 | closed | completed | SessionEnd hook: transcript file deleted before hook can read it |
| #24571 | open | - | Subagent SessionEnd crash: classifyHandoffIfNeeded is not defined |
| #27244 | open | - | [FEATURE] Hook Exit Code for Session Termination |
| #11947 | open | - | [BUG] Prompt-based Stop hook cannot response correct JSON |
| #27521 | open | - | [BUG] Marketplace plugins with hooks cause "No such file or directory" errors for non-installed plugins |
| #27755 | open | - | [BUG] SubagentStart/SubagentStop unreliable for settings.json hooks — cascade failures break agent lifecycle management |
| #27423 | open | - | [BUG] SubagentStop fires without corresponding SubagentStart for internal agents |
| #20221 | closed | not_planned | Prompt-based SubagentStop hooks send feedback but don't prevent termination |
| #22087 | closed | completed | BUG: classifyHandoffIfNeeded is not defined - SubagentStop hook failure |
| #33049 | open | - | Subagent (Agent tool) does not fire Stop hook on completion |
| #6305 | open | - | Post/PreToolUse Hooks Not Executing in Claude Code |
| #26923 | open | - | PreToolUse hook exit code 2 does not block Task tool calls (agents launch despite block) |
| #21460 | open | - | [SECURITY] PreToolUse hooks not enforced on subagent tool calls, allowing security bypass |
| #24788 | open | - | PostToolUse hooks with additionalContext not surfacing for MCP tool calls |
| #33073 | open | - | [BUG] PreToolUse hooks cause agent hang after ToolSearch deferred tool loading |
| #25655 | open | - | All plugin hooks stop firing after context compaction |
件数内訳（この表の25件）:
- open: 21
- closed(completed): 3
- closed(not_planned): 1
- ケース定義と期待値定義を固定し、同じマトリクス（5076ケース）で比較する。
- 判定は
doc_bug / doc_expectedとhookずれ / blockずれの2系統で分ける。 - 再分類は「確定再現条件を頻度順に1つずつ取り出し、取り出した分を除外する」手順を守る。
- Issue対応は、同じ問題群単位（A〜E）で更新し、状態（open/closed + state_reason）を分けて記録する。
note:この文章はGPTが書きました。私は実験方法と分類方法だけ指示してます。OS依存の再現性についてはチェックしていないので、続報あれば教えてください＆元Issueに追記してあげるとよいと思います。（多分人間には読まれなさそうですが）