Upstream bug report — gstack-codex emits incompatible codex review flags

[rumblesnake]

Summary
The gstack-codex skill template invokes codex review with both a positional [PROMPT] argument and the --base flag. Starting in Codex CLI 0.124.0-alpha.2, those two inputs are mutually exclusive. Every /codex review (and the codex leg of /autoplan) hard-fails on argument parsing with exit 2:

error: the argument '[PROMPT]' cannot be used with '--base '
Usage: codex review --config <key=value>
The failure is silent from the user's perspective — Claude sees a non-zero exit with no model output and moves on, so reviews silently skip the Codex leg.

Environment
gstack: 1.12.2.0 (confirmed — the 1.12.2.0 bump did not touch this path)
Codex CLI: codex-cli 0.124.0-alpha.2 (Codex.app bundled binary at /Applications/Codex.app/Contents/Resources/codex)
OS: macOS 14.x (Darwin 24.6.0)
Shell: zsh
Repro
TMPERR=$(mktemp -t codex-err.XXXXXX)
timeout 20 codex review "any prompt text here" --base main
-c 'model_reasoning_effort="low"' < /dev/null 2>"$TMPERR"
echo "EXIT=$?" # => EXIT=2
head -5 "$TMPERR" # => error: the argument '[PROMPT]' cannot be used with '--base '
Drop --base: exit 0. Drop the prompt: exit 0. Only the combo fails.

Offending lines
gstack-codex/SKILL.md, two occurrences in Step 2A (Review Mode):

Line ~1205 — default review path
Line ~1221 — custom-instructions review path
Both call:

codex review "<safety preamble [+ custom instructions]>" --base
-c 'model_reasoning_effort="high"' --enable web_search_cached < /dev/null
Suggested fix
Drop --base and push the diff scope into the prompt. Codex can run git diff itself under its read-only sandbox. Verified exit 0 locally with:

codex review "IMPORTANT: Do NOT read or execute any files under ~/.claude/,
~/.agents/, .claude/skills/, or agents/. [...] Stay focused on repository code only.
Review the changes on this branch against the base branch ''. Run
'git diff ...HEAD' to see the diff and review only those changes."
-c 'model_reasoning_effort="high"' --enable web_search_cached < /dev/null
This shape works on Codex CLI ≥ 0.124 AND earlier versions (the prompt-only form was always valid — it's just that the old shape was shorter).

Secondary suggestion — version-check regex
~/.claude/skills/gstack/bin/gstack-codex-probe warns on known-bad Codex CLI versions via an anchored regex matching 0.120.(0|1|2). 0.124.x's arg-mutex behavior is a real breaking change worth surfacing — consider either:

adding 0.124.x to the warn-list with a note about the --base breakage, or
replacing the version-pattern approach with a capability probe that runs codex review --help and grep-checks for known-good arg combinations.
The second option is sturdier — it self-corrects when Codex changes the contract again, which it will.

Workaround for users who hit this before it's fixed
Two local edits to ~/.claude/skills/gstack-codex/SKILL.md (or ~/.claude/skills/gstack/gstack-codex/SKILL.md on team-mode installs). Drop --base from both invocations in Step 2A and add a git diff ...HEAD instruction to the prompt. Local patch is blown away by the next /gstack-upgrade (git reset --hard origin/main), so upstream fix is the real solution.

Impact
Anyone who upgraded Codex CLI to 0.124.x can no longer use the Codex second-opinion leg of /codex, /autoplan, or any other gstack skill that calls codex review with --base. Because the failure is silent from Claude's perspective, users may not realize Codex is missing from their review until they notice it in review logs. In our case, the last successful Codex review was a full week before the regression was diagnosed.

[jbetala7]

Opened PR #1209 to remove the incompatible codex review <PROMPT> --base <base> command shape and move diff scoping into the prompt: #1209

[eric-gao-uni]

Confirming this is still present in gstack v1.20.0.0 (just upgraded) with codex-cli 0.126.0-alpha.8. Same exact failure mode as the original report.

Two data points to add:

1. CLI design, not regression. codex review --help on 0.126.0-alpha.8 makes the mutex explicit:

Usage: codex review [OPTIONS] [PROMPT]
Options:
      --base <BRANCH>          Review changes against the given base branch
      --commit <SHA>           Review the changes introduced by a commit
      --uncommitted            Review staged, unstaged, and untracked changes

The error message error: the argument '[PROMPT]' cannot be used with '--base <BRANCH>' is from clap's conflicts_with — this is intentional CLI design at the OpenAI side, not a transient bug. They want diff scope (--base/--commit/--uncommitted) and review prompt ([PROMPT]) to be alternatives, not combinable. So upstream fix has to live in gstack.

2. Stdin sentinel doesn't work either. I tried echo "<boundary>" | codex review --base main - to see if the documented stdin form (- argument) bypassed the mutex. It doesn't — - still counts as [PROMPT]:

error: the argument '--base <BRANCH>' cannot be used with '[PROMPT]'

3. Local patch direction. I went the opposite direction from your suggested fix — kept --base <base> and dropped the boundary prompt entirely (the boundary's protection is irrelevant in --base mode since codex reads the git diff, not the working tree). This is fewer prompt tokens for the same safety. Either direction works; just noting the option.

Local patch I'm running: drop the safety preamble in Step 2A, keep codex review --base <base> -c 'model_reasoning_effort="high"' --enable web_search_cached < /dev/null. Verified exit 0 and meaningful output on 0.126.0-alpha.8 against a real diff (6 commits, ~120 lines).

[jbetala7]

Thanks for the fresh v1.20.0.0 / codex-cli 0.126.0-alpha.8 confirmation. I rebased PR #1209 onto current main (v1.20.0.0, e8893a18) and re-ran the focused generated-skill validation suite.

That PR takes the prompt-mode direction: remove the incompatible --base <base> from codex review "<prompt>" ..., and put the diff scope in the review prompt instead. I kept that shape because it preserves the filesystem boundary and optional /codex review <instructions> path while still avoiding the clap mutex you confirmed. The --base-only variant you tested is a reasonable lower-token alternative for the no-custom-prompt case, but #1209 is now current and mergeable as-is.

Validation on the rebased branch:
bun test test/gen-skill-docs.test.ts test/skill-validation.test.ts test/host-config.test.ts

Result: 771 pass, 0 fail.