Delegate big problems to a fresh agent

The parent agent's dilemma

Imagine asking Claude Code to "figure out how concurrency is handled in this 100K-line Rust repo." The naive approach: it runs ls, cat, grep, explores everything in the main context.

The problem: that exploration packs 30 tool_results into messages[], each a few thousand tokens. By the time it starts writing an answer, the context is already stuffed - a few more steps and it hits the limit, with a scattered result.

s04's solution: hand the exploration off to a new agent. The new agent starts fresh from messages=[], explores on its own, and returns only a summary to the parent. The parent's context only gains one entry: "called the task tool, result was X." Clean.

def run_subagent(prompt: str) -> str:
    sub_messages = [{"role":"user", "content": prompt}]  # fresh context
    for _ in range(30):  # safety cap to prevent runaway
        response = client.messages.create(..., messages=sub_messages, tools=CHILD_TOOLS, ...)
        ...
    # return only the final text; discard all intermediate reasoning
    return "".join(b.text for b in response.content if hasattr(b, "text"))

Parent vs child context comparison

This widget simulates a real task: "List all places in this repo that call a deprecated API." Run it two ways - (A) parent does it all, (B) spawns a subagent - and compare the final context sizes side by side.

CHILD_TOOLS: what tools the child gets

There's an easy-to-miss detail in s04: the child agent does not get the task tool.

# child can only use basic tools - cannot spawn grandchildren
CHILD_TOOLS = [bash, read_file, write_file, edit_file]

# parent has one extra: task
PARENT_TOOLS = CHILD_TOOLS + [task]

Why? To prevent recursive spawning from becoming a tree explosion. One subagent spawning four sub-subagents, who each spawn four more - within a few levels you have dozens of concurrent calls, blowing past both token budgets and API rate limits. s04's contract: spawning is flat, parent to child one level deep. Claude Code's real implementation works the same way - the Task tool cannot call the Task tool.

What the parent can and can't see

A quick responsibility check. For each statement below, decide True or False.