feat: フック検出対象を副作用持ち4関数に縮小しソフトガードとして再定義 (v0.33.0)

[masuP9]

概要

PreToolUse フックの検出対象を副作用持ちヘルパー 4 関数に縮小し、マーカー判定を厳格化、フックの位置づけを「内部 API の偶発的誤用を防ぐソフトガード」として再定義します（Plan 007、v0.33.0）。

背景

「このフックは過剰ではないか」という問題提起を受け、Claude（廃止派）と Codex（存続派）による Devil's Advocate レビュー（3 ラウンド）を実施しました。評決は CONDITIONAL — 即時全廃は否決、ただし以下の条件での縮小存続が合意されました。本 PR はその承認条件 6 項目の実装です。

• 守る価値があるのは副作用を持つ関数（外部モデル実行・レビュー実行・状態書き込み）のみ
• 純粋変換関数や推測的パターン（HELPERS= 等）の検出は誤検知リスクと維持コストだけを生む
• 部分文字列一致のマーカー判定は引用テキスト内の言及でもバイパスが成立してしまう

議論の完全ログ: tmp/devils-advocate/20260612-120332-24936.md（ローカル）

変更内容

hooks/enforce-skill-usage.sh

• 検出対象を 4 関数に限定: codex_run_exec / codex_run_review / codex_save_session_state / codex_save_thread の実行位置検出のみに。source / HELPERS= / $HELPERS / CODEX_PROMPT の広域パターン 6 本を削除
• マーカー厳格化: 部分文字列一致 → 行頭の明示的 export CODEX_SKILL_CONTEXT=1 のみ認識（echo 内などの言及ではバイパス不可）
• ブロック文言を再定義: 「soft guard / not a security boundary」と意図的バイパスの手順を明記

hooks/test-enforce-skill-usage.sh（17 → 22 ケース）

• 非対象化した 5 形状（source・dot-source・HELPERS=・CODEX_PROMPT・純粋変換のパイプ実行）の期待値を反転
• 新ケース 5 件: 対象関数のパイプ実行検出 / 非対象ヘルパーの許可 / 状態書き込み関数の検出 / 部分文字列マーカーの無効化 / コメント行後の行頭 export 認識（commands/*.md の実形状）

ドキュメント

• docs/bash-usage.md: Detection Patterns 表を 1 行に集約、Sunset criteria（全廃を再検討する 3 条件）を新設
• hooks/enforce-skill-usage.md: 検出ロジック記述と description をソフトガード定義に同期

バージョン

• 0.32.2 → 0.33.0（挙動変更のためマイナー）

検証

• フックテスト: 22 passed, 0 failed
• ヘルパーテスト: 99 passed, 0 failed
• 整合性 lint: PASS（バージョン同期含む）
• 既存の正規利用（commands/*.md の bash ブロック形状・インライン前置）が新マーカー判定で通ることをテストで保証

Sunset 条項

以下のいずれかが観測された場合、フック全体の廃止を再検討します（docs/bash-usage.md に成文化済み）:

1. 修正困難な誤検知の反復
2. 記録された複数のブロックがすべて機械的なマーカー付与で終わりスキル誘導に至らない
3. スキル誘導の成功例がないまま維持作業が継続する

🤖 Generated with Claude Code