Codexに「中断されたら実行されるフック」が追加──タイムアウトは既定1秒・最大3秒

OpenAIのコーディングエージェントCLI「Codex」の0.150.0（2026年8月26日公開）に、実行を中断したタイミングでコマンドやMCPハンドラを走らせられる新しいフックが追加された。リリースノート本文の1行と、実装したマージ済みPR #40511の本文、そしてPR内の差分ファイルを確認した。

3行まとめ

• Codex 0.150.0（2026年8月26日）で、12種類あるフックイベントの1つとしてInterruptが新設され、hooks.jsonに"Interrupt"キーとして設定する
• 入力JSONはhook_event_name・session_id・turn_id・cwd・model・transcript_path・permission_modeの7フィールド（すべて必須）で、permission_modeはdefault/acceptEdits/plan/dontAsk/bypassPermissionsの5値のいずれか
• タイムアウトは既定1秒・最大3秒だが、PR内のテストコードでは「設定ファイルに20秒と書いても実際には3秒に切り詰められる」ことがアサーションで確認されている（エラー拒否ではなくクランプ）

リリースノートの1行

New Interrupt hooks can run commands or MCP handlers when an active top-level turn is interrupted. (#40511)

（新しいInterruptフックは、アクティブなトップレベルのターンが中断されたときに、コマンドやMCPハンドラを実行できる）

フックに渡される情報とタイムアウト

PR本文には、リリースノート1行以上の実装詳細が書かれている。

• Add an Interrupt hook event that runs for an active top-level turn before its interrupted abort event is emitted.
• Flush the turn transcript before invoking the hook and provide the session, turn, transcript, working directory, model, and permission mode in its input.
• Support command and MCP handlers, including asynchronous commands, with a one-second default timeout and a three-second maximum.
• Expose the event through hook configuration, managed requirements, app-server notifications, generated schemas, analytics, and the TUI hook views.

（アクティブなトップレベルのターンに対して、中断のabortイベントが発行される前に実行されるInterruptフックイベントを追加する。フックを呼び出す前にターンのトランスクリプトをフラッシュし、その入力にセッション・ターン・トランスクリプト・作業ディレクトリ・モデル・権限モードを提供する。非同期コマンドを含む、コマンドとMCPハンドラの両方をサポートし、タイムアウトは既定1秒・最大3秒。このイベントを、フック設定・管理された要件・アプリサーバー通知・生成されたスキーマ・分析・TUIのフックビューを通じて公開する）

タイムアウトの数字が明記されている点は実務上参考になる。フック側の処理が1秒を超えると既定ではタイムアウトし、設定を変えても3秒が上限になる、という制約だ。中断イベント自体を止めてしまわないよう、フックの実行時間に強い制限をかけている設計だと読み取れる。

フック入力の正確なフィールド一覧

PR本文の説明は「セッション・ターン・トランスクリプト・作業ディレクトリ・モデル・権限モード」という言葉だったが、実際にPR内で追加されたJSON Schemaファイル（interrupt.command.input.schema.json）を確認すると、フックの標準入力（stdin）に渡されるJSONの正確なフィールド名と型が分かる。

出典: PR #40511内interrupt.command.input.schema.json（2026年8月29日確認、7フィールドすべてがrequired指定）

permission_modeの5つの値がここで確認できたことで、Codexの権限モードが少なくともこの5種類に分かれていることが分かる。出力側のスキーマ（interrupt.command.output.schema.json）はさらに単純で、systemMessageという文字列フィールド1つだけが定義されていた。

設定ファイルの実際の形と、タイムアウトが「拒否」ではなく「切り詰め」であることの確認

PRに追加されたテストコード（interrupt_hooks.rs・mod_tests.rs）を読むと、Interrupt hookの設定はCODEX_HOME直下のhooks.jsonというファイルに、次のような形で書くことが分かる。

{
  "hooks": {
    "Interrupt": [{
      "hooks": [{
        "type": "mcp_tool",
        "server": "security",
        "tool": "notify",
        "input": {
          "event": "${hook_event_name}",
          "turn_id": "${turn_id}",
          "permission_mode": "${permission_mode}"
        },
        "timeout": 20
      }]
    }]
  }
}

（コマンド型の場合は"type": "command"と"command"フィールドで実行コマンドを指定する形になる）

このテストコードで特に興味深いのは、"timeout": 20（20秒）を設定ファイルに書いているにもかかわらず、実際にMCPツール呼び出しへ渡されるタイムアウトがDuration::from_secs(3)（3秒）になっている、とテストのアサーションで明示的に検証されている点だ。テスト自体の名前もbound_timeout（タイムアウトを上限で切り詰める）となっている。つまり「最大3秒」という制約は、3秒を超える設定値をエラーで拒否するのではなく、黙って3秒に切り詰める（クランプする）という実装であることが、PR本文の説明文だけでなく、実際のテストコードのアサーションからも確認できた。

12種類あるフックイベントの中の1つ

hook_config.rsを確認すると、Interruptは今回新設された13番目ではなく、既存の11種類に追加された12番目のフックイベントであることが分かる。

出典: PR #40511内codex-rs/config/src/hook_config.rs（2026年8月29日確認）

何に使えるのか

「中断されたときに何かを実行する」という機能は、たとえば作業途中の状態を外部システムへ通知する、ログを追加で書き出す、後片付け処理を挟む、といった用途を想定していると考えられる。ただし、PR本文にはこうした具体的なユースケースの記載はなく、これは本記事による推測にとどまる。テストの範囲としては「ハンドラの発見、タイムアウトの正規化、出力のパース、プロトコルの互換性、TUIでの表示、中断実行の順序」をカバーしたとPR本文に書かれている。

同じリリースにあった他の新機能

Codex 0.150.0のリリースノートには、Interrupt hooks以外にも「@メンションで他のCodexタスクを参照する」機能（別記事で扱う）、/copyにフルレスポンス・個別コードブロック・引用のピッカーが追加されたこと、名前の無いターミナルタスクに自動で説明的なタイトルが付くようになったこと、Vimモードで.キーによる直前の編集の繰り返しなどが挙げられている。

実際に中断フックを設定して動かしたわけではない

本記事はCodex 0.150.0のリリースノート本文、実装PR #40511の本文、そしてPR内の差分ファイル（JSON Schema・Rustソース・テストコード）を情報源としている。設定ファイルの構造やタイムアウトの切り詰め挙動はテストコードのアサーションから確認できたが、これはあくまでPRに含まれるテストスイートの中身であり、この記事を書いている自分の手元でCodex CLIを実際にインストールし、hooks.jsonを書いてコマンドまたはMCPハンドラをInterrupt hookとして設定し、意図的にターンを中断させて動作を確認する検証は行っていない。また、hooks.jsonというJSON形式の設定ファイルが唯一の設定経路なのか、TOML形式（config.toml）でも同様に書けるのかは、hook_config.rsがserdeのDeserializeを使っている以上どちらも技術的には可能に見えるが、実際にどちらが公式にドキュメント化された記法なのかは、今回確認したPRの差分だけからは断定できなかった。

関連記事: AIコーディングアシスタント比較──Copilot/Cursor/Claude Code【2026年】 / Codex Goal Mode 一般提供開始 / MCP（Model Context Protocol）とは

感想・指摘はコメント欄へ。