scaffold-codex-hooks

scaffold-codex-hooks

まず対象プロジェクトを監査し、現在の公式フックモデルに沿って、決定論的な管理レイアウトで Codex フックをスキャフォールドします。

判断ツリー

ユーザーは何を求めていますか？

• フック設定がまだないリポジトリに、新しいプロジェクトローカルの Codex フックを追加する： 現行の公式ドキュメントとスキーマを確認し、リポジトリを監査して、有効な機能フラグを調べます。必要に応じて有効にしてから、スキャフォールドします。
• 既存の .codex/hooks.json、.codex/config.toml、または .codex/hooks/ ファイルがある： まず既存の内容を監査し、additive または overhaul を選んでから、管理対象のフックレイヤーだけを更新します。
• ディスク上にはフックがあるのに、Codex に反映されていないように見える： まず有効な hooks 機能を確認します。まだ無効なら、意図的に有効にします。有効な場合は、プロジェクトローカルの .codex/config.toml は信頼済みプロジェクトでのみ読み込まれることに注意し、その後 hooks.json をデバッグします。
• 実装ではなく説明だけを求めている： references/hook-events.md、references/feature-flag.md、references/scaffold-layout.md を読み、スキャフォールドせずに回答します。

クイックリファレンス

タスク	操作
現行の公式 Codex フックモデルを確認する	https://developers.openai.com/codex/hooks、https://developers.openai.com/codex/config-basic、assets/hook-events.json に記載された生成済みスキーマ、およびそのマニフェストにあるランタイムソースへのリンクを読む
対象リポジトリを監査する	scripts/audit_project.sh /path/to/project を実行する
有効な hooks 機能を調べる	python3 scripts/check_hooks_feature.py --project /path/to/project --json を実行する
生成されたフック定義を確認／信頼する	スキャフォールド後、または .codex/hooks.json の変更後に、Codex で /hooks を開く
プロジェクト設定でフックを有効にする	python3 scripts/check_hooks_feature.py --project /path/to/project --enable --scope project を実行する
ユーザー設定でフックを有効にする	python3 scripts/check_hooks_feature.py --project /path/to/project --enable --scope user を実行する
現在のイベントカタログを確認する	references/hook-events.md を読む
再利用可能なリポジトリ管理スクリプトを設計する	references/reusable-scripts.md を読む
追加方式と全面刷新のどちらにするか判断する	references/merge-strategy.md を読む
管理対象のフックスキャフォールドを生成または更新する	`scripts/scaffold_hooks.sh --project /path/to/project --plan /path/to/plan.json --mode additive
生成したハンドラーを .codex/hooks.json にマージする	scripts/scaffold_hooks.sh に scripts/merge_hooks_json.sh を呼び出させるか、マージスクリプトを直接実行する
対象プロジェクトのフック README を再生成する	scripts/render_hooks_readme.sh --project /path/to/project --plan /path/to/plan.json を実行する

必須のワークフロー

1. スキャフォールドの計画を立てる前に、Codex の公式フックドキュメントの最新情報を確認します。
2. イベントセットや出力契約が変わっていないと決めつける前に、最新のドキュメント、現在のスキーマ、assets/hook-events.json を比較します。
3. 有効にするイベントや実行するコマンドを決める前に、対象プロジェクトを詳しく監査します。
4. リポジトリ内の hooks.json が有効だと見なす前に、対象プロジェクトで hooks 機能が実際に有効かを確認します。
5. 機能がオフの場合は、適切なスコープで意図的に有効化します。
   • 共有リポジトリ用のスキャフォールドでは、プロジェクトスコープをデフォルトにします。
   • 個人用／グローバルフックの場合、またはリポジトリに .codex/config.toml をコミットすべきでない場合は、ユーザースコープを使います。
6. マージ方法を選ぶ前に、既存の .codex/config.toml、.codex/hooks.json、.codex/hooks/、AGENTS.md、README*、その他の自動化ファイルを確認します。
7. 具体的なフック計画 JSON を作成または更新します。プロジェクト固有の判断はスキャフォールドスクリプトではなく計画に記述し、スキャフォールドの決定性を保ちます。
8. Claude Code、OpenCode、Git フック、GitHub Actions、ローカルシェルでの使用に移行する可能性がある動作には、リポジトリ管理下の共有スクリプトを優先します。生成する Codex フックファイルは、それらのスクリプトを呼び出す薄いアダプターにとどめます。
9. 現在の公式イベントをすべて、管理対象のフックルートにコメント付きの bash スタブとして用意します。そのイベントが hooks.json で無効のままでも用意してください。
10. 有効なイベントのみを .codex/hooks.json に接続し、非アクティブなスタブのコストを抑えます。
11. .codex/hooks/README.md を再生成し、対象プロジェクトで常に参照しやすいイベント一覧を提供します。
12. 実際にスキャフォールドした後もフックが非アクティブに見える場合は、有効な機能の状態を再確認し、プロジェクトレイヤーが信頼されていることを確かめてから、/hooks でフック定義を確認して信頼します。

機能を最初に確認するヒューリスティック

次のいずれかに該当する場合は、早い段階で hooks を確認します。

• ユーザーがリポジトリへの Codex フックのスキャフォールドを依頼している
• .codex/hooks.json は存在するのに、何も起きていないように見える
• 機能フラグがオンかどうか、ユーザーが分からない
• リポジトリ内に .codex/config.toml が存在するのに、機能が実際にはオフのように見える
• 既存の設定でレガシーな codex_hooks エイリアスが使われている

次の手順に従います。

1. まず対象プロジェクトのパスを正規化します。
2. python3 scripts/check_hooks_feature.py --project /path/to/project --json を実行します。
3. 有効な状態がオフの場合は、正規の [features].hooks = true を使って意図的に機能を有効化します。
   • 共有リポジトリ内の設定では --scope project を指定します。
   • 個人用／グローバル設定では --scope user を指定します。
4. 有効化した後、再度状態を確認します。
5. スキャフォールド後、またはフック定義を変更した後に、/hooks を使って管理対象外のコマンドフックを確認し、信頼します。
6. その後で初めて、hooks.json、マッチャーの選択、フックスクリプトのロジックのデバッグに取りかかります。

最新のドキュメントを最優先

公式の Codex ドキュメントを信頼できる情報源として扱います。

• https://developers.openai.com/codex/hooks
• https://developers.openai.com/codex/config-basic
• https://developers.openai.com/codex/config-reference

正確なワイヤ形式と現在のパーサーの動作については、次の情報も確認してください。

• https://github.com/openai/codex/tree/main/codex-rs/hooks/schema/generated
• https://raw.githubusercontent.com/openai/codex/main/codex-rs/features/src/lib.rs
• https://raw.githubusercontent.com/openai/codex/main/codex-rs/features/src/legacy.rs
• https://raw.githubusercontent.com/openai/codex/main/codex-rs/hooks/src/lib.rs
• https://raw.githubusercontent.com/openai/codex/main/codex-rs/config/src/hook_config.rs
• https://raw.githubusercontent.com/openai/codex/main/codex-rs/hooks/src/engine/discovery.rs
• https://raw.githubusercontent.com/openai/codex/main/codex-rs/hooks/src/events/common.rs
• https://raw.githubusercontent.com/openai/codex/main/codex-rs/hooks/src/events/compact.rs
• https://raw.githubusercontent.com/openai/codex/main/codex-rs/hooks/src/events/permission_request.rs
• https://raw.githubusercontent.com/openai/codex/main/codex-rs/core/src/tools/hook_names.rs

ドキュメントとランタイムソースに食い違いがある場合は、スキャフォールドの入力について、ソースで裏付けられた現在の CLI の動作を優先し、ドキュメントの差異を記録してください。現在のマニフェストでは、正規の機能キーは hooks です。codex_hooks はレガシーエイリアスです。

実用的なパターンを知るための補足資料として、https://reading.sh/codex-hooks-just-gave-you-back-complete-control-over-your-code-57d044bcae1b の記事を利用してください。信頼できる情報源としては扱わないでください。初期のフックに関する記事は、機能の進化に伴って古くなっています。

メンテナー向けの段階的な差異確認

このスキル自体を更新する際は、ドキュメントの差異確認を最初のメンテナンス手順にしてください。

1. 編集当日に公式の Codex フックドキュメント、設定ドキュメント、生成スキーマ、ランタイムソースをライブ取得し、イベント名、マッチャーのルール、入出力の契約、信頼動作、機能フラグを assets/hook-events.json と比較します。
2. 入手可能な場合は、codex --version などのローカルなバージョン情報を確認し、更新の根拠となる Codex のソースコミットまたはスキーマの URL を記録します。
3. 差異がある場合は、スキャフォールド全体をまとめて更新します。対象は assets/hook-events.json、references/hook-events.md、機能フラグと注意点に関するリファレンス、スキャフォールド生成ツール、テンプレート、計画の例、バリデーター、テスト、評価、薄いラッパーです。
4. 差異がない場合も、ライブドキュメント、スキーマ、ソースを確認したことを明記します。記憶に頼ったり、Claude Code や OpenCode の想定をそのまま流用したりして、このスキルを更新しないでください。

プロジェクト分析のルール

フックの構成を決める前に、次の項目を確認してください。

• リポジトリのルートとワークスペースの構成
• プロジェクトに .codex/config.toml、.codex/hooks.json、または .codex/hooks/ がすでにあるか
• 言語とパッケージマネージャー
• ビルド、テスト、リント、フォーマット、検証のエントリポイント
• タスクランナー、パッケージスクリプト、リポジトリ内のドキュメントに記載されたフレームワークのコマンド、CI ジョブ、Make／Just／Taskfile のターゲット、ローカルスクリプトなど、既存のリポジトリ管理下のコマンドエントリポイント
• <project>/scripts/agent-session-context.sh、<project>/scripts/agent-stop-checks.sh、アダプタースクリプト、Husky フック、GitHub Actions ジョブなど、ロジックを共有すべき再利用可能なエージェントまたは自動化スクリプト
• Turborepo、Nx、pnpm workspaces、Bun workspaces、Cargo workspaces、カスタムタスクランナーなどのモノレポ用ツール
• AGENTS.md、プロジェクトのルール、リポジトリの自動化に関するドキュメントなど、既存の AI 向け指示
• 既存の Git フック、Husky、Lefthook、または CI ゲート
• .env、シークレット、ロックファイル、生成コード、マイグレーション、インフラストラクチャのディレクトリなどの機密性の高いパス
• フックの設定をリポジトリの設定で共有すべきか、ユーザーのローカル環境に限定すべきか

まず scripts/audit_project.sh を実行し、チェックリスト全体が必要な場合は references/project-analysis.md を読んでください。

決定論的な作業とプロジェクト固有の作業

以下の部分は決定論的に保ちます。

• 管理対象フックのルートパス
• イベントスタブのファイル名
• 生成される hooks.generated.json の構造
• 以前に管理対象だったフックのマージ動作
• フック README の生成
• 現行の公式 Codex フックイベントすべてを網羅するイベントマニフェスト
• 機能フラグの確認と報告

以下の部分はプロジェクト固有のままにします。

• 有効にするイベント
• サポート対象イベントのマッチャー正規表現
• タイムアウトとステータスメッセージ
• カスタムフックロジックの前にイベントが実行するよう設定されたリポジトリコマンド
• カスタムフックロジックの前にイベントが処理を委譲する、再利用可能なリポジトリ所有スクリプト
• 機能の有効化設定をプロジェクト設定とユーザー設定のどちらに置くか
• 有効にしたイベントスクリプト内の実際のロジック
• 更新を additive にするか overhaul にするか

再実行時のルール

このスキルをプロジェクトに対して再度実行する場合：

• イベントセットが変更されていないと仮定する前に、最新のドキュメントとスキーマを再確認します。
• 現在のフック計画が引き続き適切だと仮定する前に、プロジェクトを再監査します。
• リポジトリ内のフックが有効だと仮定する前に、実効的な機能状態を再確認します。
• デフォルトでは、管理対象外のフックを保持します。
• overhaul モードでは、管理対象ルート内に以前生成されたフックを置き換え可能なものとして扱います。
• additive モードでは、管理対象レイヤーまたは README が古くなっていない限り、以前生成されたフックを追加のみ可能なものとして扱います。
• 公式イベントセットまたはパーサールールが変更された場合は、まずスキャフォールドの入力を更新します。

スキャフォールドのルール

• 管理対象のランタイムフックスタブには、Python ではなく Bash スクリプトを生成します。
• 生成される Bash スタブには、イベント固有の入力および出力の契約をコメントとして記載します。
• 生成されるイベントスクリプトは、main() と、編集箇所を 1 つに限定した handle_event() で構成し、人間やエージェントが制御フローをすぐに把握できるようにします。
• フック計画では、再利用可能なリポジトリ所有スクリプト用の言語に依存しない scripts エントリと、既存のリポジトリコマンド用の commands エントリをサポートします。生成スクリプトにパッケージマネージャー、フレームワーク、またはツールチェーンの例をハードコードしないでください。
• 共有動作は通常 scripts/ の下にあるパスに依存しないリポジトリスクリプトに置き、出力プロトコルが異なる場合は codex などのハーネス引数を渡します。生成されるイベントスタブは薄く保ちます。
• 管理対象ルートは .codex/hooks/generated をデフォルトにします。
• フックファイルの配置先は .codex/hooks.json をデフォルトにします。
• 共有リポジトリのスキャフォールドでは、.codex/config.toml で hooks を有効にする設定をデフォルトにします。
• フック設定を個人用またはマシンローカルに保つ場合に限り、~/.codex/config.toml を使用します。
• イベントマップが明確になるよう、公式イベントごとに管理対象スクリプトを 1 つ配置します。
• マージ後の hooks.json は決定論的に保ちます。以前に管理対象だったハンドラーのみを削除し、無関係なカスタムフックは削除しないでください。
• async、prompt、または agent フックが現在動作すると決して想定しないでください。現行のランタイムではこれらはスキップされます。
• PreToolUse、PermissionRequest、PostToolUse は、ツール経路に固有のものとして扱います。現行のサポート対象は、Bash、Edit／Write マッチャーエイリアスを使う apply_patch、およびフックのペイロードを公開する MCP ツール名です。ただし、WebSearch や、あらゆるシェル経路に対応しているわけではありません。
• SubagentStart と SubagentStop は、エージェントタイプに固有のものとして扱います。decision: "block" を指定した SubagentStop は、親ターンではなくサブエージェントを続行します。
• PreCompact と PostCompact は、コンパクションをトリガーとするフックとして扱います。これらのマッチャー値は manual と auto です。
• Stop は慎重に扱います。このイベントでは、decision: "block" は「ターンを拒否する」ではなく、「この新しいプロンプトで Codex を続行する」という意味です。

読み方ガイド

必要な情報	読む資料
完全な監査チェックリストと計画時の質問	references/project-analysis.md
hooks を安全に調査して有効にする方法	references/feature-flag.md
現在のソースに基づくイベント一覧、マッチャーのサポート、出力の動作	references/hook-events.md
管理対象フォルダーの構成と計画ファイルの形式	references/scaffold-layout.md
Codex、Claude Code、OpenCode、Git フック、CI で再利用可能なスクリプトを配置する方法	references/reusable-scripts.md
追加と全面的な見直しの動作の違い	references/merge-strategy.md
実行時の制限、ドキュメントの陳腐化、フェイルオープンの落とし穴	references/gotchas.md

運用スクリプト

• scripts/audit_project.sh は、実際のリポジトリの状況からプロジェクトプロファイルを作成します。
• scripts/check_hooks_feature.py は、ユーザーまたはプロジェクトの設定で hooks を調査または有効化します。
• scripts/scaffold_hooks.sh は、管理対象のフックツリー、マニフェスト、フラグメント、README、機能設定を生成します。
• scripts/merge_hooks_json.sh は、管理対象外のハンドラーを維持しながら、以前に管理されていたものを置き換えます。
• scripts/render_hooks_readme.sh は、マニフェストと現在の計画から .codex/hooks/README.md を再生成します。
• scripts/validate.py は、構造、フロントマター、マニフェストの整合性、相互参照を確認します。
• scripts/test_skill.py は、軽量な検証と一時プロジェクトでの統合チェックを実行します。

注意点

1. 機能キーは hooks です。codex_hooks は旧式の別名にすぎません。設定を編集する際は、正式なキーを記述してください。設定またはポリシーで無効にされていない限り、現在フックはデフォルトで有効です。
2. UserPromptSubmit と Stop では matcher は無視されます。これらのマッチャーに依存するロジックを設計しないでください。
3. async、prompt、agent は設定形式として解析されますが、現在のランタイムでは警告が出てスキップされます。
4. 同じイベントに一致する複数のコマンドフックは、並行して実行されます。あるフックが、ほかの一致するフックの起動を止めることはできません。
5. PostToolUse でコマンドの副作用を取り消すことはできません。できるのは、Codex が次に受け取るフィードバックを置き換えることだけです。
6. decision: "block" を指定した Stop は、新しいプロンプトで Codex を続行させます。ターンを拒否するものではありません。
7. decision: "block" を指定した SubagentStop は、新しいプロンプトでサブエージェントを続行させます。ループを避けるため、stop_hook_active を尊重してください。
8. リポジトリ内の .codex/config.toml は、信頼済みのプロジェクトでのみ読み込まれます。プロジェクトスコープで機能を有効にしても、プロジェクトが信頼されていなければ、その機能は実際には無効に見えることがあります。
9. 管理対象外のコマンドフックは、実行前に /hooks で確認して信頼する必要があります。
10. 生成されるスキーマには現在、SubagentStart と SubagentStop を含む10個のフックイベントが記載されています。初期のドキュメントや記事では、より少ないイベント数が説明されていたため、実際にスキャフォールドを生成する際は、毎回公式ドキュメント、スキーマ、ランタイムのソースを確認してください。
11. 再利用可能な検証ロジックやコンテキストロジックを、生成された .codex/hooks/generated/events/*.sh ファイルに埋め込まないでください。リポジトリ側で管理するスクリプトに配置し、Codex フックからアダプターとして呼び出してください。