feat(agent): add subagents config for per-agent task tool filtering

[marcusquinn]

Summary

Adds a new subagents configuration option that allows primary agents to specify which subagents appear in their Task tool description. This reduces token overhead when many subagents are configured but only a subset is relevant to a particular agent.

Closes #7269

Problem

The Task tool description includes all configured subagents, adding ~6-10k tokens to the system prompt regardless of whether the agent will use them. With 150+ subagents, this significantly impacts:

• Token costs (especially with reasoning models)
• Effective context window for actual work

Solution

Add a subagents field to agent config that filters which subagents appear in the Task tool description:

{
  "agent": {
    "build": {
      "subagents": ["explore", "general", "code-*"]
    }
  }
}

• Supports glob patterns (e.g., code-*, *-reviewer)
• If not set, all subagents are available (backward compatible)
• Works alongside existing permission.task (which controls runtime access)

Changes

• packages/opencode/src/config/config.ts - Add subagents field to Agent schema
• packages/opencode/src/agent/agent.ts - Add subagents to Agent.Info and state
• packages/opencode/src/tool/task.ts - Filter agents based on caller's subagents config
• packages/opencode/test/tool/task-subagents.test.ts - Tests for filtering logic
• packages/web/src/content/docs/agents.mdx - Documentation

Testing

cd packages/opencode && bun test test/tool/task-subagents.test.ts

All 9 tests pass.

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

Summary:

One potentially related PR found:

• Add context control for subagents #4119 - Add context control for subagents (Add context control for subagents #4119)

This addresses similar concerns around managing which subagents are included in context. Review it to ensure there's no duplicate effort or conflicting approaches.

[marcusquinn]

Thanks for flagging #4119! After reviewing, these PRs address different problems:

PR	Problem	Solution
#4119	Parent session context passed to subagents is too large	Filter what context is passed TO subagents at runtime
#7271 (this PR)	Task tool description lists all subagents, bloating system prompt	Filter which subagents APPEAR in the task tool description

#4119 optimizes the context sent to subagents when they're invoked.
#7271 optimizes the task tool's description in the system prompt (before any subagent is invoked).

They're complementary - both reduce token usage but at different points:

• This PR reduces tokens in the system prompt (affects every message)
• Add context control for subagents #4119 reduces tokens in subagent invocations (affects runtime)

With 150 subagents, the task tool description alone adds ~6-10k tokens to every conversation's system prompt. This PR allows agents to specify which subagents they need, reducing that overhead.