8.7 Design Insights

1. The Coordinator not executing is a core constraint: Prevents the Coordinator from both making decisions and executing them, guaranteeing objectivity in task allocation. This is also why the Coordinator's toolset is strictly limited to Agent + SendMessage + TaskStop.
2. "Never write based on your findings" is the most important prompt design: Forces the Coordinator to synthesize and understand research results rather than delegating understanding to Workers. This constraint elevates the Coordinator from a message forwarder to a truly intelligent orchestrator.
3. Continue vs Spawn is not a default choice: It depends on context overlap. High overlap -> continue, low overlap -> spawn. This decision framework avoids mindless reuse or mindless creation.
4. AbortController independence ensures fault isolation: One Worker's crash does not cascade to other Workers. This is a fundamental reliability requirement for parallel systems.
5. Backend detection priority considers the user's environment: tmux > iTerm2 > InProcess, maximizing the use of existing terminal capabilities.
6. Scratchpad solves cross-Worker knowledge sharing: Without it, Workers can only relay information through the Coordinator, increasing latency and the risk of information loss.
7. Plan mode's approval checkpoint is the materialization of trust: Two-phase design is not just a UX improvement — it transforms "user trust" from implicit (permission popups on every tool call) to explicit (one-time approval of the overall plan). This is especially important in team collaboration: a Coordinator Worker's plan needs team leader approval, rather than requiring confirmation for every file modification.
8. Fork is a cache optimization disguised as an architectural pattern: The core motivation for fork sub-Agents is not "inheriting context" — it is enabling multiple children to share the parent's Prompt Cache. The CacheSafeParams type explicitly requiring "byte-level identical" is the best evidence. Inheriting context is a byproduct of cache sharing, not the design goal.
9. Context isolation defaults to maximum safety: createSubagentContext() sets all mutable state to isolated by default (no-op / clone), and developers must explicitly opt-in to sharing via parameters like shareSetAppState, shareAbortController, etc. This "deny by default" design means newly added sub-Agent functionality is inherently safe — unless developers consciously enable sharing.
10. Tool filtering implements defense in depth: Four independent layers of filtering (global prohibition -> custom restrictions -> async whitelist -> type-level prohibition) ensure that even if one layer has a bug, other layers can still intercept dangerous tool access. MCP tools' "always pass through" seems like an exception, but is actually the correct delineation of trust boundaries — users are responsible for the security of external tools they configure themselves.

---

Hands-on practice: In claude-code-from-scratch, the Agent main loop (src/agent.ts) implements a basic tool call loop. Try adding a simple "plan mode" on top of it — collect all planned operations before executing tools, and let the user approve them all at once.

Previous chapter: Hooks & Extensibility | Next chapter: Plan Mode