Claude Code subagent

A Claude Code subagent is a separately-configured delegate that Claude Code dispatches to handle one scoped task in its own isolated context window, with its own system prompt, tool access, and permissions, returning a distilled result to the coordinating session.

How it works

A subagent is defined ahead of time as a named configuration: a description of what it is for, a system prompt that frames its job, an allowlist of the tools it may use, and a permission posture. When the coordinating session meets a task that matches that description, it hands the task off, and the subagent runs in a fresh context window the main session does not share. The subagent works on its own, and what returns to the caller is its final result, not the intermediate reading and reasoning it did to reach it. Because the window is separate, the subagent cannot see the caller's conversation unless that context is passed in, and the caller does not inherit the subagent's token history. The configuration is per-subagent, so two subagents in the same project can hold different tools and different permissions for different jobs.

Why it matters

The reason to reach for a subagent is usually containment rather than speed. Giving a task its own context window means a long or messy investigation does not crowd the main session, a wrong turn inside the subagent does not corrupt the caller's state, and a tool grant the subagent needs does not have to become a standing grant on the whole session. The trade-off is that delegation has overhead: defining the subagent, dispatching to it, and reconciling its result is work a task small enough to do inline does not need, and a vague description means the subagent fires for the wrong tasks or never fires at all. A subagent also returns less than it saw by design, so a task where the caller needs the full intermediate trail is a poor fit. It raises the floor on isolation; it does not remove the cost of coordination.

In practice

A project defines a subagent whose job is to search the codebase and report where a pattern appears, granted read-only access and no permission to edit. When the main session needs that search it dispatches the task, and the subagent reads through many files in its own window and returns a short list of locations. The main session continues from that list without ever loading those files into its own context, and because the subagent could not write, nothing it did could change the tree even if its search ran wide.

Practical considerations

A subagent is easy to conflate with two adjacent things it is not: a background agent that runs asynchronously outside the session, and an agent team that coordinates several long-lived agents; the subagent here is the in-session, configuration-defined delegate invoked for one scoped task. Its tool allowlist and permission posture are set on the definition, so the safe default is to grant a subagent the narrowest access its job needs rather than mirroring the caller's. The description is its routing surface, since the coordinating session decides to delegate based on how well a task matches it, so a sharp description is what gets the subagent invoked when it should be and left alone when it should not. Because only the final result returns, a subagent fits work that compresses to a small answer, a search, a verification, a focused edit, and fits poorly when the caller needs the reasoning rather than the conclusion. Pinning a subagent to a cheaper or faster model where the task does not need the strongest one is a cost lever, not a capability one.

Defined by Ready Solutions AI