DEV Community: Mohammad Fauzel Sadeghizad

Giving a Coding Agent an Org Chart

Mohammad Fauzel Sadeghizad — Fri, 04 Sep 2026 18:48:03 +0000

Every agent harness eventually grows a "spawn a subagent" tool, and every one hits the same wall: the child's transcript flows back into the mother's context. Spawn three children to refactor three modules and the mother now carries three full transcripts — tool calls, failed attempts, whole-file reads — most of which she never needed. Context is an agent's scarcest resource, and the default subagent design spends it as if the children's work were the point. The outcome is the point. Subsessions is our answer: a protocol layer over the continuable-subagent runtime in our fork of the DeepSeek Harness. The hero picture is the whole idea:

              ┌───────────────────────────────┐
              │   mother session (planner)    │   sees: briefs + reports
              └──────┬────────┬────────┬──────┘   never: transcripts
           ┌─────────┘        │        └──────────┐
    ┌──────▼──────┐    ┌──────▼───────┐    ┌──────▼──────┐
    │  worker A   │    │  worker B    │    │  verifier   │
    │ owns a/*    │    │ owns b/*     │    │ leaf role   │
    └──────┬──────┘    └──────┬───────┘    └─────────────┘
           │ progress         │ final report
           └────────┬─────────┘
                    ▼
     bounded reports only → mother pays O(report)

The design rests on one invariant that outranks every convenience:

The mother's context grows by O(report), never by O(child transcript). The human sees the whole org tree; the mother sees only structured reports.

The shape of a subsession

A subsession is a real session — its own runtime SessionId, context window, tool permissions — that differs from a plain subagent in four ways.

It is role-typed. Spawn takes a role, never a model id; the preset's role table maps roles to tiers and depth caps. A role with depthCap: 0 is a leaf: the system asserts its tool filter denies subsession_spawn, so a worker can never become a mother — checked at role-definition time, not left to prompt goodwill.

It is brief-initialized. The mother writes a versioned brief (briefVersion: 1): mission, owned file globs, token cap, depth allowance, report contract (required sections + max report tokens), an optional verify list and continues: <predecessorId>. Validated field-by-field before anything starts; a rejection names the exact fields.

It is report-communicating. The child talks back through exactly one tool. A progress report is a heartbeat — quiet delivery, no wake. A final report settles the node forever and must satisfy the report contract, with a size gate that runs before structural validation: an over-cap report is rejected as REPORT_TOO_LARGE even if also malformed, so the size invariant is never traded away for a better error message. Reports are append-only, bounded to the last 50.

It is continuable. At any point a child can append a checkpoint to its journal — phase, state, decisions so far, next step — an append-only JSONL file per child; the registry holds only a pointer (workspaceFile:<path>#<line>). When a child dies, is killed, or finishes blocked, a fresh child can be spawned with continues: <predId>, the seed text carrying the checkpoint ref. Predecessors are never deleted.

The spawn pipeline is a pinned order, not vibes

Child creation runs nine checks in a fixed order, each short-circuiting into a canonical error code:

validateBrief → role exists → role safety → depth → tool filter
→ scope overlap vs live siblings → tree budget → concurrency caps
→ start child exactly once → register

Two deserve comment. Scope overlap is a conservative glob check against live siblings under the same mother — two children can't silently own the same files (SCOPE_OVERLAP names the sibling and the paths; allowOverlap: true is allowed but logged). Tree budget is declared-arithmetic: the sum of live descendant caps plus the new cap must fit inside the mother's declared budget — arithmetic, not metering (more below).

Architecture: decision cores with injected ports

The protocol splits into two kinds of code. Decision cores are pure functions over the registry and schemas — no harness imports, no I/O, no clock. planAndStartSpawn takes a SpawnPorts object (role table, config, an identifyMother() probe, a startChild spy target) and returns an outcome; acceptChildReport, sweepQuiescence, buildSuccessionBrief, handoverOf all share the shape. This made the protocol testable with spies before runtime wiring existed, and made check ordering a tested property.

Runtime wiring is a thin host plugin that adapts the cores to real services — ctx.subagents.startContinuable, defineTool, the subagent/end event, file appends — with the clock injected by the wrapper, keeping the cores clockless and quiescence math deterministic in tests.

One honest wart, documented rather than hidden: the continuable-setup registry is process-global, so the registry and journal are module-level singletons. Multiple mounted instances would double-register child tools and throw; sharing the singletons makes whichever instance wins behaviorally identical, because node ids are global session ids.

Approvals: protocol-only, and we mean it

The spec's sharpest non-negotiable: children can never park on a human approval, and the mother can never approve a descendant's escalation — no code path, not even a hidden one. The runtime pins children to approvalPolicy: 'never' before dispatch; a test greps the plugin sources for approvalPolicy and user-approval on every run.
So how does a child that hits a permission wall make progress? It checkpoints, then sends a final report with outcome: 'blocked' and blockers: ["approval-required: fs write"]. The human's queue is a view over blocked finals — rendered in the browser, not a runtime state. The child settles cleanly, its slot frees, and a human decides whether to spawn a successor with the missing grant. Escalation becomes a data structure instead of a hung process.

The browser sees the org chart

A second client plugin renders what the mother never sees: the whole tree. It polls two host RPC endpoints every five seconds and shows the full org tree at any depth with live token usage per node where the projection is available — cold children show declared caps only, never faked numbers — checkpoint badges on settled nodes (a predecessor stays browsable after death), and the blocked queue with a Handover button that copies mission + blockers + checkpoint summary to the clipboard.

One deliberate data-plane detail: RPC payloads use conditional spreads (...(x !== undefined ? { x } : {})) because a key: undefined breaks the runtime's value snapshots.

Succession: firing an employee without reading their desk

When a child finishes blocked, fails, or is retired — then what? subsession_succeed { childId, role?, mission?, tokenCap? } spawns a successor: it inherits the predecessor's brief (with optional overrides), pins continues: <predecessorId>, and — critically — re-runs the entire spawn pipeline against the current tree. A stale scope claim can legitimately fail with SCOPE_OVERLAP against a sibling that moved in since. Succession is not a resurrection; it's a fresh hire with a handover letter.
The handover letter is the O(report) invariant made tangible:

continues: "a9e70fb7-…"
checkpoint: workspaceFile:.dsh/subsessions/a9e70fb7-….journal.jsonl#1
predecessor handover: need permission
predecessor blockers: approval-required: fs write
predecessor open questions: is fs write allowed?

A pointer, a phase, three lines of summary. Not the transcript.

The gate before succession is a quiescence sweep: a running child whose last sign of life (max(heartbeat, claim-stamp)) is older than retireTimeoutMs is presumed dead — settled failed, descendants orphaned, slot freed. This fixed a real leak: silently-dead children held their slots forever, because nothing else emits a death event. The sweep runs at succession entry; claim-stamps are taken at the spawn gate (silence measured from the real spawn moment), and the sweep is idempotent.

How we verified it

Four phases, four gates, one rule kept throughout: no pass claim without machine evidence (junit XML, tsc exit codes, lint counts).

Gate	Content	Result
P1	Host plugin: schemas, roles, registry, budget, scope, journal, pipelines	132/132 tests, tsc 0
P2	Client UI: org tree + blocked queue + Handover	host 141/141, client 5/5, bundle verified
P3	Succession command, quiescence sweep, claim stamps	host 155/155 (14 suites), lint 0
P4	Docs only	package README

Three layers of tests carry the weight: protocol tests over the pure cores (brief/report validation, pinned check order, budget boundaries, scope conflicts, idempotent second finals, orphan cascades — 28 cases, no runtime); integration tests driving the real cores through ports with spies, including the kill-mid-task → checkpoint → respawn roundtrip; and a driver suite over the real runtime — actual Context, children executed in-process, no model turns. The succession roundtrip asserts the successor's actual seed text contains the checkpoint ref and handover lines: the property that matters, verified end to end.

The tests earned their keep: a client bug (a transport failure wiped the UI's last-good snapshot), a tool-filter gap (subsession_succeed and subsession_checkpoint were missing from the deny-strip guard), and a clock-ownership drift (claimedAt was never stamped, so "silence since spawn" was measured from epoch zero). None visible in the passing happy path.

Related work: we're not the first to want this boundary

Claude Code — context: fork and agent frontmatter. Claude Code 2.1.0 added "running skills and slash commands in a forked sub-agent context" via context: fork in SKILL.md frontmatter — deliberately left OFF by default. agent: <name> dispatches a skill to a named subagent, model: (opus / sonnet / haiku / inherit) is honored in fork mode, allowed-tools: pre-approves a list, and subagent definitions accept skills: string[] to preload at startup. The tell that the idea crossed from "interesting" into "maintained": public bug reports — hooks not propagating into forked subagents, output swallowed by the desktop UI, infinite re-invocation loops (fixed in 2.1.145), agent: silently ignored in 2.1.112. (sub-agents docs, agent skills overview, skills spec, issue #14661)

Cognition — "Don't Build Multi-Agents" and the read-parallel/write-serial rule. Parallel agents make implicit, conflicting decisions; context passing across agents is the unsolved problem. What works in production: multiple agents contribute intelligence but writes stay single-threaded; parallel-writer swarms still don't see meaningful adoption. Anthropic's cost number: a multi-agent research system burns ~15× the tokens of chat, and token usage alone explained 80% of performance variance on BrowseComp. (Don't Build Multi-Agents, Anthropic multi-agent research)

MAST — the 14 failure modes. 1,600+ annotated traces across 7 multi-agent frameworks found 14 distinct failure modes in 3 categories — bad specification, inter-agent misalignment, failed verification — with inter-annotator kappa of 0.88. ChatDev scores 33.33% correctness on its ProgramDev benchmark, and the headline: multi-agent gains are often minimal against single-agent frameworks or even best-of-N sampling. (arXiv:2503.13657)

ReWOO — decoupling reasoning from observations. ReWOO's planner emits a plan with placeholders, workers execute the steps, and a solver composes the final answer once — instead of interleaving every tool observation back into the model's reasoning loop. Subsessions shares the instinct (don't feed raw observations upstream) but draws the boundary at the session level: the mother never receives the child's loop, only the settled report. (arXiv:2305.18323)

Where we sit: closest to Claude Code's forked-context line — role-typed children returning bounded output — but with the boundary pinned structurally (spawn gates, size gates, protocol-only approvals, succession) rather than by frontmatter convention.

Where we deviated from the spec — on purpose, at the gate

A spec that can't be argued with is a wish list. Every deviation was surfaced in a gate report, not smuggled in:

Approval parking → protocol-only. The blocked-final queue replaces runtime parking entirely (above).
Delivery modes: quiet | next-step only. Progress delivers quietly; finals deliver at the next step boundary. No retry buffer — a dead mother's report triggers the orphan cascade instead.
Tier→model is plugin config, not eval. Presets can't pin models in our runtime; per-task tier selection via evals is future work.
Journal = workspace-file JSONL. The spec wanted a memory service the fork doesn't have; append-only files with line-numbered pointers get the same properties.
verify: ['files'] = existence check. A missing claimed file marks the node disputed; changed-but-unclaimed detection needs snapshot diffs we didn't build.
Declared-budget arithmetic. No live token metering exists in the runtime for cold children; caps are enforced by arithmetic, live usage is shown only where the projection exists, and we never fake a number.
UI is polling, not push. Five seconds is fine; event push is an optimization, not a design change.

What we'd tell the next implementer

Pin the check order and test the order itself. Half the subtle bugs in permission-adjacent systems are ordering bugs.
Keep decision cores clockless and I/O-free. Every deterministic test we have is downstream of that one choice.
Make escalation a data structure. A hung child waiting for permission is a bug you can't see; a blocked final report is a row in a queue.
Never fake telemetry. Cold children show declared caps, not invented usage; a dashboard that lies once is a dashboard forever.

Status

All four phases are landed and gated in the fork: host plugin, client UI, succession + quiescence, docs. The host suite stands at 155/155 across 14 suites, the client suite at 5/5, type checks and lint clean. Gate reports record the evidence and every deviation.

Which leaves the honest ending. The O(report) invariant is enforced structurally today — every gate, every report contract, every succession letter exists to hold it. And now we have measured what it is worth on real workloads: read the follow-up measurement report, Measuring the Multi-Agent Fork Tax.

Measuring the Multi-Agent Fork Tax

Mohammad Fauzel Sadeghizad — Fri, 04 Sep 2026 18:46:27 +0000

In our previous post, Giving a Coding Agent an Org Chart, we described Subsessions: a protocol layer over agent runtimes that enforces role-typed child sessions, versioned briefs, and append-only checkpoint journals.

The entire architecture rested on one foundational invariant:

The mother's context grows by $O(\text{report})$, never by $O(\text{child transcript})$. The human sees the whole org tree; the mother sees only structured reports.

We closed that post with an unresolved question:
The invariant holds mechanically—every gate, every report contract, every succession letter exists to enforce it. What we don't know yet is what it is worth on real workloads: we haven't published the measurement.

This post publishes the measurement.

We pre-registered a formal evaluation rubric (RUBRIC.md), generated deterministic fixtures across 20 programming tasks, collected 45 full execution runs across two experimental arms, and submitted the entire dataset to an independent adversarial verification audit (results/VERIFICATION.md).

The findings are unambiguous, humbling, and a stark reminder that in software architecture, no abstraction is free.

1. The Experiment: Inline vs. Orchestrated

To test whether subsession orchestration outperforms a single agent session, we evaluated two arms under identical conditions:

The Inline Arm (Role: worker): A single autonomous session. The subsession toolset is structurally stripped (canSpawn: false). The agent receives the task prompt and executes all code navigation, editing, script execution, and verification directly within its own session.
The Orchestrated Arm (Role: coordinator): A supervisor session authorized to spawn children (canSpawn: true, depthCap: 2). Under pre-registered protocol amendments, the coordinator is required to delegate work to at least two worker subsessions and synthesize their returned reports before delivering the final answer.

Strict Fairness Controls

To ensure we measured the structural cost of orchestration rather than model variance:

Identical Model: Every session across both arms resolved to the deployment default (bai-/glm-5.3-flash).
Identical Seed Fixtures: All repository files (80 TypeScript files), financial CSVs (360 rows in integer cents), server logs (3,000 lines), and meeting notes (347 KB across 200 sections) were deterministically synthesized from a seeded PRNG (Mulberry32).
Mechanical Scoring: Outputs were evaluated mechanically by checks/check.mjs using strict deep-equality against frozen JSON ground truths.
Interleaved Execution: Runs alternated in an A/B/B/A sequence to eliminate time-of-day API throttling biases.

2. The Headline Result: The Fork Tax

We measured 20 tasks divided across four distinct software engineering classes ($5$ tasks per class). Across the 19 completed pairs, orchestration was strictly more expensive in every single case.

Caveat: One model, one day, $n=5$ per cell, mandatory fan-out ($\ge 2$ workers).

Task Class	Inline Tokens (med)	Orch Tokens (med)	Token Ratio	Inline Wall (med)	Orch Wall (med)	Wall Ratio	Mother / Inline
breadth-read (T01–T05)	76,393	304,824	3.99×	204 s	491 s	2.41×	2.65×
single-write (T06–T10)	49,269	215,631	4.38×	96 s	745 s	7.76×	3.18×
longdoc-transform (T11–T15)	170,631	592,452	3.47×	439 s	1,224 s	2.79×	1.30×
multi-step-tool (T16–T20)	104,321	390,129	3.74×	185 s	759 s	4.10×	1.70×

On accuracy, both arms achieved identical performance: both passed 100% of tasks T01 through T19. (Both arms failed T20 identically due to a disclosed ground-truth collation defect where the prompt asked for lexicographic ordering and the generator sorted directory-first).

On cost and latency, however, orchestration imposed a severe fork tax:

Token Inflation: Orchestrated execution required $3.47\times$ to $4.38\times$ more total billed tokens.
Wall-Clock Latency: Orchestrated execution was $2.41\times$ to $7.76\times$ slower. On single-write tasks, dispatching workers, awaiting tool handshakes, and merging reports took $745$ seconds versus $96$ seconds for the single inline agent.

3. Where Did the Tokens Go?

The most critical finding emerged when we disassembled the token accounting inside the subsession trees.

A naive assumption is that multi-agent systems burn tokens because multiple workers are exploring parallel paths. The telemetry revealed the exact opposite:

Orchestrated Run Token Spend (Median Across 19 Pairs):
├── Mother Session (Supervisor Loop): 55%
└── Worker Subsessions (Task Work):   45%

Over half (55%) of all tokens in an orchestrated run were consumed by the mother session's own loop, not by the children doing the work.

Look at the operational numbers:

Across all 19 completed pairs, the median volume of child reports delivered to the mother was 3,529 bytes.
The median token spend of the mother session managing those reports was 213,219 tokens.
The mother spent $\sim 60\times$ more tokens driving her own coordination loop than the total content size of the reports she received.

This is the central paradox of context engineering: the $O(\text{report})$ invariant held mechanically on disk, but was economically irrelevant.

The mother's context was indeed protected from child transcripts: she received clean, 2~KB to 7~KB JSON summaries. But the cognitive tax of running a supervisor—formulating structured briefs, specifying filesystem globs, waiting for turns, polling status, reconciling discrepancies, and formatting output—dwarfed the entire cost of the task.

In 17 of the 19 completed pairs, the mother session's spend alone exceeded the total token usage of the inline agent doing the entire task from start to finish.

4. The Elusive Crossover Point

In our pre-registered protocol, we hypothesized that as task scale and document size increased, a measurable "crossover point" would emerge where the token savings of context isolation would overtake protocol overhead (Hypothesis 3).

The data refuted this hypothesis entirely:

Pairs where orchestration used fewer total tokens: 0 / 19 (0%).
Pairs where the mother alone used fewer tokens than inline: 2 / 19 (Task T13 at $0.99\times$, Task T17 at $0.86\times$).
H4 Invariant Bar ($\text{mother tokens} < 0.5\times \text{inline total}$): 0 / 19 (0%).

Even on the largest fixture in the benchmark—a 347~KB, 200-section executive meeting document—the inline agent completed the analysis in 170,631 tokens. The orchestrated arm burned 592,452 tokens ($3.47\times$). Why? Because modern LLM context windows (128k+) can digest a 347~KB document in a single gulp. Splitting the document across two workers meant both workers had to read their respective slices, serialize findings, and send them to the coordinator, who then had to read all findings and re-verify them.

5. Checkpoint Resumption and Deadlock Risk

One promised advantage of subsession architectures is state resilience: if a subagent dies or is terminated mid-flight, a successor can resume from an append-only checkpoint journal without re-running the entire task (Hypothesis 5).

To measure this, run R38-T19-orch was deliberately killed mid-task at 18,549 tokens (step 2, 78 seconds). It was then resumed with the frozen recovery prompt: "you were stopped mid-task; recover from your checkpoint and finish; report normally."

The result was an operational disaster:

The resumed leg burned 129,945 additional tokens (total: 148,494 tokens).
The coordinator attempted 5 child spawns. Two were rejected immediately because the model hallucinated unregistered role names (log-analyst-a, log-analyst-b).
The coordinator then spawned two valid worker subsessions. Both workers subsequently failed and terminated without delivering a final report.
Crucially, the coordinator runtime possessed no timeout or dead-child detection for asynchronous reports.
The coordinator emitted its final turn message: "Both workers are running. I'll merge and write the deliverable once their final reports arrive," ended its turn, and parked indefinitely.
The run remained frozen in a deadlock state for 53,046 seconds (~14.7 hours) until the experimenter manually force-retired the session.

The takeaway for agent harness designers is stark: without active quiescence monitoring and explicit timeouts on child report arrival, checkpoint resumption does not save tokens—it introduces unbounded deadlocks.

6. Real-World Mechanism Friction

Because both arms executed against the identical frozen tasks, the benchmark illuminated four failure modes unique to multi-agent architectures:

Role Name Hallucination (UNKNOWN_ROLE): Coordinators repeatedly invented functional role names (doc-summarizer-a, summarizer, log-analyst) instead of adhering to the role table (worker). Each invalid spawn consumed a full LLM turn and tool round-trip before falling back to valid roles.
Shared Tree Budget Starvation: In our initial configuration, runs were given a shared tree budget of 150,000 tokens. In run R15, the coordinator spent so many tokens setting up its planning loop that all 6 spawned children were admitted and killed at 0 tokens, unable to take their first step. We had to issue a protocol amendment (Amendment #4) raising the budget to 1,000,000 tokens so the cap would not bind asymmetrically on the orchestrated arm.
Auto-Verifier False Negatives: In at least 8 runs, the runtime's automated verification hooks raced the filesystem writes of child sessions, falsely reporting deliverables as "missing" or "disputed." Coordinators had to burn extra turns reading the disk directly to dismiss the harness's own false alarms.
Worker Unreliability: In task T04, a worker claimed it found 53 imports when it had delivered 52. In task T13, workers claimed 103 items where the true count was 100. In both cases, the coordinator caught the discrepancies by re-running the extraction itself from raw source files. The coordinator did add value by catching hallucinations—but it did so by duplicating the worker's effort, strictly increasing total token spend.

7. The Skeptic's View: Steelmanning the Attack

An adversarial verifier was commissioned to independently audit this benchmark (results/VERIFICATION.md). What would a skeptic say about these results?

Here is the honest counter-argument:

This benchmark is an engineered test where multi-agent orchestration was structurally guaranteed to look inefficient. By mandating delegation to $\ge 2$ children on tasks that operate on small repositories and a 347~KB document, the benchmark forced a complex corporate hierarchy onto problems that comfortably fit into a single model turn. Orchestration exists to conquer tasks that exceed context limits; testing it on sub-100k token workloads merely measures the administrative overhead of JSON briefs and prompt handshakes. Furthermore, measuring cumulative billed tokens penalizes the inter-agent communication channels that keep worker contexts clean. This benchmark does not prove orchestration is flawed; it proves that requiring an agent to form a committee to write a 5-paragraph essay is wasteful.

This critique is valid, and we accept it.

Our benchmark does not prove that multi-agent systems are inherently inferior. It proves something more specific and immediately actionable: mandatory fan-out on workloads that fit within an LLM's active context window imposes a $3.5\times$ to $4.4\times$ cost multiplier with zero accuracy benefit.

When given the choice in pilot run R02b, a capable coordinator looked at the task, judged it small, and chose to do it entirely inline. Our protocol forced it to delegate. The coordinator's initial instinct was right.

8. Reproducing the Benchmark

All data, scripts, ground truths, and per-run telemetry are open-source in the public repository under bench/:

cd bench

# 1. Verify deterministic fixtures and run self-test
node generate.mjs --verify
node selftest.mjs
# Expected: 20/20 PASS, 3/3 deliberate corruptions caught

# 2. Recompile CSV and recompute all metrics
node compile.mjs
node analyze.mjs
node stats.mjs

Every number in this article is derived directly from results/results.csv. Per-run prompt definitions, metrics, and final reports are committed under bench/runs/.

Conclusion

The subsession protocol successfully solves the problem it was designed to solve: child transcripts do not leak into supervisory context.

However, solving the context isolation problem does not solve the cost problem. Coordination has mass. Writing briefs, inspecting outputs, managing tool permissions, and recovering from child stalls consumes more tokens than the work itself.

For AI engineers building agent workflows, the architectural rule of thumb is clear:

Default to inline execution. If the codebase, document, or working memory fits within the model's context window, keep it in a single session.
Do not force delegation. Allow autonomous supervisors to execute tasks inline when they deem them manageable.
Reserve orchestration for structural walls. Deploy subagents only when context saturation degrades reasoning, or when strict security and tool sandboxing mandates an isolated execution boundary.

Until an agent hits a context or permission wall, the cheapest org chart is no org chart at all.

Resources & Artifacts

GitHub Repository: REPO-URL-TBD
Technical Paper (arXiv): paper/subsessions-fork-tax.tex
Adversarial Verification Report: bench/results/VERIFICATION.md
DeepSeek Harness Upstream: deepseek-ai/deepseek-harness