[DISCUSSION] Settings: order, priority and clarifications for agents, models, variants and providers #61115

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Hello,

I wanted to open a broad discussion about agents, models, variants and providers settings for those points :

• precedence, and order of settings priority (dynamic vs agent vs variant vs provider mostly).
• differentiation between providers settings from usage settings, relevant with auto discovery for extent.
• strategies and usages for settings overrides.

Relevant for : model, temperature, reasoningEffort, textVerbosity, maxTokens, maxOutputTokens , requireReasoning, top_p, steps, context.limits. Mostly parameters for prompt quality related, with model also bounded to security concerns (see #51071).

For priority order, I have seen several problems where it became confusing for some use case to predict what settings would be applied, often between JSON versus markdown, project vs global, etc. There is some improvements done recently in documentation, and some currently in work, but with now some parameters like models that can be overridden dynamically, it became more and more complex and I think this discussion could gather those concerns.

Here some usages :

• Choose some settings dynamically, let's say with an orchestrator agent (for model now, maybe in the future temperature, reasoning, etc).
• Ensure some restrictions on agent usage to avoid drifting or hallucinations (model, temperature, maxTokens, maxOutputTokens, textVerbosity, context.limits).
• Have auto discovery on limits or capabilities for models (context.limits, tool, vision, maxTokens, etc), and how they are merge with static configuration.
• Have variants we can choose from TUI / UI Desktop by model.
• Have hard limits on number of background tasks or parallel tasks on a provider (for local models). We have already depth for subagent.

Some problems are solved pretty naturally :

• With auto discovery, take minimum for context limits.
• What happen to an agent with existing model defined but can be override dynamically ? One solution would be to create new permissions for enabling / disabling some dynamic overrides (currently in discussion in v2: subagent model overrides are accepted without user authorization #51071).
• Hard limits are already handled by some backend solution (parallel tasks on LM Studio, llama-swap,, etc). But could be also be an usage limit like context instead of queuing mechanically tasks by waiting ressources on a provider.
• For priority, we can view those settings as default scoped values :

  policies > dynamic (model for now, maybe others in the future ?) > agent (md) > agent (json) > variant > model > (>provider, relevant with auto discovery)
  

  With also opencode.json(c) definition defining those settings in :

  Subfolders > Project  > Global > Connected OpenCode Console workspace (only in policies ?) > Admin  (programdata, /etc/, Application) < macOS managed preferences
  

  (in documentation quite misleading locations config vs policies documentation , see [FEATURE]: Multiple opencode.json inside a project with documentation and git recommendation for privacy / security #61099)

But this simple interpretation it is quite subjective (variant could be truth instead of agent for exemple), and there is problems not so trivial :

• What happen to a variant chosen in a primary agent with maxTokens but with primary agent value defined too ? Not quite the same as dynamic permissions since both are static configurations. Use agent value or override it by user variant value ?
• It should not have a strict usage but what happen between json and markdown configuration ? There is three possible location for project definition (see [FEATURE]: Multiple opencode.json inside a project with documentation and git recommendation for privacy / security #61099).

And we can be pretty confused : having multiples locations possibles, mixed also in same config documentation with
permissions, policies, priority of opencode.json, locations depending on os, provider, skills, tools, etc, etc, can be quite a heavy and steep learning curve.
Add to it some feature appearing overlapping like default model configuration, agent configuration and variants, and that those settings depend on models and providers, with surely some specificity changing behaviour like needing to reload models on OpenAPI backend...

So don't hesitate to correct me or to share your own usages, what should be the strategy for handling those settings, and ask questions. For exemple, should temperature, reasoningEffort, textVerbosity, maxTokens, maxOutputTokens , requireReasoning, top_p, steps should be overriden dynamically too ?

Issues linked :
#58057
#61099
#46122
#49550
#51071
#54629