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).

[ls-michielrensen]

Running into this too. The specific use case: I have a local Ollama model (qwen3.5:9b) that handles lightweight tasks fine. The idea was custom subagents pinned to that model so the primary agent automatically delegates cheap work locally, saving cloud tokens. Doesn't work — subagent_type only accepts built-in types so there's no automatic routing. The @mention workaround requires manual intervention every time, which defeats the purpose. The model config on custom agents works fine, they load correctly. The missing piece is subagent_type accepting custom agent names.

[AlexRMU]

In my case, one model actually invokes the sub-agent, while the other doesn't

[paolothomas72]

Confirming this is still present on OpenCode Desktop 1.18.21 (Windows), 2026-08-22.

Custom agents defined as markdown under ~/.config/opencode/agents/ (solipse-plan with mode: all, model anthropic/claude-sonnet-5) load for opencode --agent / CLI Task-dispatch in some cases, but Desktop does not spawn them via the task tool.

Reproduction (Desktop GUI, not TUI):

1. Parent model = local Ollama gemma4:12b. Prompt: use the solipse-plan subagent to …
   Result: task called with subagent_type: "general" and prompt "Act as a solipse-plan subagent…". Context panel Total Cost $0.00, provider stayed Ollama. Session ses_fd48d777fffe0IEzN6UsZCP5Gw.

2. Same session, model dropdown switched to Claude Haiku 4.5, same prompt resent.
   Result: parent explicitly said it would use the general subagent. Task label: General solipse-plan: AGENTS.md scope vs Hermes memory separation. Context panel: Provider Anthropic, Model Claude Haiku 4.5, Total Cost $0.03. Session export: claude-sonnet-5 count = 0. subagent_type remained general.

So a Claude-tier parent is not sufficient. The task-tool enum still does not include the custom agent; the model roleplays into built-in general.

Workaround we are applying: convert solipse-plan / solipse-builder to keyword-triggered SKILL.md under ~/.config/opencode/skills/ (as this issue already suggested).

Happy to attach the session export (tool parts only) if useful.