Codexのフックにはレビューが必要 — 変更されたフックが再度信頼するまで停止する理由と、SessionStartフックがプロジェクトのコンテキストをすべてのセッションに供給する方法 (2026)

OpenAIのドキュメントでは、フックを「Codexのための拡張性フレームワーク」と説明しています。これらを使用すると、会話の特定のポイントでスクリプトやMCPツールを実行できます。

ドキュメントには、誤って貼り付けられたAPIキーをブロックするためのプロンプトのスキャン、ターンが停止したときのバリデーションチェックの実行、そしてメモリに直接関連するものとして「チャットを要約して永続的なメモリを自動的に作成する」などの例が挙げられています。

フックはイベントに関連付けられます。主なものは以下の通りです：

• SessionStart: セッション開始時（コンパクション後を含む）に実行されます。
• PreToolUse および PostToolUse: ツール呼び出しの前後で実行されます。
• PreCompact および PostCompact: コンパクションの前後で実行されます。
• UserPromptSubmit: プロンプトを送信したときに実行されます。
• Stop: ターンが停止したときに実行されます。

Codexは、hooks.jsonファイルまたはconfig.toml内のインライン[hooks]テーブルからフックを見つけます。ドキュメントでは、最も有用な4つの場所を挙げています：~/.codex/hooks.json、~/.codex/config.toml、および<repo>/.codex/配下の同じ2つのファイルです。有効化されたプラグインにフックが同梱されている場合もあります。

複数のソースにフックがある場合、Codexは一致するものをすべてロードします。OpenAIによると、優先度の高いレイヤーが「優先度の低いフックを置き換えることはない」としています。

OpenAIのドキュメントのレビューセクションでは、その仕組みが2文で説明されています。「管理されていないフックが実行される前に、Codexは正確なフック定義をレビューし、信頼することを要求します。Codexはフックの現在のハッシュに対して信頼を記録するため、新規または変更されたフックはレビュー対象としてマークされ、信頼されるまでスキップされます。」

キーワードは「正確（exact）」と「ハッシュ（hash）」です。Codexは、ファイルパスやスクリプト名を信頼するかどうかを尋ねているのではありません。この「正確な定義」を信頼するかどうかを尋ねているのです。そのため、以下のいずれの場合もフックはレビュー待ちに戻ります：

• 新しいフックを追加した。 まだ一度も信頼されていません。
• フックを編集した。 定義が変更されるとハッシュが変わります。
• チームメイトがプロジェクトのフックを変更した。 リポジトリの.codex/hooks.jsonがプルによって変更された場合、新しいバージョンにはレビューが必要です。

起動時にフックのレビューが必要な場合、ドキュメントにはCodexが「/hooksを開くように指示する警告を表示する」とあります。そうするまで、それらのフックはスキップされます。

これが、見落としやすい部分です。スキップされたフックはセッションを停止させません。もしそのフックがコンテキストをロードするためのものだった場合、セッションは単にコンテキストなしで開始されます。

CLIでは、/hooksがそれらを管理する場所です。OpenAIのドキュメントによると、これを使用して「フックソースの検査、新規または変更されたフックのレビュー、フックの信頼、または個別の管理されていないフックの無効化」を行うことができます。

デスクトップアプリでは、コンポーザーで「Review hooks」を選択するか、「Settings > Hooks」を開くことでプラグインのフックをレビューできます。

レビューする際は、フックが何を実行し、どこから入力を得ているかを確認してください。信頼とは、スクリプトをセッション内で実行させるという決定であるため、特に自分で書いていないプロジェクトのフックについては、承認する前にコマンドを読み込む価値があります。

以下の2種類のフックはこのレビュープロセスを経ません：

• 管理されたフック（Managed hooks）。 システム、MDM、クラウド、またはrequirements.tomlソースからのフックは「管理対象としてマークされ、ポリシーによって信頼されており、ユーザーのフックブラウザから無効化することはできません」。
• 一時的なバイパス。 他の場所ですでにフックソースを検証している自動化のために、Codexには--dangerously-bypass-hook-trustフラグがあり、その実行に限り永続的な信頼なしで有効なフックを実行できます。名前の通り、これは限定的なケースのためのものです。

フックはデフォルトでオンになっています。config.tomlの[features]の下でhooks = falseと設定することで、完全にオフにすることもできます。

プロジェクトのフックがレビューに表示されないことがあります。これはCodexがそれをロードしなかったためです。これはフックの信頼ではなく、プロジェクトの信頼に関わる問題です。

OpenAIのフックドキュメントには、「プロジェクトローカルのフックは、プロジェクトの.codex/レイヤーが信頼されている場合にのみロードされる」とあります。設定の基本ページには、プロジェクトを信頼できないものとしてマークした場合、Codexは「プロジェクトスコープの.codex/レイヤー（プロジェクトローカルの設定、フック、ルールを含む）をスキップする」と付け加えられています。ユーザーおよびシステムのフックは引き続きロードされます。

つまり、リポジトリ内のフックには2つのゲートがあります：

1. プロジェクトが信頼されており、Codexが<repo>/.codex/を読み取ること。
2. フック自体が、現在のハッシュで信頼されていること。

フックが含まれているリポジトリをクローンして何も起こらない場合は、2番目のゲートの前に1番目のゲートを確認してください。

プラグインは独自のフックを持つことができます。デフォルトでは、Codexはプラグイン内のhooks/hooks.jsonを探しますが、プラグインのマニフェストで別の場所を指定することもできます。OpenAIによると、プラグインのフックは「他の管理されていないフックと同じ信頼レビューフローを使用する」とのことです。

プラグイン特有の詳細が1つあります。ドキュメントには、「プラグインのアップデートによって同梱のスクリプトが変更された場合、フックの定義が変わらなくても、Codexは新しいレビューを要求する」と記されています。

そのため、自身の構成に何も変更がなくても、プラグインのアップデートによってフックがレビュー待ちに戻ることがあります。アップデート後にプラグインのフックが動作しなくなった場合は、まず/hooksを確認してください。

コンテキストに関しては、SessionStartが最初に注目すべきイベントです。これはセッション開始時に実行され、その戻り値がモデルに表示されるように追加されます。

OpenAIのドキュメントによると、SessionStartの場合、「stdoutのプレーンテキストは追加の開発者コンテキストとして追加される」とのことです。フックはadditionalContextフィールドを持つJSONを返すこともでき、「そのadditionalContextのテキストが追加の開発者コンテキストとして追加される」とされています。

このイベントは、セッションがどのように開始されたかをフックに伝えます。sourceフィールドはstartup、resume、clear、compact、またはforkになります。これにマッチさせることで、ケースに応じて異なるコンテキストをロードできます。

長期的なタスクで知っておくべきなのはcompact（コンパクション）のケースです。ドキュメントによると、Codexがルートセッションをコンパクションした後、compactに一致するSessionStartフックは「次のモデルリクエストの前に実行される」とあります。これには、ターンの途中で行われる自動コンパクションも含まれます。つまり、要約が以前の会話を置き換えた直後に、長期タスクで失うわけにいかないいくつかの事実をフックで再提示できるのです。GPT-6.1 SolのCodexにおける500kコンテキストに関するガイドでは、コンパクションについてより詳しく解説しています。

タイミングに関する注意点：OpenAIは、SessionStartフックがMCPサーバーの準備ができる前に実行される可能性があると指摘しています。その場合でも、セッションはブロックされません。

SessionStartフックはすべてのセッションにコンテキストを供給できるため、大量に供給したくなるかもしれません。ドキュメントでは制限を設け、その理由を説明しています。

デフォルトでは、Codexはモデルが表示する各フック出力メッセージを約2,500トークンに制限しています。フックがそれ以上を返すと、Codexは全文をファイルに保存し、モデルにはファイルパスを含む短いプレビューを提供します。OpenAIはこれを「スピリング（spilling）」と呼んでいます。

ハンドラーのadditionalContextLimitでしきい値を上げることはできますが、ドキュメントではそれに頼らないよう警告しています。「複数のフックやプラグインからのコンテキストは蓄積され、モデルのパフォーマンスを低下させる可能性があります。additionalContextLimitを上げると、そのリスクが高まります。」

また、プライバシーに関する点も指摘されています。サイズ超過の出力はディスクに書き込まれる可能性があるため、フックの出力にシークレットやその他の機密データを返さないように注意してください。

したがって、優れたSessionStartフックは、ドキュメント全体ではなく、重要なことの短く最新の要約をロードします。変更されない規約については、AGENTS.mdが標準的な場所です。CodexがAGENTS.mdのルールをスキップするのを防ぐ方法についてのガイドで、これらのファイルのロード方法を解説しています。

フックが壊れていると思い込む。 単に変更後のレビュー待ちである可能性があります。

内容を読まずに再信頼する。 レビューが存在するのは、フックがセッション内でスクリプトを実行するためです。

デバッグ中にフックを編集し、再信頼を忘れる。 編集するたびにハッシュが変わります。

信頼されていないプロジェクトでプロジェクトフックを探す。 Codexはそのプロジェクトの.codex/レイヤーをスキップします。

SessionStart経由でドキュメント全体を供給する。 大きな出力はディスクにスピルされ、モデルにはプレビューのみが届きます。

ステップ 1: /hooks を開き、保留中のものをレビューする

Codexを起動し、/hooksを開きます。レビュー対象としてマークされているフックを探し、それぞれが何を実行するかを確認して、期待通りのものを信頼します。デスクトップアプリでは、プラグインのフックに対して「Review hooks」または「Settings > Hooks」を使用します。

ステップ 2: プロジェクトのゲートを確認する

リポジトリのフックが全く表示されない場合は、プロジェクトが信頼されていることを確認してください。Codexは信頼されたプロジェクトに対してのみ<repo>/.codex/をロードします。

ステップ 3: SessionStartフックを短く安定したものにする

フックがadditionalContextを通じて簡潔な要約を返すようにし、startupだけでなくcompactにも一致させて、コンパクション後も要約が戻るようにします。フックの定義を安定させ、微調整のたびにレビュー待ちに戻らないようにします。

SessionStartフックは配信メカニズムです。コンテキストがいつセッションに届くかを決定するものであり、そのコンテキストが何であるか、どこに保管されているかを決定するものではありません。ロードされる要約が1つのリポジトリのスクリプトや1台のマシンのファイルにある場合、それは最後に編集した人の状態のままであり、そのフックが実行される場所でしか利用できません。Codex memories v2に関するガイドでは、Codexがマシン上に保持するローカルメモリについて解説しています。

MemoryLakeは、プロジェクトのコンテキストを一箇所で管理し、ChatGPT、Claude Code、Codexなどの接続されたアシスタントで利用できるようにするためのメモリレイヤーです。

エントリーはあなた自身の言葉で作成します。フック、hooks.jsonやconfig.tomlファイル、AGENTS.mdファイル、Codexセッション、Codexメモリ、あるいはベンダーのストアから何かが読み取られたり、書き込まれたり、削除されたりすることはありません。フックのレビュー、信頼、およびSessionStartは、OpenAIが説明している通りに機能します。

ステップ 1: APIキーを作成する

サインインしてダッシュボードからキーを生成します。このキーはMemoryLakeワークスペースに属し、OpenAIアカウントとは別個のものです。

ステップ 2: 最初のメモリをアップロードする

セッションの開始時に必要な短い要約から始めましょう：プロジェクトの目標、現在の決定事項、制約などです。1つのエントリーにつき1つの決定事項にすることで、他を書き換えることなく1つだけを更新できます。

ステップ 3: AIとエージェントを接続する

Codexやその他の使用しているアシスタントを接続します。同じエントリーがセッションやツールをまたいで利用可能になり、一箇所で更新できます。

第一の違いは、サイレントな欠落が減ることです。信頼しているコンテキストが、レビュー待ちで止まっている可能性のあるスクリプトの中だけに存在するわけではなくなります。

第二に、フックが安定します。要約が別の場所に保管されていれば、フックの定義を変更する頻度が減り、レビュー待ちに戻ることも少なくなります。

第三に、ツール間での一貫性です。Codexでも、接続している他のアシスタントでも、同じ決定事項を利用できるようになります。

変更のたびにレビューが必要になると想定する。 信頼はフックの現在のハッシュに紐付いています。

信頼する前に内容を読む。 フックはセッション内でスクリプトを実行します。

まずプロジェクトを信頼する。 信頼されていないプロジェクトではリポジトリのフックはロードされません。

プラグインのアップデート後に再確認する。 同梱のスクリプトが変更されると、新しいレビューが必要です。

SessionStartでcompactに一致させる。 コンパクション直後に重要な情報を復元します。

フックの出力を短く保つ。 大きな出力はディスクにスピルされ、コンテキストは蓄積されます。

フックの出力にシークレットを含めない。 サイズ超過の出力はディスクに書き込まれる可能性があります。

「フックにはレビューが必要です」というメッセージは、現在のバージョンで信頼されていない新規または変更されたフックをCodexが見つけたことを意味します。OpenAIのドキュメントによると、Codexは各フックのハッシュに対して信頼を記録するため、新規または変更されたフックは/hooksで信頼するまでスキップされます。プラグインのフックも同じルールに従い、同梱のスクリプトを変更するプラグインのアップデートには新しいレビューが必要です。また、プロジェクトのフックをロードするには、まずプロジェクト自体を信頼する必要があります。

最も適切に設定すべきフックはSessionStartです。その出力はセッション開始時に開発者コンテキストとして追加され、compactに一致するフックはコンパクション後に再実行されます。そのコンテキストを短く保ち、フックを安定させ、セッションで期待したものが存在しないときはいつでも/hooksを確認するようにしましょう。