Claude Code Task Tool vs Subagents: Which One Runs Your Work?

Claude Code’s Task tool and its subagents are two halves of one mechanism, not two options. A subagent is a worker: a separate Claude with its own instructions, its own tools and its own context window. Task is the tool the main conversation uses to hand work to one. It was renamed Agent in Claude Code 2.1.63, and old Task(...) references in settings still work as aliases. So the real question is not which one to use, but which work to delegate at all, and to which subagent.

What a subagent is

A subagent is a Markdown file with YAML frontmatter. The frontmatter says what it is called, when to use it, what it may touch and which model it runs on; the body is its system prompt. Put it in .claude/agents/ and it belongs to the project, where it can be checked into version control for the team. Put it in ~/.claude/agents/ and it is yours in every project.

---
name: test-fixer
description: Fixes one failing test. Use when a single test fails and the cause is not yet known.
tools: Read, Grep, Glob, Edit, Bash
model: sonnet
---

You fix one failing test. Reproduce it, find the cause, make the smallest change
that fixes it, and rerun the test file. Report the cause, the files you changed,
and the test output. Do not refactor anything you were not asked to touch.

Only name and description are required. Leave tools out and the subagent inherits the tools of the main conversation, MCP tools included; list them and it gets only those. model takes an alias such as sonnet, opus or haiku, a full model ID, or inherit. There are further fields — disallowedTools, permissionMode, maxTurns, mcpServers, isolation: worktree among them — but the four above are the ones that decide behaviour.

Claude Code also ships built-in subagents: Explore and Plan, both read-only, for searching a codebase and researching a plan, and a general-purpose one with the full tool set for multi-step work.

How Task hands work to a subagent

When Claude decides to delegate, it calls the tool with a prompt it writes itself — a summary of what the subagent should do. The subagent starts fresh with its own system prompt, that delegation message, your CLAUDE.md files (Explore and Plan skip those to stay fast), a snapshot of git status, and any skills its definition preloads. It does not get your conversation history.

Claude picks the subagent from the description fields, so write them as instructions: “Use when a single test fails” is better than “Testing expert”. You can also be explicit. Name it in your request — “use the test-fixer subagent on the checkout test” — or @-mention it, which guarantees it runs.

When the subagent finishes, the main conversation receives its final result and nothing else↗ (opens in a new tab). None of the intermediate tool calls, file reads or test output come back. That is the point of the design, and it is also the thing to plan around.

Context isolation, and why it helps

A test run that prints four thousand lines, a search across two hundred files, a log you need one line from: in the main conversation those fill the context window and push out what you were actually discussing. In a subagent they fill the subagent’s window, and the main conversation gets back a paragraph. The Claude Code documentation↗ (opens in a new tab) puts it plainly: hand work to a subagent when it “produces verbose output you don’t need in your main context”.

Isolation also means restriction. A reviewer subagent with only Read, Grep, Glob cannot edit a file however it is prompted, which is a stronger guarantee than asking nicely in the main conversation.

Running several at once

Subagents can run in the foreground, where the main conversation waits for them, or in the background, where you keep working and their results arrive as notifications. Several can run at the same time, and a subagent can spawn subagents of its own, up to three layers below the main conversation by default. Each one sends its own requests, and they count towards the same usage limits as your main session.

Parallel work is safest when the pieces do not share files. Setting isolation: worktree gives a subagent its own git worktree. For workers that need to talk to each other rather than just report back, Claude Code has an experimental agent teams↗ (opens in a new tab) mode with a shared task list; for most work, subagents are the lighter tool.

When to delegate, and when not to

Following the documentation’s own guidance, keep work in the main conversation when:

• It needs back-and-forth with you, or several rounds of refinement.
• Planning, building and testing all lean on the same context.
• It is a quick, targeted change — a subagent starts cold and spends time finding its bearings.

Hand it to a subagent when:

• It produces a lot of output you only need the conclusion of.
• You want hard limits on what it can touch.
• It is self-contained and can come back as a summary: one failing test, one module reviewed, one question answered.
• There are several independent pieces that can run side by side.

Tracking what each subagent did

Here is the catch. The main conversation sees each subagent’s summary. You, reading the main conversation afterwards, see even less: a line saying a subagent ran, and whatever Claude chose to say about the result. Run five in the background and by the end of the afternoon the only complete record of who did what is scattered across transcripts nobody will open.

The fix is to record outcomes where people already look. One card on a board per delegated job, and one comment per outcome: what it found, what it changed, how it checked. If your board is fenbs connected over MCP, subagents inherit its tools unless you restrict them, so you can let a subagent comment for itself by listing the tool by its MCP name.

tools: Read, Grep, Glob, Edit, Bash, mcp__fenbs__fenbs_get_item, mcp__fenbs__fenbs_comment

Then end its prompt with “Comment your result on the card you were given, starting with your name.” The sign-off matters: every subagent in a session connects through the same sign-in, so fenbs records all of them as Claude acting for you. The name at the start of the comment is what tells test-fixer’s report from reviewer’s.

Put the card’s ref in the delegation. “Use test-fixer on BUG-042” gives the subagent a place to read the problem from and a place to report to, and it means the delegation message Claude writes can be short: the detail is already on the card, written by whoever filed it. When several subagents run side by side, one card each keeps their results from blurring together, and a card still sitting in In Progress at the end of the day is the subagent that did not come back.

If you would rather subagents did not touch the board, keep the write in the main conversation: tell Claude in CLAUDE.md to comment each subagent’s result on the matching card when it comes back. Either way the review is the board’s history and each card’s comments, not the transcripts — the same idea as a task-tracking workflow for Claude Code, applied one level down.