Repository navigation
agent: unquoted colon in description silently resolves mode as primary #53909
Description
Summary
An agent file whose frontmatter description contains an unquoted : is parsed correctly by GET /api/agent (mode reports subagent) but resolves as mode: primary on the subagent tool's path, so launching it fails with Agent X cannot run as a subagent. Quoting the description fixes it — two code paths parse the same file differently and disagree silently.
Environment
- opencode version: v2.0.24
- OS: Linux 7.0.0-38-generic (linux x86_64)
- Terminal: ghostty (TERM=xterm-256color, TERM_PROGRAM=ghostty, COLORTERM=truecolor)
- Shell: /bin/bash
- Install/channel: latest release
- Active plugins: custom-tools (repo-local
.opencode/plugins/custom-tools.ts)
Reproduction
-
Create
~/.config/opencode/agents/zz-probe.md:--- description: Probe agent: shell deny only — diagnostic mode: subagent --- Reply with exactly: PROBE-OK
-
GET /api/agentshows the record with"mode": "subagent"and the full description — the frontmatter parsed fine. -
Launch it as a subagent → error:
Agent zz-probe cannot run as a subagent. -
Quote the description (
description: "Probe agent - shell deny only"), restart the service, repeat step 3 → the agent launches and replies.
Expected Behavior
Either the same parse everywhere (mode subagent in both the API listing and the subagent resolve path), or a clear frontmatter parse error — not a silent mode fallback.
Actual Behavior
GET /api/agent:"mode": "subagent"(parses the colon-containing plain scalar fine)- Subagent resolve path: sees
mode: primary→Agent zz-probe cannot run as a subagent
The two still disagree after a full service restart, and the error message points at the resulting mode rather than at whatever failed to parse.
Additional Context
- The subagent tool errors when
agent.mode === "primary"(packages/core/src/tool/plugin/subagent.ts), so the resolve path appears to read a differently-parsed agent map than the HTTP listing. - A YAML plain scalar containing
:after the key is the trigger; quoting the value removes it. - Misleading-error aspect: the file visibly says
mode: subagentand the API agrees, so "cannot run as a subagent" sends you looking at launch permissions instead of frontmatter parsing. - Workaround: quote any
descriptionvalue containing:.
Activity
opencode-agent commentedon Oct 8, 2026
Thanks for the detailed report and the minimal agent file. I could reproduce this on 2.0.24.
The cause is a cache in the frontmatter parser. With an unquoted
:indescription, the first parse fails. OpenCode then quotes the value automatically and parses again, so the first load is correct. But the failed attempt leaves an empty result in a process-wide cache. The next time the server re-reads the same file content (any config reload), it gets that empty result with no error. The agent then falls back to the defaultmode: primaryand loses its description. After that, launching it fails withAgent zz-probe cannot run as a subagent. This looks like the same cache problem as #42350 and #51218 (there for skills).What I ran: your
zz-probe.mdin the config dir. Before a reload, the agent list showssubagent. After a reload, it showsprimaryand the subagent launch fails. In my run the API listing also showedprimaryafter the reload; your listing probably came from a load that happened before it.With the same steps on the latest
v2branch (2f1a0e7), the agent stayssubagentafter reloads and launches fine. The fix is #51245, so it should be in the next release. Until then, quotingdescriptionvalues that contain:(as you found) avoids it.The bot will close this issue in 1 day unless you reply that it still happens, e.g. on a newer version.
opencode-agent commentedon Oct 9, 2026
Closing this as completed. I reproduced it on 2.0.24: after a config reload,
zz-probe.mdwith an unquoted:indescriptioncame back asmode: primary, and launching it failed withAgent zz-probe cannot run as a subagent. The same steps on the latestv2branch (2f1a0e7) keep it assubagent, and it launches fine. That's thanks to #51245, which stops the frontmatter parser from returning a stale empty result from its cache. The fix should be in the next release. Until then, quotingdescriptionvalues that contain:avoids the problem.I kept the issue open for a day in case you saw it on another version. If it still happens on a release newer than 2.0.24, please comment here or open a new issue with the version and steps. Thanks again for the clear report!