Passa al contenuto principale

Limiti delle flotte di subagenti: soglie di concorrenza e profondità di annidamento

Avanzato

Il 21 luglio 2026 Claude Code ha rilasciato v2.1.217 e imposto i primi limiti rigidi sulle flotte di subagenti: 20 subagenti concorrenti per sessione, e spawn annidato disattivato del tutto. Tre giorni dopo v2.1.219 (24 luglio) ha reintrodotto l'annidamento con profondità predefinita 3. La causa era pubblica e specifica: un ticket del 13 giugno in cui una singola attività di ricerca aveva generato 48+ agenti in background simultanei bruciando ~1,5M di token in lavoro ridondante prima che l'utente riuscisse a fermarli (anthropics/claude-code#68110).

Se orchestri più di una manciata di agenti per turno, questi limiti ora definiscono cosa può fare un singolo messaggio — e come scrivi il tuo .mcp.json, .env e i prompt di orchestrazione.

What you'll learn
  • Le quattro variabili d'ambiente che governano le flotte: concorrenza, profondità di annidamento, totale per sessione e modello del subagente
  • L'errore esatto che Claude vede quando raggiunge il limite, e perché il runtime gli dice di NON riprovare
  • Perché l'annidamento è stato eliminato per 72 ore e cosa significa davvero il valore predefinito ripristinato (profondità 3) per il fan-out
  • Quando ultracode ti esenta dal tetto di concorrenza, e quando i limiti rigidi dei workflow prevalgono su tutto
  • Un pattern con orchestrazione dal parent che resta nei limiti a qualunque scala

L'incidente che ha plasmato i limiti​

Il ticket #68110 (aperto il 13 giugno 2026) è la storia d'origine onesta. Un utente ha delegato una singola attività di ricerca a un subagente general-purpose. Quel subagente — poiché i subagenti general-purpose ereditano il tool Agent — ha generato i propri figli. Quei figli ne hanno generati altri. In pochi turni, 48+ agenti in background erano attivi, con quattro agenti separati che ricercavano indipendentemente la stessa API di terze parti (Wise), e l'utente non riusciva a ucciderli più in fretta di quanto rinascessero. Spesa totale prima dell'intervento: ~1,5M di token.

La risposta è arrivata cinque settimane dopo in due eventi di rilascio:

DataVersioneCambiamento
2026-07-21v2.1.217Limite concorrenti = 20; spawn annidato disattivato (profondità = 1)
2026-07-24v2.1.219Annidamento reintrodotto con profondità predefinita = 3

La finestra di tre giorni con l'annidamento spento è la parte interessante — chiaramente Anthropic ha pesato "niente fan-out" contro "niente orchestrazione" e ha scelto una via di mezzo.

Le quattro variabili d'ambiente​

Ogni manopola è una variabile d'ambiente CLAUDE_CODE_ — impostale nella shell, in .env, o per progetto tramite settings.json.

VariabilePredefinitoCosa fa
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS20Tetto rigido sui subagenti attivi nello stesso istante in una sessione. Superarlo fa fallire lo spawn con "Concurrent subagent limit reached".
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH3Quanti livelli di profondità un subagente può generare i propri figli. 1 = disattiva l'annidamento del tutto (solo il parent orchestra).
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION200Limite cumulativo sull'intera sessione — gli spawn oltre questo valore falliscono anche se la concorrenza è a posto.
CLAUDE_CODE_SUBAGENT_MODEL(eredita)Forza ogni subagente su un modello specifico. Instrada le fasi di massa su Haiku/Sonnet per tenere un budget Opus sul parent.

Due altri numeri vivono dentro il runtime, non come variabili d'ambiente:

  • Limiti rigidi dei workflow per Dynamic Workflows & ultracode: 16 concorrenti e 1.000 totali di agenti per esecuzione di workflow. Questi bloccano qualsiasi cosa un workflow lanci, indipendentemente dalle variabili d'ambiente della sessione.
  • Le sessioni con ultracode attivo sono esenti da CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. La logica: il layer workflow di ultracode già impone la propria coppia 16/1.000, quindi il tetto di sessione sarebbe doppio.

L'errore che vedrai davvero​

Quando il tuo agente principale prova a generare il 21° subagente concorrente (o il 4° annidato alla profondità predefinita), la chiamata del tool restituisce:

Risultato del tool — non riprovare

Concurrent subagent limit reached

Il runtime istruisce il modello a non fare loop contro il limite — deve procedere con meno agenti o serializzare. Questo è importante per due motivi:

  1. Riprovare è esattamente il comportamento che ha reso #68110 catastrofico. Fare back-off è per design.
  2. Se vedi lo stesso errore in un hook o in un log più di qualche volta di seguito, hai un problema di prompt, non un problema di limiti — il tuo parent è propenso al fan-out e va istruito a fare batch.

Come configurare una flotta​

Guided walkthrough1 of 5
  1. Parti dal predefinito 20. Alzalo solo se hai davvero lavoro indipendente — uno sweep su tutto il codice tra 60 package, ad esempio. Imposta `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=40` per progetto, non globalmente.

Un pattern con orchestrazione dal parent che sopravvive ai limiti​

La topologia più sicura di flotta sotto i nuovi predefiniti è breadth-first dal parent — la sessione principale genera worker, i worker non generano worker. Usa la semantica profondità = 1 anche quando profondità = 3 è disponibile, e rende banale la matematica della concorrenza: in qualsiasi istante hai ≤ N worker, mai un albero di dimensione ignota.

Forma concreta per uno sweep su una codebase di 60 moduli:

Sweep con batch orchestrato — prompt della sessione principale

Sweep the codebase for uses of the deprecated `legacyClient()` helper.

Batch the 60 packages into 3 waves of 20. For each wave:
1. Spawn 20 read-only `Explore` subagents in parallel, one per package.
2. Wait for all 20 to return before spawning the next wave.
3. Do NOT let a subagent spawn its own children — pass every package
   in the delegation prompt directly.

Aggregate into a single `REPORT.md` after wave 3. Report the total
count and any packages that failed with the exact error string.

Perché regge:

  • 20 worker concorrenti raggiungono il tetto predefinito esattamente una volta per ondata — nessuno spawn fallito.
  • L'annidamento non viene usato, quindi CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH non conta — la configurazione funziona su v2.1.217 (annidamento spento) e v2.1.219 (annidamento acceso).
  • Spawn cumulativi: 60, ben sotto i 200 predefiniti per sessione.

Quando rompere il pattern (e usare l'annidamento)​

Profondità = 3 esiste per un motivo: alcuni problemi sono davvero gerarchici. Due forme beneficiano dell'annidamento:

  • Alberi di ricerca profondi. Un subagente research di primo livello che a sua volta deve confrontare cinque fonti — ognuna non triviale — può generare cinque figli researcher fratelli. Profondità = 2 totali.
  • Map/reduce con finalize per shard. Il parent genera N owner di shard; ogni owner genera 1 finalizer una volta terminato lo shard. Profondità = 2 totali, ma strutturalmente più pulito che se il parent tracciasse ogni finalize da solo.

Se una di queste forme descrive il tuo lavoro, lascia stare il predefinito. Se la tua topologia è piatta, imposta CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 esplicitamente — vale come documentazione e come rete di sicurezza.

Interazione con /agents e i subagenti in background​

Due sottigliezze che inciampano chi incontra i limiti per la prima volta:

  • I subagenti in background contano. Dalla Week 27 (29 giugno – 3 luglio 2026) i subagenti girano in background di default. Un agente in background conta comunque contro il tuo tetto di concorrenza mentre è attivo, anche se il parent non è bloccato in attesa.
  • background: true nel frontmatter non annulla il limite. Fissare un subagente in background nel suo frontmatter cambia quando il parent riprende — non se il runtime lo conta.

Se vedi l'errore di limite e la sessione principale sembra ferma, esegui /agents (o controlla la status line — vedi Statusline) per scoprire cosa è ancora vivo da prima nella sessione.

Sonnet 5, Opus 5 e i costi sotto i limiti​

Il comportamento predefinito di CLAUDE_CODE_SUBAGENT_MODEL è eredita — un subagente gira sul modello del parent. Per sessioni Opus 5 con 20 worker concorrenti, il conto sale veloce. La forma consigliata dopo l'arrivo dei limiti è:

  • Parent su Opus 5 per l'orchestrazione e la sintesi finale.
  • CLAUDE_CODE_SUBAGENT_MODEL=claude-sonnet-5 per i worker che fanno task ben delimitati IO-heavy.
  • Per qualsiasi cosa meccanica (lavoro tipo grep, controlli di formato), Haiku 4.5.

Vedi Scegliere un modello per i trade-off tra tier, e MCP Token Cost per come i subagenti tool-heavy gonfiano il conto indipendentemente dal modello.

Verifica te stesso

0/3
  1. Generi 25 subagenti tutti insieme dalla sessione principale. Cosa succede con le impostazioni predefinite?
  2. Impostare `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1` produce quale topologia?
  3. Esegui un workflow che richiede 200 agenti concorrenti. Quale strada funziona?
Limiti di flotta — gira ogni carta
Premi Invio o Spazio per girare la carta. Usa le frecce sinistra e destra per spostarti tra le carte.Termine mostrato.
1 / 6
Key takeaways
  • Il tetto predefinito di concorrenza è 20; la profondità di annidamento predefinita è 3 (era 1 per 72 ore a fine luglio 2026).
  • Le quattro manopole sono tutte variabili d'ambiente `CLAUDE_CODE_*` — concorrenza, profondità di spawn, totale per sessione e modello del subagente.
  • 'Concurrent subagent limit reached' è un segnale di fallimento-e-stop, non di retry. Occorrenze ripetute significano che il tuo prompt parent è propenso al fan-out.
  • L'orchestrazione dal parent a ondate è la topologia più sicura sotto i nuovi limiti e funziona identica su v2.1.217 e v2.1.219.
  • Se ti serve più di ~40 concorrenti, hai superato la singola sessione — passa ai Dynamic Workflow e ai suoi limiti workflow 16/1.000.

Prossimi passi​

Fonti e letture di approfondimento​