Zsh completion treats subcommands as the optional prompt, breaking nested completion

What version of Codex CLI is running?

codex-cli 0.154.0

What platform is your computer?

Linux x86_64, Zsh 5.9. Reproduced with interactive Zsh after loading the completion script.

What issue are you seeing?

The generated Zsh completion script fails to complete nested subcommands. For example, codex remote-control pa<Tab> produces no match, although codex remote-control --help lists pair and the generated completion script contains the corresponding candidate.

What steps can reproduce the bug?

1. Start zsh -f.
2. Run autoload -Uz compinit; compinit.
3. Run source <(codex completion zsh).
4. Type codex remote-control pa and press Tab without submitting the command.

Expected: completion to codex remote-control pair.
Actual: no completion.

Additional information

The root _arguments specification emitted by codex completion zsh lists the optional free-form prompt before the subcommand slot:

'::prompt -- Optional user prompt to start the session:' \
":: :_codex_commands" \
"*::: :->codex-cli"

The generated dispatcher then selects case $line[2] in. This treats remote-control as the prompt and pa as a top-level command, rather than entering the remote-control completion branch.

As a diagnostic only, inserting a dummy positional word (codex dummy remote-control pa<Tab>) makes the completion expand to pair. No pairing command needs to be executed to reproduce this.

The generator is called from codex-rs/cli/src/main.rs::print_completion, using MultitoolCli::command() and clap_complete::generate.

Related but different: #16368 concerns dynamic profile candidates; #4692 changed prompt value hints to avoid excessive filename suggestions. Neither addresses the nested subcommand offset.

Implementation and validation

A focused fix is available in commit fc443338, based on upstream ddea03a.

The change omits the root free-form prompt from the command definition used for Zsh completion generation. A terminal integration test snapshots actual completions for remote-control pairing, a preceding global option, MCP, a deeper app-server subcommand, and --version.

• just fmt: passed.
• just test -p codex-cli: 423 passed, 0 skipped.
• The regression test fails against Codex 0.154.0 and passes against the patched binary.
• The generated script also completes codex remote-control pa<Tab> to pair with the normal interactive Zsh configuration and fzf Tab binding.

An upstream PR was attempted, but GitHub rejected CreatePullRequest for this account; the REST create-PR endpoint also rejected the request. The commit above contains the complete two-file change for review.

Co-Authored-By: Codex noreply@openai.com

Start at codex-rs/cli/src/main.rs::print_completion and inspect how MultitoolCli::command() is passed to clap_complete for Zsh generation. Run the terminal integration regression test described in the issue; done means nested remote-control completion reaches pair, including with a preceding global option, while the other listed completions remain valid.