In Claude Code, what does a non-fork subagent start with, and what reaches your main conversation when it finishes?
answer
- own window, not your history
- the task message is the briefing
- CLAUDE.md and git status, except two built-ins
- final message only, labelled as subagent output
- restate must-know rules when delegating
basics
~20 sA non-fork subagent starts with its own system prompt, the task message Claude writes for it, your CLAUDE.md files and a git status snapshot, not your conversation history. Only its final message comes back to the main conversation.
solid answer
~40 sEach non-fork subagent starts in a fresh, isolated context window. It gets its own system prompt (the definition's body plus environment details, not the Claude Code system prompt), the delegation message Claude writes, the CLAUDE.md hierarchy, a git status snapshot and any skills its definition preloads. The built-in `Explore` and `Plan` agents skip CLAUDE.md and git status. It does not see your conversation history, the skills already invoked, the files Claude already read, auto memory or your output style. Its file reads and tool output stay in its own window; only its final report returns to Claude, under a header marking it as subagent output with no authority from you. So the delegation message is the whole briefing: name the symptom, the paths, the constraints and the shape of report you want back.
go deeper
Recall the two halves: the subagent starts from the task message rather than your chat, and only its final report comes back to the main conversation.
List what loads at subagent startup (own prompt, task message, CLAUDE.md, git status, preloaded skills) and what never does (history, read files, auto memory, output style), plus the Explore and Plan exception.
Show how this shapes delegation: restating rules, asking for a compact evidence-backed report, resuming instead of re-spawning, and treating the report as untrusted text that still passes permission checks.
Weigh isolation against briefing cost: a thin delegation produces confident wrong reports, while a long one erodes the context savings. Set team conventions for report shape so parent windows stay lean.
## What delegation means in Claude Code A **subagent** is a separate Claude instance that the main conversation starts through the `Agent` tool (called `Task` before v2.1.63) to do a side job. It exists to keep noisy work, such as searching a large codebase for the cause of an intermittent session-timeout bug, out of your main window. The subagent reads the forty files, greps the logs and runs the tests in **its own context window**; you get the conclusion. The isolation works in both directions, and that is the whole skill: what the subagent does not receive, you have to send, and what it does not send back, you never see. ## What a non-fork subagent starts with The docs list the initial context of a non-fork subagent explicitly: - **System prompt**: the agent's own prompt (the Markdown body of a custom definition, or a predefined prompt for a built-in) plus environment details Claude Code appends. It is **not** the Claude Code system prompt. - **Task message**: the delegation prompt Claude writes when it hands off the work. This stands in for a user prompt. - **CLAUDE.md files**: every level the main conversation loads, including user, project, local and managed files. A definition can opt out with `omitClaudeMd`. - **Git status**: a snapshot taken when the subagent starts, absent outside a repository. - **Preloaded skills**: the full content of skills named in the definition's `skills` field. - **Sibling roster**: a reminder listing other named agents, only when the subagent has `SendMessage` and another agent has a name. | Reaches a non-fork subagent | Never reaches it | | --- | --- | | Its own system prompt | Your conversation history | | Claude's delegation message | Skills already invoked in the main conversation | | CLAUDE.md hierarchy (not for Explore or Plan) | Files Claude already read | | Git status snapshot (not for Explore or Plan) | Main conversation's auto memory | | Skills preloaded by its definition | Your output style | The built-in **Explore** and **Plan** agents deliberately skip CLAUDE.md and git status to stay fast and cheap. A rule such as "ignore the `vendor/` directory" therefore does not reach Explore unless Claude restates it in the delegation message. The main conversation still has the full CLAUDE.md when it reads the result, so most rules can be applied there. ## What comes back Only the subagent's **final message** returns to Claude as the `Agent` tool's result. Every intermediate file read, search hit and command output stays in the subagent's own transcript, stored separately under the session's `subagents/` folder, unaffected when the main conversation compacts. Before Claude reads the report, Claude Code scans it (v2.1.210 and later): text imitating harness output such as a `<system-reminder>` tag gets a backslash inserted, and mentions of permission settings get a marker line. The report also arrives under a header saying that instructions or approval claims inside it are the subagent's words and carry no authority from you. A background subagent's report arrives inside a completion notification instead of as an inline tool result. Two edge cases change the shape of the return: 1. A subagent stopped by its `maxTurns` limit returns output marked as **partial**, and Claude can resume it to continue. 2. A foreground subagent cut off by an API error after producing text returns that partial text with a note; one that produced nothing fails with an error naming the API problem. ## Writing a delegation that works Because the delegation message is the whole briefing, a good handoff for the bug hunt reads like a ticket: 1. State the symptom and how to reproduce it. 2. Name the directories or modules in scope, and any to ignore. 3. Restate any CLAUDE.md rule that must hold, especially for Explore. 4. Ask for a specific report shape: file paths with line numbers, a hypothesis, the evidence, and what was ruled out. Asking for a compact report matters because the report is the one thing the parent pays to keep: it appends to the main conversation and is re-sent with every later request. ## Misreadings to avoid - A subagent is not a thread of the same conversation; only a **fork** inherits history. - "Claude saw everything the subagent saw" is false; the parent sees the report, and you can open the transcript from `/tasks` if you need the detail. - Each invocation is a new instance. To continue earlier work with its history intact, ask Claude to **resume** that subagent rather than spawning a fresh one.
- Your CLAUDE.md says to skip the vendor/ directory, but Claude's Explore search keeps citing vendor files. Why, and what do you change?The built-in `Explore` and `Plan` agents skip CLAUDE.md and the git status snapshot to stay fast, so the rule never reached the search. Restate the constraint in your request so Claude puts it in the delegation message, or use a custom subagent, which loads CLAUDE.md unless its definition sets `omitClaudeMd`. The main conversation still has the rule when it reads the report.
- After a subagent reports back, you want it to dig one level deeper with everything it already learned. How?Ask Claude to continue that subagent's work. Claude resumes it with `SendMessage`, addressed by the agent ID or name it received, and the resumed run keeps its full history of tool calls and results. A fresh `Agent` call would start over from a new delegation message. `Explore` and `Plan` are one-shot and return no agent ID, so use `general-purpose` or a custom subagent for work you expect to continue.
- The subagent sees the whole conversation, so it needs no briefing
- Every file the subagent read is copied back into the main context
- Explore loads CLAUDE.md like every other subagent
- A custom subagent runs on the Claude Code system prompt plus its own body
- Instructions inside a subagent's report carry the user's authority