feat(tui): make model assignment lists adaptive and add role guidance #2301

Pre-flight Checklist

• I have searched existing issues and this is not a duplicate
• I understand that PRs will be rejected if the linked issue does not have status:approved

🔍 Affected Area

TUI (terminal UI)

💡 Problem Statement

Summary

Improve the OpenCode model-assignment experience in two related ways:

1. Use the available terminal dimensions to display as many model and agent assignments as possible instead of always hiding entries behind fixed more limits.
2. Provide contextual guidance that helps users understand which model capabilities, reasoning levels, and speed/cost tradeoffs are appropriate for each SDD, Judgment Day, and review role.

The goal is to let users compare the complete assignment matrix when their terminal can display it, while also helping them make informed model-selection decisions.

Current behavior

Fixed list limits

The Assign Models to SDD, JD & Review Agents screen always renders at most 16 assignment rows. Provider, model, and reasoning-effort selectors are limited to 10 visible entries.

These limits are fixed constants:

• maxVisiblePhaseRows = 16
• maxVisibleItems = 10

The complete assignment matrix contains more rows than the fixed viewport permits. The review-agent section is therefore hidden behind ↓ more assignments even when the terminal has enough unused vertical space to display it.

The hidden entries remain reachable with keyboard navigation, so this is not data loss. However, it reduces discoverability and prevents users from comparing the complete configuration at a glance. The indicator currently reflects an implementation limit rather than actual terminal overflow.

Limited model-selection guidance

The screen displays the provider, model, and reasoning effort assigned to each role, but it does not explain:

• What the selected agent is responsible for.
• What type of work the agent performs.
• Whether the role benefits more from reasoning quality, coding ability, tool use, review ability, speed, or lower cost.
• Which reasoning-effort range may be appropriate.
• Whether Fast mode affects model capability or only processing speed and pricing.
• What tradeoffs apply to coordinators, implementation agents, verifiers, judges, and reviewers.

Users therefore need prior knowledge of every internal role before they can configure the assignment matrix confidently.

Expected behavior

Adaptive list height

The assignment screen should:

• Use the current terminal height to calculate how many rows fit.
• Show all assignment rows when they fit together with the title, actions, warnings, and keyboard help.
• Expand provider, model, and reasoning-effort lists beyond 10 entries when space is available.
• Use bounded cursor-following scrolling only when content genuinely exceeds the viewport.
• Show ↑ more, ↓ more, and ↓ more assignments only when entries exist outside the calculated viewport.
• Preserve the selected item after resize.
• Clamp cursor and scroll offsets safely after resize or search filtering.
• Keep search, keyboard navigation, warnings, Continue, Back, and help text usable.

Contextual role guidance

When an assignment row is selected, the TUI should offer contextual help describing:

• The agent's purpose and type of work.
• The capabilities to prioritize when selecting a model.
• A suggested reasoning range, when appropriate.
• Relevant quality, speed, cost, context, and tool-use tradeoffs.
• Whether the role primarily coordinates, implements, verifies, or performs adversarial review.

The guidance should help users make informed decisions without prescribing one model vendor or hard-coding model IDs that may become outdated. Fast/service-tier guidance must remain separate from reasoning-effort guidance.

📦 Proposed Solution

Viewport-aware rendering

Pass the current terminal dimensions into the model-picker rendering path and derive the visible-row budget from the space remaining after fixed screen chrome.

Use separate calculations for:

• Assignment list mode.
• Provider selection.
• Model selection and search.
• Reasoning-effort selection.
• Warnings and errors.
• Continue and Back actions.
• Keyboard help.
• Optional contextual guidance.

The root Bubble Tea model already receives terminal dimensions through tea.WindowSizeMsg. The model-picker renderer should consume that information instead of relying exclusively on fixed 16-row and 10-item limits.

Preserve a minimum usable viewport for small terminals, cap the calculated budget at the number of entries, and reuse the existing cursor-following scrolling. Render overflow indicators only when entries exist outside the calculated window.

Capability-based role guidance

Associate each configurable agent role with small, stable guidance metadata, for example:

type ModelSelectionGuidance struct {
    Purpose            string
    Priorities         []string
    SuggestedReasoning string
    ToolUse            string
    Tradeoffs          []string
}

The guidance should describe capabilities rather than hard-coded model names. Useful guidance may cover:

• Coding and tool-use reliability.
• Reasoning depth for architecture or adversarial evaluation.
• Balanced latency and reasoning for orchestration.
• Cost efficiency for mechanical or low-risk tasks.
• Context capacity for specs, designs, and implementation tasks.
• Fast mode when reduced latency justifies the additional cost.

Where runtime metadata is available, the help can also explain supported reasoning efforts, tool-call support, context limits, Fast/service-tier availability, and provider availability.

Example guidance

For sdd-apply:

Role: sdd-apply
Purpose: Implements approved tasks and modifies project files.

Consider:
• Strong coding and tool-use reliability
• Medium or high reasoning for non-trivial changes
• Sufficient context for specs, design, and tasks
• Fast mode when lower latency justifies the additional cost

Fast changes processing speed and pricing.
It does not replace the selected reasoning effort.

For jd-judge-a:

Role: jd-judge-a
Purpose: Performs an independent adversarial review.

Consider:
• Strong reasoning and defect detection
• High reasoning effort
• Reliable evidence analysis
• Independence from the implementation model

Prefer review quality over generation speed.

For gentle-orchestrator:

Role: gentle-orchestrator
Purpose: Coordinates agents, routes work, and maintains workflow state.

Consider:
• Reliable instruction following
• Strong tool and workflow coordination
• Balanced latency and reasoning
• Medium reasoning for normal orchestration

Responsive presentation

Possible presentations include a compact help line, a collapsible section opened with ? or i, a side panel when width allows, or a lower panel in narrow terminals. Users should be able to hide detailed guidance to maximize list space.

The guidance must adapt to terminal dimensions and must not recreate the viewport problem by unnecessarily hiding assignments.

Acceptance criteria

Adaptive viewport

• A tall terminal displays all current assignment rows without more assignments when the complete screen fits.
• A short terminal keeps the list bounded and allows every row to be reached with keyboard navigation.
• Provider, model, and effort lists can display more than 10 entries when terminal height allows.
• Overflow indicators appear only when entries exist outside the calculated viewport.
• Continue, Back, warnings, search, and keyboard help remain visible at supported terminal sizes.
• Resizing preserves the selected assignment and safely clamps the visible window.
• Search filtering safely clamps cursor and scroll state.
• Profile creation and editing continue to render correctly.

Role guidance

• Selecting an assignment provides a concise explanation of that agent's purpose.
• Guidance identifies the capabilities that matter for the selected role.
• Guidance distinguishes reasoning effort from Fast/service-tier selection.
• Guidance explains relevant quality, speed, cost, context, and tool-use tradeoffs.
• Guidance does not depend on hard-coded model brands or transient model IDs.
• Detailed guidance can be expanded or hidden without disrupting keyboard navigation.
• Small terminals retain a usable assignment viewport when guidance is enabled.
• The selected model, provider, reasoning effort, and assignment remain clearly visible.
• The number of matching results is shown where lists can be filtered.
• Existing assignment persistence and keyboard behavior remain unchanged.
• Focused tests cover tall, short, resized, filtered, guidance-expanded, and guidance-collapsed states.

🔄 Alternatives Considered

Keep the fixed 16/10 row limits

This prevents uncontrolled growth, but wastes available space and displays overflow indicators when there is no real viewport overflow.

Render every row unconditionally

This removes unnecessary hiding in tall terminals but can push actions and help text outside smaller terminals.

Add a manual list expansion action

This introduces additional state and another interaction even though Bubble Tea already provides terminal dimensions.

Display model guidance permanently

A permanently expanded panel could reduce the viewport and create clutter. Responsive or collapsible guidance preserves discoverability without consuming space when unnecessary.

Hard-code recommended models

Model catalogs, aliases, pricing, and provider capabilities change over time. Guidance should describe required capabilities and tradeoffs rather than permanently recommending one model ID.

📎 Additional Context

Screenshot evidence

The supplied screenshot shows ↓ more assignments after the Judgment Day agents while unused vertical space remains below the assignment list. The review-agent assignments remain hidden.

It also demonstrates the decision complexity: the interface displays provider, model, and reasoning effort, but does not explain each role or which model characteristics should be prioritized.

The unrelated LM Studio discovery failed warning visible in the screenshot is not part of this request.

Screenshot attachment pending.

Source evidence

• Fixed viewport limits
• Assignment window and overflow rendering
• Provider, model, and effort rendering
• Additional selector rendering
• Terminal dimensions captured by the root model
• Model-picker rendering path
• Profile creation reuses the renderer

Related issues

• fix(tui): preserve Codex capabilities and OpenCode fast variants #2218 covers runtime model capabilities, OpenCode Fast aliases, service-tier persistence, and the distinction between Fast and reasoning effort.
• [Bug]: Oversized TUI elements and header truncation on Windows Terminal (PS 7.6.3) #1009 covers general terminal clipping and measured layout.
• fix(tui): bound and scroll long welcome advisories #1140 implemented terminal-aware bounded scrolling for welcome advisories.
• OpenCode model picker omits custom native agents, causing unconfigured subagents to fallback to expensive general model #2098 and feat(tui): expose OpenCode native fallback agents (general/explore) in TUI model picker #2197 concern which agents are included in the picker, not how existing rows use the available terminal height.

This issue is limited to the user experience of displaying and configuring model capabilities. It should consume capability information resolved through #2218 without duplicating that issue's backend discovery or persistence scope.