Delegate a noisy investigation to a subagent with isolated context

The ledger audit is exactly the kind of task that should never run in your main thread. It’s high-volume — pages of grep output, dozens of files opened once and never referenced again — and self-contained: you don’t need the journey, only the destination, the map of where the writes happen. That shape, verbose work whose output you’ll never look at again, is the textbook case for delegating to a subagent.

Just ask for it

There’s no special command. You describe the work and say to use a subagent, and Claude spawns one:

> use a subagent to map every place the payments code writes to the ledger,
  and every test that covers those writes. return a table — write site,
  the function, and the test files that exercise it.

What happens next is the whole point. The subagent starts with a fresh, isolated context window — it doesn’t see your conversation history or the files you’ve already read; Claude writes it a delegation message describing the task, and it works from there. Then it goes to town in its own memory:

> use a subagent to map every place the payments code writes to the ledger...

  ⏵ Agent (general-purpose)  mapping ledger writes
     ⎿ Grep  "INSERT INTO ledger"  src/        → 14 hits
     ⎿ Read  src/services/charge.js
     ⎿ Read  src/services/refund.js
     ⎿ Read  src/jobs/reconcile.js
     ⎿ Read  src/webhooks/gateway.js
     ⎿ Grep  "ledger" test/                     → 38 hits
     ⎿ Read  test/charge.test.js
     ⎿ ... 20 more reads
  ⎿ Done (31 tool uses)

  The subagent found four write sites:

  | Write site            | Function            | Tests                          |
  |-----------------------|---------------------|--------------------------------|
  | charge path           | postCharge()        | test/charge.test.js            |
  | refund path           | postRefund()        | test/refund.test.js            |
  | nightly reconcile job | reconcileLedger()   | test/jobs/reconcile.test.js    |
  | gateway webhook       | onSettlement()      | test/webhooks/gateway.test.js  |

  The reconcile job's writes are not covered by any test.

Look at what landed in your conversation versus what didn’t. The thirty-one tool calls — every grep result, every full file the subagent read — stayed in its context and were thrown away when it finished. What came back to your thread is the table and one sharp finding: the reconcile job is untested. You asked a sprawling question and got back a tight answer, and your main session is no heavier than if you’d typed that table yourself.

Why this protects the main context

It helps to see the cost you avoided. Run that audit inline and your window fills with the raw material:

in your main thread (inline)        in your main thread (delegated)
────────────────────────────        ───────────────────────────────
38 test-file greps                   "use a subagent to map ledger writes"
24 full files read                   the 4-row table
14 source-file greps                 "reconcile job is untested"
the actual migration work…           the actual migration work…
   ↑ buried under file dumps            ↑ still right there, in reach

Same answer, wildly different footprint. The migration you came here to plan is still the most recent, most prominent thing in your context — not pushed twenty file-reads into the past where the agent half-forgets it. This is the same context-as-a-resource discipline from the Sessions & context chapter, but bought up front instead of reclaimed after the fact: rather than compacting the noise away once it’s accumulated, you arrange for it never to enter the thread at all.

The docs put the rule plainly: reach for a subagent when a side task would flood your main conversation with search results, logs, or file contents you won’t reference again — see isolate high-volume operations for the canonical framing. Running the test suite, fetching documentation, chewing through log files — anything where you want the verdict and not the transcript.

When to keep it in the main thread instead

Delegation isn’t free, and the docs are explicit about the other side. Keep the work in your main conversation when it needs frequent back-and-forth, when several phases share real context — planning into implementation into testing — or when it’s a quick, targeted change where spinning up a fresh agent that has to re-gather context just adds latency. The current guidance lives at choose between subagents and main conversation.

The test is the same one from delegation everywhere: would I hand this to someone, get back a paragraph, and be happy? The ledger audit, yes — you want the map, not the reading. A delicate refactor you’ll be steering line by line, no — the context the subagent throws away is exactly the context you need.

One subagent gave you a clean map of four write sites. But notice they’re independent — the charge path, the refund path, the reconcile job, and the webhook don’t depend on each other. When a problem splits cleanly like that, one worker grinding through them in sequence is leaving speed on the table. Next we fan the work out.