Subagent—Break big tasks into small ones, each with a clean context

"Break big tasks into small ones, each small task with a clean context" — Subagent uses an independent messages[], without polluting the main conversation.

The problem

The Agent can plan now. But if a task is too big, such as "refactor the entire auth module", a TODO list alone is not enough. This task itself is a collection of dozens of small tasks, and putting them in the same conversation will drown them in context. Imagine the Agent is fixing a bug. It reads 30 files to trace the call chain, with 60 rounds of conversation in between. The messages list grows to 120 entries, most of which are the intermediate process of "tracing the call chain" and unrelated to the final goal of "fixing the bug".

These intermediate processes occupy context space and make the Agent increasingly "forgetful"; it can no longer remember what the original problem was.

Or, to put it another way, when you fix a bug, you "open a new terminal" to trace the call chain. Once tracing is done, you close the terminal, write the result into notes, and return to the original terminal to continue fixing the bug—The Agent also needs this capability: open an independent subprocess, give it an independent message list, and let it focus on doing one thing.

Solution

📍 The difficulty jumps up right here, so look carefully～

Keep the minimal hook structure and todo_write tool from the previous chapter; this chapter focuses on the newly added task tool. When calling it, spawn a child Agent with a brand-new messages[], which runs its own loop and, when finished, only passes summary text back to the main Agent. The conversation context is discarded, but the file system side effects (writing files, modifying files, running commands) remain in the working directory.

This is the concept of Subagent I mentioned earlier when introducing the designer's new toy Claude Code. The main agent, i.e., the Parent agent, is the Agent actually used by the user; it then splits tasks into several independent Subagents to do the work, and finally it reviews the results, strings them together, and hands the results to the user.

But it should be noted here that this child agent is not exactly the same as the Agent loop we introduced before: it has no task tool, so it cannot spawn new sub-subagents itself, and its security policy is not independent—it is subject to the permission management of the main agent's hook.

How it works

spawn_subagent, giving the sub-agent a brand-new messages list, running its own loop, and returning only the conclusion — this is the brilliance of this Subagent. It keeps the main Agent's context very clean, so compression won't happen so quickly.

In summary, the Subagent has 4 most critical designs:

Subagents in CC

More types of Subagents

Subagents in CC are more complex; they do not begin with the message from our conventional loop cycles. There are 3 types:

Scared to tears—these things above are all familiar, but you completely don't understand them? Don't worry, let's break them down and explain them one by one.

• Normal: This is the Subagent we see most often, an agent named xxx that we specify or that Claude Code specifies. For example, to review a contract, the boss says: "Have legal review it." The main agent is the boss, and legal is the Subagent.

• General: This is just an outsourced worker who does everything, not even worthy of a name, does everything. Still the same question as before: the boss won't say to give it to legal, only "give it to that new outsourced worker to do." Nobody cares what this outsourced worker does; just give it to them and that's it.

• Fork: This is the most complex one, and also the most impressive one in CC. We'll go into more detail on it later. Simply put, the boss copies himself, inherits all of the boss's context, and then works separately. If you know git, you'll find it's actually git's branch, Codex's worktree

Complex context control

Subagents are not fully isolated: file read state is shared. The degree of isolation for UI and notifications depends on the execution path. What CC does here is very complex, and the implementation is even more explosively complex.

Simply put, these agents are not truly fully isolated, communicating only results and input content; rather, there is a very complex isolation mechanism, where some things are isolated and some are not, and the isolation strategy differs depending on the situation.

The reason for doing this is to solve this problem: suppose you are a boss and you need your subordinates to do a task, requiring three employees A, B, and C. You send them the files and assign them the task. If it were the fully isolated situation of the earlier teaching version, then the same document would have to be read once by you and once by each of your three employees, which wastes too many tokens and is very inefficient. So CC did one thing: the context content in this respect is shared among the four of you, so it only needs to be read once, and whenever it is needed, it can be used directly.

Recursion levels and protection

CC introduced something calledabortController, which lets agents completely follow the command of the main Agent. When the main Agent says stop, all Subagents immediately stop and obediently comply.

In addition, they also made something calledqueryTracking, which makes it convenient for subsequent AI or humans to trace problems. For example, the main agent's thing is layer 0, employee A is layer 1, and so on, so it is easy to attribute whose problem it is and who is to blame :)

Another thing is Fork protection. This is what was just mentioned: a Subagent is not allowed to create subagents itself, that is, in a company, a big boss is not allowed to hand off to a small boss, a small boss to a team leader, and a team leader to a junior employee, with layer upon layer of nesting. In a company this is called layer-by-layer exploitation and architectural redundancy. The same applies in Agents, and it would also cause the CPU to explode.

Permissions bubble upward

CC has aPermissionBubblingmechanism: sub-agents cannot directly ask the user; they must bubble up to the main Agent, which then asks the user.

If a Subagent wants to delete a file during execution, it does not have permission to directly ask the user to choose allow or deny; it must tell the main Agent, and then the main Agent asks the user.

Asynchronous tasks

Between the main Agent and Subagents in CC, communication can be synchronous or asynchronous.

Synchronous mode

In synchronous mode, the main Agent really just waits the whole time for all the Subagents it has handed tasks to to finish and give it the results, that is,

老板
 ↓
派活
 ↓
等着
 ↓
等着
 ↓
等着
 ↓
拿结果

The advantage of this approach is that the process is clear, but the disadvantage is that the main Agent effectively does nothing for a rather long time, just waiting, so efficiency is not high.

Asynchronous mode

Asynchronous mode is what we learned in elementary school math: while boiling water, we can do other things. After the main Agent assigns tasks to Subagents, it goes off to do other things itself, and when the Subagents have finished the tasks, it then looks at the results.

老板
 ↓
派活
 ↓
继续干别的