[BUG] SDK programmatic agents ignored - ClaudeAgentOptions(agents={...}) not working with Task tool

Preflight Checklist

• [x] I have searched existing issues and this specific SDK issue hasn't been reported
• [x] This is a single bug report (focused on SDK programmatic agents only)
• [x] I am using the latest version of Claude Code and SDK
• [x] This is a REGRESSION - documented SDK feature that doesn't work

What's Wrong?

The Claude Agent SDK's documented feature for programmatic custom agents is completely non-functional.

The SDK allows defining custom agents programmatically:

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

options = ClaudeAgentOptions(
    agents={
        "my_specialist": AgentDefinition(
            description="A custom specialist agent",
            prompt="You are a specialist in X",
            tools=["Read", "Grep", "Bash"]
        )
    }
)

This is documented and promised to work:

• https://docs.claude.com/en/api/agent-sdk/subagents
• Python SDK: ClaudeAgentOptions(agents=...)
• TypeScript SDK: Similar agent definition pattern

But when you try to use these agents with the Task tool, they are completely ignored.

Error:

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

Why This Is Critical

For SDK Users:

• ❌ Cannot create agents programmatically
• ❌ Cannot integrate with CI/CD pipelines
• ❌ Cannot dynamically configure agents based on runtime conditions
• ❌ Cannot build multi-agent systems as documented
• ❌ All SDK documentation examples fail

Use Cases That Don't Work:

• Multi-agent orchestration systems (like my looper project)
• Specialist delegation workflows
• Dynamic tool access control per agent
• Programmatic agent configuration from databases/config files
• Integration with existing codebases

Steps to Reproduce

Python SDK Example

1. Install SDK:

pip install claude-agent-sdk

1. Create test script:

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

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

async for message in query(
    prompt="Use Task tool with subagent_type='test_specialist' to read this file",
    options=options
):
    print(message)

1. Run the script

Expected: Custom agent 'test_specialist' should be available to Task tool

Actual: Error - "Agent type 'test_specialist' not found. Available agents: general-purpose, statusline-setup, output-style-setup, Explore"

Root Cause Analysis

I've traced this through the codebase:

✅ SDK Side Works Correctly:

File: claude-agent-sdk/src/_internal/transport/subprocess_cli.py:171-176

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 correctly serializes agents and passes them via --agents CLI parameter

✅ CLI Receives Parameter:

The CLI accepts --agents parameter:

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

✅ CLI correctly receives the parameter

❌ CLI Doesn't Populate activeAgents Array:

File: cli.js (from decompiled Claude Code)

// Task tool looks up agents here:
let J = Z.options.agentDefinitions.activeAgents  // Only 4 built-in agents!
let I = J.find((z) => z.agentType === B);

if (!I) throw Error("Agent type not found");

THE BUG: The activeAgents array is never populated with custom agents from the --agents parameter. It only contains the 4 built-in agents.

Evidence This Breaks Documented Features

Official Documentation Says This Should Work:

1. SDK docs show ClaudeAgentOptions(agents={...})
2. Subagent documentation shows custom agent definitions
3. All code examples in docs fail with this bug

This is NOT a feature request - it's a documented feature that's broken.

Confirmed Broken Across Versions

• SDK v0.1.4 (Oct 2025): Broken
• SDK v0.1.18 (Jan 2026): Still broken
• Claude Code v2.0.22 → v2.1.9: Still broken
• 4+ months unfixed

Impact on Real Projects

I'm building a multi-agent orchestration system (looper) that relies on programmatically defining specialist agents:

• router-i: Fast coordinator that delegates to specialists
• custom-i: Deep forensic analysis specialist
• looper-i: Looper-specific work specialist

I cannot use the official SDK because programmatic agents don't work. I've had to work around this by:

• Spawning agents via tmux directly
• Bypassing the Task tool entirely
• Managing agent lifecycle manually

This defeats the entire purpose of the SDK.

Related But Separate Issue

Note: Issue #8697 tracks .claude/agents/*.md filesystem agents (also broken). That's a related but separate problem from SDK programmatic agents.

• #8697: Filesystem agents from .claude/agents/*.md
• This issue: SDK programmatic agents via --agents parameter

Both should work, but they're different use cases:

• Filesystem: Static agents defined in files
• SDK: Dynamic agents created programmatically

Suggested Fix

Based on code analysis, the fix appears straightforward:

In CLI initialization (when parsing --agents parameter):

// Somewhere in cli.js initialization:
if (cliArgs.agents) {
    let customAgents = JSON.parse(cliArgs.agents);

    for (let [name, definition] of Object.entries(customAgents)) {
        Z.options.agentDefinitions.activeAgents.push({
            agentType: name,
            description: definition.description,
            tools: definition.tools || [],
            prompt: definition.prompt,
            model: definition.model || 'sonnet'
        });
    }
}

Estimated effort: ~Half day (20-50 lines of code + tests)

The infrastructure already exists:

• ✅ Subprocess spawning works (for built-in agents)
• ✅ Tool access control works (via allowed-tools)
• ✅ Agent lifecycle management works
• ❌ Just need to populate activeAgents array from --agents parameter

What Should Happen?

1. SDK passes agents via --agents parameter ✅ (already works)
2. CLI parses --agents parameter ✅ (likely already works)
3. CLI adds custom agents to activeAgents array ❌ (THIS IS MISSING)
4. Task tool shows custom agents in available types ❌ (broken)
5. Task tool can spawn custom agents ❌ (broken)

Error Messages/Logs

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

Claude Model

All models affected (this is a CLI bug, not model-specific)

Is this a regression?

Yes - This is a documented SDK feature that has never worked properly, making it a regression from documented functionality.

Last Working Version

Unknown - this feature may have never worked since SDK release

Claude Code Version

2.1.9 (latest)

SDK Version

• Python SDK: 0.1.18 (latest)
• TypeScript SDK: Similar issue

Platform

Anthropic API (but affects all platforms - CLI bug)

Operating System

All OS (macOS, Windows, Linux) - CLI bug is platform-independent

Terminal/Shell

All terminals - CLI bug

Additional Information

Why I'm Filing This Separately:

My original issue #9865 covered both SDK programmatic agents AND filesystem agents. It was closed as duplicate of #8697, which ONLY covers filesystem agents.

SDK programmatic agents are a distinct use case that deserves separate tracking:

• Different users (SDK developers vs CLI-only users)
• Different use cases (dynamic vs static agents)
• Different implementation (--agents parameter vs file scanning)

Request to Maintainers:

• Please label as bug not enhancement (this is documented functionality)
• Please prioritize - this breaks core SDK features for all programmatic users
• The fix appears straightforward based on code analysis

Thank you for maintaining Claude Code! This is critical for SDK users building multi-agent systems programmatically.