v1.91.94.0 feat(codex): --effort <level> overrides reasoning effort for one run (#3146) (#3151)

* feat(codex): --effort <level> sets GSTACK_CODEX_EFFORT for one run

/codex review --effort medium (or --effort=medium) prefixes each
run-with-timeout dispatch with GSTACK_CODEX_EFFORT=<level>, which outranks
codex_effort and the per-mode default; --xhigh becomes shorthand for
--effort xhigh. The probe keeps owning validation. A missing value, a value
that is not one lowercase word, or conflicting flags stop instead of falling
back.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(codex): per-run effort prefix reaches the rendered /codex review dispatch

Runs the rendered review fence against the fake codex: no prefix uses
codex_effort, GSTACK_CODEX_EFFORT=medium|xhigh wins over it, an unknown level
never reaches codex. Step 1 check pins --effort tokens and the stop rule.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(codex): document codex_effort and --effort; Challenge runs at high, not xhigh

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(changelog): [Unreleased] entry for /codex --effort

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(codex): --effort reaches the probe as an allowlisted request level, parsed before the mode and checked before the paid probe

The level now travels as run-with-timeout --request-effort '<effort-level>'
(placeholder grammar ^[a-z]*$) instead of an agent-built env prefix, and the
probe names /codex --effort when it rejects one. Effort flags count only right
after /codex or its mode word and are removed before mode detection. Step 0.5
runs check-effort before probe-model, so a bad level makes no Codex call even
on a cold cache. Tests cover all five dispatch fences and the zero-call cases.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* docs(codex): per-request --effort in model-policy, CHANGELOG behavior changes, TODOS follow-ups

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* chore: stamp v1.91.93.0

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(codex): effort flags sit among /codex's leading flags; the probe names an unfilled '<effort-level>' placeholder

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* docs(codex): per-request row in the effort precedence table, in-tool help names /codex --effort, late-flag notice

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* test(codex): binding tripwire sees the request-effort dispatch; valid and unfilled levels through Step 0.5 and every fence; doc accuracy

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: John Nunemaker <nunemaker@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
This commit is contained in:
authored and GitHub committed 2026-10-12 13:17:02 -07:00
1 parent e23f7b807f
commit 70fab3e246
26 files changed
+257 -86

No files matched your search

+12 -5
View File
@@ -123,11 +123,12 @@ explicit implementation model rather than delegating to a hidden native choice.
## Reasoning effort
Codex calls carry a `model_reasoning_effort`. It follows the same shape as the
model: a per-run environment override, then a stored setting, then the default
each gate ships with.
model: a per-request flag on `/codex`, a per-run environment override, then a
stored setting, then the default each gate ships with.
| Order | Source | Set it with |
| --- | --- | --- |
| 0 | `/codex ... --effort <level>` (this request only; `/codex` alone) | `/codex review --effort medium` |
| 1 | `GSTACK_CODEX_EFFORT` (this shell, this run) | `export GSTACK_CODEX_EFFORT=max` |
| 2 | `codex_effort` in config.yaml | `gstack-config set codex_effort low` (`unset` restores the defaults) |
| 3 | the gate's default | nothing: `high` for reviews, plan reviews and `/codex` review and challenge; `medium` for `/codex` consult and design direction |
@@ -138,9 +139,15 @@ through the usual model error. An invalid value never reaches Codex:
`gstack-config set` rejects it, and `gstack-codex-probe run-with-timeout --effort
<default>` (which resolves the order above and appends the flag) stops the call
before anything is sent, naming the source to fix. `gstack-codex-probe
check-effort <default>` prints the same resolution without a call. `/codex ...
--xhigh` outranks all three for that request (it sets `GSTACK_CODEX_EFFORT=xhigh`
on the dispatch).
check-effort <default>` prints the same resolution without a call.
For one request, `/codex review --effort medium` (or `--effort=<level>`; `--xhigh` is
shorthand for `--effort xhigh`) outranks the other three, including an exported
`GSTACK_CODEX_EFFORT`, and changes nothing that persists. The flag counts only
directly after `/codex` or its mode word, among the leading flags (`-m`/`--model`,
`--role`, in any order) and before the prompt text; a later `--effort` is part of the
prompt, and `/codex` says so. A Consult follow-up resolves its effort afresh. `/codex` passes the level to the probe as `--request-effort`,
so an unknown level stops before any Codex call, naming the flag.
`/spec`'s quality gate keeps `medium` inside its 120-second budget whatever you
set, because a higher effort would spend the time the gate is sized for.
+3 -1
View File
@@ -1193,7 +1193,9 @@ selection. See [model policy](model-policy.md) for pins, precedence and recovery
A severity-gate PASS is separate from [review freshness](#review-readiness-dashboard): unresolved recorded findings (`findings > findings_fixed`, with missing `findings_fixed` treated as zero) prevent CURRENT even when the gate passes. This does not change the severity gate. Fixes still require a new completed, unchanged review pass before the fixed tree can grade CURRENT.
**Challenge** — adversarial mode. Codex actively tries to break your code. It looks for edge cases, race conditions, security holes, and assumptions that would fail under load. Uses maximum reasoning effort (`xhigh`). Think of it as a penetration test for your logic.
**Challenge** — adversarial mode. Codex actively tries to break your code. It looks for edge cases, race conditions, security holes, and assumptions that would fail under load. Think of it as a penetration test for your logic.
**Reasoning effort** — Review and Challenge run at `high`, Consult at `medium`. `gstack-config set codex_effort <level>` changes that for every run; `--effort <level>` right after `/codex` or its mode word, among the leading flags (`-m`, `--model`, `--role`), changes it for one (`/codex review --effort medium` for a faster, cheaper review). `--xhigh` is shorthand for `--effort xhigh`. An unknown level stops before Codex runs. See [model policy](model-policy.md#reasoning-effort) for levels and precedence.
**Consult** — open conversation with session continuity. Ask Codex anything about the codebase. Follow-up questions reuse the same session, so context carries over. Great for "am I thinking about this correctly?" moments.