Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Problem

The task tool definition includes the full list of all configured subagents with their descriptions, injected into every conversation's system prompt. With many subagents configured, this adds significant token overhead before the user even sends their first message.

Example: With 150 subagents configured in ~/.config/opencode/agent/, the task tool description alone adds ~6,000-10,000 tokens to every conversation, regardless of whether the agent will actually use subagents.

Current Behavior

The task tool description contains entries like:

Available agent types and the tools they have access to:
- general: General-purpose agent...
- explore: Fast agent specialized for exploring codebases...
- dev-browser: Read ~/.aidevops/agents/tools/browser/dev-browser.md
- authentication: Read ~/.aidevops/agents/tools/git/authentication.md
... (150+ entries)

This is injected for every agent that has task: true in their tools config.

Impact

• ~6,000-10,000 tokens added to system prompt per conversation
• Affects cost (especially with reasoning models - relates to Dramatic increase in token consumption #924, High Token Consumption Observed with Opus 4.5 in OpenCode #6728)
• Reduces effective context window for actual work
• No way to scope which subagents are available per primary agent
• Agents that rarely spawn subagents still pay the full token cost

Measured Example

Comparing two agents with identical instructions but different tool access:

The ~11k difference is primarily the task tool's subagent list.

Proposed Solutions

Option A: Per-agent subagent filtering (preferred)

Allow primary agents to specify which subagents they can spawn:

{
  "agent": {
    "Build+": {
      "tools": {
        "task": ["explore", "dev-browser", "code-review"]
      }
    }
  }
}

Only listed subagents would appear in that agent's task tool definition. This also improves focus - the LLM only sees relevant options.

Option B: Lazy loading / on-demand lookup

Instead of injecting all descriptions upfront, provide a minimal task tool that can look up subagent details on demand:

task tool: "Launch subagents. Use `task list` to see available agents, or `task run <name> <prompt>` to launch."

The LLM would call task list only when it needs to spawn a subagent, paying the token cost only when needed.

Option C: Compact mode flag

Add a config option to use minimal descriptions:

{
  "task_tool_mode": "compact"
}

Compact mode would list only agent names without descriptions, or use a much shorter format.

Option D: Hierarchical/categorized listing

Group subagents by category with collapsed descriptions:

Available agent categories: browser (5), git (4), code-review (6), seo (7)...
Use task(category="browser") to see browser agents, or task(agent="explore") directly.

Related Issues

• Dramatic increase in token consumption #924 - Dramatic increase in token consumption
• High Token Consumption Observed with Opus 4.5 in OpenCode #6728 - High Token Consumption Observed with Opus 4.5
• [FEATURE]: Dynamic model selection for subagents via Task tool #6651 - Dynamic model selection for subagents via Task tool (related architecture)
• [FEATURE]: Add visibility flags for merged config and system prompt #4960 - Add visibility flags for merged config and system prompt
• unexpected system prompt parts despite disabling default agent(s) #5005 - Unexpected system prompt parts despite disabling default agents

Environment

• OpenCode version: 1.x
• Subagents configured: 150+
• Framework: aidevops (generates many specialized subagents)