Skip to main content
Claude Code subagents are workers that Claude delegates tasks to within a session. A custom subagent gives a repeatable task its own instructions and tool selection, then returns findings to the caller. Use one for a focused investigation or review whose result you can check. Native subagents do not require AMS. See Anthropic’s subagent documentation. Checked against official Anthropic documentation on 5 November 2026. The exercise below is a local example, not a report of a live Claude Code run.

When to delegate

A useful assignment has an input, a stopping point and a deliverable. “Compare these two files and list unsupported claims” is easier to review than “improve our documentation.” Keep a quick edit or a conversation that needs frequent decisions in the main session. Anthropic’s team comparison explains the native distinction. Teams are experimental and require separate enablement. They can also affect delegation: with teams enabled, a subagent Claude names can launch as a teammate. For the broader setup, see multiple Claude Code agents. For a one-off codebase lookup, Claude also has a built-in read-only Explore subagent. Define a custom worker when you want to reuse a particular review contract. See built-in subagents. Start with one worker. Add parallel assignments only when each can finish without waiting for another worker’s changes.

Prerequisites

You need an installed, signed-in Claude Code CLI, a local project where you may create example files, and permission to read those files. Check your installed version:
Use the CLI reference to check supported commands and claude auth status if sign-in is uncertain. This exercise needs no MCP server, external API, package installation or credentials in files. Leave experimental agent teams disabled for the exercise so you can inspect ordinary subagent delegation.

1. Prepare two small inputs

From your project root, create these directories if they do not already exist:
Use a new filename for each example; preserve any existing files with the same names. Save this as subagent-demo/routes.json:
Save this as subagent-demo/api-guide.md:
Treat the JSON as the complete route inventory for this fixture only. The second documented route deliberately has no matching inventory entry. This gives you a known discrepancy to look for without calling a real service.

2. Define a reusable, read-only reviewer

Save the following as .claude/agents/docs-route-auditor.md. Project definitions live in .claude/agents/; personal definitions live in ~/.claude/agents/. The frontmatter configures the worker and the Markdown body supplies its instructions. See subagent file configuration.
The tool list deliberately omits shell execution, editing, MCP actions and further delegation. The path restriction in the prompt is an assignment boundary; use permission rules when you also need enforced file-access restrictions. Anthropic distinguishes prompt instructions from enforced permissions. maxTurns bounds agentic turns, not elapsed time or spending. A worker reaching that limit can return partial output; decide whether the remaining question merits another run. See the frontmatter reference.

3. Invoke that worker with a complete assignment

Start a fresh interactive session from the same project root after saving the files:
In the prompt, type @ and select docs-route-auditor from the agent picker. Current Claude Code also accepts the manual mention below. An agent mention selects the worker explicitly; a natural-language request leaves delegation to Claude’s judgment. See explicit invocation.
Reuse that shape for real work: name the authoritative inputs, permitted paths, question, output format and stop condition. For example, assign a reviewer one module and its tests rather than an entire repository. The separate claude --agent docs-route-auditor flag starts the main session using that agent definition. It is useful for a dedicated reviewer session, but it is a different exercise from delegating a worker inside your current conversation. See --agent in the CLI reference.

4. Observe the run and verify the result

Use /tasks to inspect running shells and subagents. In the terminal, Ctrl+O opens the detailed transcript viewer. Ctrl+T toggles Claude’s checklist, which is a different view. See interactive controls. Subagents can work in the background. Wait for the completion result before assessing findings; an active task is still work in progress. See foreground and background execution. Check the actual delegation and tool activity before accepting the answer. For this fixture, a useful report should:
  • Identify GET /status in the guide as absent from the supplied inventory.
  • Cite the relevant files and lines, with a suggested removal or qualification.
  • State that no server was queried and no runtime behavior was verified.
  • Leave the two inputs unchanged.
Open both files yourself to confirm the discrepancy. A worker that merely says “looks good” has not demonstrated the requested comparison. A worker reporting a live endpoint failure has gone beyond the available evidence. For a real investigation, ask the main session to check the cited evidence before implementing a correction. If a test run is needed, make it a separate, authorized action with the appropriate tools.

Permissions and context boundaries

Review /permissions before broadening access. Deny rules take precedence over ask and allow rules, and managed policies can constrain the session. A description such as “read-only” expresses intent; the tool list and permission system enforce what calls are available. See permission rules. This definition omits permissionMode, so it inherits the parent mode. Setting that field does not guarantee an independent mode: the parent can override it. Check subagent permission modes before adding a mode to another worker. Do not solve a blocked review by granting every tool. First decide whether the task actually requires the blocked action. This fixture needs file reads; a shell or write permission would not help prove the mismatch. An ordinary non-fork subagent starts with a separate context, rather than the full chat history. Send the decision-relevant facts and paths in the assignment. A conversation fork is an exception and inherits the conversation. See startup context and fork behavior. Keep important constraints in the assignment even when project instructions also cover them. For example: “The inventory is a fixture; do not probe production” removes ambiguity that a filename alone cannot resolve. Context separation also does not assign file ownership or isolate simultaneous edits. Use worktrees when independently editing checkouts is appropriate.

Troubleshooting

The configuration and version checks follow Anthropic’s subagent troubleshooting details. For installation and settings diagnostics, use the read-only claude doctor command documented in the CLI reference.

When AMS helps

Native delegation and its result return work without AMS. Use an optional shared channel when findings need to reach another task or tool, such as a separate implementation session. The caller can review the subagent’s evidence and hand off the relevant result without adding messaging tools to this read-only worker. Follow sharing context between coding agents or Claude Code and Codex together for that workflow. Record the input revision, finding, evidence and requested next action. A stored AMS message does not itself wake an inactive task or prove that its recipient accepted the handoff.