[DOCS] Conflicting instructions regarding `Task` tool in Subagent SDK documentation

Documentation Type

Unclear/confusing documentation

Documentation Location

URL: platform.claude.com/docs/en/agent-sdk/subagents

Section/Topic

Section: "Creating subagents" -> "Programmatic definition (recommended)"

Current Documentation

The documentation provides a code example that includes the Task tool in the allowed_tools list:

options=ClaudeAgentOptions(
    # Task tool is required for subagent invocation
    allowed_tools=["Read", "Grep", "Glob", "Task"],
    agents={
        "code-reviewer": AgentDefinition(
            # ...
            tools=["Read", "Grep", "Glob"],
            # ...
        )
    }
)

Directly following this or in the "AgentDefinition configuration" table notes, it states:

"Subagents cannot spawn their own subagents. Don't include Task in a subagent's tools array."

What's Wrong or Missing?

There is a logic flaw and a high potential for developer confusion.

1. Ambiguity of "Options": Because ClaudeAgentOptions (for the main agent) and AgentDefinition (for the subagent) both utilize a tools/allowed_tools parameter, a developer copy-pasting the "allowed tools" list from the example may inadvertently include Task in the subagent definition.
2. Conflicting Proximity: The example explicitly labels Task as "required for subagent invocation," while the warning note says "Don't include Task." To a new user, it is not immediately clear that the "required" instruction applies strictly to the Main Agent and the "don't include" applies strictly to the Subagent.
3. Risk: If a user includes Task in a subagent's toolset, they risk creating recursive loops or encountering runtime errors that the documentation warns against but doesn't clearly demonstrate how to avoid via object naming.

Suggested Improvement

The code example should explicitly differentiate between the configuration for the orchestrator (main agent) and the specialist (subagent) to make the exclusion of the Task tool obvious.

Suggested Text/Code:

# Define the specialist subagent (Note: 'Task' is omitted to prevent recursion)
reviewer_definition = AgentDefinition(
    description="Expert code review specialist.",
    prompt="Analyze code quality and suggest improvements.",
    tools=["Read", "Grep", "Glob"] # No 'Task' tool here
)

# Define the main agent options
# 'Task' is required here so the main agent can invoke the subagent
main_agent_options = ClaudeAgentOptions(
    allowed_tools=["Read", "Grep", "Glob", "Task"],
    agents={
        "code-reviewer": reviewer_definition
    }
)

async for message in query(
    prompt="Review the auth module",
    options=main_agent_options
):
    # ...

Impact

High - Prevents users from using a feature

Additional Context

• Related Documentation: Claude Code Subagents
• Rationale: Standardizing the nomenclature (e.g., mainAgentOptions vs subAgentOptions) provides a "pit of success" for developers. Many users are migrating from simpler LLM implementations and may not realize that subagents in this SDK have a completely isolated tool permission scope that strictly forbids the Task tool.