Research: Codex Plan mode behavior and prompt architecture

English translation:

Research Scope

A source code review was conducted based on commit 363427b5e3fe1b6d7499e6bc47651f62a5a3b1d2 (2026-08-13) of openai/codex, focusing on Plan mode's state, prompts, tool constraints, streaming protocol, and implementation transition flow.

Conclusions

Plan mode is a distinct collaboration mode, not the update_plan task-list tool. It primarily relies on developer prompts to constrain model behavior, combined with a small number of hard runtime constraints, the <proposed_plan> protocol, and the TUI's “implement after approval” interaction to complete the workflow.

Execution Flow

1. The user selects/switches to Plan in the TUI. The built-in preset uses Medium reasoning effort by default, which can be overridden by plan_mode_reasoning_effort.
2. On each turn, the world state wraps the Plan prompt in a <collaboration_mode> developer message and injects it into the model context. The state persists throughout the session.
3. The model first performs read-only exploration, clarifies intent, and fills in implementation decisions, then outputs a complete plan inside <proposed_plan>...</proposed_plan> on dedicated lines.
4. The runtime strips this block from ordinary assistant text, streams it as PlanDelta, and ultimately generates a TurnItem::Plan.
5. After receiving the PlanItem, the TUI provides three options: switch to Default while retaining the context and implement it, start a new context carrying the plan and implement it, or continue in Plan mode.

Key Points of the Plan Prompt

Full original text: plan.md

• It is strictly divided into three phases: exploring environmental facts, clarifying intent, and clarifying implementation details.
• A user's request to “implement directly” cannot end Plan mode; it can only be understood as “plan how to implement it.” Only developer instructions can switch modes.
• Reading, searching, static analysis, side-effect-free commands, and builds/tests that write only to caches are allowed.
• Editing the repository, applying patches, migrations, rewriting formatters/code generators, and all side-effecting operations that actually execute the plan are prohibited.
• Prefer using request_user_input to ask about preferences or tradeoffs that cannot be discovered from the environment and would materially affect the approach.
• A final plan may be generated only when “the implementer does not need to make any further decisions.” Each turn may contain at most one <proposed_plan>.
• By default, the final plan should be concise and include a title, summary, public interface changes, tests, and explicit default assumptions.

Hard and Soft Constraints

| Behavior | Implementation |
|---|---|
| Do not exit Plan because of a user command | Developer prompt |
| Do not modify the repository in Plan | Developer prompt |
| update_plan | Explicitly rejected at runtime |
| request_user_input | Available in Plan and blocks while awaiting input; unavailable by default in Default unless enabled by a feature |
| Automatic wake-up while idle | Prevented from starting in Plan mode |
| <proposed_plan> | Parsed at runtime into a separate streaming event and PlanItem |

Important boundary: No uniform backend rejection specific to Plan was found in Core for general tool execution involving mutation tools such as exec and apply_patch. Therefore, “must not write” is primarily enforced through high-priority prompt constraints rather than complete mandatory sandbox isolation; update_plan is a confirmed special case with hard blocking.

Key Implementation Locations

• Mode and mask definitions
• Built-in Plan / Default presets
• World-state developer prompt injection
• Plan streaming routing and PlanItem lifecycle
• <proposed_plan> parser
• Rejection of update_plan in Plan
• Implementation confirmation dialog and context handoff

Additional Notes

The prompt used at runtime may differ from the repository template: if the model catalog returns collaboration_mode_messages.plan, its content takes precedence over the local preset; if include_collaboration_mode_instructions = false, the developer prompt block is not injected.

<!-- codex-issue-translator -->