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>

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## [Unreleased]
+## [1.91.93.0] - 2026-10-11
 
 **`/codex review --effort medium` runs one review at the effort you name, without changing your saved setting.**
 
@@ -8,9 +8,15 @@
 
 ### What this means for you
 
-- **`--effort <level>` on any `/codex` mode.** `/codex review --effort medium`, `/codex challenge --effort=low` and so on set `GSTACK_CODEX_EFFORT` for that dispatch only. It outranks `codex_effort` and the per-mode defaults, and the probe still rejects an unknown level before any Codex call. `--xhigh` keeps working as shorthand for `--effort xhigh`.
-- **No silent fallback.** A missing value, a value that isn't a single lowercase word, or conflicting effort flags stop the run with a message instead of quietly using a default.
-- **docs/skills.md** documents `codex_effort` and `--effort`, and no longer claims Challenge runs at `xhigh` (it runs at `high`).
+- **`--effort <level>` on any `/codex` mode.** `/codex review --effort medium`, `/codex challenge --effort=low` and so on set the effort for that request only. It outranks an exported `GSTACK_CODEX_EFFORT`, `codex_effort` and the per-mode defaults. `--xhigh` keeps working as shorthand for `--effort xhigh`.
+- **Flags only where flags go.** The flag counts directly after `/codex` or its mode word, before your prompt. `/codex what does --effort do?` sends that question to Codex instead of eating `--effort` as a setting, and `/codex review --effort medium` stays on native review.
+- **A typo costs nothing and says what to fix.** `--effort turbo` stops before any Codex call, including the model probe on a cold cache, with `'turbo' from /codex --effort is not a Codex reasoning effort level` and the list of levels. A missing value or conflicting effort flags stop with a message too.
+- **docs:** `docs/model-policy.md` documents the per-request flag, and `docs/skills.md` documents `codex_effort` and `--effort` and no longer claims Challenge runs at `xhigh` (it runs at `high`).
+
+### For contributors
+
+- `gstack-codex-probe check-effort <default> --request <level>` and `run-with-timeout --effort <default> --request-effort <level>` take the request level (empty means none) and name `/codex --effort` as its source. The five `/codex` dispatch fences pass it as the allowlisted `'<effort-level>'` placeholder (grammar `^[a-z]*$`), so the level reaches the shell only through the placeholder lint, never through prose. Test parsers of the `run-with-timeout` line accept the new argument.
+- `test/codex-effort.test.ts` runs all five rendered dispatches against a fake `codex`, and the bogus-level case asserts the rejection and zero calls. `test/model-role-invocation.test.ts` adds a zero-call case for an invalid level in Step 0.5.
 
 Contributed by @jnunemaker
 

TODOS.md

@@ -2,6 +2,13 @@
 
 ## NEXT PRIORITY
 
+### P3: `/codex --effort` follow-ups (filed 2026-10-11, from the #3146 autoplan review)
+
+- **Show the effort that ran.** The probe's `CODEX_EFFORT: <level> (source: ...)` line stays in `$TMPERR`, so a user cannot see that `--effort` took effect. Add an `Effort:` line to the review, challenge and consult result footers. Blocked on skeleton bytes in `codex/SKILL.md` (cap 60,200). **Effort:** S. **Priority:** P3.
+- **Timeouts at high effort.** `xhigh`, `max` and `ultra` can exceed the fixed 330 s / 540 s wrappers, and the timeout copy blames prompt size or API speed. Name the effort in the timeout message and suggest a lower `--effort`; consider effort-scaled budgets. **Effort:** S. **Priority:** P3.
+- **Per-run effort for gate voices (#2934).** `/review`, `/ship` and plan-review outside voices take `GSTACK_CODEX_EFFORT` and `codex_effort` but have no per-request flag; the Claude Code runner takes no effort at all. Needs its own precedence and consent review. **Effort:** M. **Priority:** P3.
+- **`minimal` with web search.** Every `/codex` dispatch passes `web_search="cached"`, and Codex reportedly rejects that with `reasoning.effort: minimal` (openai/codex#3559, #5002). Unverified here (no Codex CLI on the release machine); the same path already ships through `codex_effort minimal`. Verify on the pinned CLI and drop web search for `minimal` if it fails. **Effort:** S. **Priority:** P3.
+
 ### P2/P3: open bugs by area after the Wave 9 triage (filed 2026-10-11)
 
 The 158 older open issues were re-checked against main 5cb5e1c (v1.91.83.0). Of the 30 still-valid bugs, Wave 9 lanes take #915, #1080, #1081, #1150, #1315 and #1675 and park #2118 and #2623 (next section). The rest stay open here: issue, root-cause file, size. Bugs already tracked elsewhere in this file point there instead of repeating it.

docs/model-policy.md

@@ -138,9 +138,14 @@ 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 all three, including an exported
+`GSTACK_CODEX_EFFORT`, and changes nothing that persists. The flag counts only
+directly after `/codex` or its mode word, before the prompt text; a later `--effort`
+is part of the prompt. `/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.

docs/skills.md

@@ -1195,7 +1195,7 @@ A severity-gate PASS is separate from [review freshness](#review-readiness-dashb
 
 **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>` 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.
+**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 the mode 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.