Add `/shell` for native terminal handoff while Codex keeps working

What variant of Codex are you using?

CLI / TUI

What feature would you like to see?

I often use Ctrl-Z, work briefly in my shell, and then fg back into Codex. This is useful for inspecting paths and files, editing a plan, running git diff, or using other terminal-native tools while a Codex session is open.

That workflow has one important drawback: suspending the TUI suspends the entire Codex process, so the active agent turn stops too.

I would like an explicit /shell command that temporarily hands the current terminal to the user's native interactive shell while Codex continues processing the active turn. Exiting the shell (for example with Ctrl-D) would restore and redraw the TUI, including any agent progress made during the handoff.

The intended experience is a real shell, not another command-entry widget:

• shell-native tab completion and history
• job control
• pagers and full-screen editors
• the current Codex session working directory
• inherited stdin, stdout, and stderr

Proposed behavior

1. The user enters /shell.
2. The TUI pauses input and rendering, restores the terminal, and starts the user's native shell attached directly to the terminal.
3. Codex continues processing backend and active-thread events while the child shell owns the terminal.
4. When the shell exits, Codex restores terminal modes, redraws the TUI, and presents accumulated progress normally.

Continuing to drain backend events is important for correctness as well as progress. The relevant event paths use bounded queues; simply waiting for the child shell could eventually apply backpressure or reject/drop events during a long handoff. The handoff should therefore keep those paths moving without trying to render while the shell owns the terminal.

Deliberate scope

The first version should stay small:

• local CLI workspaces only, including a local app-server daemon
• reject remote workspaces rather than pretending a local shell is remote
• no panes, embedded PTY, or terminal multiplexer
• no capture of shell commands or output
• no injection of shell activity into model context
• no new app-server protocol
• the shell is an explicit local escape hatch and is not run in the Codex sandbox

This keeps /shell conceptually equivalent to intentionally leaving Codex for a local terminal, except that the Codex backend remains alive.

Alternatives considered

• Ctrl-Z / fg provides the right terminal experience, but pauses the agent and can also expose terminal-state restoration bugs.
• ! commands are excellent for quick commands, but even with completion they do not provide full native shell semantics.
• Launching a new terminal window loses the convenient same-session handoff.
• Embedding a PTY or adding panes starts to reinvent tmux and greatly expands the implementation surface.

Related but distinct requests:

• #31462 proposes autocomplete within ! mode.
• #13444 proposes taking over a particular agent command for editing or password entry.

Additional information

I have a focused local prototype of this design and would be happy to adapt it based on maintainer feedback. It includes:

• /shell discovery and availability during active tasks and side conversations
• native shell selection, inherited terminal I/O, and session-cwd behavior
• local/remote workspace gating
• backend and active-thread event draining while the child shell is running
• deferral of terminal-mutating failover until the TUI owns the terminal again
• TUI snapshot coverage and focused handoff tests

The full codex-tui test suite passes locally (2,967 runnable tests passed, 4 skipped), along with just fix -p codex-tui and just fmt.

Following the invitation-only contribution policy, I am filing the design before opening a PR. If this direction fits the product roadmap, would a maintainer please invite me to submit the implementation as a focused PR?