Repository navigation
Custom mode: "subagent" agents not invocable via @name or task tool #29616
Description
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:
- @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.
- 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
- 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..."
}
}
} - Restart opencode to load the config.
- In a conversation, type @gap-scout find me leads in High-End Residential Painting.
- Observe that the message lands on the primary agent instead of spawning a gap-scout subagent session.
- 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
Metadata
Metadata
Assignees
Labels
No labels
Activity
github-actions commentedon May 27, 2026
This issue might be related to existing issues. Please check:
opencode.jsonare incorrectly treated as primary agents (ignoringmode: subagentfrom agent files) #22130: Custom agents inopencode.jsonwithmode: subagentfrom.mdfiles being treated as primary agents — related tomode: subagentconfig not being respected correctlysubagent_typelist (only built-in agents listed correctly) — closely related to the second problem you describeThese issues share the same root area (custom agent config not being fully wired into the task/subagent system) but may be distinct bugs.
LanceHaverkamp commentedon May 27, 2026
The seems to have fixed itself. Or more likely, OpenCode needed to be restarted, rather than just /new (new conversation).
ls-michielrensen commentedon Jun 30, 2026
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_typeonly accepts built-in types so there's no automatic routing. The@mentionworkaround requires manual intervention every time, which defeats the purpose. The model config on custom agents works fine, they load correctly. The missing piece issubagent_typeaccepting custom agent names.AlexRMU commentedon Jul 5, 2026
In my case, one model actually invokes the sub-agent, while the other doesn't
paolothomas72 commentedon Aug 23, 2026
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-planwithmode: all, modelanthropic/claude-sonnet-5) load foropencode --agent/ CLI Task-dispatch in some cases, but Desktop does not spawn them via the task tool.Reproduction (Desktop GUI, not TUI):
Parent model = local Ollama
gemma4:12b. Prompt: use the solipse-plan subagent to …Result:
taskcalled withsubagent_type: "general"and prompt "Act as a solipse-plan subagent…". Context panel Total Cost $0.00, provider stayed Ollama. Sessionses_fd48d777fffe0IEzN6UsZCP5Gw.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-5count = 0.subagent_typeremainedgeneral.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-builderto keyword-triggeredSKILL.mdunder~/.config/opencode/skills/(as this issue already suggested).Happy to attach the session export (tool parts only) if useful.
docs: correct the OpenCode subagent claim — I got it backwards (gh-493)
docs: journal that OpenCode custom subagents work (gh-493)
thdxr commentedon Oct 11, 2026
Thanks for the report! OpenCode 2.0 is now out and development is focused on V2, so we're closing issues filed against OpenCode 1. Please upgrade (
opencode upgrade --major, details: https://anoma.ly/notes/opencode-2-0), and if this is still relevant on 2.0, reopen this issue or open a new one with your 2.0 version.— from 𝕺𝖕𝖊𝖓𝕮𝖔𝖉𝖊