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…UseWhy
Fast code or web search with no editsexploreRead-only by design
Open-ended research or multi-step workgeneralBroad tool access, but cannot launch subagents
A repeatable review with fixed rulesCustom subagentOwn system prompt and permissions
A cheaper model for simple checksCustom subagent with modelPer-agent model choice
An orchestrator that only calls approved helpersCustom primary with subagent rulesParent 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?

ChooseWhenLocation
MarkdownOne agent per file, long prompts, easy sharing.opencode/agents/<name>.md
JSONCMany short agents, central config, overrides of built-insagents 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 tools and maxSteps; see the migration guide.
  • Treating hidden as 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.