Anthropic describes subagents as specialised assistants that run in their own context window with a custom system prompt, specific tool access and independent permissions, and that return a summary to the main conversation, so that noisy work such as searches or logs stays out of it (Source 1). The picture to keep in mind is a colleague you hand a brief to: they work at their own desk, you do not watch every page they read, and you receive their note.

Two consequences follow, and the rest of the chapter keeps returning to them:

• It does not know what you know. A subagent does not see your conversation, your invoked skills or the files you already read. It receives its own prompt, the task message Claude writes for it, and a few environment items such as project CLAUDE.md files (Source 1). A brief that says "check the thing we discussed" is useless to it.
• You only see the summary. That keeps your main context small, and it means you must verify claims yourself. The runs below do exactly that.

Claude Code ships built-in subagents. The ones you meet first:

The skill you wrote in Chapter 18 with agent: Explore was already using the first of these. A custom subagent is the same mechanism with your own prompt and tool list.

A subagent is a Markdown file with YAML frontmatter. The body becomes its system prompt. Only name and description are required, and unrecognised fields are silently ignored, so a misspelled key fails quietly (Source 1).

Two more are documented separately: omitClaudeMd (skip CLAUDE.md files) and autoCompactWindow. Where the file lives decides who gets it, and higher entries win when names collide:

1. Managed settings (organisation-wide)
2. The --agents command-line flag (JSON, this session only)
3. .claude/agents/ in the project (commit it; teammates get it)
4. ~/.claude/agents/ (all your projects)
5. A plugin's agents/ directory

This file was written in Chapter 12 and already sits in the bookshelf project. It is deliberately small: three read-only tools and a prompt that says what to report and what to skip.

The bookshelf project has a test, BookQueryCountTest, that says listing books must run exactly one SQL statement. The question for the reviewer is the next one over: can listing books, or any neighbouring path, run more? The prompt names the agent but does not paste any code, so the subagent has to go and read it:

Open the step table. The rows marked Subagent are the reviewer's own tool calls, a Glob and six Read calls. They happened in its own context. The main session shows one Agent call out and one result back, which is the whole boundary from the diagram above.

The second agent reviews the HTTP layer. Its body says it is read-only, but the sentence that matters is in the frontmatter: tools: Read, Grep, Glob. There is no Edit, no Write and no Bash for it to misuse, whatever its prompt says.

To test the guardrail I ran it as the whole session with --agent api-reviewer, and asked for exactly what it must not do, a fix. I also passed Edit and Write in --allowedTools, so the session itself would have permitted them:

• No edit happened. The agent said it could not edit, and git status in the project shows no changed tracked files. No permission denial was recorded in the log. That fits the tool never being offered rather than being refused, but I did not capture the tool list, so treat that as an inference.
• The review was real. I probed the HTTP layer with a temporary MockMvc test: a POST without year, a search without title and GET /api/books/abc each returned 400 with no application/problem+json body, while the handled 404 returned one. The convention in the project's CLAUDE.md says all errors should be ProblemDetail, so this is a genuine gap.
• Model: not what the file says. The agent file says model: haiku. The log lists only claude-sonnet-5-5, and my runner script passes --model sonnet. I did not test which one wins, so the haiku line was not exercised in this run.

Subagents run in the foreground (they block you; permission prompts reach you) or in the background (they run alongside, and prompts surface in your main session). Background agents get a smaller built-in tool set. In an interactive session, fork mode is on by default in current versions, which affects how Claude waits for helpers (Source 1). Chapter 17 shows how to read what happened afterwards.

A fork deserves a sentence of its own. A normal subagent starts fresh and costs you the effort of briefing it. A fork starts with everything the main session knows, shares its prompt cache and therefore costs less for context-heavy side tasks, but loses the isolation that was the point of a subagent. Use a fork when the briefing would be longer than the task.

• A vague description routes badly. Claude chooses by description. Write one that singles the agent out ("reviews REST controllers and exception handling for contract problems"), not "helps with code". The combined descriptions of your custom agents should stay under 15,000 tokens or Claude Code warns at start-up (Source 1).
• A thin brief. The subagent starts from zero. In AG-01 the main session wrote a full prompt for it (row 2 of the table shows the brief the reviewer received); a one-line brief would have produced a worse review. When you delegate by hand, include the file names and the question.
• Results flow back into your context. Many subagents returning long reports can fill the window anyway. Ask for a short, structured summary in the agent's body.
• Unverified summaries. Both runs above ended with "I read the code and ran nothing". That is the honest answer, and it is also your cue to check.
• Nesting and concurrency have limits. By default subagents can spawn subagents up to three layers deep and up to 20 can run at once; both limits can be changed with environment variables. To stop one agent from spawning others, leave Agent out of its tools.
• Cost. Each subagent uses its own tokens against the same limits as your main conversation. The two runs above cost about $0.13 and $0.06 by the log's own estimate; they were small on purpose.

One agent file in the examples repository was not run: test-writer, which edits files and sets isolation: worktree so that its changes land in a temporary copy of the repository. It is a good second step once you trust a read-only agent, but I did not spend on it.