Subagents

Writing a good brief

Imagine leaving a note for a temp who starts while you're away. They can't ask you anything, so the note has to carry it all. The brief is the subagent's whole world. Include:

1. The goal, and why it matters.
2. What's known: what the parent already found or ruled out.
3. Where to look: files, folders, services.
4. The output wanted: format and length ("a list of path:line, under 20 items").
5. Limits: read-only, time budget, what not to touch.

"Find bugs" is a weak brief. "Review src/auth/ for ways an expired session token could still be accepted. We already checked verify_token. Report each issue as path:line and one sentence, most serious first" is a strong one.

def missing(brief):
    text = brief.lower()
    checks = {
        "the goal": ["find", "why", "fix", "check", "list"],
        "where to look": ["src/", "file", "folder", "repo"],
        "what to return": ["return", "report", "answer with", "list of"],
        "what's been ruled out": ["already", "not the", "ruled out"],
    }
    return [part for part, words in checks.items() if not any(w in text for w in words)]

print(missing("Look into the login bug."))
print(missing("Find why login fails after a password reset. Look in src/auth. "
              "It's not the session store, I already checked. Return the file and line."))

Parallel subagents

Three people can search three floors at once. Independent subagents can run at the same time too. On a normal machine:

from concurrent.futures import ThreadPoolExecutor

briefs = {"billing": "...", "search": "...", "accounts": "..."}
with ThreadPoolExecutor(max_workers=3) as pool:
    futures = {name: pool.submit(run_subagent, "explorer", brief) for name, brief in briefs.items()}
    results = {name: f.result() for name, f in futures.items()}

The parent then combines the three short reports. (Browsers have no threads, so the exercise runs subagents one at a time.)

HARNESS_TOOLS = {"read", "grep", "glob", "edit", "bash", "web_fetch"}

AGENT_TYPES = {
    "explorer": {"system": "Find code and report locations. Never edit.",
                 "tools": ["read", "grep", "glob"], "max_turns": 15},
    "reviewer": {"system": "Review changes for bugs. Report, don't fix.",
                 "tools": ["read", "grep", "git_diff"], "max_turns": 10},
}

for name, spec in AGENT_TYPES.items():
    offered = sorted(t for t in spec["tools"] if t in HARNESS_TOOLS)
    print(name, offered)

def can_delegate(depth, max_depth=1):
    return depth < max_depth

print(can_delegate(0), can_delegate(1))

Three things people get wrong

A subagent can't see your conversation. It starts with nothing but its brief. Everything you worked out over the last hour, including the file you already ruled out, is invisible to it unless you write it down. This is the most common reason subagents disappoint: the brief felt complete to the person writing it, since they had all the context.

Don't delegate small things. You wouldn't send someone to the archive for a book on your own shelf. Spawning a subagent costs thousands of tokens before it does any work. If you know the file and the line, read it yourself. Subagents pay off when the search is broad, and you only need the conclusion.

Parallel subagents must not touch the same files. Two agents editing one file will overwrite each other, or make changes based on versions that no longer exist. Keep parallel ones read-only, or give each its own folder or worktree.

Fewer tools, not more

Handing a subagent every tool the main agent has feels generous. It's also risky. A subagent searching the docs doesn't need to send email, and if a page it reads contains a prompt injection, then any tool it holds can be misused. Give it only what the job needs.

There's a benefit beyond safety too. With fewer tools, each call carries fewer definitions, and the model has fewer ways to wander off. A research subagent with only read and search tools stays focused on reading and searching.

When not to use them at all

Work that needs many small decisions in sequence is usually better in one agent, because each step depends on what the last one found. Subagents suit tasks that split cleanly and don't need to talk to each other. If you find yourself passing long notes between them, one agent would probably have done it better.