OpenCode Reasoning Variants: Validate Overrides After 1.19.3
Validate OpenCode reasoning variants after 1.19.3 with a lane inventory, configuration precedence checks, agent override tests and a clear rollback record.
Go deeper. Build your own.
OpenCode reasoning variants need a configuration check before version 1.19.3 becomes your fleet baseline. The official October 16, 2026 release says model reasoning options now generate reasoning variants, replacing catalog variants while preserving configured variant overrides. That is a specific reason to revisit what each lane selects, especially when a project, a named agent and a global model definition all contribute settings.
A familiar variant name is insufficient evidence that a lane requests the intended configuration. Preserve the working setup, identify the layers that contribute to it, compare the available choices, then exercise the intended selection against a fixed task. This guide proposes that validation procedure; it does not report tests performed on an OpenCode installation.
The scope is deliberately narrow. The existing CLI upgrade canary guide covers general upgrade drift, while model default promotion evidence covers earning the default slot. Here, the artifact is a per-lane record connecting configuration provenance, model identity, variant selection and observable results.
Source: Anomaly’s OpenCode v1.19.3 release page on GitHub. The capture shows the release’s reasoning-variant improvement; it is not evidence of a successful local upgrade.
Define the lane before comparing variants
Start with a lane that has a stable purpose: repository review, implementation planning or a bounded maintenance task. Two sessions using the same model can still represent different operating configurations because their agents, project files and startup choices differ. Name the lane by its job and owner, then record its expected model and selection before changing versions.
The model documentation uses the full identifier provider_id/model_id. Preserve both parts. A short model name loses the provider context that determines which model configuration you are inspecting. Record the actual identifier from the working lane, rather than copying a documentation example or treating the documentation’s recommended-model list as a current procurement recommendation.
- Record the installed OpenCode version and the lane’s normal launch context, including its working directory and interface.
- Record the full provider/model identifier, selected agent and selected variant, or explicitly record that no variant was selected.
- List model-level options, named variant overrides and agent-specific model options separately.
- Name the fixed task, expected result and permissions that will remain constant during comparison.
- Assign one owner who can hold promotion and restore the working setup.
Keep the record free of credential values. Configuration can reference environment variables and files, so copying an entire resolved configuration into an unrestricted ticket can reveal more than this exercise needs. Preserve the complete working configuration through your existing protected process; put only the relevant, redacted settings and their provenance into the review packet.
A useful inventory row answers a concrete question: when the review lane starts in this repository with this agent, which model and variant should it use? If the answer is merely “the default,” finish the inventory first. The default may be intentional, but its resolved identity still needs to be recorded.
Trace conflicting keys through the configuration layers
OpenCode’s configuration reference says configuration files are merged, rather than replaced wholesale. Later sources override earlier ones for conflicting keys, while non-conflicting settings remain. A project file that changes the model therefore does not erase unrelated global settings. This makes inspecting only the nearest file an unreliable way to describe a lane.
Follow the documented load order below. Treat it as a provenance checklist, not permission to edit every layer. Managed settings belong to their administrator, and remote organizational configuration supplies defaults that ordinary later layers can override. The reference separately describes a custom configuration directory; inventory that directory when present rather than silently treating it as identical to a custom configuration file.
| Documented source order | What to establish for this lane |
|---|---|
| Remote organizational configuration | Which relevant defaults arrive from the organization’s endpoint |
| Global configuration | Which user-wide model definitions and options remain applicable |
Custom file through OPENCODE_CONFIG |
Whether a selected file contributes an override |
| Project configuration | Which repository-specific keys conflict with earlier settings |
.opencode directories |
Which agents and other project configuration participate |
Inline OPENCODE_CONFIG_CONTENT |
Whether the runtime contributes additional conflicting keys |
| Managed configuration files | Which administrator-controlled settings override ordinary layers |
| macOS managed preferences | Whether enforced preferences supply the highest-priority values |
- Mark every applicable source as present, absent or unresolved.
- For each relevant key, record the contributing source and any later conflicting value.
- Distinguish a key that is absent from one explicitly configured to a value.
- Review the resolved configuration using the documented diagnostic facility where available in the installed version.
- Stop if the resolved value cannot be explained by the inventory.
The reference documents opencode debug config when verifying managed preferences. Its output can help inspect resolution, but it does not by itself prove what a provider received during a task. Keep configuration inspection and request observation as separate evidence categories. Also record the version to which the inspection applies: these are current documentation pages, not an archived specification of every historical build.
Consider a hypothetical lane whose global file defines two named variants while the project changes only the selected model. The merge rule tells you unrelated settings can survive; it does not tell you that both variants apply to the newly selected model. Reconcile the full provider/model path before deciding whether an inherited override is relevant.
Separate generated choices from preserved overrides
The release note establishes two linked changes: reasoning options generate variants, and configured variant overrides are preserved while catalog variants are replaced. It does not publish a new reasoning-options schema or a complete ordering rule for every combination of generated variants, model options and agent options. Avoid expanding that single sentence into undocumented configuration machinery.
The model reference documents model-level options, named variants, custom variant overrides and disabling a variant with disabled: true. It also describes cycling variants through the variant_cycle keybind. Use those documented concepts to label your evidence. Do not assume that a name such as high represents the same parameters across providers or across every model from one provider.
| Observed condition | Operator decision |
|---|---|
| Expected variant appears and its configured override is retained | Continue to the fixed task; appearance alone is insufficient |
| Expected variant disappears after the upgrade | Hold the lane and compare its model identity and contributing settings |
| A previously disabled choice becomes selectable | Treat it as a mismatch and investigate before promotion |
| The name survives but relevant options differ | Hold until the changed configuration is explained and accepted |
| A new generated choice appears | Record it without automatically adopting it |
Before the upgrade, capture the available choices for the lane’s exact model and identify which are explicitly configured. Afterward, repeat from the same project and agent context. Preserve the two observations as separate records. Do not rewrite the old record to match the new display; the difference is what makes the comparison useful.
A provider-specific parameter belongs only where its documentation and the installed schema support it. The selected evidence demonstrates existing examples, but it does not justify inventing a generic reasoning configuration that works everywhere. This runbook therefore supplies an inventory and acceptance procedure rather than a paste-ready configuration for an unspecified fleet.
Check agent options independently of variant selection
The agent reference allows an agent to specify its own model. It says primary agents without a specified model use the globally configured model, while subagents without one use the model of the invoking primary agent. Additional agent options can be passed through as provider-specific model options. The model reference also states that agent configuration overrides global model options.
That creates a second inspection task after tracing file precedence. First determine the resolved configuration sources; then examine the selected agent and its model options. Do not flatten these two questions into a single stack that claims to establish undocumented precedence between a selected variant and every agent-specific option. The overlapping case needs observation.
- Identify the primary agent used by the fixed task and any subagent the task intentionally exercises.
- Record each explicit agent model and distinguish it from inherited model selection.
- List additional agent options that overlap with relevant model-level or variant settings.
- Run the primary-agent path and the relevant delegated path as separately labeled cases.
- Hold any case whose requested configuration remains ambiguous.
For example, a review agent may explicitly request a reasoning option even when the operator changes the displayed variant. The documentation supports checking that agent option; the supplied release note does not establish the complete resolution behavior of that overlap. Mark the expected outcome as a hypothesis to verify, rather than presenting it as a guaranteed consequence.
Do not use the assistant’s prose as the deciding witness. A response claiming “I used the high variant” is not request metadata. Capture the UI selection and configuration separately, then use any legitimate, available request evidence to narrow what is known. If no request evidence exists, state that limitation and avoid calling provider-side settings verified.
Original editorial inspection map based on OpenCode’s release and documentation. The arrangement identifies separate questions; it does not assert an undocumented merge algorithm.
Run the comparison with a fixed task and fixed authority
Choose a task small enough that an operator can inspect the result directly, yet representative of the lane. For a review lane, use a known fixture with a short answer key. For planning, require a bounded plan against a fixed repository state. Avoid a sprawling live backlog item whose changing inputs make configuration differences impossible to isolate.
Use the same task text, repository state, model identifier, agent and permission posture on both sides of the comparison. If the upgrade changes available variants, preserve the old observation and record which intended selection is possible afterward. Do not silently substitute the closest-sounding choice. A necessary substitution is a proposed lane change that needs its own acceptance decision.
- Complete the baseline case on the working version and retain the task, selection and result.
- Repeat on 1.19.3 with the working configuration preserved.
- Record available variants before selecting the intended choice.
- Execute the fixed task and retain the observable result and available metadata.
- Compare mismatches before making any configuration adjustment.
The permissions reference defines allow, ask and deny, and says agent permission rules take precedence over global rules. Keep these settings unchanged throughout the comparison. A deeper reasoning selection supplies no additional tool authority. Check both primary and delegated paths if both are in scope, because their permissions may differ.
Also preserve approval mode and session context. The permissions reference says auto mode approves requests that would otherwise ask, while explicit denials remain enforced. Switching into that mode would confound a comparison intended to isolate reasoning configuration. For the broader operating principle, use the existing house permission dialect: lane authority is a separate contract from model behavior.
A correct answer demonstrates the fixture’s result, not complete equivalence between configurations. Latency, wording and answer length can vary without establishing which reasoning parameter was sent. Record those observations where useful, but do not reverse-engineer hidden settings from a response’s apparent depth or confidence.
Require evidence at each boundary
Make the acceptance packet readable by someone who did not operate the session. It should connect what the lane was intended to request with what was configured, selected and observed. Use the fleet replay guide for the broader reason to preserve session evidence outside an ephemeral UI; this packet adds the configuration details needed for this release.
The chart below is an editorial coverage checklist. Its filled cells indicate which evidence belongs in each case, not measured success rates. The central discipline is to avoid using one artifact to answer several different questions. A variant menu documents available choices; a result documents task behavior; neither replaces configuration provenance.
Original editorial coverage chart. Filled cells mean evidence required by this proposed procedure. No tests or pass rates are represented.
| Evidence item | Acceptance question |
|---|---|
| Version and launch context | Can another operator identify the runtime and project context? |
| Redacted settings with source locations | Can each relevant value be traced to its contributor? |
| Model and available variant observations | Was the intended choice available for the exact model? |
| Selected agent and overlapping options | Were agent-specific settings reviewed explicitly? |
| Fixed task and observable result | Did the task meet its declared acceptance conditions? |
| Request metadata, when available | What additional provider-request facts can actually be established? |
Record unavailable request metadata as unavailable, not as an empty field that a reviewer might interpret as passing. Configuration-level confidence can still be useful, but it must remain distinguishable from provider-request verification. If your lane’s approval standard requires the latter, missing evidence means the lane stays held.
Assign each case one outcome: accepted, held for explanation or restored. Include the reviewer, date and evidence references. An accepted case should identify the exact configuration retained for that lane. Avoid a fleet-wide green badge based on a single personal session whose project files and agent definitions differ from everyone else’s.
Resolve one conflict at a time and preserve rollback
When the comparison diverges, resist changing the global model options, project variant and agent configuration together. Multiple simultaneous edits can produce a working result while destroying the explanation. The objective is a lane whose configuration can be understood and reproduced, rather than an unexplained combination that happened to answer one task correctly.
- Hold promotion for the affected lane and preserve the failing observation.
- Confirm the exact model and agent before inspecting reasoning options.
- Identify the smallest relevant conflicting setting and its owning layer.
- Propose one change within that owner’s authority, leaving permissions fixed.
- Repeat the same case and document whether the mismatch changed.
- Restore the previous working configuration when the result remains unexplained.
Restoring configuration is only part of rollback. The packet should identify the prior runtime and the process your team uses to restore it, without assuming a particular installation method. Preserve the pairing between runtime version and configuration. A previous file restored under a different binary is another combination to inspect, not automatically the known-good baseline.
If managed settings cause the conflict, send the evidence to the administrator rather than attempting to defeat the managed layer. If a project override is responsible, keep the correction scoped to that project unless the inventory demonstrates a broader problem. These decisions keep the diagnostic change aligned with the source that actually owns it.
Do not infer billing from variant labels during this exercise. Once configuration is explained and accepted, the separate effort economics guide can inform a measured workload comparison. That is a later decision with its own denominator, rather than a justification for accepting an unexplained override.
Promote the configuration that the packet describes
Promotion should name a reproducible lane configuration, not merely “OpenCode 1.19.3 passed.” Review the source inventory, available choices, selected agent, fixed task and limitations together. A successful primary-agent case does not automatically cover a subagent with its own model, and one repository’s result does not establish another repository’s merged configuration.
Use a short release checklist before widening the lane:
- The expected provider/model and variant are recorded explicitly.
- Every applicable configuration source is accounted for.
- Preserved overrides and overlapping agent options have an explanation.
- The fixed task meets its declared result criteria.
- Permission settings and approval mode remain unchanged.
- Unavailable evidence is visible, and the acceptance standard permits that limitation.
- The previous runtime/configuration pairing and restore owner are recorded.
Apply the same packet when the relevant model definition, agent file or configuration layer changes later. That makes this a durable fleet practice: selections become reviewable configuration decisions. The operating layer described in AgentOps needs that level of specificity because a fleet contains many legitimate lanes, each with different context. Preserve the differences that are intentional and investigate the ones nobody can explain.
