Subagents

This tiny program puts a number on why delegation is worth it. It compares two ways of doing several file-heavy subtasks: cramming everything into one agent's memory (inline) versus sending each subtask to a subagent that returns only its conclusion (delegated).

1. context_used(main_tokens, subtasks, tokens_per_subtask, inline) is a function (a reusable recipe) that estimates how many tokens — the chunks of text a model reads and is billed for — end up in the main agent's memory.
2. When inline is True, it returns main_tokens + subtasks * tokens_per_subtask: every subtask's full material (8000 tokens each) piles into the one context.
3. When inline is False (delegated), it returns main_tokens + subtasks * 100: each subagent reads its own big pile privately and sends back only a small ~100-token conclusion.
4. The two print lines run the same 6 subtasks both ways so you can see the difference side by side.

What the output means: Inline costs 50000 tokens (2000 + 6×8000); delegated costs only 2600 (2000 + 6×100). Same work, roughly 10× less clutter in the main thread — which is exactly what lets long, complex work fit in the context window.

Try this: Change tokens_per_subtask from 8000 to 20000 (heavier files) and re-run. The inline number explodes while the delegated number barely moves — that gap is the case for subagents.

This is not Python — it's a subagent definition file (Markdown). It's how you actually create a subagent: a small header (called front-matter) describes the agent, and the text below it is the agent's instructions (its system prompt). Save this as a .md file and the tool can spin it up as a helper.

1. The block fenced by --- lines at the top is the front-matter — settings in key: value form. Everything after the second --- is the prompt.
2. name is the agent's id; description tells the main agent when to reach for it ("use proactively after code changes") — this is what makes delegation automatic.
3. tools: [Read, Grep, Bash] is the allow-list of what this agent may do. A reviewer only needs to read and search code, so it gets no Edit or git push — that's least privilege: give each agent only the tools its job needs.
4. model: sonnet picks which model runs it. The instructions below tell it to find bugs, cite file:line, and return only the findings — a scoped job with a clean output.

Try this: Imagine adding Edit to the tools list. Now a review could silently change your code — the opposite of what you want. Keeping the list narrow is a safety feature, not a limitation.

Because each subagent works in its own context, you can run many at once instead of waiting for each to finish. This program estimates the real-world time saved (wall-clock time — the time you actually wait) for 6 reviews done serially versus in parallel.

1. wall_clock(tasks_secs, parallel, workers=4) takes a list of how long each task takes, whether to run in parallel, and how many can run at the same time (workers).
2. If parallel is false, it returns sum(tasks_secs) — every task runs one after another, so the times simply add up.
3. If parallel, it splits the tasks into waves of 4 at a time: math.ceil(len(tasks) / workers) rounds up the number of waves (6 tasks ÷ 4 workers = 2 waves). Each wave takes as long as its slowest task, so time ≈ waves × max(tasks_secs).
4. The test data is 6 module reviews at 30 seconds each; the two prints show both strategies.

What the output means: Serial takes 180 s (6×30). Parallel takes 60 s — 2 waves × 30 s each. Same work, 3× faster wall-clock, purely from running independent subagents side by side.

Try this: Raise workers to 6 so all six fit in one wave, and the parallel time drops to 30 s. More workers help only until every task fits in a single wave.

This models a powerful team pattern: fan-out (send one subagent per unit of work), then verify (a second subagent double-checks each finding before you trust it). Here the 'subagents' are plain functions so the pattern is easy to see without any real API calls.

1. review_module(name) plays the role of a review subagent: given a module name it returns a list of findings. The fake dictionary just supplies canned results so the demo runs offline (auth has a secret, billing a money bug, search is clean).
2. verify(finding) is the verifier subagent: it returns True only if the finding looks genuinely serious (mentions a "secret" or "money"). This is the "try to refute it" step that filters out weak claims.
3. raw = [f for m in modules for f in review_module(m)] is the fan-out: it runs the reviewer over every module and collects all findings into one list.
4. confirmed = [f for f in raw if verify(f)] is the verify step: it keeps only the findings that survive the check. The loop then prints each survivor.

What the output means: raw findings: 2 | confirmed: 2 — two issues were found and both passed verification (the empty search module contributes nothing). You then see the auth secret and the billing money bug listed as the trusted, synthesized result.

Try this: Add "typo" to one module's fake findings and re-run. It shows up in raw but not in confirmed, because verify rejects it — that's the adversarial check earning its keep.

Subagents aren't free — each one spins up its own context, which costs time and money. This function encodes the rule of thumb for when to delegate and when not to, so you don't over-use subagents (a real anti-pattern).

1. should_delegate(independent, context_heavy, quick_edit) takes three yes/no facts about the work and returns a (decision, reason) pair.
2. The checks run in order, and the first match wins. if quick_edit: return False — a trivial change is faster done inline, so bail out immediately.
3. if independent and context_heavy → delegate to both isolate and parallelize (the ideal case). if context_heavy alone → still delegate, just to keep the main context clean.
4. If none of those hold, the final return False says it's not worth the spin-up overhead. The loop feeds four example cases through and prints each verdict.

What the output means: Each line pairs the inputs with the decision, e.g. (True, True, False) -> (True, 'isolate + parallelize'). The two True results are context-heavy work; the two False results are a quick edit and a trivial task — exactly when the main agent should just do it.

Try this: Trace should_delegate(True, False, False) by hand (independent but light, not a quick edit): it falls past every if to the last line and returns False — being independent alone isn't enough to justify a subagent.