Repository navigation
config: instructions field is parsed but never loaded (v2 regression) #54157
Description
Version: v2.0.24 (tag v2.0.24)
Summary
The instructions config field is still defined in the v2 config schema ("Additional paths or URLs supplying ambient instructions") and survives normalization, but no runtime code consumes it: files listed in instructions are never read nor injected into sessions. In v1 this field worked, so this is a silent regression for migrating users — the config validates cleanly and is then ignored.
Evidence (tag v2.0.24)
-
The schema still documents the field —
packages/schema/src/config.ts:90:instructions: Schema.String.pipe(Schema.Array, optional).annotate({ description: "Additional paths or URLs supplying ambient instructions",
-
Normalization decodes and round-trips it —
packages/core/src/config/normalize.ts:226-227:const instructions = decodeList(input.instructions, Schema.String, ["instructions"], diagnostics, decodeEncoded) if (instructions.length || Array.isArray(input.instructions)) encoded.instructions = instructions
-
But nothing ever reads it. Session instructions are assembled by
InstructionDiscovery(packages/core/src/instruction-discovery.ts), fed byConfigInstructionPlugin(packages/core/src/config/plugin/instruction.ts), which only ever injects:- the global
$CONFIG_DIR/AGENTS.md, and AGENTS.mdfiles found walking up from the project directory.
A repo-wide search for consumers of the config
instructionsarray finds only the normalizer (other.instructionshits are MCP-server instructions and OAuth UI text, both unrelated). - the global
Reproduction
- In the global
opencode.json:"instructions": ["/absolute/path/to/AGENTS.md"](file exists and contains a unique marker). - Start a session → the marker never appears in the system prompt / instruction sources.
- Copy the same file to
$CONFIG_DIR/AGENTS.md→ it is injected (Instructions from: …), confirming the discovery pipeline works and only the config field is unwired.
Expected
Either honor the field (v1 parity), or reject/warn on it during config validation so users don't end up relying on dead config.
Activity
opencode-agent commentedon Oct 9, 2026
Thanks for the detailed write-up! I think this is a duplicate of #51341, which reports the same problem: the config
instructionsarray validates in v2, but nothing ever loads it into sessions.Possible duplicates and related items, most likely first:
instructionsentries in the global config never reach session context, whileAGENTS.mdloads fine. It is still open, and several other users have confirmed it.~/and absolute paths, and HTTP(S) URLs.If you'd like to follow progress, please subscribe to #51341 or #51422. Your suggestion to warn about the field during config validation until it works is a good one to add there.
The bot will close this issue as a duplicate in 1 day unless you reply explaining how your problem is different.
WhiteGiverMa commentedon Oct 9, 2026
Follow-up after filing: I found this behavior is actually documented at https://opencode.ai/v2/docs/config —
So this is intentional/documented rather than an accidental regression, and the "silent regression" framing above is too strong. Apologies for not finding that page first.
The remaining pain point is the silence at load time: the field validates and normalizes cleanly, so a migrating user only discovers the no-op when their instructions never show up (which is how I got here). The migration guide says e.g.
compaction.pruneis "ignored with a warning" — would you consider emitting a similar config-load warning forinstructions? Happy to close this issue if you'd rather track that separately or not at all.opencode-agent commentedon Oct 9, 2026
Thanks for finding that, you're right. The v2 config docs say OpenCode accepts
instructionsbut does not load its entries.You're also right that nothing warns about it when the config loads. Other unsupported v1 fields like
compaction.pruneget a config warning.instructionsis decoded and kept without any warning, so the field is silently ignored, as you found.I'd still keep this together with #51341. There are two possible fixes and maintainers will pick one:
instructionsentries again: paths,~/paths, globs and URLs. If that is merged, the field works and no warning is needed.Could you add your warning suggestion as a comment on #51341, so both options are discussed in one place? Unless there's something here that #51341 doesn't cover, the bot will still close this issue as a duplicate as planned.
opencode-agent commentedon Oct 10, 2026
Closing this as a duplicate of #51341, which tracks the same problem: the config
instructionsfield passes validation in v2 but is never loaded. Thanks again for the clear report and for finding the docs note.To follow progress, subscribe to #51341 or to the open PR #51422, which would load
instructionsentries again. If maintainers choose not to restore the field, your idea of a config-load warning (like the one forcompaction.prune) is worth raising on #51341. If your case turns out to differ from #51341, just reply here and we'll take another look.