Een grote taak delegeren in Claude Code met geneste subagents

Wat veranderde er in Claude Code v2.1.172?#

Als je de afgelopen maanden iets hebt gelezen over AI-agents in Claude Code, ben je dezelfde zin tegengekomen. Hij staat in de officiële documentatie, in mijn gids over subagents en in de analyses van elke concurrent. Het gaat zo: “een subagent kan geen andere subagent starten.” Op 11 juni 2026 staat die zin nog steeds op drie verschillende plekken op code.claude.com/docs/en/sub-agents. Anthropic heeft die simpelweg nog niet bijgewerkt.

Op 10 juni om 20:44 UTC verscheen Claude Code v2.1.172 op GitHub Releases. Het belangrijkste punt in het changelog was één regel:

Deze release loste ook een bug op die alleen bij nesting kon optreden: een achtergrond-subagent bleef in het agentspaneel als actief gemarkeerd nadat de geneste subagent die hij had gestart al was gestopt.

Dit is een zeldzaam geval waarin de officiële documentatie nog steeds in tegenspraak is met de uitgebrachte build. Hierna leg ik uit hoe nesting verschilt van parallelle subagents, wat “diepte 5” betekent en in welke drie scenario's het vandaag echt nuttig is.

Hoe verschillen geneste subagents van parallelle en sequentiële subagents?#

Ik heb deze drie aanpakken lang zelf uitgeprobeerd, en zo zie ik het: delegeren heeft drie dimensies. Breedte, lengte en diepte. Elke dimensie lost een ander probleem op.

Breedte — parallelle subagents. De hoofdchat start N onafhankelijke subagents op hetzelfde niveau. Elk krijgt een afgebakende taak, werkt in een eigen geïsoleerd venster en geeft alleen het resultaat terug. Breedte zorgt voor snelheid: 5 parallel werkende subagents zijn klaar in de tijd die één subagent nodig heeft om hetzelfde werk sequentieel te doen. Dit model besprak ik in mijn gids over parallelle subagents met worktrees.

Lengte — een keten van subagents. A werkt, geeft het resultaat door aan B, B werkt en geeft het door aan C. Elke agent ziet de invoer van de vorige. Lengte legt de volgorde vast: B kan pas beginnen als die gegevens van A heeft gekregen. Een klassiek voorbeeld: eerst verzamelt een onderzoeks-subagent bronnen, daarna schrijft een redactie-subagent een artikel op basis van die bronnen en vervolgens controleert een factcheck-subagent het artikel. Het is een vlakke reeks; de hoofdchat houdt het hele verhaal bij.

Diepte — geneste subagents. A start B, B start C, C start D. Elk kind werkt binnen zijn ouder, in een eigen geïsoleerd venster, en geeft alleen het resultaat terug aan de ouder. De hoofdchat ziet niets van wat er gebeurt bij de kinderen, kleinkinderen en achterkleinkinderen. Dit is nieuw in v2.1.172.

De grootste verwarring is dat mensen denken dat diepte 5 betekent: “je kunt 5 subagents tegelijk starten.” Dat klopt niet. Diepte is een verticaal niveau in de boom, niet het aantal gelijktijdige kinderen. Op elk niveau kunnen er één of honderd subagents zijn. Diepte 5 betekent dat de delegatieketen 5 stappen omlaag kan gaan: hoofdchat → kleinkind-1 → kleinkind-2 → kleinkind-3 → kleinkind-4 → kleinkind-5. En op elk niveau kan de boom vertakken.

Versie 2.1.172 verwijderde de regel dat een subagent geen andere subagent kon starten.

Als je snelheid wilt, heb je breedte nodig. Als je een strikte uitvoeringsvolgorde hebt, heb je lengte nodig. Diepte is nuttig in precies één geval: wanneer een van je taken een luidruchtige subtaak bevat (15 webverzoeken, logbestanden doorzoeken, een dozijn bestanden lezen). En je die ruis niet in je hoofdvenster wilt hebben.

Wat betekent “5 niveaus diep” in de praktijk?#

Hier is een belangrijk punt van eerlijkheid. Ik heb een halve dag besteed aan documentatie en communityanalyses om erachter te komen dat Anthropic geen precieze definitie heeft gegeven. Dit moet je weten.

Het is een limiet, geen instelling.

De limiet is ingebouwd aan de serverkant. Reverse engineering van client v2.1.172 vond geen constante MAX_DEPTH. Dat betekent dat de controle ergens in de Anthropic API plaatsvindt, niet lokaal op je machine. Je kunt geen --max-depth 7 instellen om de boom dieper te maken. Je kunt ook geen --max-depth 2 instellen om een lagere, veiligere limiet vast te leggen. De enige controle die je hebt is de allowlist Agent(agent_type) in de frontmatter — maar die beperkt de typen kindagents, niet de diepte.

Anthropic heeft “5” niet precies gedefinieerd. Dat is het tweede belangrijke punt:

Anthropic heeft niet precies gedefinieerd wat “5” betekent. Officiële bronnen specificeren niet of depth=5 vijf niveaus onder de root betekent of in totaal vijf agents, inclusief de root.

Integraties van derden interpreteren het voorlopig verschillend. ADR-147 in het project ruvnet/ruflo gaat uit van “5 kindniveaus onder de root = 6 agents in de keten”. In mijn experimenten gebruik ik dezelfde conventie: de hoofdchat is niveau 0, de directe kinderen zijn niveau 1, enzovoort tot en met niveau 5. Maar dit staat niet in de openbare documentatie.

De limiet is al ingeschakeld, zonder vlaggen. Je hoeft niets te activeren. Na het bijwerken van Claude Code naar v2.1.172 kun je Agent toevoegen aan de tools van een kindagent, waarna die een andere subagent kan starten. Het belangrijkste is dat de ouderagent dit moet toestaan (tools: Agent(...)).

Waar vindt jouw delegatie vandaag plaats: in de breedte, lengte of diepte?#

Loop je laatste 5 prompts na. Hoe vaak heb je dit gedaan: een taak begint, Claude gaat bestanden doorzoeken, doet 10 webverzoeken, dumpt een hele muur aan logs in de context — en 20 minuten later besef je dat het venster vol is. Het uiteindelijke antwoord moet het dan doen met een schamel tokenbudget, omdat 70 procent van de context is opgeslokt door tussentijdse dumps.

Dat is een scenario waarin je diepte nodig hebt. Geen parallelisme, geen keten — diepte. De hoofdchat moet “onderzoek” delegeren aan één subagent, die vervolgens vanuit zijn eigen venster kinderen start voor specifieke zoekopdrachten op het web, het lezen van bestanden en het doorzoeken van bestanden. De kinderen geven alleen samengevatte oordelen terug. Een kleinkind vertelt zijn ouder: “gevonden, bevestigd” of “niet gevonden, reden X”. De ouder maakt daar één samenvatting van en geeft die aan jou terug. De hoofdchat blijft overzichtelijk.

Vóór 9 juni deed ik dit handmatig na. Ik opende een tweede Claude Code-instantie, kopieerde de prompt “onderzoek dit”, voerde die uit en zette het resultaat daarna handmatig terug in het hoofdvenster. Ik beschreef deze opzet uitgebreid in mijn gids over het delegeren van code aan veel AI-agents. Met v2.1.172 kun je dit rechtstreeks beschrijven in de systeemprompt van de orchestrator — Claude bouwt de boom zelf.

In welke 3 scenario's zijn geneste subagents echt nuttig?#

Scenario 1. Diepgaand onderzoek met factchecking

Stel dat je materiaal verzamelt voor een artikel of een verkoopvoorstel. Eerst moet je 5–10 beweringen uit openbare bronnen verzamelen en vervolgens elke bewering controleren — de oorspronkelijke bron vinden, nagaan of het citaat exact is en de werkelijke cijfers berekenen.

Vóór v2.1.172 had je twee opties. Je kon alles met één subagent doen, die zich door 30 webverzoeken heen worstelde en alles in zijn context propte. Of je kon het handmatig opdelen: één prompt om de beweringen te verzamelen en daarna een reeks prompts om de beweringen een voor een te controleren, met voor elke bewering een aparte subagent. De hoofdchat zou vollopen met muren aan tussentijdse lijsten.

In het onderstaande recept delegeert de hoofdchat naar research-orchestrator (niveau 1). De orchestrator verzamelt zelf de beweringen, geeft elke bewering aan fact-verifier (niveau 2) en elke verifier delegeert gerichte zoekacties naar web-deep-search (niveau 3). De hoofdchat ontvangt alleen een lijst met gecontroleerde beweringen en bronnen. Al het andere blijft in kindvensters en komt nooit in je context terecht.

Scenario 2. Een grote repository analyseren

Je krijgt een project met 200 bestanden. Je moet de architectuur begrijpen, de belangrijkste modules vinden en de technische schuld beoordelen. Voer handmatig Glob uit plus een dozijn Read-aanroepen, en je venster loopt binnen 10 minuten vol.

Diepte lost het zo op: de hoofdchat start een “architect”-subagent. De architect start intern drie kinderen — één inspecteert de mapstructuur (voert Glob uit en maakt een samenvatting), de tweede leest 5 belangrijke configuratiebestanden en de derde zoekt naar de belangrijkste patronen. Elk kind geeft een beknopte samenvatting aan de architect terug. De architect brengt alles samen en geeft de hoofdchat een eindrapport van een half scherm. Je krijgt een overzicht van het project zonder dat een muur aan cat-uitvoer van alle bestanden je context overspoelt.

Scenario 3. End-to-endafhankelijkheden analyseren

Je wijzigt een databaseschema, een API-contract of een gedeeld configuratiebestand. Je moet begrijpen waar de gevolgen zichtbaar zullen zijn. Deze taak verbruikt context het snelst, omdat er veel afhankelijkheden zijn en elke afhankelijkheid in de broncode moet worden gecontroleerd.

Met diepte start de hoofdchat een impact-analyzer (niveau 1). Die start één dependency-tracer per betrokken bestand (niveau 2). Elke tracer start intern een consumer-finder (niveau 3), die de codebase doorzoekt op gebruikers van die afhankelijkheid. Elke tracer geeft vervolgens alleen de kern terug: “deze drie plekken gaan stuk”. De hoofdchat stelt een tabel samen met “betrokken bestanden → impact” zonder de zoekresultaten te zien.

Geneste subagents in 10 minuten instellen#

Stap 1. Controleer of je v2.1.172 of hoger gebruikt.

claude --version

Is de versie lager, voer dan een update uit. De belangrijkste functie van deze release is één regel in het changelog: “Subagents kunnen nu hun eigen subagents starten, tot 5 niveaus diep” (volledige tekst).

Stap 2. Maak een ouderagent die kinderen kan starten.

Bestand .claude/agents/research-orchestrator.md:

---
name: research-orchestrator
description: Delegeert onderzoek met diepgaande factchecking
tools: Agent(fact-verifier), Read, WebFetch
model: opus
---

Jij bent een onderzoeksorchestrator. Zodra je een onderwerp krijgt:
1. Lees het aangeleverde materiaal of haal de opgegeven openbare bron-URL’s op.
   Haal zelf maximaal 5 concrete beweringen uit de bronnen. Noteer per bewering de tekst,
   bron-URL of het bestand en de exacte ondersteunende passage.
   Is geen bronmateriaal gegeven, vraag daar dan om voordat je delegeert.
2. Roep fact-verifier voor elke bewering aan — die start zelf
   zijn kindsubagents voor zoeken op het web en controleren.
3. fact-verifier geeft jou alleen de uiteindelijke oordelen terug —
   laad geen tussentijdse dumps in je context.

Het eindrapport is uitsluitend een array { claim, sources[], confidence }.

De regel tools staat alleen het kindtype fact-verifier toe. Beweringen verzamelen is de eerste stap van de orchestrator zelf, dus er is geen ongedefinieerd claim-extractor-bestand nodig. Een typetoelatingslijst beperkt welk kind kan worden aangeroepen, niet hoe vaak dat type start. Begrens het recept tot maximaal vijf verzamelde beweringen.

Stap 3. Maak een kindagent die zelf kleinkinderen kan starten.

Bestand .claude/agents/fact-verifier.md:

---
name: fact-verifier
description: Controleert een bewering via zoekopdrachten op het web door kinderen
tools: Agent(web-deep-search), Read
model: sonnet
---

Jij bent een factchecker. Zodra je een bewering krijgt:
1. Formuleer 2-3 zoekopdrachten.
2. Start voor elke opdracht web-deep-search — die voert zelf
   WebSearch en WebFetch uit en geeft gecontroleerde fragmenten terug.
3. Breng alles samen in één oordeel: { claim, sources[], confidence }.

Zie je het belangrijkste deel? Ook hier staat op de regel tools Agent(web-deep-search). Dat betekent dat de fact-verifier (niveau 2 in onze boom) zelf nog een subagent kan starten (niveau 3). Eerder had deze regel geen effect — de documentatie bevat nog steeds deze zin:

Met v2.1.172 is die zin verouderd. De syntaxis is hetzelfde, maar werkt nu op elk niveau in de boom.

Stap 4. Maak een kleinkind.

Bestand .claude/agents/web-deep-search.md:

---
name: web-deep-search
description: Voert zoekopdrachten op het web uit en geeft fragmenten terug
tools: WebSearch, WebFetch
model: haiku
---

Je hebt een zoekopdracht gekregen. Voer WebSearch uit, kies de top 3
relevante URL's en haal via WebFetch letterlijke bevestigingen van de
bewering op. Geef een array terug: { url, snippet, supports_claim: yes|no }.

De kleinkindagent heeft geen Agent bij tools staan, dus die start geen verdere agents in de boom.

Stap 5. Voer de orchestrator uit.

claude --agent research-orchestrator

Geef daarna de brontekst of openbare bron-URL’s in de chat: “Haal maximaal 5 concrete beweringen uit deze bronnen en controleer ze; geef beweringen, bronnen en zekerheid terug.” Met --agent research-orchestrator is de sessie zelf de orchestrator; de verifier- en zoekkinderen voegen daaronder twee gedelegeerde niveaus toe. Delegeert een gewone hoofdsessie naar die orchestrator, dan zijn er drie gedelegeerde niveaus onder de hoofdsessie.

Welke 5 antip patronen verspillen tokens en maken het werk ondoorzichtig?#

Antipatroon 1. De taak past in één venster.

Als één subagent de taak zonder ruis aankan, voeg dan geen niveaus toe: nesting verhoogt alleen de kosten en vertraging.

Antipatroon 2. Je wilt snelheid, geen isolatie.

Als je snelheid wilt, heb je parallelisme nodig, geen diepte. Start 5 subagents naast elkaar op hetzelfde niveau in plaats van een keten te bouwen. Diepte is bedoeld om luidruchtig voorbereidend werk naar een kindvenster te verplaatsen, niet om dingen sneller te doen.

Antipatroon 3. Het werk is per definitie oppervlakkig.

“Zoek dit bestand en laat het me zien” is een opdracht in twee stappen; daar is geen hiërarchie met drie niveaus voor nodig. Nesting is de moeite waard wanneer een taak een luidruchtige subtaak bevat. Is er geen ruis, voeg dan geen subagents toe.

Antipatroon 4. Vage prompts op het eerste niveau.

Dit is het gevaarlijkste scenario. Als je de orchestrator op niveau 1 een vage prompt geeft, vermenigvuldigt de vaagheid zich. Eén vage prompt op niveau 1 wordt 4 vage prompts op niveau 2 en 16 op niveau 3. Tegen de tijd dat de kleinkinderen aan het werk gaan, weten ze niet eens waarnaar ze moeten zoeken.

Antipatroon 5. Geometrische kostengroei.

Het belangrijkste economische argument: nesting vermenigvuldigt het tokengebruik, en die vermenigvuldiging stapelt zich op met de diepte.

Een ruwe berekening: een keten met diepte 3 en een fan-out van 3 op elk niveau betekent 27 subagents. Dat zijn minstens 27 keer zoveel tokens als voor een eenvoudige opdracht. Met het Pro-abonnement van Claude is je daglimiet daarmee binnen een paar uur op. Met een Max-abonnement verbruik je binnen één dag je tegoed voor een hele week.

Bonus-antipatroon (uit eigen ervaring): “50 agents die zinloos werk doen.”

Als ik naar projecten van anderen kijk, zie ik vaak dit: “Ik heb 50 agents aan het werk.” Ik vraag wat ze doen. En dan blijken die 50 agents zinloos werk te doen. Ze genereren stapels onnodige uitvoer, bergen ruwe samenvattingen, duplicaten en muren aan logs. Elk doet iets “in het algemeen nuttigs”, en het resultaat is een overvolle context en een tokenrekening als die van een klein bedrijf. Diepte 5 lost dit probleem niet op — het maakt het erger. Als op niveau 1 al onduidelijk is wie wat doet, betekent diepte 5 vijf niveaus verwarring.

Stel jezelf voordat je een subagent start vier vragen, en beantwoord ze binnen een halve minuut:

• Wat doet die precies (in één zin)?
• Welke bestanden raakt die aan?
• Wat geeft die terug aan de ouder?
• Wie controleert het werk?

Kun je daar binnen 30 seconden geen antwoord op geven, dan hoort deze subagent niet te bestaan. Ik legde deze regel apart uit in mijn gids over parallelle subagents.

Waarom leidt nesting zonder context engineering tot 5 niveaus hallucinaties?#

Hier vragen mensen vaak: “Ik heb Claude Code bijgewerkt en Agent aan tools toegevoegd. De boom wordt opgebouwd, maar het eindantwoord klopt nog steeds niet. Hoe kan dat?”

Het antwoord is eenvoudig. Elke subagent in Claude Code begint helemaal opnieuw. Uit de officiële documentatie:

Op niveau 1 is dit beheersbaar: de orchestrator geeft zijn kind een korte taakomschrijving. Maar op niveau 3 krijgt het kleinkind een delegatiebericht van zijn ouder, die zelf ook alleen een delegatiebericht heeft gekregen. Elke agent geeft een beetje door. Op niveau 5 heb je een subagent in wiens venster alleen de tekst “controleer bewering X” staat. Die weet niet aan welk project die werkt, welke taak die oplost of waar die zich op moet richten.

Zonder CLAUDE.md is een kleinkindagent op niveau vijf als een medewerker die voor het eerst in zijn leven op kantoor verschijnt zonder enige introductie. Die zal iets doen omdat die een taak heeft gekregen. Maar het is niet wat het project nodig heeft.

Daarom is de opzet essentieel. Diepte 5 zonder een goed geconfigureerde CLAUDE.md, business/ en skills-pijplijn is een casino. Met die onderdelen is het een hulpmiddel.

Wat veranderde er in v2.1.172 naast nesting?#

Open het volledige changelog van v2.1.172 en je ziet dat de hele release over subagents gaat.

Oplossing 1. Een achtergrond-subagent blijft niet langer als actief “vastzitten” in het agentspaneel nadat de geneste subagent die hij startte is gestopt. Deze bug kan alleen met nesting optreden.

Oplossing 2. Beperkingen op availableModels gelden nu ook voor subagents. Voorheen konden subagents de regel omzeilen met een override in hun eigen configuratie als je beperkte welke modellen het team mocht gebruiken (bijvoorbeeld om opus te verbieden en geld te besparen). Met v2.1.172 geldt de regel overal.

Oplossing 3. De pijl omhoog in de promptgeschiedenis toont nu prompts uit het huidige tabblad van de subagent, niet uit dat van de hoofdagent. Een verfijning voor de zichtbaarheid.

Oplossing 4. Het inactieve CPU-gebruik is verminderd: de /goal-indicator tekent de terminal niet langer 5 keer per seconde opnieuw wanneer die inactief is, en de gebruikersinterface wordt minder vaak opnieuw getekend terwijl parallelle subagents werken.

Ik wil erop wijzen dat alle vier oplossingen over subagents gaan. Dat betekent dat Anthropic de hele infrastructuur voor nesting heeft uitgebracht, niet alleen één regel in het changelog. Nesting werd al enige tijd vóór de publicatie intern bij Anthropic gebruikt.

Checklist: wanneer nesting helpt en wanneer het tegenwerkt#

Gebruik nesting als:

• De taak een subtaak bevat met veel webverzoeken, zoekacties in bestanden of bestandslezingen.
• Het aanvaardbaar is om die subtaak te verliezen (als het kleinkind “niets gevonden” teruggeeft, kan de orchestrator doorgaan).
• Je geen tussentijdse resultaten in het hoofdvenster nodig hebt.
• Je een CLAUDE.md hebt en een samengestelde projectcontext waar de subagent op kan vertrouwen.
• Je duidelijk kunt beschrijven wat elk niveau teruggeeft (invoer, uitvoer, formaat).
• Je een Max-abonnement hebt of ruimte voor ×27 tokens.

Gebruik nesting niet als:

• Eén subagent de taak zonder ruis kan oplossen.
• Je tussentijdse resultaten in het hoofdvenster nodig hebt (dan wil je parallelisme).
• Het project geen CLAUDE.md heeft of slechts weinig zakelijke context.
• De prompts voor niveau 1 vaag zijn (de vaagheid vermenigvuldigt zich exponentieel door de boom).
• Je snelheid nodig hebt — parallelisme is sneller dan diepte voor een vergelijkbaar resultaat.
• Je het Pro-abonnement hebt en de hele dag werkt — binnen een paar uur verbruik je je limiet.

Meer materiaal is beschikbaar op Ailoot.