Codex CLI Hooks: The Full Timeline From 0.148.0 to 0.152.0

Hooks went from shell scripts to a real extension point in five releases

Codex CLI's hooks started as a way to run a shell command at a lifecycle event. Across five releases between 18 August and 1 September 2026, OpenAI turned that into something closer to a real extension system: hooks that run without blocking the session, that call MCP tools directly, that fire on interruption, and that can rewrite what a tool hands back to the model before it ever gets there. None of this is covered in one place in OpenAI's own release notes, it's scattered across five separate changelog entries, so this piece lines them up in order.

Everything below is sourced directly from OpenAI's release notes on the openai/codex GitHub repository, a primary source in its own right. developers.openai.com, which would carry the full configuration reference and exact payload shapes, was not reachable while researching this piece. Where a release note describes a capability without giving its schema, that's stated plainly rather than guessed at.

The timeline

0.148.0: hooks stop being shell-only

The release note is a single line: "Hooks can now run commands asynchronously and invoke MCP tools." That's two separate capabilities bundled into one sentence, and both change what a hook can reasonably be used for.

Asynchronous execution means a hook no longer has to block the session while it runs. A hook that ships telemetry, kicks off a slow lint pass, or notifies a chat channel can fire and let the session continue rather than stalling on it. The trade-off is the one you'd expect: you lose the guarantee that the hook finished before the next step runs, so a hook whose entire job is gating something (blocking a commit until a check passes, say) still needs to stay synchronous.

Invoking MCP tools from a hook is the more structurally interesting half. A hook is no longer limited to shell commands; it can reach anything exposed through an MCP server, the same way the agent itself does. A post-edit hook can file a ticket, update a tracker, or query a knowledge base through an existing MCP connection, without a bespoke CLI wrapper written for each integration. Our roundup of MCP servers for developers covers what's commonly available to point a hook at.

This release also shipped codex exec fork, /export to Markdown, session archive and restore, and Amazon Bedrock as a built-in provider, covered in full in Codex CLI 0.148.0: Session Branching and Export.

0.150.0: hooks can react to being interrupted

Two features landed in the same release: @ mentions, letting you reference other Codex tasks from the terminal and ask agents to read, create or message them, and a new hook event. The release note: "New Interrupt hooks can run commands or MCP handlers when an active top-level turn is interrupted."

Before this, a hook's lifecycle coverage stopped at whatever normal turn completion looked like. Interrupt closes a real gap: if a user cuts off a running turn, whether by hitting the interrupt key or by some other mechanism, a hook now has a defined point to run cleanup, logging, or notification logic specifically for that case, rather than never firing at all because the turn didn't finish normally.

OpenAI's release notes confirm what triggers the event (an interrupted active top-level turn) and that it can invoke either a command or an MCP handler, matching the shape of other hook events since 0.148.0. They don't publish the payload shape Interrupt delivers, so treat "what fields does the hook receive" as unconfirmed until developers.openai.com is reachable or a fuller reference appears in the repository itself.

0.151.0: tool discovery gets patient, and results become editable

Two changes matter here, and they're doing different jobs. First: "Added a configurable grace period for discovering tools from optional MCP servers." Previously, an MCP server that was slow to respond during tool discovery risked being treated as unavailable before it had a chance to register its tools. A configurable grace period gives a slower server room to finish discovery rather than getting skipped by a timeout that was really just impatience.

Second, and the more consequential one for hook authors: "Extensions can now inspect or replace MCP tool results before they reach the model." This is a different capability from triggering on a lifecycle event. It's interception: a hook (or, per the release note's own phrasing, an extension more broadly) can look at what an MCP tool is about to hand back to the model and change it before the model ever sees the original. That opens the door to redacting sensitive fields from a tool's raw output, reformatting a response into something more model-friendly, or catching and correcting an error condition a tool surfaces before it derails the turn.

This release also added telemetry for stdin review escalations and remote executor MCP discovery, which is infrastructure supporting the discovery and interception changes above rather than a hook capability in its own right.

0.152.0: interruption gets a second angle, and output gets bounded

The 1 September release ties several threads together. "Run executor hooks for interrupted turns" extends the interruption coverage 0.150.0 introduced with the general Interrupt event: this time specifically for hooks scoped to the executor, so cleanup logic tied to command execution also runs when a turn is cut short, not just hooks listening for the general event.

"Allow bundled browser cleanup hooks on subagent stop" is a narrower, practical fix: hooks that clean up browser state now run when a subagent stops, not only when the top-level session ends, which matters if you're running Codex against multi-agent workflows where a subagent might spin up and tear down its own browser session independently.

Two changes affect hooks indirectly by changing what they're working with. "Individual MCP tools support an output_token_limit setting, with consistent truncation across session resumes" means a verbose tool's output can now be capped per-tool, and that cap applies the same way whether the session is fresh or has been resumed, so a hook inspecting or logging tool output sees consistent, bounded data rather than output that varies in size depending on session history. And "MCP server names can contain :, @, /, and ., supporting package-style names throughout CLI commands and authentication" is a naming change that affects how you address a specific MCP server from a hook or CLI command, allowing conventions like @namespace/package-name rather than a flat identifier.

One more 0.152.0 change worth flagging even though it's not a hooks feature: the planning tool switched from enabled by default to opt-in, requiring tools.update_plan.enabled = true. If a hook or workflow depended on the planning tool being present without explicit configuration, that assumption broke in this release.

What this adds up to

Read in sequence, the direction is consistent: Codex hooks started as a way to run a script when something happened, and five releases later they can run without blocking, reach MCP tools directly, react specifically to interruption from two different angles (the general event and the executor-scoped one), and edit what a tool actually says before the model reads it. That last capability, result inspection and rewriting from 0.151.0, is the one that changes hooks from an observation mechanism into something closer to a middleware layer sitting between tools and the model.

If you're building automation around Codex CLI today, the practical takeaway is to check your version before assuming any of this is available: codex --version, and compare against the table above. A hook config written against 0.147.0 or earlier predates all five of these changes.

Where to go next

For the session-management side of this same stretch of releases, see Codex CLI 0.148.0: Session Branching and Export and Codex CLI's Interactive Task Dashboard: What's New in 0.149.0. If you're comparing how Codex CLI and Claude Code each let you react to events without polling, see Claude Code Channels and Claude Code Routines vs /loop. For the skill side of Codex CLI specifically, How to Install Skills in Codex CLI and Claude Code vs Codex CLI for Skills cover discovery and activation, which none of these five hooks releases touched. Browse the current skill catalog at getclaudeskills.com/skills.