Custom mode: "subagent" agents not invocable via @name or task tool

[LanceHaverkamp]

Description

Custom mode: "subagent" agents in opencode.jsonc are not invocable — @name routing doesn't fire, and the task tool's subagent_type only exposes built-in agents (explore, general).

Not a known duplicate — closest is #22130 (opposite problem).

Defining a custom agent with mode: "subagent" in opencode.jsonc does not make it invocable. Two problems:

1. @name routing doesn't fire — typing @gap-scout find me leads (the project I was working on) sends the message to the primary agent instead of spawning the subagent.
2. task tool's subagent_type enum is hardcoded — only explore and general appear as available subagent types. Custom agents are not listed, so the primary agent cannot spawn them via the task tool either.
   Config used:
   {
   "$schema": "https://opencode.ai/config.json",
   "agent": {
   "gap-scout": {
   "description": "Market Research Scout finding 'Diamonds in the Rough'...",
   "mode": "subagent",
   "temperature": 0.3,
   "permission": {
   "edit": "deny",
   "bash": "deny",
   "websearch": "allow",
   "webfetch": "allow",
   "question": "allow"
   },
   "prompt": "SYSTEM INSTRUCTION: The Reputation-Visibility Gap Scout\n\n..."
   }
   }
   }
   Expected behavior: Custom subagent-mode agents should either (a) be spawnable via @name in-chat routing, or (b) appear as options in the task tool's subagent_type parameter (or both).
   Actual behavior: Neither works. The @name mention passes through as plain text, and task only offers explore and general.
   Workaround: The agent can be converted to a skill (SKILL.md), which gets injected into context when keywords match. This bypasses the routing gap entirely.

Big huge disclaimer: I'm not a coder/dev, this ticket was written by opencode & DeepSeeek 4 Flash.

Plugins

No added plugins

OpenCode version

1.15.11

Steps to reproduce

1. Add a custom subagent to ~/.config/opencode/opencode.jsonc:
   {
   "agent": {
   "gap-scout": {
   "description": "Market research scout for Colorado Springs",
   "mode": "subagent",
   "temperature": 0.3,
   "permission": {
   "edit": "deny",
   "bash": "deny",
   "websearch": "allow",
   "webfetch": "allow",
   "question": "allow"
   },
   "prompt": "You are a market research scout..."
   }
   }
   }
2. Restart opencode to load the config.
3. In a conversation, type @gap-scout find me leads in High-End Residential Painting.
4. Observe that the message lands on the primary agent instead of spawning a gap-scout subagent session.
5. Alternatively, as the primary agent, try to invoke the subagent via the task tool by passing subagent_type: "gap-scout" — observe that the tool's enum only lists explore and general.
   Expected: @gap-scout routes to the subagent, or task tool accepts "gap-scout" as a valid subagent_type.
   Actual: @gap-scout passes through as plain text. The task tool only offers explore and general as available subagent types.

Screenshot and/or share link

No response

Operating System

Debian 13

Terminal

Konsole

[github-actions]

This issue might be related to existing issues. Please check:

• [Bug]: Subagents listed in opencode.json are incorrectly treated as primary agents (ignoring mode: subagent from agent files) #22130: Custom agents in opencode.json with mode: subagent from .md files being treated as primary agents — related to mode: subagent config not being respected correctly
• Custom markdown-defined subagents show "should only be called manually" in Task tool despite having description in frontmatter #27831: Custom markdown-defined subagents not appearing with their description in the Task tool's subagent_type list (only built-in agents listed correctly) — closely related to the second problem you describe

These issues share the same root area (custom agent config not being fully wired into the task/subagent system) but may be distinct bugs.

[LanceHaverkamp]

The seems to have fixed itself. Or more likely, OpenCode needed to be restarted, rather than just /new (new conversation).