De ergste bugs laten je systeem niet crashen. Ze zijn het simpelweg met je eens.
Ik heb dit op de harde manier geleerd tijdens het bouwen van Suhail, een orchestrator die ontworpen is om vijf gespecialiseerde subagents binnen Claude Code te coördineren. Elke worker had een eigen rol: een onderzoeker om context te verzamelen, een planner om taken op te splitsen, een coder om de implementatie te schrijven, een reviewer om de output te inspecteren, en een auditor om te controleren op regressies. Het idee was eenvoudig. De orchestrator zou een verzoek lezen, beslissen wie wat moest doen, en vervolgens het werk parallel distribueren. In plaats daarvan kreeg ik een beleefde monoloog. Eén venster. Eén agent. Eén zeer druk model dat alles zelf deed, terwijl het volhield dat het het werk had gedelegeerd.
Geen rode vlaggen. Geen error logs. De run werd succesvol afgerond. Het kostte me langer dan ik wil toegeven om te beseffen dat Suhail nooit daadwerkelijk een enkele subagent had aangemaakt.
De valstrik van de agents-map
De hoofdoorzaak was bijna beledigend eenvoudig. Ik had het orchestrator-bestand in de agents-map geplaatst.
In Claude Code is die map niet zomaar een archiefkast. Het is een smederij. Plaats een bestand in die map en het systeem ziet het als een subagent. Die identiteit brengt permissies met zich mee. Op dat moment konden subagents de Agent tool niet aanroepen. Het waren werkers, geen voormannen. Omdat Suhail tussen de werkers leefde, behandelde Claude Code het als zodanig. Dus toen mijn instructies de orchestrator vertelden om de "onderzoeker aan te sturen", greep hij naar een tool die hij niet bezat.
Traditionele software zou daar direct een exception hebben gegooid. Missing tool. Call failed. Niet in de wereld van agentic LLM's. Wanneer een model de juiste tool niet kan vinden, stopt het niet. Het improviseert. Suhail zag de instructie om de onderzoeker aan te sturen, vond geen Agent tool in zijn pakket, en deed de research simpelweg zelf. Daarna ging het verder met plannen. Dan coderen. Daarna het eigen code reviewen. Daarna de eigen review auditen. De output zag er redelijk uit. Het transcript las als een goed geleid project. Maar de architectuur was een fictie.
Dit is wat de fout zo gevaarlijk maakt. Een crash geeft je een signaal. Een stille vervanging niet. Het model is niet misleidend bezig. Het is té behulpzaam. Gegeven een doel en een gebrek aan capaciteit, vult het de leemte in met zijn eigen redenering. Het resultaat is een systeem dat succes rapporteert terwijl het systematisch de structuur die je hebt gebouwd, omzeilt.
De oplossing, en waarom het werkte
De oplossing vereiste niets meer dan het orchestrator-bestand uit de agents-map te verplaatsen en het om te zetten in een slash command.
Slash commands in Claude Code draaien in de top-level sessie. Het zijn geen subagents. Ze zijn het instappunt voor de gebruiker. Vanaf die positie is de Agent tool beschikbaar en kan de orchestrator eindelijk zijn eigenlijke werk doen: workers aanmaken, taken toewijzen en wachten tot de echte resultaten binnenkomen. De vijf specialisten begonnen op te starten in hun eigen contexten. Er vond daadwerkelijk parallellisme plaats. De hiërarchie begon betekenis te krijgen.
Maar de onderliggende kwetsbaarheid verdwijnt niet alleen omdat je de mappenstructuur goed hebt. Zelfs als de orchestrator op de juiste plek staat, kunnen drie specifieke risico's de boel weer laten instorten.
Drie risico's die nog steeds sluimeren
Curated tool lists. Claude Code stelt je in staat om precies te definiëren welke tools een subagent kan gebruiken. Dit is nuttig voor security volgens het principe van 'least privilege'. Het is echter ook een 'foot-gun'. Als je een aangepaste tool-lijst voor een subagent maakt en vergeet de Agent tool op te nemen, wordt die subagent een leaf node. Hij kan geen verdere workers aanmaken. Als je ontwerp ervan uitgaat dat hij een andere laag agents coördineert, zal de distributie net zo stil mislukken als bij Suhail. Het model ziet de instructie, ziet geen tool en voert het werk zelf uit.
Depth limits. Claude Code hanteert een limiet op nesting. Subagents kunnen andere subagents aanmaken tot vijf niveaus diep. Zodra je die grens bereikt, verdwijnt de Agent tool. Dit is geen bug. Het is een beveiliging tegen ongecontroleerde recursie. Maar als je architectuur uitgaat van een zesde niveau van delegatie, zal die laag stilletjes oplossen. De agent op niveau vijf zal de taken absorberen die bedoeld waren voor zijn 'kinderen'. Je boom verandert in een struik, en dat merk je misschien pas als je de herkomst van elke output inspecteert.
Sessietools. Bepaalde tools, zoals AskUserQuestion, zijn gebonden aan de sessie op het hoogste niveau. Ze worden niet doorgegeven aan subagents. Als een gedispatched worker op een ambiguïteit stuit en om verduidelijking probeert te vragen, kan dit niet. De tool ontbreekt. In plaats van de gebruiker te waarschuwen, zal het model gokken. Het zal afleiden wat je waarschijnlijk bedoelde. Soms gokt het goed. Soms bouwt het de verkeerde feature. Hoe dan ook, je krijgt nooit de kans om te antwoorden.
Hoe je het kunt onderscheppen voordat het je iets kost
Je kunt niet elke misconfiguratie voorkomen, maar je kunt wel stoppen met het vertrouwen op het transcript als bewijs van werk.
Het lezen van de conversatie is de eerste verdedigingslinie. Als de tekst zegt "dispatching the researcher" maar de eigenlijke onderzoekscontent verschijnt direct in hetzelfde venster, dan heeft de dispatch nooit plaatsgevonden. Het model beschreef een actie en voerde die actie vervolgens zelf uit. Het eigen paneel van Claude Code zal dit bevestigen. Controleer het aantal afstammelingen (descendants count) voor elke agent waarvan je verwacht dat deze kinderen heeft aangemaakt. Als dit op nul staat, is je hiërarchie verzonnen.
Die visuele controles zijn nuttig, maar ze blijven afhankelijk van menselijke aandacht. De betere aanpak is om het systeem te versterken met artefactverificatie.
Na elke dispatch controleert mijn systeem nu op een specifiek, verwacht bestand. De researcher moet een research.md produceren. De coder moet een diff achterlaten. De reviewer moet een review_notes.json schrijven. Als het bestand niet bestaat, stopt de pipeline onmiddellijk. Geen uitzonderingen, geen graceful degradation. De orchestrator stopt en meldt dat de dispatch is mislukt. Dit verlegt de last van de narratie van het model naar concrete resultaten.
Codeer je beperkingen niet en hoop vervolgens dat het model ze respecteert. Codeer controles die bewijzen dat aan de beperkingen is voldaan. Een model kan een regel in een prompt negeren. Het kan een ontbrekend bestand dat nodig is voor de volgende stap niet negeren.
Bouw met wantrouwen
De les van Suhail gaat niet alleen over de mappenconventies van Claude Code. Het gaat over de bredere realiteit van het bouwen met agentic systemen. Deze modellen zijn optimizers. Wanneer het pad dat je hebt uitgezet geblokkeerd is, zullen ze een ander pad vinden. Vaak is dat pad een kortere route via hun eigen gewichten. Ze zullen het werk zelf doen, de overdracht overslaan en een aannemelijk resultaat voor je voeten leggen.
Jouw taak als bouwer is om sceptisch te blijven. Ga ervan uit dat de dispatch is mislukt totdat het artefact het tegendeel bewijst. Ontwerp je orchestratielaag niet alleen om taken toe te wijzen, maar om te verifiëren dat de toewijzing is geaccepteerd door de juiste worker. Structuur is goedkoop. Verificatie is wat de structuur integer houdt.
Bron: Why Your Claude Code Orchestrator Silently Stops Dispatching Subagents
Doe mee aan de discussie: GyaanSetu AI Community on Telegram