Codex 擴充能力與工具系統 Part 03｜Hooks：把控制點放進 Agent Lifecycle

把「完成前跑測試」寫進 AGENTS.md 或 Skill，Codex 知道該做什麼。這條要求仍然要靠模型在對的時機想起來。

如果 repo 的規則是「每次這一輪準備結束，都先跑 validator；沒過就繼續修」，控制點就不該只放在 instruction 裡。

OpenAI 把 Hooks 推到 GA 時，官方列出的用途包括掃 prompt 裡的 secrets、跑 validators、記錄 conversation、建立 memories，以及依 repository 或 directory 客製 Codex 行為。[1][2] 這些用途都掛在 lifecycle event 上。Runtime 發出 event 之後，對應的 Hook 邏輯才會進入執行路徑。

把 validation 掛在 Stop

一個 Codex issue 把 Stop Hook 能控制到哪裡切得很清楚。

Stop Hook 回傳 decision: "block" 後，Codex 確實阻止了正常結束，也送出了 continuation prompt，要求先處理 lint、type 或 test failure。接著下一個 Responses API request 因為 message id 不合法而失敗。[3]

Stop Hook 有觸發，block 有生效，continuation prompt 也有產生；真正失敗的是接下來那個 API request。

Codex 準備結束這一輪
        ↓
    Stop event emitted
        ↓
   validation hook
      ↙       ↘
    pass      fail
     ↓         ↓
   finish   block stop
              ↓
        return rationale
              ↓
       Codex 繼續處理

Stop Hook 把 validation 放到 lifecycle 的 Stop control point

這個案例能證明的範圍從 event 已經被 runtime 發出之後開始：Hook 有固定的處理點。Event 是否會在每個 execution path 出現、command 有沒有跑完、後續 API 和模型能不能繼續，都要另外驗證。

Skill 在這個例子裡可以教 Codex 該跑哪些 test、順序怎麼排、失敗訊息怎麼判讀。Stop Hook 則把 validator 綁在 Stop 這個 lifecycle 節點。同一個 workflow 裡，Skill 可以管做法，Hook 管觸發時機。

Hook 沒跑，先查 event path 和 trust

公開的歷史紀錄已經能看到 SessionStart、UserPromptSubmit、PreToolUse、PostToolUse 和 Stop 這幾個 event。[4]

SessionStart 的觸發時機曾在 issue 裡被質疑，因為它會等到第一個 prompt 才執行。後續 OpenAI contributor 說明，等到第一個 prompt 才開始是當時的預期行為；需要保證的是執行順序，SessionStart 會先於 UserPromptSubmit。[5]

UserPromptSubmit 的 additionalContext 也有獨立紀錄。Context 的確進到了模型，但當時整塊內容會顯示成 developer message。Context injection 有作用，出問題的是對話紀錄的顯示方式。[6]

PreToolUse 的坑更直接。有 issue 記錄到 Code Mode 的 exec path 沒有發出 PreToolUse，但直接的 exec_command 會觸發。[7] Desktop / app-server 也出現過同一套 Hook 設定在 CLI 正常、在另一條 client path 沒有觸發的 regression。[8]

PreToolUse 適合拿來做 tool execution 前的檢查，但 coverage 只到真的會發出這個 event 的 tool path。某條 path 沒有發出 event，Hook 就沒有介入點。

Trust 是另一個獨立狀態。本文引用的 unmanaged Hook 案例裡，hooks.json 可以配置會實際執行的 command，風險層級和普通 prompt text 不一樣。User-level Hook 在 /hooks review 前可能不會跑；command 本身改變後，也可能再次要求 review。Codex app 另外提供了 in-app Hook trust review flow。[9][2]

看到設定檔，只能知道設定存在。Hook 是否已經 trust、event 有沒有送到、command 最後有沒有跑完，要分開驗。完整的啟用驗證留給後面的文章。

四個名詞按責任分

遇到擴充需求時，可以先問它到底缺在哪裡：缺一套做法、缺外部能力、缺 lifecycle 觸發點，還是缺一個方便安裝與分享的包。下面這張圖只拿來放這四種責任的位置，不是 Codex 的官方四層分類，也不是 runtime 流程圖。

元件	主要責任	適合先問的問題
Skill	reusable procedure	Codex 應該怎麼做這類工作？
MCP	external capability path	workflow 是否需要透過 MCP 接外部工具、資料或 context？
Hook	lifecycle-triggered logic	哪個 event 被 emit 時，要自動執行什麼？
Plugin	packaging / distribution	這組可重用設定要怎麼安裝、分享？

Skill、MCP、Hook、Plugin 的責任分工

OpenAI 的 team plugin-sharing changelog 給了其中一條實際產品關係：reusable plugin bundle 可以包含 skills、MCP servers 和 lifecycle hooks。[2] 這能確認 Plugin 的封裝角色，但不會把表格裡的四種責任變成官方架構。

Plugin 可以把幾種能力一起打包。它不是 runtime 的最後一站。一個 repo 可以只有 Stop Hook，完全不用 MCP；另一個 workflow 可以用 Skill 加 MCP，沒有任何 Hook。

需求如果能精確寫成：

event Y 被 runtime 發出時，執行 X。

就值得往 Hook 看。像這篇的例子，「這個 repo 的測試怎麼跑」可以放進 Skill；「每次走到 Stop 都要跑一次」則是 lifecycle 的事。至於 Hook command 能做多少，仍然受當下的 execution environment、trust 與其他權限限制。

References

OpenAI, Work with Codex from anywhere, 14 May 2026.
https://openai.com/index/work-with-codex-from-anywhere/
OpenAI, ChatGPT & Codex changelog, entries dated 8 May, 14 May and 21 May 2026.
https://developers.openai.com/codex/changelog
openai/codex GitHub issue #20783, Blocking stop hook continuation can fail with invalid local message id, 2 May 2026.
https://github.com/openai/codex/issues/20783
openai/codex GitHub issue #16226, Hooks: distinguish subagent events from main agent, 30 March 2026.
https://github.com/openai/codex/issues/16226
openai/codex GitHub issue #15266, UserPromptSubmit and SessionStart hooks fire simultaneously on first prompt, 20 March 2026.
https://github.com/openai/codex/issues/15266
openai/codex GitHub issue #16933, Codex CLI renders hook additionalContext as visible developer message, 6 April 2026.
https://github.com/openai/codex/issues/16933
openai/codex GitHub issue #23411, Code Mode exec doesn’t fire PreToolUse hooks, 19 May 2026.
https://github.com/openai/codex/issues/23411
openai/codex GitHub issue #21639, Hooks no longer run after Codex Desktop update, 8 May 2026.
https://github.com/openai/codex/issues/21639
openai/codex GitHub issue #21615, Provide a supported way for local IDE/wrapper installers to request trust for installed hooks, 7 May 2026.
https://github.com/openai/codex/issues/21615