Codex CLI 0.154.0 and SDK 0.154.0: Worktrees, ExternalMessage, and the ultra Reasoning Effort

Codex CLI 0.154.0 is the stable command-line agent released on 2026-09-09, with the official Python SDK openai-codex 0.154.0 and TypeScript SDK @openai/codex-sdk 0.154.0 following the next day. The headline is one sentence: GPT-6-Astra becomes selectable for the first time (full story in GPT-6-Astra Goes Live: Codex Model Picker and Amazon Bedrock Catalogs). But the release carries much more than the model — worktrees, inline Q&A, a Windows background server, and an SDK pair that adds the max/ultra reasoning efforts and ExternalMessage all change daily workflows.

Every fact below comes from GitHub release notes, PR bodies, and tag sources loadable on 2026-09-15; the voice section draws a hard line between build-side disclosure and a shipped feature.

1. Overview: two change lists

CLI 0.154.0 (published 2026-09-09T22:35 UTC) carries six New Features, six Bug Fixes, and one removal; SDK 0.154.0 (published 2026-09-10T19:51 UTC) adds four features and three migration notes. Regrouped by impact:

2. CLI 0.154.0: six changes worth remembering

2.1 Experimental worktrees: --worktree and /worktree

Official wording: create isolated checkouts for new or forked sessions using --worktree on the command line or /worktree inside a session, then browse and resume them. Labeled experimental. Manual multi-tasking flows built on bare git worktree (see Codex Team Workflow: worktrees, reviews, and CI integration) now have a first-party entry point.

2.2 Inline Q&A while tasks run

While Codex keeps working, you can drop in a question — using suggested choices or custom text, without losing your main draft. A genuine improvement for the "long task running, quick question in passing" pattern.

2.3 Windows: a shared background server

Windows sessions can now share a background Codex server, with daemon lifecycle commands and managed updates. Combined with this version's batch of Windows sandbox provisioning changes (#42337, #42341, #42348, #42351, #42353 and friends in the changelog), Windows-side support landed in dense batches this release.

2.4 MCP and security fixes

• MCP OAuth: connections coordinate OAuth token refreshes; when refresh fails, a login challenge surfaces, and rejected tool calls are never automatically replayed (#42413 / #42552).
• Startup trust: workspace-controlled PATH helpers no longer run before trust is established (#42324); the macOS sandbox blocks terminal input injection (#42590).
• Plugin hot refresh: existing sessions pick up newly installed plugin tools and refresh skills and hooks after external plugin upgrades or rollbacks (#42284 / #42593 / #42990).
• Approval context: automatic approval reviews better preserve authorization context through compaction and reject approvals invalidated by new user instructions or answers (#42844 / #42852 / #43442).
• Remote resume: remote resume and fork operations preserve saved permissions; resuming a conversation open in another app shows a read-only transcript with a retry option while preserving your draft (#43253).

2.5 The codex mcp-server entry point is gone

The deprecated codex mcp-server entry point is no longer available (#42993). Scripts still calling it must change before upgrading. Standard MCP server practices (stdio / Streamable HTTP transports) are unaffected — the guides in our MCP channel still apply.

2.6 Editor details

Vim editing gains an R replace mode with undo and dot-repeat (plus more reliable Escape handling in legacy terminals); copying responses preserves formatting in rich-text apps, and /copy can copy status output or individual session fields.

3. SDK 0.154.0: the effort ladder completes, and external messages arrive

On the Python side: pip install --upgrade openai-codex==0.154.0 (Python 3.10+, bundling the openai-codex-cli-bin==0.154.0 runtime). On the TypeScript side: @openai/codex-sdk 0.154.0 is the npm latest (verified via the registry on 2026-09-15).

3.1 max and ultra: the ladder reaches seven rungs

PR #39662 (merged 2026-08-20, shipped in this release) writes the two new efforts into the SDK types. The full TypeScript type (from the PR diff; it was five values, minimal through xhigh, before):

export type ModelReasoningEffort =
  | "minimal"
  | "low"
  | "medium"
  | "high"
  | "xhigh"
  | "max"
  | "ultra";

Note that this TypeScript seven-value set contains no none — while the official Python example (13_model_select_and_turn_params, python-v0.154.0 tag) ships a REASONING_RANK dictionary that lists both none and minimal, nine effort names ranked 0 through 7:

REASONING_RANK = {
    "none": 0,
    "minimal": 1,
    "low": 2,
    "medium": 3,
    "high": 4,
    "xhigh": 5,
    "max": 6,
    "ultra": 7,
}

The two bottom-rung names coexist in the Codex ecosystem, and the two languages' effort sets do not fully match — code against the type definition of your language rather than copying effort strings across. In the gpt-6-astra bundled metadata, ultra is described as "Maximum reasoning with automatic task delegation"; the semantics are unpacked in the Astra article.

3.2 ExternalMessage: external content with tool authority

The most important new SDK capability. The motivation, from PR #44086 verbatim: applications need to deliver content from other agents, tools, or services with tool-level authority, without treating it as user input or granting authorization. The official example (16_external_message/sync.py, python-v0.154.0 tag):

from openai_codex import Codex, ExternalMessage, Sandbox

with Codex(config=runtime_config()) as codex:
    thread = codex.thread_start(sandbox=Sandbox.read_only)
    thread.run(
        "When deployment notifications arrive, summarize their status and suggest "
        "what I should check. Do not change files or deploy anything."
    )

    # External content has tool authority; it does not supply user permission.
    result = thread.run(
        ExternalMessage(
            tool_name="notifications",
            namespace="slack",
            content="Staging deployment failed: the health check returned HTTP 503.",
        ),
        source="slack_notification",
    )

Three semantic boundaries: external content is preserved in history as function output; external messages are kept separate from user-input lists and steer(...); and it requires CLI 0.151.0 or newer (custom codex_bin deployments, check your version gate).

3.3 include_turns, turn_service_tier, and source

PR #44084 rounds out history and per-turn options: include_turns lands on resume/fork (omission preserves server defaults; False skips response-history loading without changing the model context); turn_service_tier overrides the service tier for one newly started turn; source is attached metadata. The bundled runtime dependency is pinned to 0.153.4, and SDK packaging rejects unsupported runtime versions.

3.4 Migration notes (three, from the official release notes)

• HookMetadata grew a .root wrapper: hook.command becomes hook.root.command; check hook.root.handler_type before reading handler-specific fields.
• Some previously unknown notifications now have typed payloads: read named fields instead of .params; unknown or invalid payloads still arrive as UnknownNotification.
• Turn-handle attachment semantics: manually constructed or late-joining handles receive events from their attachment point with no replay of earlier output — collected results can be partial; attaching after completion can raise TransportClosedError, and saved history belongs to thread.read(include_turns=True). Handles returned directly by thread.turn(...) are unaffected (they retain events from when their request is sent).

4. Voice runtimes: build-side signals, not a shipped feature

The 0.154.0 changelog hides a cluster of entries: an macOS voice runtime projection (#42204), GNU Linux voice runtime preparation (#42208), Windows voice runtime preparation (#42209), and packaging of prepared runtimes with the voice host (#42332). The next day brought a prerelease, voice-cygwin-*: offline build inputs for native Windows voice releases — 103 pinned Cygwin binary packages with the signed package index, 83 corresponding source archives, and a per-package SHA-512 map. That release states explicitly that the archives are not included in Codex user packages.

Conclusion: voice runtimes for three platforms are in preparation, with all evidence at the build layer and no user-facing statement that a voice feature is available. Keep that framing when citing it on a roadmap.

5. Version status and installation

# Python SDK (bundling the CLI runtime)
pip install --upgrade openai-codex==0.154.0

# TypeScript SDK (npm latest, checked 2026-09-15)
npm install @openai/[email protected]

# CLI binaries follow the 0.154.x stable line; 0.155.0 is in alpha (alpha.4, 2026-09-14)

6. Common errors and fixes

• All hooks stop working after upgrade: nine times out of ten it is the HookMetadata .root wrapper — change access paths per the first item in 3.4.
• ExternalMessage fails on runtime incompatibility: it needs CLI 0.151.0+; check the version in custom codex_bin setups — the SDK runs compatibility checks when sending the new options.
• A turn handle misses early events: late-joining handles start at their attachment point — by design, not a bug; use thread.read(include_turns=True) for full history.
• The codex mcp-server command vanished: removed in this version; migrate first, upgrade second.
• MCP tools do not retry after an OAuth refresh failure: this version never auto-replays rejected calls — by design; log in again and retry manually.
• Reading voice changelog entries as a feature launch: see section 4; build-side disclosure only.

7. Next steps

• GPT-6-Astra Goes Live: Codex Model Picker and Amazon Bedrock Catalogs: the full breakdown of this batch's biggest news.
• Getting started with OpenAI Codex CLI: from install to daily use: the on-ramp article.
• Codex Team Workflow: worktrees, reviews, and CI integration: the manual practices that predate native worktrees; the ideas still transfer.
• Codex CLI vs IDE Extension vs Codex Cloud: Choosing a Codex Surface: picking a surface.
• OpenAI Models Release Notes (2026, Living Document): the full model timeline.