Spawning Subagents: the Agent (Task) Tool and AgentDefinition

1.The Agent tool: how a coordinator spawns a subagent

In the Claude Agent SDK, a coordinator delegates work by calling a tool. Exam questions and older code call it the Task tool. Current SDK versions emit it under the name Agent. The SDK's own detection sample checks for both names, so code that watches for subagent calls should do the same. Each call carries a subagent_type, which names the subagent that was picked.

        # Check for subagent invocation. Match both names: older SDK
        # versions emitted "Task", current versions emit "Agent".
        if hasattr(message, "content") and message.content:
            for block in message.content:
                if isinstance(block, ToolUseBlock) and block.name in (
                    "Task",
                    "Agent",
                ):
                    print(f"Subagent invoked: {block.input.get('subagent_type')}")

You can define subagents in code with the agents option of query(), or as markdown files in .claude/agents/. Claude can also call a built-in general-purpose subagent without any definition from you. Every coordinator sample in the docs also adds the tool to allowed_tools / allowedTools. The exam guide states this as a requirement: the coordinator's allowed tools must include "Task" (now "Agent"). Be precise about what that list does. The SDK reference calls it a list of tools to *auto-approve*, not a whitelist. Tools not on it fall through to permissionMode and canUseTool. Listing Agent means delegation runs without a permission prompt. To actually block a tool, use disallowedTools.

            # Auto-approve these tools
            allowed_tools=["Read", "Grep", "Glob", " ? "],

Sources12

2.AgentDefinition: description, system prompt, tool restrictions

Each subagent type is an AgentDefinition keyed by name. The fields have different jobs. description is what the coordinator reads to decide *when* to delegate. prompt is the subagent's own system prompt, which sets *how* it behaves after it is spawned. A detailed prompt does nothing for routing if the description is vague, because the coordinator chooses by description.

AGENTS = {
    "endpoint-finder": AgentDefinition(
        description="Locates and catalogs API endpoints in a codebase.",
        prompt="You find and document API endpoints. Report each endpoint's path, method, and handler.",
        tools=["Read", "Grep", "Glob"],
    )
}

Restricting tools does two things. It lowers the risk of unintended actions: a reviewer limited to Read and Grep can inspect files but cannot change them. It also saves context, because every tool definition takes space. The agent-loop docs recommend scoping each subagent to the smallest set of tools it needs. Leaving tools out does not make a subagent safe. It gets every tool available to subagents.

Sources13

3.Spawning subagents in parallel

The SDK docs give the code-review case directly: style-checker, security-scanner and test-coverage subagents can run at the same time instead of one after another. Anthropic's Research system learned this from experience. Its early agents ran searches one at a time, which was very slow. The fix was to have the lead agent launch 3–5 subagents in parallel, and to have each subagent call 3 or more tools in parallel. The engineering post reports that this cut research time by up to 90% on complex queries.

Sources14

4.Forking a session to explore divergent approaches

Subagents are not the only way to explore alternatives. Sessions have their own tool for it. Suppose an agent has already analyzed the auth module in one session. That session is your shared analysis baseline. Resuming it appends to the same history, so a second approach would overwrite the first thread. Forking instead branches from the baseline into a new session. The fork starts with the baseline's analysis, so nothing has to be re-read, and it then diverges on its own. The sessions docs list this as the choice when you want to try an alternative approach without losing the original. In the SDK you pass resume with the baseline's session ID and also set fork_session (Python) or forkSession (TypeScript). The fork option only applies together with resume.

            prompt="Instead of JWT, outline how OAuth2 would work for the auth module",
            options=ClaudeAgentOptions(
                resume=session_id,
                fork_session=True,
                max_turns=5,
            ),

The sample captures the fork's session ID from the result message. That ID is distinct from the baseline's, so each branch can be resumed on its own later. Resuming the baseline ID continues the original thread, untouched by the fork. To compare several approaches, fork once per approach from the same baseline ID.

Sources526

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Putting tools in allowedTools restricts the coordinator to those tools only.Why is that wrong?

   allowedTools only auto-approves the listed tools. Tools not on it fall through to permissionMode and canUseTool, and disallowedTools is what removes a tool.

   Covered in The Agent tool: how a coordinator spawns a subagent

2. 2.A detailed subagent prompt is what makes the coordinator delegate to it.Why is that wrong?

   The coordinator decides when to delegate from the description field. The prompt only shapes the subagent's behaviour once it is running.

   Covered in AgentDefinition: description, system prompt, tool restrictions

3. 3.Launching independent subagents one per turn costs about the same time as launching them together.Why is that wrong?

   Subagents that run concurrently finish in the time of the slowest one. Launching them one after another adds up all their run times.

   Covered in Spawning subagents in parallel

4. 4.Resuming a session with a new prompt is the way to try an alternative approach while keeping the original analysis intact.Why is that wrong?

   Resume continues the original session. Forking creates a new session ID, and the original session stays as it was.

   Covered in Forking a session to explore divergent approaches