Ability to restrict Subagents use to Specific Primary Agents only

[malhashemi]

Rational

One of OpenCode most powerful features is the ability to disable MCPs globally and turn them on for specific agents only.
Similarly the ability to turn off all subagents by default and only enable them on the agent level would allow for greater performance by restricting non necessary context and reducing the choices the primary agent would have to make.

In most cases subagents are only useful for specific primary agent, would make much sense to allow for such use case.

[rekram1-node]

Definitely makes sense @malhashemi!

We have been planning to merge our concepts of tools + permissions and we should support this as part of that change

[malhashemi]

I was quickly imagining how it should work, let me know what you think here imagine the below getting added to agents.mdx as the end result of that PR. I quickly vibe coded those requirements but honestly drowning at the moment to do deep testing let me know if you suggest that I make a PR with these requirements so you can review. Or I just drop my changes.

---

Subagents access

You can globally disable all subagents and selectively enable them per primary agent. This reduces token usage and decision overhead when most subagents are irrelevant for a workflow.

Global control uses the top-level subagents map. Per-agent overrides use agent.<name>.subagents.

If you do nothing, current behavior is unchanged: all subagents are available.

{
  "$schema": "https://opencode.ai/config.json",
  "subagents": { "*": false }
}

Enable one subagent back for a specific primary agent:

{
  "$schema": "https://opencode.ai/config.json",
  "subagents": { "*": false },
  "agent": {
    "build": {
      "subagents": { "general": true }
    }
  }
}

Use wildcards to enable a group:

{
  "$schema": "https://opencode.ai/config.json",
  "subagents": { "*": false },
  "agent": {
    "plan": { "subagents": { "doc-*": true } },
    "build": { "subagents": { "doc-*": true, "git-committer": true } }
  }
}

Enable everything except one:

{
  "$schema": "https://opencode.ai/config.json",
  "subagents": { "*": false },
  "agent": {
    "build": { "subagents": { "*": true, "git-committer": false } }
  }
}

Refine globally enabled patterns per agent:

{
  "$schema": "https://opencode.ai/config.json",
  "subagents": { "*": false, "general": true, "git-*": true },
  "agent": {
    "plan": { "subagents": { "git-*": false } }
  }
}

Resolution rules:

• Start allow = true unless "*": false is present globally (default deny mode)
• Most specific matching pattern wins (longer literal prefix first; later definition on tie)
• Per-agent overrides always applied after global

If a subagent is disabled:

• It won't appear in the Task tool list
• @mention attempts return a short advisory message

[rekram1-node]

This will be addressed as part of: #1961

Should be addressed as part of the move to opentui since dax is working on this