Verdict: OpenCode subagents are now worth using for any multi-step job, because v2.3.0 made them run in the background by default, so they no longer block your main session.
Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →
This page weighs the built-in subagents against custom ones, Markdown against JSONC, and shows where each choice pays off.
If you want agent workflows like these applied to SEO, get your Backlink Gameplan, or try Polar Rank free for 3 days.
Every fact here comes from OpenCode's agents documentation and its release notes.
Decision table: built-in or custom?
| If you need… | Use | Why |
|---|---|---|
| Fast code or web search with no edits | explore | Read-only by design |
| Open-ended research or multi-step work | general | Broad tool access, but cannot launch subagents |
| A repeatable review with fixed rules | Custom subagent | Own system prompt and permissions |
| A cheaper model for simple checks | Custom subagent with model | Per-agent model choice |
| An orchestrator that only calls approved helpers | Custom primary with subagent rules | Parent permissions control launches |
Verdict on the v2.3.0 change
The v2.3.0 notes say subagents now return immediately, continue in the background, and report back whenever they become idle, with the change made in PR 63382.
Verdict: a clear win, because you can run several helpers at once and keep working.
One caution: a subagent that goes idle while its own background work continues now says it is still running, so wait for the final report before acting on partial output.
Verdict on the v2.3.1 change
v2.3.1 moves timed-out shell commands to the background instead of killing them, and makes a foreground timeout: 0 mean 120 seconds.
Verdict: good for long builds and test runs; just remember a "timed out" command may still be working.
Background compaction is also on by default now; switch it off with compaction.background: false if you would rather not spend tokens on unused summaries.
Decision table: Markdown or JSONC?
| Choose | When | Location |
|---|---|---|
| Markdown | One agent per file, long prompts, easy sharing | .opencode/agents/<name>.md |
| JSONC | Many short agents, central config, overrides of built-ins | agents in opencode.jsonc |
Verdict: Markdown for most custom subagents, JSONC for overriding built-ins and setting orchestrator rules.
📞 Want a verdict on how agents could run your SEO? Get your Backlink Gameplan and we will show you the subagent setups Goldie Agency uses for audits, or try Polar Rank free for 3 days. Backlink Gameplan or try Polar Rank free for 3 days
Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →
Example: a verdict-ready reviewer
---
description: Reviews changes and returns a ship / fix / block verdict
mode: subagent
steps: 10
permissions:
- action: edit
resource: "*"
effect: deny
---
Review the current changes. End with one line:
VERDICT: SHIP, FIX or BLOCK, followed by the single most
important reason.
Then ask: "Use the reviewer subagent on my current changes."
Verdict on permissions
OpenCode's permissions guide uses ordered rules with action, resource and effect, and the last matching rule wins.
Verdict: always deny broadly, then allow narrowly, and give each subagent only what its job needs.
{
"agents": {
"lead": {
"permissions": [
{ "action": "subagent", "resource": "*", "effect": "deny" },
{ "action": "subagent", "resource": "reviewer", "effect": "allow" }
]
}
}
}
🔥 Want tested agent setups you can copy? Inside the AI Profit Boardroom you get step-by-step video trainings, the installable Agent OS, four coaching calls a week and 3,400+ members. Members get agent workflows with permissions already set sensibly. → Join the AI Profit Boardroom
Verdict on model choice per subagent
Set model as provider/model#variant per agent; with none set, the subagent inherits the parent's model.
Verdict: inherit by default, then move simple, high-volume helpers to a faster model once you trust their output.
What to avoid
- Legacy V1 fields like
toolsandmaxSteps; see the migration guide. - Treating
hiddenas a security setting; it only affects visibility. - Expecting the General subagent to launch more helpers; it cannot.
- Looking for a built-in scout agent; V2 does not have one.
Overall verdict
For anyone already using OpenCode, v2.3 makes subagents the default way to split up work.
Start with Explore for read-only searches, add one custom reviewer, and expand from there; the tools docs list what each agent can call.
For agent workflows built around business tasks, see the AI Profit Boardroom.
Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →
FAQ: OpenCode Subagents Verdict
Do OpenCode subagents run in the background?
Yes. Since v2.3.0 they always run in the background, return their session ID immediately and report to the parent when they go idle.
Which subagents come built in?
General, for research and multi-step work (it cannot launch more subagents), and Explore, which searches and reads without editing files.
Should I write subagents in Markdown or JSONC?
Markdown suits most custom subagents; JSONC suits overriding built-ins and central permission rules.
Is v2.3.0 a breaking change?
Subagents now always run in the background, so any workflow that expected the parent to wait should wait for the final report.
Does hidden: true make a subagent safe?
No. It only hides the agent from listings; use permission rules to restrict behaviour.
📺 Video notes + links to the tools 👉
🎥 Learn how I make these videos 👉
🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉
About Julian
I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.
I help business owners scale with AI agents, automation and SEO.
- I've built a 7-figure SEO and link building agency, Goldie Agency, with a team of 70+ SEO experts.
- I've grown a YouTube channel to 400,000+ subscribers.
- I wrote "Link Building Mastery".
- My Udemy courses have taught over 29,000 students.
→ Get my best AI training inside the AI Profit Boardroom
Final verdict: OpenCode subagents are ready for daily use, so set up one narrow helper today; to see agents applied to SEO, get your Backlink Gameplan, or try Polar Rank free for 3 days.











