Task tool cannot find custom agents (filesystem or programmatic)

Bug Report: Task Tool Cannot Find Custom Agents (Filesystem or Programmatic)

Environment

• Claude CLI Version: 2.0.22 (latest as of Oct 18, 2025)
• Claude Agent SDK: 0.1.4 (Python)
• OS: macOS (Apple Silicon)
• Installation Method: npm (npm install -g @anthropic-ai/claude-code)

Summary

The Task tool only recognizes 4 built-in agents and completely ignores custom agents defined via:

1. Programmatic agents passed via --agents CLI parameter (from SDK)
2. Filesystem agents defined in .claude/agents/*.md

This makes the documented custom agent system completely non-functional.

Expected Behavior

Custom agents should be available to the Task tool, as documented in:

• https://docs.claude.com/en/api/agent-sdk/subagents
• Python SDK documentation for ClaudeAgentOptions(agents=...)

Actual Behavior

Task tool only sees these 4 built-in agents:

• general-purpose
• statusline-setup
• output-style-setup
• Explore

When attempting to use a custom agent:

Agent type 'custom_agent_name' not found. Available agents: general-purpose, statusline-setup, output-style-setup, Explore

Steps to Reproduce

Test 1: Filesystem Agents (NOT working)

1. Create .claude/agents/linear_specialist.md in project directory:

---
description: Expert in Linear project management
tools:
  - mcp__linear__linear_search_issues
  - mcp__linear__linear_get_issues
model: sonnet
---

You are a Linear specialist focused on issue tracking.

1. Run from project directory:

cd /path/to/project
claude "Use Task tool with subagent_type='linear_specialist'"

1. Result: Error - agent not found

1. Verify the agent file exists:

ls -la .claude/agents/linear_specialist.md  # ✓ File exists

1. Check what agents Claude sees:

claude "What agents are available via Task tool?"

Output: Only the 4 built-in agents (linear_specialist NOT included)

Test 2: Programmatic Agents via SDK (NOT working)

1. Create Python script using claude-agent-sdk:

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

options = ClaudeAgentOptions(
    agents={
        "custom_agent": AgentDefinition(
            description="A custom test agent",
            prompt="You are a test agent",
            tools=["Read", "Grep"]
        )
    }
)

async for message in query(
    prompt="Use Task tool with subagent_type='custom_agent'",
    options=options
):
    print(message)

1. SDK correctly passes --agents parameter to CLI (verified in SDK source code at _internal/transport/subprocess_cli.py:171-176)

1. Result: Same error - agent not found

Evidence

1. SDK Correctly Passes Agents

From claude-agent-sdk v0.1.4 source (subprocess_cli.py):

if self._options.agents:
    agents_dict = {
        name: {k: v for k, v in asdict(agent_def).items() if v is not None}
        for name, agent_def in self._options.agents.items()
    }
    cmd.extend(["--agents", json.dumps(agents_dict)])

✅ The SDK IS passing the agents parameter correctly.

2. CLI Accepts --agents Parameter

claude --help | grep agents
# Output shows: --agents <json>  JSON object defining custom agents

✅ The CLI accepts the parameter.

3. Task Tool Doesn't See Custom Agents

From CLI source code (cli.js), the Task tool looks up agents here:

let J = Z.options.agentDefinitions.activeAgents
let I = J.find((z) => z.agentType === B);

if (!I) throw Error(`Agent type '${B}' not found. Available agents: ${J.map((z)=>z.agentType).join(", ")}`);

❌ The activeAgents array only contains built-in agents. Custom agents from --agents parameter or filesystem are NOT added to this array.

Impact

This bug makes the entire custom agent system non-functional:

• ❌ Cannot use programmatic agents via SDK (as documented)
• ❌ Cannot use filesystem agents (as documented)
• ❌ Only 4 built-in agents work
• ❌ Multi-agent workflows are impossible
• ❌ Specialist delegation pattern doesn't work

This affects:

• All Python SDK users trying to use custom agents
• All TypeScript SDK users trying to use custom agents
• Anyone trying to create filesystem-based agents
• All documentation examples showing custom agents

Workarounds

Currently, the only workaround is to not use the Task tool and instead:

1. Use MCP tools directly in the main agent
2. Skip specialist delegation entirely

This defeats the purpose of the multi-agent architecture.

Additional Context

Verified on Clean Install

# Uninstalled all versions
npm uninstall -g @anthropic-ai/claude-code

# Clean install of latest
npm cache clean --force
npm install -g @anthropic-ai/claude-code

# Verified version
claude --version  # 2.0.22 (Claude Code)

# Bug still present

Test Environment Details

• Node.js: v18+
• Python: 3.13
• Working directory: Project with valid .claude/agents/ directory
• MCP servers: Working correctly (52 tools available)
• Other CLI features: Working correctly

Suggested Fix

The agent discovery system needs to:

1. Load agents from --agents CLI parameter into activeAgents array
2. Scan .claude/agents/ directories and add to activeAgents array
3. Make both programmatic and filesystem agents available to Task tool

The bug appears to be in the agent loading pipeline before the Task tool executes.

Questions

1. Is this a known issue?
2. Is there a timeline for fixing this?
3. Are there any other workarounds?
4. Should we expect custom agents to work in v2.0.22?

Related Issues

• #8256 - Custom agents in .claude/agents/ not loading (marked as resolved, but still broken)
• #4182 - Sub-agent Task tool not exposed (different issue, but related to Task tool)

Thank you for looking into this! The custom agent system is a powerful feature when it works.