Docs list --ask-for-approval as global, but codex exec rejects the post-subcommand form

What version of Codex CLI is running?

codex-cli 0.137.0

pnpm view @openai/codex version also returns 0.137.0, so this appears to reproduce on the current npm release.

What subscription do you have?

N/A. This is a CLI argument parsing and documentation issue.

Which model were you using?

N/A. The failing repro exits during argument parsing before any model run.

What platform is your computer?

Arch Linux x86_64, Linux 7.0.10-arch1-1.

What terminal emulator and version are you using, if applicable?

Observed in tmux 3.6b over SSH, but the repro uses only --help and --version style invocations.

Codex doctor report

codex doctor --json reports codexVersion: 0.137.0 and runtime.provenance as running npm on linux-x86_64. The overall doctor status is failed because of unrelated local network/update-path checks in this sandboxed environment.

What issue are you seeing?

The current Codex manual lists --ask-for-approval, -a under Global flags in the CLI command reference. The same row says it controls when Codex pauses for human approval and recommends never for non-interactive runs. The non-interactive docs also describe codex exec as suitable for runs with explicit, pre-set sandbox and approval settings.

In the installed current CLI, --ask-for-approval is accepted before exec, but rejected after exec:

codex --ask-for-approval never exec --version
# exits 0, prints: codex-cli-exec 0.137.0

codex exec --ask-for-approval never --version
# exits 2, prints: error: unexpected argument `--ask-for-approval` found

codex exec -a never --version
# exits 2, prints: error: unexpected argument `-a` found

This is confusing for script and adapter authors because several other propagated options work naturally after exec, for example codex exec --sandbox ..., codex exec --model ..., and codex exec --config .... The manual currently calls --ask-for-approval global, but codex exec --help does not list it and the post-subcommand form fails.

This appears related to #13614, which was closed after the codex exec --help text was made consistent with the implementation. The remaining current-version issue is that the manual still makes the approval flag look like a global setting usable for non-interactive runs, while current exec rejects the common post-subcommand form.

What steps can reproduce the bug?

1. Install current @openai/codex from npm.
2. Confirm version:

codex --version
pnpm view @openai/codex version

1. Compare accepted and rejected forms:

codex --ask-for-approval never exec --version
codex exec --ask-for-approval never --version
codex exec -a never --version

1. Check the docs/manual:

• CLI command reference lists --ask-for-approval, -a under Global flags.
• Non-interactive docs describe codex exec as supporting explicit sandbox and approval settings.
• codex exec --help does not expose --ask-for-approval or -a.

What is the expected behavior?

Either:

• codex exec --ask-for-approval never ... and codex exec -a never ... should be accepted if this flag is intended to propagate like other runtime flags, or
• the manual should explicitly document that approval policy for exec must be passed before the subcommand, for example codex --ask-for-approval never exec ..., or configured via -c approval_policy=... / config.

Additional information

This matters for wrappers and adapters that construct argv in the usual command subcommand options shape. The current workaround is to avoid emitting --ask-for-approval after exec and use only flags exposed by codex exec --help, plus config overrides for approval/model/reasoning settings when needed.