When to Fold Sub-Agents Into Your Main Claude Code Agent

Anthropic published guidance in October 2026, authored by Diane Sarkis, arguing that most teams over-build multi-agent systems by mirroring their org charts, and that a single main agent loop using "progressive disclosure" is often the better design. Anthropic said the approach let it cut the Claude Code system prompt for its more advanced models by over 80 percent, and one customer case in the guidance found a single-loop agent ran roughly twice as fast as the multi-agent setup it replaced. The guidance says sub-agents still earn their place for fresh-context verification, genuinely parallel work and modular permissioning, and warns that tool choice degrades past roughly 30 to 50 tool definitions in one prompt.

When to Fold Sub-Agents Into Your Main Claude Code Agent Anthropic's new guidance explains when multi-agent setups help vs hurt, and when folding sub-agents into one main loop wins instead. What does Anthropic’s “fold sub-agents into your main loop” guidance actually say? Anthropic published guidance arguing that most teams over-build multi-agent systems by copying their org chart into their agent architecture. Instead of a billing sub-agent, a support sub-agent, and an orchestrator routing between them, the guidance recommends a single main agent loop that loads skills and tools only when a task needs them, a pattern it calls progressive disclosure. The piece, authored by Anthropic’s Diane Sarkis and published in October 2026, says this approach let Anthropic cut the Claude Code system prompt for its more advanced models by over 80 percent. TL;DR - Over-splitting agents mirrors Conway’s law : teams build a sub-agent for every department because that’s how their org is shaped, not because the task needs it, and the result is slower and more expensive than it looks on a diagram. - Progressive disclosure is the core fix : a single agent loop starts with short descriptions of tools and skills and only pulls in full detail at the moment it’s needed, instead of front-loading every rule into every run. - Sub-agents still earn their place in three cases : fresh-context verification, genuinely parallel work, and modular permissioning where a narrow task only gets narrow access. - Splitting badly creates named failure modes : sub-agent sprawl, Frankenprompts where every team bolts on another instruction, and a telephone-game effect where handoffs quietly lose detail. - One customer case in the guidance found a single-loop agent ran roughly twice as fast as the multi-agent setup it replaced, a reminder that every nested sub-agent call is another full model run adding latency. - Tool choice degrades past roughly 30 to 50 tool definitions in one prompt , so folding work into one loop doesn’t mean dumping every tool into it. It means a small, well-named set plus disclosure on demand. - Changes should be measured, not vibes-driven : fold one sub-agent at a time, test against a small set of real examples the guidance says even 10 is enough to start , and run each test more than once since a broken fold can pass by luck. Other agents ship a demo. Remy ships an app. Real backend. Real database. Real auth. Real plumbing. Remy has it all. Why do companies over-use sub-agents in the first place? The guidance points to a specific habit: organizations structure their agents the way they structure their teams. If there’s a billing department, there’s a billing sub-agent. If there’s a support team, there’s a support sub-agent, with an orchestrator sitting on top routing requests between them. This is a direct echo of Conway’s law, the old observation that systems end up shaped like the organizations that build them. The problem is that this structure looks clean on a diagram but doesn’t reflect how the work actually flows. Steps that build on each other, share the same data, or almost always get called together end up split across agent boundaries anyway, just because that’s how the teams were divided. Every one of those splits adds a handoff, and every handoff is a place where context gets lost or latency piles up. How does progressive disclosure replace the orchestrator pattern? Instead of routing tasks to specialized sub-agents up front, progressive disclosure keeps one main agent loop that starts with lightweight descriptions of available skills and tools. The full detail, whether that’s a complete skill definition or a tool’s parameters, only gets loaded when the agent actually needs it for the task at hand. This is why Anthropic was able to shrink the Claude Code system prompt for its most advanced models by more than 80 percent. Rather than stuffing every possible instruction into every run, the agent pulls in what’s relevant on demand. One loop can then cover a wide range of work without carrying the weight of every rule for every scenario. The guidance also gives a simple framework for organizing what goes where inside that one loop: - Domain judgment , the kind of reasoning an expert applies to a specific case, belongs in a skill. - An action, a live data pull, or a hard constraint belongs in a tool. - A fact you only need occasionally doesn’t belong in the prompt at all. It belongs in a knowledge base lookup the agent calls when relevant. That single split, judgment in skills, action in tools, occasional facts in lookups, cleans up a lot of architectures that have grown messy over time. When should you actually keep a sub-agent separate? The guidance is not a blanket argument against multi-agent systems. It names three legitimate reasons to keep a sub-agent split out: 1. You can measure that extra context is actively hurting the main agent’s performance. This isn’t a guess, it’s something you test for. 2. The work runs well in parallel, in fresh contexts that can be thrown away once the task finishes. Independent research tasks are a good example: several workers investigate different angles simultaneously and hand back compact summaries. 3. A single agent keeps struggling with tool choice, or its instructions start conflicting with each other. Past a certain density of tools and rules, one agent genuinely performs worse than a split one. Remy is new. The platform isn't. Remy is the latest expression of years of platform work. Not a hastily wrapped LLM. The underlying principle is to split by context, not by problem type. A separate agent makes sense for work that needs very little from the rest of the system and can report back a single compact result, like a black-box review of finished code or an independent research pass. It doesn’t make sense just because a task maps to a different department or skill area. What goes wrong when teams split agents too aggressively? The guidance names several recognizable failure patterns. Sub-agent sprawl happens when every team ships its own overlapping agent and nobody owns the full set, so duplication piles up unchecked. The Frankenprompt happens when every team adds one more instruction to a shared system prompt until the rules start contradicting each other. The telephone game describes how each handoff between agents loses a bit of detail, so by the time a task reaches the last agent in a chain, it’s working from a faded copy of what the first agent understood. On top of those quality problems, there’s a hard latency cost. Every sub-agent call is a full additional model run. In one customer case cited in the guidance, a single consolidated agent loop ran roughly twice as fast as the multi-agent pipeline it replaced. That’s one data point, not a universal law, but the direction makes sense: a deep chain of agents burns time with every extra hop. How do you fold sub-agents back without breaking a working system? The guidance recommends a careful, incremental process rather than a wholesale rewrite: 1. Fold one sub-agent at a time , starting with whichever pair is used most often or most tightly coupled. 2. Convert that sub-agent’s prompt into a skill and its API calls into tools within the main loop. 3. Measure before touching the next one. The guidance says a small set of real tasks, even as few as 10 “golden examples” where the correct output is known, is enough to start comparing the old setup against the folded one. 4. Run each evaluation more than once. The guidance describes a support chain where folding silently broke part of the flow, and the break only showed up in one run out of two. Testing once and passing by chance means shipping something closer to a coin flip than a verified fix. Is a team of agents ever worth the overhead? Multi-agent setups earn their cost in specific situations: parallel research across a codebase, a feature big enough to split into independent file scopes with a separate reviewer checking the result afterward, running the same prompt across multiple models for comparison, offloading bulk edits to a cheaper model while a stronger model plans and reviews, and tasks long enough that a single context window would fill up before the work is done. They’re overhead for small, tightly coupled tasks: one-file fixes, interactive back-and-forth where you want to watch every step, debugging a single failing test where each attempt builds on the last, or repeated edits to the same file. In all of these, the steps share data and build on each other, which is exactly the condition the guidance says belongs in one loop, not split across agents. Plans first. Then code. Remy writes the spec, manages the build, and ships the app. The tradeoff is straightforward. Splitting work across agents buys parallel execution and fresh, unbiased context for verification. It costs more tokens, since every additional agent is another model run, and it risks losing detail at each handoff. The practical rule is to default to a single agent and only add a team when there’s a specific, nameable reason: real parallelism, a clean task split, an independent check, or a task too long for one context window. Frequently Asked Questions What is progressive disclosure in AI agents? Progressive disclosure is a design pattern where an agent starts with short, lightweight descriptions of its available tools and skills, then loads the full detail only when a task actually calls for it, instead of including every instruction in every prompt upfront. Does Anthropic’s guidance say sub-agents are bad? No. It argues against over-using them by default, but explicitly supports sub-agents for fresh-context verification, genuinely parallel work, and modular permissioning where a task should only get narrow, limited access to systems. How many tools can you put in one agent’s prompt before performance drops? The guidance points to a degradation point around 30 to 50 tool definitions in a single prompt. Past that range, tool choice accuracy tends to suffer, which is why consolidation should pair with a small, well-named tool set rather than dumping everything into one loop. How should I test whether folding a sub-agent into the main loop is safe? Run both the old multi-agent version and the folded version against a small set of real examples with known good outputs, even as few as 10. Run each test more than once, since some failures only appear intermittently rather than every time. What’s a practical rule for choosing between one agent and a team of agents? Default to a single agent loop. Only bring in a team of agents when you can name a specific reason: real parallel work, a clean division of labor, an independent verification step, or a task too long to fit in one context window.