Skip to content

docs: fix per-model Shift+Tab thinking-level cycle description#3111

Open
aheritier wants to merge 2 commits into
mainfrom
docs/auto-update
Open

docs: fix per-model Shift+Tab thinking-level cycle description#3111
aheritier wants to merge 2 commits into
mainfrom
docs/auto-update

Conversation

@aheritier

Copy link
Copy Markdown
Contributor

Documentation changes

Updates `docs/guides/thinking/index.md` to fix the description of how the TUI's Shift+Tab thinking-level cycling works after #3097 changed the behaviour from per-provider to per-model.

What was wrong

The "Changing Thinking Level at Runtime" section said:

The level steps through the model's supported range (provider-specific), wrapping around — for example `none → minimal → low → medium → high → xhigh → none` on OpenAI.

After #3097, cycling is model-specific — each model only offers the levels its API actually accepts. The old OpenAI example implied every OpenAI reasoning model cycles through `xhigh`, but that's only true for gpt-5.2+; gpt-5, gpt-5.1, and the o-series all top out at `high`.

What was fixed

The bullet now reads:

The level steps through the model's supported range (model-specific), wrapping around — for example `none → minimal → low → medium → high → none` on OpenAI gpt-5/o-series, `none → minimal → low → medium → high → xhigh → none` on gpt-5.2+, `none → low → medium → high → none` on Anthropic Sonnet, `none → low → medium → high → max → none` on Anthropic Opus 4.6, and `none → low → medium → high → xhigh → none` on Anthropic Opus 4.7+.

Commits

Commit Source PR What changed
818742d1 #3097 Fix Shift+Tab cycle description — model-specific, accurate per-model examples

PRs reviewed and found up to date

Source PR Reason
#3099 Docs-only PR — already updated docs
#3098 Wider dialog widths — UI cosmetic, no user-facing behaviour change, no docs needed
#3096 Docs included in the PR (thinking_budget, Bedrock adaptive thinking)
#3095 Docs included in the PR (force_handoff, hooks reference)

@aheritier aheritier requested a review from a team as a code owner June 14, 2026 04:04
@aheritier aheritier added the kind/docs Documentation-only changes label Jun 14, 2026

@docker-agent docker-agent left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assessment: 🟡 NEEDS ATTENTION

This documentation fix correctly changes the cycling description from "provider-specific" to "model-specific". Two inconsistencies were found in the updated examples on line 335.

Comment thread docs/guides/thinking/index.md Outdated
While running in the TUI, press **Shift+Tab** to cycle the thinking effort level for the current model without editing your YAML config:

- The level steps through the model's supported range (provider-specific), wrapping around — for example `none → minimal → low → medium → high → xhigh → none` on OpenAI.
- The level steps through the model's supported range (model-specific), wrapping around — for example `none → minimal → low → medium → high → none` on OpenAI gpt-5/o-series, `none → minimal → low → medium → high → xhigh → none` on gpt-5.2+, `none → low → medium → high → none` on Anthropic Sonnet, `none → low → medium → high → max → none` on Anthropic Opus 4.6, and `none → low → medium → high → xhigh → none` on Anthropic Opus 4.7+.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] Anthropic Sonnet Shift+Tab example uses effort-string cycle incompatible with token-budget-only models

The new description shows none → low → medium → high → none for Anthropic Sonnet, but the same document (line 123) explicitly states:

"Every string effort value on Anthropic is sent as adaptive thinking (output_config.effort), which only newer Claude models (Opus 4.6+) accept. For older models like Sonnet 4.5, use an integer token budget instead."

If Shift+Tab actually cycles through effort strings (low, medium, high) for Sonnet, this contradicts the documented API constraint. Pre-4.6 Claude Sonnet models only accept integer token budgets — passing effort strings would result in an API error. Either:

  1. The Sonnet cycle should reflect token-budget steps (e.g. none → 1024 → 4096 → 8192 → none) rather than effort strings, or
  2. "Anthropic Sonnet" here specifically refers to a Claude 4+ Sonnet that supports adaptive thinking, in which case the model name should be more precise (e.g. "Claude Sonnet 4.5+" or similar).

Comment thread docs/guides/thinking/index.md Outdated
While running in the TUI, press **Shift+Tab** to cycle the thinking effort level for the current model without editing your YAML config:

- The level steps through the model's supported range (provider-specific), wrapping around — for example `none → minimal → low → medium → high → xhigh → none` on OpenAI.
- The level steps through the model's supported range (model-specific), wrapping around — for example `none → minimal → low → medium → high → none` on OpenAI gpt-5/o-series, `none → minimal → low → medium → high → xhigh → none` on gpt-5.2+, `none → low → medium → high → none` on Anthropic Sonnet, `none → low → medium → high → max → none` on Anthropic Opus 4.6, and `none → low → medium → high → xhigh → none` on Anthropic Opus 4.7+.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[MEDIUM] gpt-5.2+ as an xhigh cutoff is unsupported by the rest of the documentation

The new line introduces gpt-5.2+ as the threshold above which xhigh becomes available, implying that plain gpt-5 and the o-series stop at high. However, this version sub-number does not appear anywhere else in the documentation:

  • Line 40: lists supported OpenAI reasoning models as "o-series, gpt-5, gpt-5-mini" — no mention of gpt-5.2.
  • Line 61: states "These five effort levels (minimal–xhigh) are the **only** values accepted for OpenAI" — with no per-version distinction for xhigh.
  • Line 27 (Quick Reference): shows minimal, low, medium, high, xhigh, none as OpenAI's supported range with no version caveat.

Splitting gpt-5 into gpt-5 (tops at high) vs gpt-5.2+ (adds xhigh) is contradicted by line 61 which implies all gpt-5 models accept xhigh. If this split is intentional and accurate, the rest of the documentation needs corresponding updates to reflect the per-minor-version capability difference.

@aheritier aheritier added the area/tui For features/issues/fixes related to the TUI label Jun 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/tui For features/issues/fixes related to the TUI kind/docs Documentation-only changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants