From 2b1c746aac0ffe8e3256cc311297c356ed55d5f9 Mon Sep 17 00:00:00 2001 From: garrytan Date: Mon, 12 Oct 2026 00:57:28 +0000 Subject: [PATCH] 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 | 14 ++++++++++---- TODOS.md | 7 +++++++ docs/model-policy.md | 11 ++++++++--- docs/skills.md | 2 +- 4 files changed, 26 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a7697b9ef..9441bb42f 100644 --- a/CHANGELOG.md +++ b/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 ` 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 ` 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 --request ` and `run-with-timeout --effort --request-effort ` take the request level (empty means none) and name `/codex --effort` as its source. The five `/codex` dispatch fences pass it as the allowlisted `''` 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 diff --git a/TODOS.md b/TODOS.md index b2aadc566..a82e741e5 100644 --- a/TODOS.md +++ b/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: (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. diff --git a/docs/model-policy.md b/docs/model-policy.md index 7a9459485..92115b90e 100644 --- a/docs/model-policy.md +++ b/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 ` (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 ` 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 ` prints the same resolution without a call. + +For one request, `/codex review --effort medium` (or `--effort=`; `--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. diff --git a/docs/skills.md b/docs/skills.md index 9e1e04a9c..6be19fb42 100644 --- a/docs/skills.md +++ b/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 ` changes that for every run; `--effort ` 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 ` changes that for every run; `--effort ` 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.