E3 · Read-only explorer
10 minCreate .claude/agents/explorador.md in the training project and run the checker.
Done when: the checker prints explorador · tools: Read, Grep, Glob · model: inherit · escreve: não.
Lesson 2 · 18 min
Subagents: clean context, short return
A subagent does the noisy part in its own context window and returns only the summary. It's worth what doesn't come back: logs, searches, and files the main conversation will never read again. In this lesson you write a read-only subagent with a return of up to 12 lines and actually check the size of what came back.
Start the lesson
In this lesson you will
- 1What the subagent receives and what it returns
- 2The .claude/agents/[nome].md file and the fields that matter
- 3Restricted tools: what the list locks and what only the instruction asks for
- 4Fixed-format return with a confidence line
Goal: create a read-only subagent with a return of up to 12 lines and check that its answer fits in the main conversation.
01Round trip of a subagent
Behavior of Claude Code 2.1.303, from the official docs read on 10/19/2026. Click each step.
Click each block in the diagram to see what it does.
Fork is something else: it inherits the whole conversation (/subtask) and loses input isolation. Good for a side task that needs what has already been said.
02The fields that decide
Of the supported frontmatter, four change behavior day to day.
1. description
Claude delegates when the task matches the description. Write when to use it and when not to use it, in one sentence.
A new file in .claude/agents/ takes effect without restarting, except when the agents/ folder didn't exist at the start of the session.
2. tools
List of tools it can use. Without the field, it inherits the conversation's tools. Without Write, Edit and Bash, it writes nothing, no matter how much the model wants to.
disallowedTools with a specifier, like Bash(git push *), removes the whole tool; to block only that command, use permissions.deny.
3. model
Accepts an alias or inherit. Choose by the role's level (lesson 7), not by the name of the day: names change.
The runtime kit uses opus, sonnet and haiku in the three roles; treat that as an example of different levels.
4. Body
The body of the file becomes the system prompt. Put the response format in it: maximum number of lines, path:line as proof, and a final confidence line.
This format lets the orchestrator read 10 summaries without filling its own window.
03A read-only explorer
Create the file, check the fields without spending quota, then make a real call.
.claude/agents/explorador.md · in ~/treino-multi
--- name: explorador description: Searches the project and returns only a summary. Use it to sweep many files without filling the main conversation. tools: Read, Grep, Glob model: inherit --- You are the explorer. Change nothing. Return at most 12 lines: 1. The answer in one sentence. 2. Up to 8 lines in the format path:line — what is there. 3. Last line: CONFIANÇA alta|média|baixa and what you did not check.
Terminal · no-quota rehearsal: check the project's subagents
cd ~/treino-multi
python3 - .claude/agents/*.md <<'PY'
import sys, re
for f in sys.argv[1:]:
m = re.match(r"---\n(.*?)\n---", open(f, encoding="utf-8").read(), re.S)
if not m:
print(f, "→ SEM frontmatter"); continue
d = {k.strip(): v.strip() for k, v in (l.split(":", 1) for l in m.group(1).splitlines() if ":" in l)}
tools = d.get("tools", "(herda todas)")
escreve = "tools" not in d or any(x in tools for x in ("Write", "Edit", "Bash"))
print(f"{d.get('name', '?')} · tools: {tools} · model: {d.get('model', '(herda)')} · escreve: {'sim' if escreve else 'não'}")
PYTerminal · real call (uses a little quota)
cd ~/treino-multi claude -p "Use o subagente explorador para descobrir onde este projeto define a própria versão e quais arquivos citam essa versão. Repita apenas o resumo que ele devolver, sem comentar." < /dev/null > resposta.md grep -c "^CONFIANÇA" resposta.md; wc -l < resposta.md
Example from the repository
## conferidor (sem cota) executor · tools: Read, Write, Edit, Bash, Grep, Glob · model: sonnet · escreve: sim explorador · tools: Read, Grep, Glob · model: inherit · escreve: não planejador · tools: Read, Grep, Glob · model: opus · escreve: não revisor · tools: Read, Bash, Grep, Glob · model: haiku · escreve: sim ## resposta.md (chamada real, 29 s) A versão é 0.3.0 e a fonte da verdade é o arquivo VERSION na raiz. Não existe package.json nem pyproject, e nenhuma constante no código define a versão. Ela também aparece em mais 6 arquivos, num total de 9 ocorrências: - `VERSION:1`: `0.3.0` (definição) - `CHANGELOG.md:3`: `## 0.3.0 — 2026-10-05` - `runtime/mods/runtime-guarda/.claude-plugin/plugin.json:3`: `"version": "0.3.0"` - `runtime/mods/runtime-painel/.claude-plugin/plugin.json:3`: `"version": "0.3.0"` - `guia/index.html:329` e `:335`: rótulo "Fase 3 · 0.3.0" e rodapé "INEMA Agent Runtime 0.3.0" (… guia/en e guia/es, as mesmas duas citações …) CONFIANÇA alta. Não conferi o que o .gitignore exclui nem os outros números de versão (0.1.0, 0.2.0), e não verifiquei se algum script lê o VERSION.
The ## headings separate the two rounds. Declared cuts: two lines of the translated guide and a final line that the global CLAUDE.md of the capture machine adds. On your machine, wc -l should be between 10 and 15.
The checker marked revisor · … · escreve: sim. The kit file says "Não altere arquivos", but the tool list includes Bash, and Bash writes. The instruction is a request to the model; the tool list is the lock.
revisor · tools: Read, Bash, Grep, Glob · model: haiku · escreve: sim
The reviewer needs Bash to run the criteria. To keep it from actually writing, the way out is sandbox (lesson 5) or a permission rule; guarding against deleting and writing is covered in course 4. And the real call without < /dev/null waits 3 s for stdin and warns: Warning: no stdin data received in 3s.
04Practice
The rehearsal checks the file; the real call checks the return.
E4 · A return that fits
10 minMake the real call. Then swap the question for one from your real project, with the same subagent.
Done when: grep -c "^CONFIANÇA" resposta.md → 1 and wc -l < resposta.md → at most 15, on both questions.
05Lesson quiz
Question 1 of 4
What comes back from the subagent to the main conversation?skill
Correct
Only the final answer comes back. That's why the return format, written in the body of the file, is the most important part.Not this one
Only the final answer comes back. That's why the return format, written in the body of the file, is the most important part.Review: Round trip of a subagentQuestion 2 of 4
Does the subagent receive the main conversation's history?skill
Correct
A regular subagent starts clean. The fork inherits the whole conversation, and in doing so loses input isolation.Not this one
A regular subagent starts clean. The fork inherits the whole conversation, and in doing so loses input isolation.Review: Round trip of a subagentQuestion 3 of 4
A reviewer has tools: Read, Bash, Grep, Glob and the instruction "don't change files". Can it write?
Correct
With Bash it can write using echo, sed, or rm. To really lock it down: sandbox (lesson 5) or a permission rule (course 4).Not this one
With Bash it can write using echo, sed, or rm. To really lock it down: sandbox (lesson 5) or a permission rule (course 4).Review: A read-only explorerQuestion 4 of 4
When is it NOT worth delegating to a subagent?
Correct
Back and forth and shared context stay in the main conversation; the subagent starts from scratch and would have to reread everything.Not this one
Back and forth and shared context stay in the main conversation; the subagent starts from scratch and would have to reread everything.Review: Round trip of a subagentQuiz completed
You got {a} of {n} right. Get them all right and the lesson is marked as completed.Choose one option. The explanation appears after your attempt.
06In three sentences
Worth it for what doesn't come backLogs, searches, and files stay in the subagent's window; only the summary comes back.
A tool is a lockRead, Grep, Glob don't write; Bash does, no matter what the instruction says.
Fixed formatMaximum lines, path:line as proof, and a confidence line, written in the body of the file.