Subagents in Claude Agent SDK Applications

## Overview

Subagents are separate agent instances your main agent can spawn for focused
subtasks. Use them to isolate context, run analyses in parallel, and apply
specialized instructions without bloating the main prompt. The Agent SDK
recommends defining them programmatically with the `agents` option.

## Define subagents programmatically

Each subagent is an `AgentDefinition` with a `description` (when to use it),
`prompt` (its behavior), optional `tools`, and optional `model`. Include `Agent`
in `allowedTools` so invocations auto-approve.

```typescript
for await (const message of query({
  prompt: "Review the authentication module for security issues",
  options: {
    allowedTools: ["Read", "Grep", "Glob", "Agent"],
    agents: {
      "code-reviewer": {
        description: "Expert code review specialist. Use for quality and security reviews.",
        prompt: "You are a code review specialist...",
        tools: ["Read", "Grep", "Glob"],
        model: "sonnet",
      },
    },
  },
})) {
  if ("result" in message) console.log(message.result);
}
```

`AgentDefinition` also supports `disallowedTools`, `skills`, `mcpServers`,
`maxTurns`, `effort`, `background`, and `permissionMode`.

## Why subagents

- **Context isolation**: each subagent runs in a fresh conversation; only its
  final message returns to the parent.
- **Parallelization**: independent subagents run concurrently.
- **Specialization**: tailored system prompts and knowledge per subagent.
- **Tool restriction**: limit a subagent to specific tools to reduce risk.

## What a subagent inherits

A subagent receives its own system prompt, the Agent tool's prompt string,
project CLAUDE.md (via settingSources), and inherited tool definitions. It does
**not** receive the parent's conversation history, system prompt, or preloaded
skills (unless listed in `skills`). Put any file paths or context it needs into
the prompt.

## Invoke and detect

Claude invokes subagents automatically based on `description`, or you can name one
explicitly ("Use the code-reviewer agent to..."). Subagents run via the Agent
tool; detect them by `tool_use` blocks named `Agent` (older SDKs used `Task`), and
messages from inside a subagent carry `parent_tool_use_id`.

## Resume

When a subagent completes, the Agent tool result includes `agentId: <id>`.
Capture the `session_id` and `agentId`, then resume with `resume: sessionId` and
reference the agent id in the prompt to continue with full context.

## Scale up

For runs coordinating dozens to hundreds of agents, use the `Workflow` tool
(TypeScript SDK), which moves orchestration into a script outside the conversation
context.

## Source

- Subagents in the SDK: https://code.claude.com/docs/en/agent-sdk/subagents