Subagents and Parallelism: Independent Context, a Tool Allowlist, Worktree Isolation, and Result Aggregation

What a subagent is: a one-shot loop, not another user

Start by correcting the impression that sends people off course. A subagent is not "another user talking to your Agent," and it is not a new architectural layer. It is the same run() loop from day five, run once more, with four things swapped out: a different message array, a smaller tool table, a tighter budget, and a different working directory.

That claim has a hard test attached. In today's lab, not one line under kernel/ changes — no field is added to the message, tool or event protocols, and the loop is untouched. A subagent wraps around the loop; it is not a branch inside it.

So what does "independent" actually mean? Three things, each blocking a different kind of failure.

An independent message array blocks contamination. A subagent doing one small job may need seven or eight round trips: read the file, edit it, notice the edit was wrong, edit again. Those round trips are worth nothing to the main session and occupy its window for real. Worse, they drag it off course — the main session was thinking about how to break the requirement down, and now its context is full of "the indentation on line 37 is off."

An independent allowlist blocks wandering. Fewer tools, fewer chances to pick the wrong one. A subagent that only has to edit documentation gains nothing from a tool that runs commands, and carries all the downside of it suddenly deciding to run a build.

An independent budget blocks collateral damage. One subagent spinning until it hits a ceiling should not burn through the allowance for a different job. Day six's LimitTracker is reused here verbatim, just with tighter numbers — do not build a second ledger for subagents, or you will shortly own two sets of books that disagree.

There is one more rule, and it runs the other way: a subagent must never inherit the main session's system prompt. That prompt is full of things that are only true of the main session — the conversation may have been compacted, the user pastes material with @ references, skills may appear on their own, and when something is unclear you can ask. None of that holds for a subagent: it has no history, nobody to ask, and no next turn. Inheriting the prompt does not leave it "knowing a bit more." It leaves it waiting for something that will never happen.

The allowlist: authorization happens at the moment of dispatch

The implementation is simple: pick a few ToolDef objects out of the parent registry by name and register them again. What matters is that it reuses the same tool objects. Truncation (day three), approval (day five) and repeat detection (day six) all hang off the ToolDef interface, so reusing the objects carries every one of those mechanisms into the subagent with nothing rewritten.

export function buildSubRegistry(parent: ToolRegistry, allow: string[]): SubRegistry {
  const registry = new ToolRegistry()
  const unknown: string[] = []
  const blocked: string[] = []
  for (const name of [...new Set(allow)]) {
    // The dispatch tool never enters a sub-table, even if the allowlist names it
    if (name === DISPATCH_TOOL) {
      blocked.push(name)
      continue
    }
    const tool = parent.get(name)
    // A misspelled tool name must be reported: silently ignoring it looks like
    // "this subagent got nothing done"
    if (!tool) {
      unknown.push(name)
      continue
    }
    registry.register(tool)
  }
  return { registry, unknown, blocked }
}

def build_sub_registry(parent: ToolRegistry, allow: Iterable[str]) -> SubRegistry:
    registry, unknown, blocked = ToolRegistry(), [], []
    # dict.fromkeys dedupes and keeps order, steadier than a set — tool order
    # ends up in the prompt
    for name in dict.fromkeys(allow):
        if name == DISPATCH_TOOL:
            blocked.append(name)
            continue
        tool = parent.get(name)
        if tool is None:
            unknown.append(name)
            continue
        registry.register(tool)
    return SubRegistry(registry=registry, unknown=unknown, blocked=blocked)

The line about the dispatch tool never entering a sub-table is a hard rule, not a precaution. Let subagents dispatch subagents and the dispatch tree has no boundary: the budget stops adding up (whose account does the third level spend from?), and when something goes wrong you cannot say which level edited the file. If you want more layers, build them explicitly. Do not let recursion happen by default.

The allowlist also answers a permission question on the way past: where exactly does approval happen?

It happens once, at dispatch. dispatch_agents is itself a tool that changes things, so it passes through day five's approval gate — and inside the subagent there is no further gate. That is not laziness. Approving every step is theater here: a user can understand "send two workers to do these two jobs, and they may only read and edit files," and cannot understand a subagent's seventh edit_file, because they cannot see its context and have nothing to judge it on. The boundary of authorization moves to the allowlist instead: if no command-running tool is on the list, no command can ever run. One authorization a person can understand beats ten confirmations they cannot.

Isolation by worktree: a shared working tree guarantees collisions

Now for the most concrete part of the day. What happens when two subagents edit files in one repository at the same time?

Not "sometimes they conflict." You cannot know what happened. A and B both read calc.js. A writes its change back; B, still holding the copy it read, performs an exact replacement — and day four's rule that the old text must match verbatim saves you, once: B's replacement fails. Next time B edits a different passage, the match succeeds, and the file now holds A's change and B's change together, two changes never designed with each other in mind. A green test run does not mean it is right, only that those two happened not to collide.

So isolation is not an optimization, it is the precondition for parallelism. That is exactly what git's worktree is for: one repository can be checked out into several directories, each with its own HEAD and index, while the object store is shared — opening a desk is a constant-cost operation, and a two-gigabyte repository does not get copied twice.

A real implementation runs these four commands, none of them mysterious:

git worktree add --detach ../.mca/agents/calc-guard HEAD   # open a desk
# ...the subagent works in this directory, its cwd pointing here...
git -C ../.mca/agents/calc-guard diff HEAD                 # collect its output
git worktree remove --force ../.mca/agents/calc-guard      # pack up

One thing has to be said plainly: what this course's lab uses is not a real git worktree. Our sandbox repo work/repo has not been under git since day one (the seed.ts that generates it is a frozen file and does not change all course), so there is no object store to lean on, and the lab simulates a desk by copying the directory and recording its contents at the moment of dispatch. The two share the same semantics — take a baseline at dispatch, work only in your own room, collect the difference between baseline and now — so the conflict rules below hold just as well with real git underneath. But the simplified version does not recognize renames, does not handle binary files, and does not preserve permission bits, and real git does all three. Do not lift the simplified version into production as an implementation reference.

One piece of timing is easy to get wrong: the baseline must be taken at the moment of dispatch, not by comparing against the main working tree at collection time. During the seconds a subagent works, the main working tree may already have moved under someone else's hand — another subagent, or the user's editor. Treat an already-changed scene as the baseline and the computed difference will include things that subagent never touched.

flowchart TD
  A[Main session: the model splits the job into two work orders] --> B[Approval gate: the user approves once]
  B --> C1[Desk calc-guard<br/>own messages, allowlist, budget]
  B --> C2[Desk doc-writer<br/>own messages, allowlist, budget]
  C1 --> D1[Difference from baseline to now]
  C2 --> D2[Difference from baseline to now]
  D1 --> E[Three-way comparison]
  D2 --> E
  E -->|Different files| F[Write to disk and feed back a structured receipt]
  E -->|Same place changed| G[Report a conflict, write nothing]

How results come back: a receipt, not a transcript

The subagent is done. What should go back to the main session?

The intuitive answer is "paste back what it said," which hands straight back the window you just saved. What should come back is a structured receipt: who it was, what the work order said, whether it finished, which files it changed, which tools it used, what it cost, and its closing sentence. Everything it said along the way stays on its side and is discarded with it.

The lab's receipt looks like this — seventeen lines, and the shape is reproducible offline:

Dispatched 2 subagents. Receipts:
 
[calc-guard] done  order: add a divide-by-zero guard to divide in src/calc.js,
                   throwing "divide by zero" when the divisor is 0
  changed: src/calc.js
  tools used: edit_file
  usage: 1 tool call / about 398 tokens / 458ms
  receipt: src/calc.js updated: divide throws "divide by zero" when the
           divisor is 0; all other behavior unchanged.
 
Merge result: 2 files written, 0 conflicts.
  README.md -> changed by doc-writer, written
  src/calc.js -> changed by calc-guard, written

Three details deserve their own mention. Keep only what was said on the last turn: the "let me take a look first" lines are process, not conclusion, and cutting at each tool call is a good enough boundary. Truncate the receipt: one chatty subagent should not blow out the main session's window. Put conflicts first: a conflict is the thing in a dispatch that most needs a human decision next, and the model weights the first lines of a long text most heavily.

Conflicts on aggregation: two people changed the same place

This step is most often assumed to be easy. The intuitive implementation is "write each subagent's changes back in order," which means last writer wins: both receipts say "done," the main working tree holds one of the changes, and nothing on screen says so. This is the classic silent data loss of parallel Agents, and today's biggest trap.

The right approach is a three-way comparison: what the baseline was, what this side changed it to, and what the other side changed it to. Three rules, blunt but honest.

for (const [file, edits] of [...byPath].sort((a, b) => a[0].localeCompare(b[0]))) {
  const by = edits.map((e) => e.by)
  const versions = new Set(edits.map((e) => e.after))
  // Rule three: several people produced different versions — write none of them,
  // because you have no way to judge which one is right
  if (versions.size > 1) {
    entries.push({
      path: file,
      by,
      action: 'conflict',
      why: `${by.join(' and ')} produced ${versions.size} versions`,
    })
    continue
  }
  // The main working tree drifts too: if the baseline no longer matches, do not
  // write, or you will silently overwrite what someone just saved
  if ((current.get(file) ?? null) !== (edits[0]?.before ?? null)) {
    entries.push({ path: file, by, action: 'conflict', why: 'this file changed in the main working tree after dispatch' })
    continue
  }
  // Rules one and two: one person changed it, or several produced identical
  // content — write it once
  applied.set(file, edits[0]?.after as string)
  entries.push({ path: file, by, action: 'apply', why: by.length > 1 ? 'identical content' : 'written' })
}

for file, edits in sorted(by_path.items()):
    by = [e.by for e in edits]
    versions = {e.after for e in edits}       # a set: we only care how many distinct versions
    if len(versions) > 1:
        entries.append(MergeEntry(file, by, "conflict", f"{' and '.join(by)} produced {len(versions)} versions"))
        continue
    if current.get(file) != edits[0].before:  # the main tree drifted, the baseline no longer counts
        entries.append(MergeEntry(file, by, "conflict", "this file changed in the main working tree after dispatch"))
        continue
    applied[file] = edits[0].after
    entries.append(MergeEntry(file, by, "apply", "identical content" if len(by) > 1 else "written"))

Two of those judgments are worth explaining.

Why write nothing on a conflict instead of picking one? Picking automatically requires a way to tell which is right, and you do not have one. Real git's line-level three-way merge can combine changes that do not overlap, which needs baseline line information plus a merge algorithm; this course leaves that to real implementations and guarantees one thing: nothing is lost silently. Reporting a readable conflict always beats quietly producing a version nobody designed.

Why is identical content not a conflict? That is one job done twice; write it once and move on. Report it as a conflict and the conflict signal becomes cheap, people stop reading it — and a warning nobody reads is no warning at all.

The cost of parallelism: when it is not worth it

Everything so far has been about doing parallelism correctly. This section is about when not to do it.

Look at the bill first. In the lab's dispatch, the main session's turn used 1405 input and 51 output tokens, and all that scrolled past on screen was one line saying two subagents had been dispatched. Then /agents unfolds the hidden part: calc-guard about 398, doc-writer about 363, 761 tokens the main session never saw and you pay for all the same. (Those figures come from the offline estimator and are identical across two consecutive runs on the same machine; the timing columns only support relative comparison.)

That is parallelism's first cost: every subagent pays for the system prompt and the tool table all over again. Context cannot be shared; that is a consequence of isolation, not a gap in the implementation. The smaller the task, the larger that fixed cost looms — dispatch a subagent to change one line of copy and explaining who it is and what it may use costs more than the work.

The second cost is debugging. When a serial run goes wrong you read back along one event log. In parallel there are N interleaved timelines, and the log is written in arrival order — two subagents' output ends up threaded together, and telling at a glance which sentence belongs to whom is hard. This is why a receipt must carry the desk name: it is your only attribution clue.

The third cost is merging. The rules in the last section are already the minimum version; real situations add renames, deletions and binary files. You committed to those costs the moment you chose to parallelize; the invoice just arrives later.

So the criteria can be stated bluntly. Three kinds of work should not be sent out:

Turned around, there is a very serviceable self-check for work that does suit parallelism: if these two jobs were given to two real people at the same time, would they need to talk to each other? If yes, do not dispatch. If no, that is where parallelism belongs. The lab's two jobs — add a divide-by-zero guard to divide, and add a paragraph to the README — are typical: different files, and whoever finishes first does not affect the other.

One boundary to close on, so today does not blur into the days ahead: today is about working at the same time and not stepping on each other. Tomorrow's background tasks are a different thing — how a long-running job reports back without interrupting the conversation, where the difficulty is lifecycle and notification, not isolation.

Source Reading

Hands-On Lab

Today leaves five exercises, all of the "runs fine without them, and fails silently" kind: a shared working tree, an allowlist that does nothing, subagents spending the main session's budget, last-writer-wins on merge, and prose fed back instead of a structured receipt. The starter passes six of thirteen unmodified.

1. Make opening a desk really copy an independent worktree, and take the baseline at the moment of dispatch, then watch the isolation check go from red to green — the main working tree should not change by one byte before the merge.
2. Get the allowlist right: register only the named tools, report misspelled names, and hard-block the dispatch tool itself, then watch the parent's 9 tools narrow to 2.
3. Give each subagent its own budget, then squeeze one of them to a single round and watch it hit its own ceiling while the other is untouched.
4. Switch the merge to a three-way comparison and run the conflict command from the README: two subagents change one file to different versions, and it should report a conflict and write nothing.
5. Turn the feedback into a structured receipt, run MOCK=1 SELFTEST=1 pnpm start to see all thirteen checks pass, then use /agents to see how many tokens that dispatch quietly spent.

Acceptance is five ticks: all thirteen self-test checks pass; the two subagents' time ranges genuinely overlap; the main working tree is untouched before the merge; nothing is written when one file is changed to two different versions; and no desks are left behind under work/agents.

Interview Questions

Today's three questions test engineering judgment about parallel Agents, not "what is multi-agent":

1. What should a subagent inherit from the main session, and what must it never inherit?
2. Editing one repository in parallel, what do you isolate with? How are conflicts found and handled?
3. Which tasks suit delegation to a subagent, and which get worse in parallel?

Full prompts, analyses and key points are in this course's day-seventeen question bank. Question three discriminates most — most people answer "parallelize anything separable," and few can state both the fixed cost of dispatch and the "do they need to talk to each other" test.

Checklist and Tomorrow

• I can say that a subagent is the same loop run again, and why no protocol field changed today
• I can name what each of the three kinds of independence blocks
• I can explain why a subagent must not inherit the main session's system prompt
• I can say why the dispatch tool may never enter a subagent's allowlist
• I can say why approval happens only at dispatch, and what carries the authorization boundary instead
• I can explain why a shared working tree is not "sometimes conflicts" but "you cannot know what happened"
• I can name the four real git worktree commands, and why it is cheaper than copying a directory
• I can say why the baseline must be taken at the moment of dispatch
• I can name the fields a receipt carries, and why conflicts go first
• I can explain why merging needs a three-way comparison, and why a conflict writes nothing
• I can name parallelism's three costs, and the three kinds of work not to dispatch

Tomorrow is D18, "Hooks and Background Tasks: Lifecycle Hooks, Deterministic Checks, and Notifications That Don't Interrupt the Conversation." Today split the work so it happens at the same time; tomorrow makes certain checks happen automatically at fixed moments — one governs division in space, the other governs points in time.