Config loading: silent failures, undocumented fields, and path resolution inconsistencies #28733

Summary

Four related issues found while setting up a multi-agent project using OpenCode. All share a common root: undocumented implicit contracts + silent failure when config or agent loading fails.

Bug 1 — Invalid provider.anthropic.options block accepted silently

Behavior: opencode.json accepts a provider.anthropic.models[*].options block that does not exist in the official Anthropic SDK schema. No error or warning is emitted — the config loads silently with the invalid block ignored.

Workaround: Remove the invalid block.

Suggestion: Validate provider config against the SDK schema at startup and emit an error or warning for unrecognized fields.

Bug 2 — source field in AgentConfig is undocumented but processed by runtime

Behavior: The source field is not listed in the public AgentConfig schema, but the runtime processes it. When present in the global config (~/.config/opencode/opencode.json), a relative path like .opencode/agents/zeus.md resolves to ~/.config/opencode/.opencode/agents/zeus.md — which does not exist, because global agents live at ~/.config/opencode/agents/ (without the .opencode/ prefix).

Result: Global agents silently fail to load with no warning, error, or log entry.

Workaround: Remove source from the global config and rely on auto-discovery.

Suggestion (high priority):

• Document the source field in the AgentConfig schema, OR
• Emit a warning when source points to a non-existent file (a single line that would save hours of debugging for users)

Bug 3 — Global vs. project layout distinction is undocumented

Behavior: The runtime expects different directory layouts depending on context:

• Project config: agents in .opencode/agents/
• Global config: agents in ~/.config/opencode/agents/ (no .opencode/ prefix)

Relative paths in source resolve differently in each context, with no documentation or error to explain this.

Suggestion:

• Document both layouts explicitly in the configuration reference
• Consider normalizing paths automatically, or at minimum warn when a resolved path does not exist

Bug 4 — default_agent behavior with subagent routing is undocumented (unconfirmed)

Behavior (observed, not fully confirmed): With default_agent: "zeus" set in the global config, tasks of type general may be routed to zeus instead of creating a generic agent via the task tool.

Suggestion:

• Document whether default_agent affects only the interactive session or also subagent routing via the task tool
• If it affects subagent routing, consider a separate config key (e.g., default_interactive_agent) to avoid unintended side effects

Environment

• OpenCode version: latest
• Platform: Linux
• Config: global (~/.config/opencode/opencode.json) + project (.opencode/opencode.json)
• Provider: Anthropic

Root Cause (across all 4 bugs)

Silent failure without logging. When agent loading or config parsing fails, the system enters a degraded state with no user-facing feedback. A structured warning on any agent load failure (with path, context, and reason) would dramatically reduce debugging time for all users.