Document the `update_plan` default-off change, configuration/migration, and future

What is the type of issue?

Documentation is missing

What is the issue?

Codex 0.152.0 changed update_plan from enabled by default to disabled by default. This was a significant workflow change for existing users, but the only release-note entry appeared under “Chores”:

The planning tool is disabled by default; enable it with tools.update_plan.enabled = true.

I upgraded from 0.151.0 to 0.152.0 and use update_plan throughout my work. I have approximately 4 GB of session history containing repeated update_plan usage. After upgrading, the tool silently disappeared. When asked about it, models could only report that the tool was unavailable in the current turn; they could not explain why or tell me how to restore it.

I had to inspect old rollout files, compare versions, and find PR #41744 before discovering that the default had changed.

Describing this solely as making the tool “opt-in” obscures the impact on existing users. Users who already depended on the default-enabled behavior were silently opted out.

The minimal missing documentation is:

1. Configuration reference, stating how existing users can restore it:

   [tools.update_plan]
   enabled = true
   

I also feel that what is also missing, and I urge you to document this too:

1. Why update_plan was disabled by default.
2. Whether it will remain supported or is expected to be deprecated or removed.
3. What workflow or tool is intended to replace it, if any.
4. That this is a user-facing behavioral change, not merely a chore.
5. Whether the setting applies immediately or requires restarting Codex or starting a new session.

Please also consider migration handling for established users. For example, Codex could detect prior update_plan usage and preserve the setting, or display a one-time startup notice explaining that it was disabled and how to re-enable it.

Even if automatic migration is not feasible, a prominent release note and documented rationale would prevent users from having to reverse-engineer why a frequently used tool disappeared.

Where did you find it?

• Codex 0.152.0 release notes, under “Chores”: https://github.com/openai/codex/releases/tag/rust-v0.152.0
• PR #41744: https://github.com/openai/codex/pull/41744
• Implementing commit: https://github.com/openai/codex/commit/a9519cbcdd2d664530edb2469224ee03c1056799

Start by reading the 0.152.0 release notes, PR #41744, and commit a9519cbcdd2d664530edb2469224ee03c1056799 to identify the relevant documentation locations and confirmed behavior. Document the [tools.update_plan] enabled = true configuration, explain the default change and its rationale or known future, and clearly state any restart or migration behavior supported by the project.