Repository navigation
v2.27.0
What's new
Two hardening-and-learning changes: one closes a latent converter dependency before it becomes a breaking change in v3.0.0; the other turns a failed detection attempt into a permanent correctness rule.
Features
mode: subagent is now declared explicitly on all 51 bundled agents. Previously, 36 agents relied on the OpenCode runtime converter to fill in mode: subagent as a default at load time — an invisible dependency that would silently break when the converter is removed in v3.0.0. Without an explicit mode, those agents would fall back to OpenCode's native default (all) and appear as primary agents in the agent picker rather than staying hidden as background workers.
This is a zero-runtime-behavior-change hardening. The converter already resolves these agents to subagent, so making the field explicit changes nothing today while severing the converter dependency for the future. To lock in the invariant, a new checkAgentMode gate in scripts/content-integrity.ts fails CI if any bundled agent is missing an explicit mode: subagent, sets a non-subagent value, or has non-object frontmatter. A converter-equivalence test mechanically proves the change is behavior-preserving by resolving agent config both with and without an explicit mode and asserting the outputs are identical.
The PR also records a tracked audit of every other field the converter injects — notably temperature, which is computed per-agent via a name/description heuristic and represents an equally high-risk dependency for v3.0.0. Resolving the temperature dependency is out of scope for this patch; the audit exists so it is not forgotten.
Documentation
A new solution doc under docs/solutions/ captures the undecidability lesson from the content-integrity verification work: some YAML frontmatter problems cannot be detected by parse-diff analysis alone.
The concrete case: a truncating comment (problem: cache miss # under load, where the author intended the full string including # under load) and a legitimate inline comment (date: 2026-01-01 # created) are byte-identical to the YAML parser — both parse to the text before the #. No amount of parse-diff analysis can distinguish "lost content" from "intentional comment." Rather than ship a heuristic that would silently misclassify edge cases, the ban rule approach was taken: unquoted inline comments in solution-doc frontmatter are banned outright. This collapsed the detector to a simple lexical rule and removed approximately 50 lines of parse-diff guessing that could never have been correct.
The doc records the undecidability, the reasoning for the ban, and the general principle: when a detection problem is provably undecidable at the data level, a clear bright-line rule beats a heuristic that quietly gets edge cases wrong.