Claude Code Subagents Explained for Engineering Leaders

An engineering lead opens Claude Code, describes a multi-step task, adding a payment webhook handler, wiring it to Stripe, and getting a security pass done before the PR goes up, and watches one context window try to hold all three jobs at once. By the time the security check starts, the session has read six files, planned an implementation, argued with itself over a bug in the retry logic, and burned through 60,000 tokens of context. The requirement from turn one has drifted. The model conflates "review this diff" with "the diff you and I are still mid-discussion about," and the review comes back softer than a fresh set of eyes would produce, because it isn't a fresh set of eyes, it's the same tired context trying to switch hats mid-conversation. This is the actual failure mode hiding behind the search term "claude code subagents explained": leads have heard the word, know Claude Code has some mechanism for it, and have no working model for what it changes or when to reach for it.

Why one long chat session cannot do what a subagent does

ChatGPT and Claude.ai give you exactly one context window per conversation. Every instruction, every pasted file, every clarifying question, every unrelated tangent, lives in the same growing thread. There is no mechanism to say "go read these 40 files and come back with a security finding, but don't bring the 40 files back with you." Everything you feed the model stays in its working memory for the rest of the session, so a long task degrades the way a long meeting does, the details from the start get fuzzier as more gets piled on top. Ask a generalist chatbot to review a diff for security issues right after it spent 30 turns writing that diff, and you get a reviewer emotionally invested in the code it just produced, not an independent check.

Cursor and GitHub Copilot solve a narrower problem well, fast, in-editor completions scoped to the file or function on screen. But neither has a subagent primitive either. There is no concept of dispatching a distinct actor with its own context window to go do a bounded task and report back a result. Everything Cursor's chat panel does happens inside the same session context as your main work. If you ask it to check for security issues, it's reasoning with the same context it used to write the code, the same blind spots, the same assumptions, just phrased as a second question in the same thread.

What a Claude Code subagent actually is

A subagent is a separate actor, invoked from your main Claude Code session, that runs in its own independent context window. It only sees what the main thread hands it, a task description, maybe a diff, maybe a directory to search, does its own reading and reasoning inside that isolated window, and then returns a final report to the parent thread. The parent's context grows by the size of that report, not by the size of the exploration it took to produce it. That's the whole mechanism. The discipline problem, the thing that actually determines whether Claude Code sessions stay useful past turn 40, is knowing which tasks belong in the main thread and which belong dispatched to a subagent. Getting that judgment call wrong in either direction has a cost: dispatch too little and your main context fills with exploration that didn't need to live there; dispatch too much and you lose the continuity a task genuinely needed.

A Claude Code subagent runs in its own context window and returns only a final report. The parent thread's context grows by the report, not by the work it took to produce it.

Tonone's Apex is built specifically to own that judgment call. It doesn't just write code in the main thread, it decides, task by task, whether a piece of work should stay in the conversation you're already having or get handed to a specialist running in its own window. Two of Apex's related specialists show up constantly in that decision: Atlas, who documents the architectural reasoning behind a delegation once it's made, and Pave, who audits whether the environment a new subagent-produced change lands in is actually set up correctly.

Apex decides what goes in-thread and what gets dispatched

The apex-plan skill is where Apex first draws this line. Given a rough brief, it scopes the work into S/M/L options and, as part of that scope, flags which pieces of the plan are conversational (need the ongoing thread's context to execute well) and which are boundable (have a clear input, a clear output, and no dependency on the rest of the conversation). Payment webhook logic that needs to match a product decision you're mid-debate about stays in-thread. A security audit of a finished diff, which needs nothing from the conversation except the diff itself, is boundable, and gets flagged for dispatch.

Once specialist work comes back from a subagent, apex-review is what integrates it. This is the step generalist tools have no equivalent for: reading the security subagent's report alongside the API contract, alongside the infra assumptions, and checking whether the findings from one specialist create a problem for another. A subagent's report is only useful if something in the main thread actually reads it critically instead of pasting it into the PR unread.

Tonone's Apex decides when a task belongs in your main Claude Code thread and when it belongs in a subagent. That judgment call is the whole discipline behind orchestration.

A worked example: dispatching Warden instead of reviewing inline

Priya leads a six-person engineering team at a 40-person fintech startup. She opens Claude Code and asks for a Stripe subscription webhook handler, then a security check on it before she opens the PR. Apex scopes the work with apex-plan, she approves the Medium option, and the build proceeds in the main thread: a handler for subscription.updated events, 9 files touched, 480 lines changed. By the time the implementation is done, the main thread sits at roughly 28,000 tokens, requirement, scoping, and three rounds of fixing a retry bug all still live in context.

Here is where the decision matters. The security check does not need Priya's conversation history. It needs the diff. Apex recognizes this as a boundable task and dispatches it, not to itself, but to Warden, Tonone's security specialist, running as a subagent in a fresh context window. Warden never sees the 28,000 tokens of build history. It reads the 9 changed files and the relevant Stripe webhook documentation, checks signature verification, idempotency handling, and the retry loop, spends its own roughly 15,000 tokens doing that exploration inside its isolated window, and returns a compact, structured finding.

Main thread (Priya's session), ~28,000 tokens in
> Build the Stripe subscription.updated webhook handler,
> then check it for security issues before I open the PR.

Apex: scope approved (M), Spine implementation complete.
  9 files touched, 480 lines changed.

Apex: this check needs the diff, not the conversation.
Dispatching Warden as a subagent.

  Warden (subagent, fresh context, 0 tokens in)
  Reads:    9 changed files, Stripe webhook signature docs
  Explores: signature verification, idempotency handling,
            retry loop behavior  (~15,400 tokens spent inside
            the subagent's own window)
  Returns:  2 HIGH, 1 MEDIUM
    HIGH    Missing Stripe-Signature header verification
            on POST /webhooks/stripe
    HIGH    Retry loop has no max-attempt cap, can hot-loop
            on repeated 4xx responses
    MEDIUM  Idempotency key not persisted, duplicate events
            can double-process a subscription change

Main thread receives: 1 report, ~460 tokens
Main thread total after review: ~28,460 tokens

(Est. cost if the review had run inline instead of as a
 subagent: ~43,400 tokens, and Priya's original requirement
 from turn 1 would now be 60+ turns back in scroll history.)

Apex takes Warden's report and runs apex-review against it, checking the two HIGH findings against the API contract Spine built and confirming neither fix requires reopening the retry logic decision from earlier in the thread. Atlas then writes a short atlas-adr documenting the decision to dispatch security review as a subagent rather than inline, useful the next time someone on Priya's team asks why the webhook PR shows a Warden-authored review comment instead of one from the same session that wrote the code. Separately, Pave runs pave-audit against the environment the webhook endpoint deploys into, confirming the Stripe signing secret is pulled from the secrets manager rather than hardcoded, a check that has nothing to do with the code diff and everything to do with where it runs.

The difference Priya notices isn't the quality of any single finding, it's that her main thread never had to hold 15,400 tokens of Stripe documentation exploration it didn't need to keep. Six turns later, when she asks a follow-up question about the original webhook requirement, the model is still reasoning from a 28,460-token context instead of a 43,400-token one bloated with an unrelated specialist's reading list.

A working rule for delegate versus do-it-yourself

Dispatch to a subagent when the task is read-heavy relative to its output (a security audit reads a lot and returns a short verdict), when the result needs to be independent of your ongoing reasoning (a review that agrees with you because it remembers agreeing with you earlier isn't a review), or when nothing about the task needs to persist in your main thread once the answer comes back. Keep it in the main thread when the next step depends on the specific reasoning trail you're already in, or when the task is small enough that the overhead of framing a clean handoff costs more than just finishing it inline. Apex applies this rule inside apex-plan automatically, but the rule itself is worth knowing even if you're driving Claude Code without any orchestration layer at all.

Tonone's Apex dispatches Claude Code subagents like Warden into independent context windows, so a security review returns findings without dragging its own exploration back into your main session.

Subagent orchestration: tonone vs the alternatives

The comparison below is specific to the subagent question, not a general capability comparison. It's about whether a tool can recognize a boundable task, hand it to an isolated context window, and integrate the result without polluting the thread that's still doing the main work.

None of this replaces good judgment, and Apex doesn't claim to remove the decision from you, it makes the decision explicit instead of implicit. The failure mode this fixes isn't a rare edge case. It's the default behavior of every long Claude Code session that tries to do build, debug, and review in one continuous thread: context grows past the point where the model can hold the original requirement clearly, and every subsequent answer gets a little less grounded in what you actually asked for. Subagents exist to stop that from happening to the parts of the work that never needed to share your thread in the first place.

Install and try

Tonone is free and MIT-licensed. Install it once and all 100 agents, including Apex, Warden, Atlas, and Pave, are available in your Claude Code session, ready to be dispatched as subagents the moment a task stops needing your main thread's memory. You pay only for Claude Code token usage during the work itself.