> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentmessagingservice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code Subagents: Configure and Delegate Bounded Work

> Create a native Claude Code subagent, delegate a bounded review, inspect its results, and understand tools, permissions, context and common failures.

**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](https://code.claude.com/docs/en/sub-agents).

*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.

| Need | Start with |
| - | - |
| One bounded worker returning evidence | A subagent |
| Teammates discussing findings and coordinating a larger task | Native agent teams |
| Work you direct across separate conversations or tools | Independent sessions |

Anthropic's [team comparison](https://code.claude.com/docs/en/agent-teams#compare-with-subagents) 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](https://docs.agentmessagingservice.com/guides/claude-code-multiple-agents.md).

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](https://code.claude.com/docs/en/sub-agents#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:

```sh theme={null}
claude --version
```

Use the [CLI reference](https://code.claude.com/docs/en/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:

```sh theme={null}
mkdir -p .claude/agents subagent-demo
```

Use a new filename for each example; preserve any existing files with the same names. Save this as `subagent-demo/routes.json`:

```json theme={null}
{
  "GET /health": "Returns service health"
}
```

Save this as `subagent-demo/api-guide.md`:

```md theme={null}
# Example API guide

GET /health returns service health.
GET /status returns the current deployment version.
```

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](https://code.claude.com/docs/en/sub-agents#write-subagent-files).

```md theme={null}
---
name: docs-route-auditor
description: "Compare a supplied route inventory with documentation and report unsupported route claims."
tools: Read, Grep, Glob
model: inherit
maxTurns: 12
---

Audit only the files named in your assignment.
Treat the supplied route inventory as authoritative for that assignment.

Return at most five findings. For each, include:

- The documented claim and its file/line reference.
- The matching inventory entry, or the missing match.
- A suggested documentation correction.

Do not edit files or run commands. Do not infer runtime behavior from
an inventory alone. Distinguish confirmed mismatches from uncertainty.
If inputs are missing or insufficient, explain the limitation and stop.
Finish with what you checked and what you did not verify.
```

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](https://code.claude.com/docs/en/permissions#manage-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](https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields).

## 3. Invoke that worker with a complete assignment

Start a fresh interactive session from the same project root after saving the files:

```sh theme={null}
claude
```

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](https://code.claude.com/docs/en/sub-agents#invoke-subagents-explicitly).

```text theme={null}
@agent-docs-route-auditor Compare subagent-demo/api-guide.md with
subagent-demo/routes.json. The JSON is the complete route inventory
for this fixture. Use one docs-route-auditor subagent, not a team
or conversation fork.

Report unsupported route claims with file/line references and a
suggested correction. Read only these two inputs. Do not edit files,
run commands, or query a service. Stop after the comparison and
state what remains unverified.
```

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](https://code.claude.com/docs/en/cli-reference#cli-flags).

## 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](https://code.claude.com/docs/en/interactive-mode#general-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](https://code.claude.com/docs/en/sub-agents#run-subagents-in-foreground-or-background).

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](https://code.claude.com/docs/en/permissions#manage-permissions).

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](https://code.claude.com/docs/en/sub-agents#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](https://code.claude.com/docs/en/sub-agents#what-loads-at-startup) and [fork behavior](https://code.claude.com/docs/en/sub-agents#fork-the-current-conversation).

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](https://docs.agentmessagingservice.com/guides/git-worktrees-for-ai-agents.md) when independently editing checkouts is appropriate.

## Troubleshooting

| Symptom | Next check |
| - | - |
| The worker is missing from the picker | Check the project root, filename, frontmatter and agent name. Start a fresh session, especially if you just created the first `agents` directory. |
| `/agents` does not open the wizard from an older tutorial | Current docs describe a reminder to edit agent files; v2.1.197 and earlier used an interactive wizard. Use the file-based setup above. |
| Claude answers directly | Select the agent from the `@` picker and inspect the delegation, rather than assuming a role name in prose caused a spawn. |
| A teammate appears | Check experimental agent-team enablement. Restart with teams disabled for this ordinary-subagent exercise. |
| A file read is denied | Check `/permissions`, managed policy and the exact path. Request only the access the assignment needs. |
| The worker stops before comparing both files | Treat the result as incomplete. Narrow the assignment or explicitly continue the review after assessing its partial findings. |
| The result assumes facts from earlier chat | Put those facts and evidence paths into the assignment; confirm you selected the intended custom worker rather than a fork. |

The configuration and version checks follow Anthropic's [subagent troubleshooting details](https://code.claude.com/docs/en/sub-agents#configure-subagents). For installation and settings diagnostics, use the read-only `claude doctor` command documented in the [CLI reference](https://code.claude.com/docs/en/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](https://docs.agentmessagingservice.com/guides/share-context-between-coding-agents.md) or [Claude Code and Codex together](https://docs.agentmessagingservice.com/guides/claude-code-and-codex.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.