Claude Code: delegare con subagenti annidati

Che cosa è cambiato in Claude Code v2.1.172?#

Se negli ultimi mesi hai letto qualcosa sugli agenti IA in Claude Code, avrai incontrato la stessa frase. Compare nella documentazione ufficiale, nella mia guida sui subagenti e nell'analisi di ogni concorrente. È questa: «un subagente non può avviare un altro subagente». All'11 giugno 2026, quella frase è ancora presente in tre punti diversi di code.claude.com/docs/en/sub-agents. Anthropic non l'ha ancora aggiornata.

Il 10 giugno alle 20:44 UTC, Claude Code v2.1.172 è apparso su GitHub Releases. La voce principale del changelog era una sola riga:

Questa stessa release ha anche corretto un bug che poteva verificarsi solo con l'annidamento: un subagente in background restava evidenziato come attivo nel pannello degli agenti dopo che il subagente annidato da lui avviato era già stato arrestato.

È un caso raro in cui la documentazione ufficiale contraddice ancora la versione rilasciata. Ora spiegherò in che cosa l'annidamento differisce dai subagenti paralleli, che cosa significa «profondità 5» e quali sono i tre scenari in cui oggi è davvero utile.

In che cosa i subagenti annidati differiscono da quelli paralleli e sequenziali?#

Ho passato molto tempo a provare manualmente questi tre approcci; ecco come li vedo: la delega ha tre dimensioni. Larghezza, lunghezza e profondità. Ognuna risolve un problema diverso.

Larghezza — subagenti paralleli. La chat principale avvia N subagenti indipendenti allo stesso livello. Ognuno riceve un'attività circoscritta, lavora nella propria finestra isolata e restituisce solo il risultato. La larghezza risolve il problema della velocità: 5 subagenti che lavorano in parallelo finiscono nel tempo che serve a uno solo per fare lo stesso lavoro in sequenza. È il modello trattato nella mia guida sui subagenti paralleli con worktree.

Lunghezza — una catena di subagenti. A lavora, passa il risultato a B; B lavora e lo passa a C. Ognuno vede l'input del precedente. La lunghezza stabilisce l'ordine: B non può iniziare finché non riceve i dati da A. Un esempio classico: prima un subagente di ricerca raccoglie le fonti, poi un subagente editoriale scrive un articolo basato su quelle fonti e infine un subagente di verifica dei fatti controlla l'articolo. È una sequenza lineare; la chat principale contiene l'intera storia.

Profondità — subagenti annidati. A avvia B, B avvia C, C avvia D. Ogni agente figlio lavora all'interno del proprio genitore, in una finestra isolata, e restituisce solo il risultato al genitore. La chat principale non vede nulla di ciò che accade tra figli, nipoti e pronipoti. Questa è la novità di v2.1.172.

La confusione principale nasce dal pensare che profondità 5 significhi «puoi avviare 5 subagenti contemporaneamente». Non è così. La profondità è un livello verticale dell'albero, non il numero di figli simultanei. A ogni livello può esserci un subagente o cento. Profondità 5 significa che la catena di delega può scendere di 5 passaggi: chat principale → nipote-1 → nipote-2 → nipote-3 → nipote-4 → nipote-5. E a ogni livello può esserci una ramificazione.

La versione 2.1.172 ha rimosso la regola che impediva a un subagente di avviarne un altro.

Se cerchi velocità, ti serve larghezza. Se hai un ordine di esecuzione rigoroso, ti serve lunghezza. La profondità è utile in un solo caso: quando una delle tue attività contiene un sotto-compito rumoroso (15 richieste web, esplorazione dei log, lettura di una dozzina di file) e non vuoi che quel rumore invada la finestra principale.

Che cosa significa in pratica «5 livelli di profondità»?#

Ecco un'importante precisazione. Ho dedicato mezza giornata alla documentazione e alle analisi della community per scoprire che Anthropic non ha fornito una definizione precisa. Ecco che cosa devi sapere.

È un limite massimo, non un'impostazione.

Il limite è implementato lato server. Il reverse engineering del client v2.1.172 non ha trovato alcuna costante MAX_DEPTH. Questo significa che il controllo avviene da qualche parte nell'API Anthropic, non sul tuo computer. Non puoi impostare --max-depth 7 per rendere l'albero più profondo. Né puoi impostare --max-depth 2 per definire un limite più basso e sicuro. L'unico controllo che hai è la allowlist Agent(agent_type) nel frontmatter, ma limita i tipi di agenti figli, non la profondità.

Anthropic non ha definito con precisione «5». Questo è il secondo punto importante:

Anthropic non ha definito con precisione il significato di “5”. Le fonti ufficiali non specificano se depth=5 significhi cinque livelli sotto la radice oppure cinque agenti in totale, radice compresa.

Per ora le integrazioni di terze parti la interpretano in modo diverso. ADR-147 nel progetto ruvnet/ruflo presume «5 livelli figli sotto la radice = 6 agenti nella catena». Nei miei esperimenti uso la stessa convenzione: la chat principale è il livello 0, i figli diretti sono il livello 1 e così via fino al livello 5. Ma questa convenzione non è riportata nella documentazione pubblica.

Il limite è già attivo, senza flag. Non devi attivare nulla. Dopo aver aggiornato Claude Code a v2.1.172, puoi aggiungere Agent a tools di un agente figlio e questo avvierà un altro subagente. La condizione essenziale è che il genitore lo consenta (tools: Agent(...)).

Oggi, a quale tipo di delega ricorri: larghezza, lunghezza o profondità?#

Ripensa agli ultimi 5 prompt. Quante volte è successo questo: avvii un'attività, Claude comincia a cercare nei file, fa 10 richieste web, riversa nel contesto un muro di log e, 20 minuti dopo, ti rendi conto che la finestra è piena. La risposta finale sta già funzionando con un budget di token misero, perché il 70 percento del contesto è stato consumato da dump intermedi.

È uno scenario in cui ti serve la profondità. Non il parallelismo né una catena: la profondità. La chat principale dovrebbe delegare la «ricerca» a un subagente, che poi avvia i propri figli per ricerche web specifiche, letture di file e ricerche nei file. I figli restituiscono solo valutazioni distillate. Un nipote dice al genitore: «Trovato, confermato» oppure «Non trovato, motivo X». Il genitore assembla il tutto in un unico riepilogo e te lo restituisce. La chat principale resta pulita.

Prima del 9 giugno, simulavo questo processo a mano. Aprivo una seconda istanza di Claude Code, copiavo il prompt «fai una ricerca», lo eseguivo e poi trasferivo manualmente il risultato alla finestra principale. Ho descritto questa configurazione in dettaglio nella mia guida sulla delega di attività di programmazione a molti agenti AI. Con v2.1.172 puoi descriverla direttamente nel prompt di sistema dell'orchestratore: Claude costruirà l'albero da sé.

In quali 3 scenari i subagenti annidati sono davvero utili?#

Scenario 1. Ricerca approfondita con verifica dei fatti

Supponiamo che tu stia raccogliendo materiale per un articolo o una proposta commerciale. Per prima cosa devi estrarre 5–10 affermazioni da fonti pubbliche, poi verificarle una per una: trovare la fonte originale, accertarsi che la citazione sia esatta e calcolare i valori effettivi.

Prima di v2.1.172 avevi due possibilità. Potevi fare tutto con un solo subagente, che si trascinava attraverso 30 richieste web, stipando tutto nel proprio contesto. Oppure potevi suddividere manualmente il lavoro: un prompt per estrarre le affermazioni, poi un ciclo sulle affermazioni, avviando un subagente separato per ciascuna. La chat principale si riempiva di muri di elenchi intermedi.

Nella ricetta seguente, la chat principale delega a research-orchestrator (livello 1). L’orchestratore estrae da sé le affermazioni, le invia a fact-verifier (livello 2) e ogni verificatore delega ricerche mirate a web-deep-search (livello 3). La chat principale riceve solo un array di affermazioni verificate con le fonti. Tutto il resto resta nelle finestre figlie e non entra mai nel tuo contesto.

Scenario 2. Analisi di un repository ampio

Ti è stato affidato un progetto con 200 file. Devi capirne l'architettura, individuare i moduli principali e valutare il debito tecnico. Esegui Glob e una dozzina di chiamate Read a mano e in 10 minuti avrai riempito la finestra.

La profondità risolve il problema così: la chat principale avvia un subagente «architect». L'architect genera internamente tre figli: uno ispeziona la struttura delle directory (esegue Glob e la riassume), il secondo legge 5 file di configurazione chiave e il terzo cerca nel codice i pattern principali. Ognuno restituisce all'architect un riepilogo conciso. L'architect compone il quadro e fornisce alla chat principale un rapporto finale lungo mezza schermata. Ottieni una mappa del progetto senza inondare il contesto con un muro di output di cat proveniente da tutti i file.

Scenario 3. Analisi delle dipendenze end-to-end

Stai modificando uno schema di database, un contratto API o un file di configurazione condiviso. Devi capire dove si manifesteranno gli effetti. Questa attività consuma il contesto più rapidamente perché ci sono molte dipendenze, ognuna delle quali va verificata nel codice sorgente.

Con la profondità, la chat principale avvia un impact-analyzer (livello 1). Questo avvia un dependency-tracer per ogni file interessato (livello 2). Ogni tracer avvia internamente un consumer-finder (livello 3), che cerca nella codebase i consumer di quella dipendenza. Ciascuno restituisce solo il succo: «questi tre punti si romperanno». La chat principale compone una tabella «file interessati → impatto» senza conoscere i risultati delle ricerche nel codice.

Come configurare i subagenti annidati in 10 minuti#

Passaggio 1. Assicurati di usare v2.1.172 o una versione successiva.

claude --version

Se è una versione precedente, aggiorna. La funzionalità principale della release è una sola riga nel changelog: «Ora i subagenti possono avviare a loro volta subagenti, fino a 5 livelli di profondità» (testo completo).

Passaggio 2. Crea un agente genitore che possa avviare figli.

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

---
name: research-orchestrator
description: Delega ricerche con fact-check approfondito
tools: Agent(fact-verifier), Read, WebFetch
model: opus
---

Sei un orchestratore di ricerca. Quando ricevi un argomento:
1. Leggi i materiali forniti o recupera gli URL pubblici indicati.
   Estrai personalmente fino a 5 affermazioni concrete. Per ciascuna registra testo,
   URL o file di origine e passaggio esatto di supporto.
   Se mancano materiali, chiedili prima di delegare.
2. Per ogni affermazione chiama fact-verifier: genererà autonomamente
   i propri subagenti figli per la ricerca web e il controllo.
3. fact-verifier ti restituirà solo i verdetti finali:
   non caricare nel tuo contesto i dump intermedi.

Il rapporto finale deve essere solo un array { claim, sources[], confidence }.

La riga tools concede solo il tipo figlio fact-verifier. L’estrazione è il primo passo dell’orchestratore e non serve un file claim-extractor indefinito. La lista limita il tipo richiamabile, non quante volte venga avviato. Mantieni la ricetta circoscritta a cinque affermazioni al massimo.

Passaggio 3. Crea un agente figlio che possa generare autonomamente dei pronipoti.

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

---
name: fact-verifier
description: Verifica un'affermazione tramite ricerche web figlie
tools: Agent(web-deep-search), Read
model: sonnet
---

Sei un verificatore dei fatti. Quando ricevi un'affermazione:
1. Formula 2-3 query di ricerca.
2. Per ciascuna, avvia web-deep-search: eseguirà da sé
   WebSearch e WebFetch e restituirà snippet verificati.
3. Riassumi tutto in un unico verdict: { claim, sources[], confidence }.

Noti il punto essenziale? Anche qui tools dice Agent(web-deep-search). Ciò significa che il fact-verifier (livello 2 del nostro albero) può avviare direttamente un altro subagente (livello 3). In precedenza, questa riga non aveva alcun effetto: la documentazione contiene ancora la frase:

Con v2.1.172, quella frase è obsoleta. La sintassi è la stessa, ma ora funziona a qualsiasi profondità nell'albero.

Passaggio 4. Crea un pronipote.

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

---
name: web-deep-search
description: Esegue ricerche web e restituisce snippet
tools: WebSearch, WebFetch
model: haiku
---

Hai ricevuto una query di ricerca. Esegui WebSearch, seleziona i 3 URL
più pertinenti e usa WebFetch per estrarre conferme letterali dell'affermazione.
Restituisci un array { url, snippet, supports_claim: yes|no }.

Il pronipote non ha Agent in tools, quindi non avvia altri agenti lungo l'albero.

Passaggio 5. Esegui l'orchestratore.

claude --agent research-orchestrator

Fornisci poi testo o URL pubblici nella chat: «Estrai e verifica fino a 5 affermazioni concrete da queste fonti; restituisci affermazioni, fonti e confidenza». Con --agent research-orchestrator, la sessione stessa è l’orchestratore; verificatori e ricercatori aggiungono due livelli sotto di esso. Se una sessione principale ordinaria delega all’orchestratore, ci sono invece tre livelli delegati sotto la principale.

Quali 5 anti-pattern sprecano token e distruggono l'osservabilità?#

Anti-pattern 1. L'attività può stare in un'unica finestra.

Se un subagente può gestirla senza generare rumore, non aggiungere livelli: l'annidamento aggiunge costi e latenza senza alcun vantaggio.

Anti-pattern 2. Cerchi velocità, non isolamento.

Se cerchi velocità, ti serve il parallelismo, non la profondità. Avvia 5 subagenti affiancati allo stesso livello invece di costruire una catena. La profondità serve a spostare il lavoro preparatorio disordinato in una finestra figlia, non ad accelerare le cose.

Anti-pattern 3. Il lavoro è intrinsecamente poco profondo.

«Trova questo file e mostramelo» è una richiesta in due passaggi; non richiede una gerarchia a tre livelli. L'annidamento vale la pena quando un'attività contiene un sotto-compito rumoroso. Se non c'è rumore, non aggiungere subagenti.

Anti-pattern 4. Prompt vaghi al primo livello.

Questo è lo scenario più pericoloso. Se dai un prompt vago all'orchestratore di livello 1, la vaghezza si moltiplica. Un prompt vago al livello 1 diventa 4 prompt vaghi al livello 2 e 16 al livello 3. Quando i nipoti iniziano a lavorare, non sanno nemmeno che cosa stanno cercando.

Anti-pattern 5. Crescita geometrica dei costi.

Il principale argomento economico: l'annidamento moltiplica l'uso dei token e la moltiplicazione si accumula con la profondità.

Un calcolo approssimativo: una catena di profondità 3 con una ramificazione di 3 a ogni livello significa 27 subagenti. Sono almeno 27 volte più token rispetto a una semplice richiesta. Con il piano Pro di Claude, questo calcolo consuma il limite giornaliero in un paio d'ore. Se hai un piano Max, esaurirai in un giorno il budget di una settimana.

Anti-pattern bonus (per esperienza personale): «50 agenti che fanno lavoro inutile».

Quando guardo i progetti altrui, spesso vedo questo: «Ho 50 agenti al lavoro». Chiedo: che cosa stanno facendo? E quei 50 agenti fanno lavoro inutile. Generano pile di output superfluo, una quantità enorme di riepiloghi grezzi, duplicati e muri di log. Ognuno fa qualcosa di «generalmente utile» e il risultato è un contesto sommerso e una fattura di token come quella di una piccola azienda. La profondità 5 non risolve il problema: lo peggiora. Se già al livello 1 non è chiaro chi fa cosa, la profondità 5 significa cinque livelli di confusione.

Prima di avviare un subagente, rispondi a 4 domande in mezzo minuto:

• Che cosa fa esattamente (in una frase)?
• Quali file tocca?
• Che cosa restituisce al genitore?
• Chi lo verifica?

Se non sai rispondere in 30 secondi, quel subagente non dovrebbe esistere. Ho spiegato questa regola a parte nella mia guida sui subagenti paralleli.

Perché annidare senza progettare il contesto significa avere 5 livelli di allucinazioni?#

È qui che spesso mi chiedono: «Ho aggiornato Claude Code, aggiunto Agent a tools, l'albero si costruisce, ma la risposta finale è ancora sbagliata. Perché?»

La risposta è semplice. Ogni subagente in Claude Code parte da zero. Dalla documentazione ufficiale:

Al livello 1, è gestibile: l'orchestratore passa al figlio una breve descrizione dell'attività. Ma al livello 3, il pronipote riceve un messaggio di delega dal genitore, che aveva ricevuto anch'esso solo un messaggio di delega. Ognuno ha trasmesso un pezzetto. Al livello 5 hai un subagente la cui finestra contiene la frase «verifica l'affermazione X» e nient'altro. Non sa in quale progetto sta lavorando, quale attività sta svolgendo o su cosa concentrarsi.

Senza CLAUDE.md, un pronipote di quinto livello è come un dipendente che si presenta in ufficio per la prima volta nella vita senza ricevere alcun orientamento. Farà qualcosa perché ha ricevuto un'attività. Ma non sarà ciò di cui il progetto ha bisogno.

Ecco perché la configurazione è essenziale. La profondità 5 senza un CLAUDE.md configurato correttamente, una cartella business/ e una pipeline di skill è un casinò. Con questi elementi, è uno strumento.

Che cos'altro è cambiato in v2.1.172 oltre all'annidamento?#

Apri il changelog completo di v2.1.172 e vedrai che l'intera release riguarda i subagenti.

Correzione 1. Un subagente in background non resta più «bloccato» come attivo nel pannello degli agenti dopo che il subagente annidato da lui avviato viene arrestato. Questo bug può verificarsi solo con l'annidamento.

Correzione 2. Ora le restrizioni di availableModels si applicano anche ai subagenti. Prima, se limitavi i modelli utilizzabili dal team (per esempio, vietando opus per risparmiare), i subagenti potevano aggirare la regola tramite un override nella propria configurazione. Con v2.1.172, la regola si applica ovunque.

Correzione 3. La freccia su nella cronologia dei prompt ora mostra i prompt della scheda corrente del subagente, non quelli dell'agente principale. Un ritocco all'osservabilità.

Correzione 4. L'uso della CPU quando il sistema è inattivo è ridotto: l'indicatore /goal non ridisegna più il terminale a 5 Hz quando è inattivo e l'interfaccia si ridisegna meno spesso mentre i subagenti paralleli lavorano.

Sottolineo che tutte e quattro le correzioni riguardano i subagenti. Questo significa che Anthropic ha rilasciato l'intero stack dell'infrastruttura per l'annidamento, non solo una riga nel changelog. L'annidamento era già in uso all'interno di Anthropic da qualche tempo prima della pubblicazione.

Checklist: quando l'annidamento aiuta e quando è controproducente#

Usa l'annidamento se:

• L'attività contiene un sotto-compito con un grande volume di richieste web, ricerche nei file o letture di file.
• Puoi fare a meno di quel sotto-compito (se il pronipote non trova nulla, l'orchestratore può continuare).
• Non hai bisogno dei risultati intermedi nella finestra principale.
• Hai un CLAUDE.md e un contesto di progetto strutturato su cui il subagente può fare affidamento.
• Sai descrivere chiaramente che cosa restituirà ogni livello (input, output, formato).
• Hai un piano Max o un margine sufficiente per ×27 token.

Non usare l'annidamento se:

• Un subagente può risolvere l'attività senza generare rumore.
• Hai bisogno dei risultati intermedi nella finestra principale (in tal caso ti serve il parallelismo).
• Il progetto non ha un CLAUDE.md o dispone solo di un contesto aziendale scarno.
• I prompt di livello 1 sono vaghi (la vaghezza si moltiplicherà esponenzialmente lungo l'albero).
• Ti serve velocità: a parità di risultato, il parallelismo è più rapido della profondità.
• Hai il piano Pro e lavori tutto il giorno: consumerai il limite in un paio d'ore.

Altri materiali sono disponibili su Ailoot.