Codex produces two kinds of plans:
- Checklist plans from the
update_plantool (turn/plan/updated). Each update replaces the whole list. A session has at most one, so it always uses theplanIdcodex-structured-plan. - Markdown plans that Codex writes in plan mode (the
planitem). TheplanIdis the Codex item id.
The adapter follows the ACP plan operations.
On v1, a client opts in to plan_update with clientCapabilities.plan: {}. On v2,
every client gets plan_update, and no capability is needed.
A checklist update is an items plan:
{
"sessionUpdate": "plan_update",
"plan": {
"type": "items",
"planId": "codex-structured-plan",
"entries": [
{"content": "Read code", "priority": "medium", "status": "completed"},
{"content": "Change code", "priority": "medium", "status": "in_progress"}
]
}
}Codex has no step priority, so every entry has priority: "medium".
A Markdown plan is sent as markdown snapshots while Codex writes it, at most
one every 150 ms. The last snapshot has the text of the completed item.
Session replay sends one snapshot for each saved plan.
{
"sessionUpdate": "plan_update",
"plan": {"type": "markdown", "planId": "item-id", "content": "# Plan\n\n1. Read."}
}AIR clients with planContentDelta get the appended text instead of whole
snapshots; see AIR extensions.
A v1 client without clientCapabilities.plan gets:
- checklist plans as the legacy
planupdate with the sameentries; - each Markdown plan as one
agent_message_chunkwith the item id asmessageId, when the plan item completes. Replay sends the same chunk.
An explicit empty checklist from turn/plan/updated clears
codex-structured-plan. Clients with plan updates (opt-in on v1, baseline on v2)
receive an empty items update, then plan_removed. A v1 client without plan
receives only the legacy plan with empty entries.
Completion does not remove a plan. Codex has no equivalent removal event for
Markdown plan items. Markdown plans omit path because Codex streams plan text
rather than reporting a plan file. The schema no longer defines a file plan
type. Codex's explanation of a checklist update is not sent.