Feature Request: Custom Subagent Support in Task Tool

Feature Request: Custom Subagent Support in Task Tool

Status: Open | Priority: High | Created: 2026-01-19 Component: Claude Code Task Tool | Target: Next Release

---

Summary

Enable the Task() tool to discover and use custom subagents from:

1. ~/.claude/subagents.json (JSON-formatted subagents)
2. Installed plugins' agents/ directories
3. ~/.claude/agents/*.md (Markdown agents)

---

Current Problem

Task Tool Agent Discovery is Hardcoded

The Task() tool currently only recognizes 3 built-in subagents:

| Subagent | Model | Tools | Purpose |
|----------|-------|-------|---------|
| general-purpose | Sonnet | All | Complex research & multi-step operations |
| plan | Sonnet | Read, Glob, Grep, Bash | Plan mode research and analysis |
| explore | Haiku | Glob, Grep, Read, Bash (read-only) | Fast codebase searching |

Problem: Any attempt to use Task("custom-agent", ...) fails with:

Agent type 'custom-agent' not found.
Available agents: Bash, general-purpose, plan, explore, ...

What Doesn't Work

The Task Tool does NOT scan or load custom agents from:

| Location | Format | Status |
|----------|--------|--------|
| ~/.claude/agents/*.md | YAML frontmatter + Markdown | Ignored |
| ~/.claude/subagents.json | JSON with subagents array | Ignored |
| ~/.claude/plugins/*/agents/*.md | Plugin agents | Ignored |

Impact

This limitation prevents:

• Domain-specific agents: GSD Pipeline, Security Auditors, Performance Analyzers
• Workflow automation: Autonomous spec execution, code review pipelines
• Team collaboration: Sharing custom agents via plugins
• Agent delegation patterns: The Core Agent Triad, Pre-Deployment Gate, etc.

---

Proposed Solution

Option A: Auto-Discovery (Recommended)

The Task Tool should automatically discover custom agents from multiple sources:

# Pseudo-code for agent discovery
def discover_subagents():
    agents = {}

    # 1. Built-in agents (always available)
    agents.update(load_builtin_agents())

    # 2. JSON subagents
    if os.path.exists("~/.claude/subagents.json"):
        agents.update(load_json_subagents("~/.claude/subagents.json"))

    # 3. Markdown agents
    for md_file in glob("~/.claude/agents/*.md"):
        agents.update(load_markdown_agent(md_file))

    # 4. Plugin agents
    for plugin in get_installed_plugins():
        for agent_file in glob(f"{plugin}/agents/*.md"):
            agents.update(load_markdown_agent(agent_file))

    return agents

Priority Order: Built-in → JSON → Markdown → Plugins (later sources override earlier)

Option B: Explicit Registration

Add a subagents field to settings.json:

{
  "subagents": [
    {
      "id": "gsd-executor",
      "source": "~/.claude/agents/gsd-executor.md"
    },
    {
      "id": "security-scanner",
      "source": "plugin:security-tools"
    }
  ]
}

Option C: Plugin Namespace Prefix

Allow invoking plugin agents with namespace prefix:

Task("plugin-name:agent-id", "Execute this task")
// Example: Task("gsd-pipeline:gsd-executor", "Execute plan 01-03")

Recommended: Implement Option A (auto-discovery) with Option C (namespace) as fallback.

---

Use Cases

Use Case 1: GSD Pipeline Automation

Current Workaround:

// Doesn't work - agent not found
Task("gsd-executor", "Execute plan 01-03")

// Workaround: Use general-purpose with embedded prompt
Task("general-purpose", cat("~/.claude/agents/gsd-executor.md"))

With Custom Agent Support:

Task("gsd-executor", "Execute plan 01-03")

Use Case 2: Code Review Pipeline

Current: Manual spawning of multiple agents
Proposed: Single Task() call to code-review-agent

Use Case 3: Team-Shared Agents

Scenario: Team creates a plugin with company-specific agents

Current: Can't use via Task Tool
Proposed: Install plugin + invoke via Task()

---

Implementation Details

File Format Standards

JSON Subagents (~/.claude/subagents.json)

{
  "subagents": [
    {
      "id": "my-agent",
      "name": "Display Name",
      "description": "When to use this agent",
      "model": "sonnet",
      "tools": ["Read", "Write", "Edit"],
      "instructions": "System prompt here..."
    }
  ]
}

Markdown Agents (agents/*.md)

---
name: my-agent
model: sonnet
description: "When to use this agent"
tools: Read, Write, Edit
---

System prompt here...

Agent Resolution Algorithm

1. Check built-in: Is agent in hardcoded list?
2. Check JSON: Look in ~/.claude/subagents.json
3. Check Markdown: Look in ~/.claude/agents/*.md
4. Check Plugins: Look in installed plugins' agents/ directories
5. Error: "Agent type 'X' not found. Available: [list]"

Backwards Compatibility

• Built-in agents remain unchanged
• Existing Task("general-purpose") calls continue to work
• No breaking changes to existing code

---

Benefits

1. Domain-Specific Automation: Specialized agents for specific workflows
2. Team Collaboration: Share agents via plugins/JSON
3. Extensibility: Community can build custom agent ecosystems
4. Consistency: Use Task() for all agent delegation
5. Future-Proof: Plugin system ready for agent marketplace

---

Alternatives Considered

Alternative 1: Use Skill Tool Instead

Idea: Wrap agents as Skills
Rejected: Skills are for instructions, not agent spawning

Alternative 2: Always Use General-Purpose

Idea: Pass agent content as prompt to general-purpose
Rejected: Inefficient, loses type safety, no tool isolation

Alternative 3: Direct Bash Spawning

Idea: Spawn new Claude processes via Bash
Rejected: Loses context, no agent tracking, resource-intensive

---

Related Documentation

• ~/.claude/docs/claude-code/sub-agents.md - Subagent documentation
• ~/.claude/docs/claude-code/plugins.md - Plugin system
• ~/.claude/agents/README.md - Agent inventory

---

Example Implementation

Testing Custom Agent Discovery

# After implementation, this should work:

# 1. Create test agent
cat > ~/.claude/agents/test-agent.md << 'EOF'
---
name: test-agent
model: haiku
description: "Test agent for Task Tool"
tools: Read, Bash
---
You are a test agent. Echo back what you receive.
EOF

# 2. Test via Task Tool
# In Claude Code session:
Task("test-agent", "Hello from Task Tool")
# Expected: "Hello from Task Tool" echoed back

---

Discussion

Open Questions:

1. Should there be a Task() permission rule for custom agents?
2. How to handle agent name conflicts (built-in vs custom)?
3. Should there be agent versioning?

Vote: Thumbs up if you need custom subagent support!

---

Tags: task-tool, subagents, plugins, feature-request, agent-delegation