Creare subagent personalizzati

Creare e utilizzare subagent AI specializzati in Claude Code per flussi di lavoro specifici di attività e una migliore gestione del contesto.

I subagent sono assistenti AI specializzati che gestiscono tipi specifici di attività. Utilizzi uno quando un'attività secondaria allagherebbe la sua conversazione principale con risultati di ricerca, log o contenuti di file che non farà più riferimento: il subagent svolge quel lavoro nel suo proprio contesto e restituisce solo il riassunto. Definisca un subagent personalizzato quando continua a generare lo stesso tipo di worker con le stesse istruzioni.

Ogni subagent viene eseguito nella propria finestra di contesto con un prompt di sistema personalizzato, accesso a strumenti specifici e autorizzazioni indipendenti. Invia anche le proprie richieste, che contano verso gli stessi limiti di utilizzo della sua conversazione principale. Quando Claude incontra un'attività che corrisponde alla descrizione di un subagent, la delega a quel subagent, che lavora in modo indipendente e restituisce i risultati. Per vedere il risparmio di contesto in pratica, la visualizzazione della finestra di contesto illustra una sessione in cui un subagent gestisce la ricerca nella sua finestra separata.

[!NOTE]

I subagent funzionano all'interno di una singola sessione. Per eseguire molte sessioni indipendenti in parallelo e monitorarle da un unico posto, consulti background agents. Per sessioni separate che si scambiano messaggi, consulti cross-session messaging. Per un team coordinato di sessioni che Claude genera e supervisiona, consulti agent teams.

I subagent la aiutano a:

• Preservare il contesto mantenendo l'esplorazione e l'implementazione fuori dalla sua conversazione principale
• Applicare vincoli limitando quali strumenti un subagent può utilizzare
• Riutilizzare configurazioni tra progetti con subagent a livello utente
• Specializzare il comportamento con prompt di sistema focalizzati per domini specifici
• Controllare i costi instradando le attività a modelli più veloci ed economici come Haiku

Claude utilizza la descrizione di ogni subagent per decidere quando delegare le attività. Quando crea un subagent, scriva una descrizione chiara in modo che Claude sappia quando utilizzarlo.

Quelle descrizioni occupano contesto, quindi le mantenga brevi. Quando le descrizioni combinate dei suoi subagent, ad eccezione di quelli integrati, superano i 15.000 token, Claude Code mostra un avviso all'avvio con il conteggio totale dei token. Riduca i campi description dei suoi subagent e sposti i dettagli nel prompt di sistema di ogni subagent, che si carica solo quando quel subagent viene eseguito.

Subagent integrati

Claude Code include subagent integrati che Claude utilizza automaticamente quando appropriato. Ognuno eredita le autorizzazioni della conversazione principale; la maggior parte viene eseguita con un set di strumenti limitato.

Explore e Plan si avviano senza i tuoi file CLAUDE.md e senza lo snapshot dello stato git per mantenere la ricerca veloce ed economica. Gli altri subagent integrati e i subagent personalizzati caricano entrambi, a meno che tu non imposti omitClaudeMd nella definizione di un subagent personalizzato per avviarlo senza i file CLAUDE.md dell'utente, del progetto e locali. Per la suddivisione completa di ciò che raggiunge un subagent, consulta cosa si carica all'avvio.

[tab] Explore

Un agente veloce e di sola lettura ottimizzato per la ricerca e l'analisi delle basi di codice.

• Model: il modello della conversazione principale. Quando la conversazione principale usa Fable, il modello di Explore dipende da come ti connetti:
  • Con un abbonamento Claude, un account Anthropic Console o un gateway LLM raggiunto tramite ANTHROPIC_BASE_URL, Explore viene eseguito sul modello Opus a cui si risolve l'alias opus.
  • Su Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, Claude Platform su AWS o un gateway delle app Claude, Explore resta sul modello della conversazione principale.
• Tools: strumenti di sola lettura; Write e Edit sono negati
• Purpose: scoperta di file, ricerca di codice, esplorazione del codebase

Un subagent utente o progetto denominato Explore sovrascrive quello integrato e mantiene il proprio campo model, quindi definiscine uno con model: haiku per eseguire l'esplorazione su un modello a costo inferiore. Per forzare un unico modello su ogni subagent, Explore incluso, consulta Eseguire ogni subagent su un modello.

Claude delega a Explore quando ha bisogno di cercare o comprendere una base di codice senza apportare modifiche. Questo mantiene i risultati dell'esplorazione fuori dal contesto della conversazione principale.

Quando invoca Explore, Claude specifica un livello di accuratezza: quick per ricerche mirate, medium per esplorazione equilibrata, o very thorough per analisi completa.

[tab] Plan

Un agente di ricerca utilizzato durante la Plan Mode per raccogliere contesto prima di presentare un piano.

• Model: eredita dalla conversazione principale, a meno che non impostiate CLAUDE_CODE_SUBAGENT_MODEL e lo forziate su ogni subagent
• Tools: strumenti di sola lettura; Write e Edit sono negati
• Purpose: ricerca della base di codice per la pianificazione

Quando è in Plan Mode e Claude ha bisogno di comprendere la vostra base di codice, delega la ricerca al subagent Plan in modo che l'output dell'esplorazione rimanga in una finestra di contesto separata mentre la conversazione principale rimane di sola lettura.

[tab] General-purpose

Un agente capace per attività complesse e multi-step che richiedono sia esplorazione che azione.

• Model: il modello CLAUDE_CODE_SUBAGENT_MODEL se lo impostate e niente assegna un modello in un altro modo, altrimenti il modello della conversazione principale; Scegliere un modello indica l'ordine completo, e Eseguire ogni subagent su un modello mostra come fare in modo che la variabile sostituisca quelle fonti
• Tools: ogni strumento disponibile per i subagent
• Purpose: ricerca complessa, operazioni multi-step, modifiche del codice

Claude delega a general-purpose quando l'attività richiede sia esplorazione che modifica, ragionamento complesso per interpretare i risultati, o più step dipendenti.

[tab] Other

Claude Code include agenti helper aggiuntivi per attività specifiche. Questi vengono generalmente invocati automaticamente, quindi non avete bisogno di utilizzarli direttamente.

Agent	Model	Quando Claude lo utilizza
claude	Nessuno proprio; segue l'ordine dei modelli quando Claude lo genera come subagent	Quando un'attività non si adatta a un agente più specializzato. Un catch-all con ogni strumento disponibile per i subagent. Anche l'agente predefinito per una sessione in background inviata; quale modalità di autorizzazione inizia dipende da come è stata avviata la sessione
statusline-setup	Sonnet	Quando eseguite /statusline per configurare la vostra linea di stato
claude-code-guide	Haiku	Quando fate domande sulle funzionalità di Claude Code

I subagent integrati sono registrati per impostazione predefinita nelle sessioni interattive. Per limitarli:

• Per bloccare un tipo integrato specifico, aggiungetelo a permissions.deny come mostrato in Disabilitare subagent specifici.
• Per impedire a Claude di delegare a qualsiasi subagent, negate lo strumento Agent stesso con permissions.deny.
• Per rimuovere solo i subagent integrati Explore e Plan, impostate CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1. Claude legge ed esplora i file direttamente invece di delegare a loro. Richiede Claude Code v2.1.198 o successivo.
• In modalità non interattiva e in Agent SDK, impostate CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 per rimuovere tutti i tipi integrati e fornire solo i vostri.

Una chiamata dello strumento Agent che omette subagent_type non riesce con subagent_type is required quando la sessione non ha alcun subagent general-purpose su cui ripiegare.

Oltre a questi subagent integrati, potete creare i vostri con prompt personalizzati, restrizioni di strumenti, modalità di autorizzazione, hooks e skills. Le sezioni seguenti mostrano come iniziare e personalizzare i subagent.

Guida rapida: crea il tuo primo subagent

I subagent sono file Markdown con frontmatter YAML. Per crearne uno, chiedi a Claude di scriverlo per te, oppure scrivi il file manualmente.

Questa procedura crea un subagent a livello utente che esamina il codice e suggerisce miglioramenti.

1. Chiedi a Claude di creare il subagent

In Claude Code, descrivi il subagent che desideri e dove salvarlo:

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude scrive il file con un name, una description, un elenco tools, un model e un prompt di sistema.

2. Esamina il file

Apri ~/.claude/agents/code-improver.md e verifica che il frontmatter corrisponda a quello che hai richiesto. Il risultato è simile a questo:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Poiché il file si trova in ~/.claude/agents/, il subagent è disponibile in ogni progetto sulla tua macchina. Per limitarlo a un solo progetto, spostalo nella directory .claude/agents/ di quel progetto. Scegli l'ambito del subagent confronta le due opzioni.

3. Provalo

Chiedi a Claude di delegare al nuovo subagent:

Use the code-improver agent to suggest improvements in this project

Claude delega al tuo nuovo subagent, che scansiona il codebase e restituisce suggerimenti di miglioramento. Nella trascrizione, la delega appare come una riga di chiamata a uno strumento che mostra il nome del subagent seguito da una breve descrizione dell'attività, ad esempio code-improver(Suggest code improvements).

Se Claude non riesce a trovare il nuovo subagent, riavvia Claude Code e riprova. Questo accade solo quando ~/.claude/agents/ non esisteva prima dell'inizio della sessione, perché una sessione in esecuzione non rileva una directory agents appena creata.

Ora hai un subagent che puoi utilizzare in qualsiasi progetto sulla tua macchina per analizzare i codebase e suggerire miglioramenti.

Puoi anche scrivere file subagent manualmente, definirli tramite flag CLI o distribuirli tramite plugin. Le sezioni seguenti coprono tutte le opzioni di configurazione.

[!NOTE]

L'esecuzione di /agents stampa un promemoria per chiedere a Claude o modificare direttamente .claude/agents/ e ~/.claude/agents/. Su Claude Code v2.1.197 e versioni precedenti, /agents apre una procedura guidata interattiva con una scheda Running che elenca i subagent attivi e una scheda Library per crearli, modificarli ed eliminarli.

Configuri i subagent

La posizione del file di un subagent determina chi ha accesso ad esso, e il suo frontmatter determina cosa può fare. Questa sezione copre dove vivono i file dei subagent e ogni campo che supportano.

Scelga l'ambito del subagent

Archivi i file dei subagent in posizioni diverse a seconda dell'ambito. Quando più subagent condividono lo stesso nome, Claude Code utilizza quello dalla posizione con priorità più alta.

I subagent di progetto (.claude/agents/) sono ideali per subagent specifici di una base di codice. Li archivi nel controllo della versione in modo che il suo team possa utilizzarli e migliorarli in modo collaborativo.

I subagent di progetto vengono scoperti camminando verso l'alto dalla directory di lavoro corrente, quindi ogni .claude/agents/ tra lì e la radice del repository viene scansionato. Quando più di una di queste directory annidate definisce lo stesso name, Claude Code utilizza la definizione più vicina alla directory di lavoro.

Quando aggiunge una directory con --add-dir o /add-dir, Claude Code carica anche la sua cartella .claude/agents/, insieme ai subagent di progetto. Consulti Directory aggiuntive per quali altri tipi di configurazione si caricano da --add-dir. Per condividere i subagent tra progetti senza --add-dir, usi ~/.claude/agents/ o un plugin.

I subagent utente (~/.claude/agents/) sono subagent personali disponibili in tutti i suoi progetti.

Claude Code scansiona .claude/agents/ e ~/.claude/agents/ ricorsivamente, quindi può organizzare le definizioni in sottocartelle come agents/review/ o agents/research/. Il percorso della sottodirectory non influisce su come un subagent viene identificato o invocato, perché l'identità proviene solo dal campo frontmatter name.

Mantieni i valori name univoci in tutto l'albero: se due file all'interno della stessa directory .claude/agents/, incluse le sue sottocartelle, dichiarano lo stesso nome, Claude Code carica solo uno di essi, scelto in base all'ordine di lettura del filesystem anziché in base a una precedenza documentata. Tra le directory di progetto annidate, ha la precedenza la definizione più vicina alla directory di lavoro, come descritto sopra. Il controllo di configurazione /doctor segnala i file nella stessa directory che condividono un nome e propone di rinominarli o rimuoverli tutti tranne uno.

Le directory agents/ del plugin vengono scansionate anche ricorsivamente. A differenza degli ambiti di progetto e utente, una sottocartella all'interno della directory agents/ di un plugin diventa parte dell'identificatore con ambito: un file in agents/review/security.md nel plugin my-plugin si registra come my-plugin:review:security.

I subagent definiti da CLI vengono passati come JSON quando avvia Claude Code. Esistono solo per quella sessione e non vengono salvati su disco, rendendoli utili per test rapidi o script di automazione. Può definire più subagent in una singola chiamata --agents:

[tab] macOS, Linux, WSL

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

[tab] Windows PowerShell

claude --agents @'
{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}
'@

In modalità non interattiva, --agents accetta anche il percorso di un file JSON che contiene lo stesso oggetto, per definizioni troppo grandi per passare sulla riga di comando. Ad esempio, claude -p --agents ./agents.json "Review my changes" legge le definizioni da quel file. In una sessione interattiva, Claude Code rifiuta un percorso di file. La forma di file richiede Claude Code v2.1.281 o successivo.

Ogni chiave di primo livello nel JSON è il nome di un agente, e il suo valore è la definizione di quell'agente. Non inizi un nome con -. Una definizione accetta questi campi:

• prompt: il prompt di sistema dell'agente, equivalente al corpo markdown nei subagent basati su file. prompt può essere vuoto. Se seleziona un agente con un prompt vuoto e nessun campo memory come agente della sessione con --agent, il prompt di sistema della sessione rimane invariato. Un prompt vuoto richiede Claude Code v2.1.281 o successivo.
• Campi del frontmatter: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, autoCompactWindow, skills, initialPrompt, memory, effort, background, omitClaudeMd e isolation.
• Campi ignorati: color e experimental non vengono accettati qui e vengono ignorati piuttosto che rifiutati.

Per quello che Claude Code fa con un valore che non può caricare, e i flag e la variabile di ambiente che saltano quel controllo, consulti Invalid --agents configuration.

I subagent gestiti vengono distribuiti dagli amministratori dell'organizzazione. Posizioni file markdown in .claude/agents/ all'interno della directory managed settings, utilizzando lo stesso formato frontmatter dei subagent di progetto e utente. Le definizioni gestite hanno la precedenza sui subagent di progetto e utente con lo stesso nome.

I subagent plugin provengono da plugins che ha installato. Si caricano automaticamente insieme ai suoi subagent personalizzati e appaiono nella typeahead @-mention con il loro nome con ambito. Consulti il riferimento dei componenti plugin per i dettagli sulla creazione di subagent plugin.

[!NOTE]

Per motivi di sicurezza, i subagent dei plugin non supportano i campi del frontmatter hooks, mcpServers o permissionMode. Questi campi vengono ignorati quando si caricano agenti da un plugin. Se ti servono, copia il file dell'agente in .claude/agents/ o ~/.claude/agents/. Puoi anche aggiungere regole a permissions.allow in settings.json o settings.local.json, ma queste regole si applicano all'intera sessione, non solo al subagent del plugin.

Se sei l'autore del plugin, distribuisci invece gli hook nel file hooks/hooks.json del plugin e i server MCP nel suo .mcp.json. Si applicano ogni volta che il plugin è abilitato, anziché solo all'interno del subagent.

Puoi anche riutilizzare la definizione di un subagent per un compagno di squadra di un team di agenti: indica il tipo di subagent quando chiedi a Claude di generare il compagno di squadra, e Claude Code gli applica parti di quella definizione. Usare le definizioni dei subagent per i compagni di squadra indica quali ambiti e quali parti si applicano in ciascuna modalità di visualizzazione.

Scriva file subagent

I file subagent utilizzano frontmatter YAML per la configurazione, seguito dal prompt di sistema in Markdown:

[!NOTE]

Claude Code osserva ~/.claude/agents/ e .claude/agents/. Quando aggiunge o modifica un file subagent su disco, o chiede a Claude di scriverne uno per lei, Claude Code rileva il cambiamento entro pochi secondi e la prossima delega utilizza la definizione aggiornata, senza necessità di riavvio.

Tre casi richiedono ancora un riavvio:

• L'osservatore copre solo le directory che esistevano quando la sessione è iniziata, quindi dopo aver creato il primo file agente di un ambito in una nuova directory agents, riavvii per caricarlo.
• Claude Code non osserva .claude/agents/ all'interno di directory aggiunte con --add-dir o /add-dir, quindi dopo aver aggiunto o modificato un subagent lì, riavvii per caricare il cambiamento.
• Le sessioni avviate con --disable-slash-commands non osservano affatto queste directory.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Il frontmatter definisce i metadati e la configurazione del subagent. Il corpo diventa il prompt di sistema che guida il comportamento del subagent. I subagent ricevono solo questo prompt di sistema più dettagli di base sull'ambiente come la directory di lavoro, non il prompt di sistema di Claude Code.

In modalità non interattiva, passa --append-subagent-system-prompt per aggiungere il suo testo alla fine del prompt di sistema di ogni subagent, inclusi i subagent annidati, a parte un subagent con fork, che riutilizza il prompt della conversazione. Richiede Claude Code v2.1.205 o successivo. Se il suo testo è troppo lungo per passare sulla riga di comando, lo salvi in un file e passi il percorso con --append-subagent-system-prompt-file invece. Il flag del file richiede Claude Code v2.1.261 o successivo.

Un subagent inizia nella directory di lavoro corrente della conversazione principale. All'interno di un subagent, i comandi cd non persistono tra le chiamate dello strumento Bash o PowerShell e non influenzano la directory di lavoro della conversazione principale. Per dare al subagent una copia isolata del repository, imposti isolation: worktree.

Un subagent con isolation: worktree esegue i suoi comandi Bash e PowerShell all'interno del proprio worktree. Un comando la cui directory di lavoro si risolve invece nel tuo checkout principale, ad esempio perché la directory del worktree è stata rimossa mentre il subagent era in esecuzione, fallisce con un errore.

Questo controllo della directory di lavoro copre l'intero repository che contiene la directory da cui hai avviato Claude Code. Quando la tua sessione viene eseguita in un proprio worktree collegato, il controllo copre anche il checkout principale a cui quel worktree è collegato.

Per i comandi Bash, Claude Code controlla anche il comando stesso in due modi:

• Blocca un comando che reindirizza git nel checkout principale.
• Rifiuta un comando quando non può verificare dal testo del comando che qualsiasi git che il comando esegue rimane all'interno del worktree, ad esempio quando il nome del comando viene calcolato al runtime.

I vettori di reindirizzamento e le regole di forma sono elencati in Come Claude Code applica l'isolamento. I comandi PowerShell ottengono solo il controllo della directory di lavoro.

I comandi Monitor passano attraverso gli stessi controlli della directory di lavoro e del contenuto del comando dei comandi Bash.

Quando la conversazione principale stessa viene eseguita isolata in un worktree, Claude Code applica gli stessi controlli alla sessione e a ogni subagent che genera, inclusi i subagent senza isolation: worktree; consulti Come Claude Code applica l'isolamento.

Riferimento frontmatter

Configuri un subagent con YAML frontmatter tra marcatori --- all'inizio del suo file, e scriva il suo prompt di sistema come Markdown dopo la chiusura ---. Solo name e description sono obbligatori.

I nomi di campo composti da più parole utilizzano il camelCase, come maxTurns e disallowedTools, e devono corrispondere esattamente alla tabella: Claude Code ignora un campo che non riconosce senza segnalare un errore.

• Per trovare un campo scritto in modo errato in un subagent che è stato caricato, esegui claude --debug nella tua shell e cerca does not recognize or apply nel log di debug in ~/.claude/debug/<session-id>.txt. Il log di debug indica fino a cinque campi di primo livello nel file del subagent che Claude Code non riconosce, con il nome probabilmente previsto quando un campo supportato è simile. Richiede Claude Code v2.1.296 o successivo.
• Per scoprire perché un file di subagent non è stato caricato, consulta File di subagent che Claude Code salta.

Scriva cacheTtl all'interno della mappa experimental, non al livello superiore del frontmatter.

---
name: repo-auditor
description: Audits a large repository and reports what it finds
experimental:
  cacheTtl: 1h
---

File subagent che Claude Code salta

Claude Code salta un file in una directory agents di progetto, utente o gestita, o in una sotto una directory che aggiunge con --add-dir, senza segnalarlo nella sessione, quando il frontmatter ha uno di questi problemi:

• No name: Claude Code tratta il file come documentazione mantenuta accanto ai suoi agenti.
• Un --- di apertura che non è la prima riga del file: Claude Code legge il file come non avente frontmatter e lo tratta come documentazione.
• Un name che inizia con -, contiene : o supera i 256 caratteri: Claude Code salta il file e scrive un errore nel log di debug.
• Un name ma nessuna description: Claude Code salta il file e scrive il motivo nel log di debug.
• YAML che non analizza: Claude Code non legge alcun campo dal file, lo salta e scrive l'errore di analisi nel log di debug.

Per vedere il log di debug, esegua Claude Code con --debug.

Un subagent plugin il cui frontmatter non ha name o non analizza comunque si carica, con il suo nome file.

Controlli una directory agents prima di una sessione

Per trovare file in una directory agents il cui frontmatter non analizza, esegua claude plugin validate contro la directory, ad esempio .claude/agents o ~/.claude/agents. Claude Code controlla solo la directory che nomina, e non segnala un file il cui frontmatter analizza ma non ha name. Richiede Claude Code v2.1.233 o successivo.

Scelga un modello

Il campo model controlla quale modello utilizza il subagent:

• Alias modello: usi uno degli alias disponibili: sonnet, opus, haiku, o fable
• ID modello completo: usi un ID modello completo come claude-opus-5-5 o claude-sonnet-5. Accetta gli stessi valori del flag --model
• inherit: usi lo stesso modello della conversazione principale

Quando Claude invoca un subagent, può anche passare un parametro model per quella specifica invocazione. In una chiamata allo strumento Agent, quel parametro accetta un alias del modello: sonnet, opus, haiku o fable. Claude non può passare un ID modello completo né inherit in quella chiamata. Claude Code risolve il modello del subagent in questo ordine:

1. Il parametro model per invocazione
2. Il frontmatter model della definizione del subagent, dove inherit seleziona il modello della conversazione principale
3. La variabile di ambiente CLAUDE_CODE_SUBAGENT_MODEL, quando la imposta su un alias modello o ID modello
4. Il modello della conversazione principale

Se un mod installato imposta un modello nel suo hook agent.spawn, Claude Code utilizza quel modello al posto del parametro della singola invocazione.

In due casi, un alias di famiglia come opus nel parametro per invocazione o nel frontmatter si risolve al modello della conversazione principale invece della versione a cui l'alias punta:

• Il modello della conversazione principale appartiene a quella famiglia: il subagent viene eseguito sul modello esatto della conversazione principale, incluso qualsiasi suffisso [1m], quindi ottiene la stessa finestra di contesto esteso della conversazione principale.
• Claude Code non può dire la famiglia del modello della conversazione principale, su un provider diverso dall'API Anthropic: questo può accadere con un ARN del profilo di inferenza dell'applicazione su Amazon Bedrock che Claude Code non ha risolto a un modello di supporto. Questo caso copre solo l'alias opus, e non si applica quando imposta ANTHROPIC_DEFAULT_OPUS_MODEL, poiché opus allora si risolve al modello che imposta.

Un alias in CLAUDE_CODE_SUBAGENT_MODEL si risolve sempre nella versione a cui punta l'alias, anche quando indica la famiglia della conversazione principale. Impostare la variabile su inherit equivale a lasciarla non impostata.

L'impostazione di CLAUDE_CODE_SUBAGENT_MODEL da sola non cambia il modello su cui vengono eseguiti i subagent Explore e Plan integrati. Per cambiarlo, consulti Esegui ogni subagent su un modello.

Prima di v2.1.251, CLAUDE_CODE_SUBAGENT_MODEL veniva per primo in questo ordine e sostituiva sia il parametro per invocazione che il frontmatter, incluso model: inherit.

Claude Code controlla il parametro per invocazione, il frontmatter e i valori della variabile di ambiente rispetto alla lista di consentimento availableModels della sua organizzazione. Per un valore bloccato, sostituisce un altro modello:

• Quando il valore bloccato è un alias di famiglia come opus, Claude Code esegue il subagent sulla versione più recente di quella famiglia che la lista di consentimento consente, seguendo le stesse regole di sostituzione e ambito del provider di /model. Prima di v2.1.222, Claude Code eseguiva il subagent sul modello ereditato anche per un alias di famiglia bloccato.
• Per qualsiasi altro valore bloccato, su provider dove quella sostituzione non opera, o quando la lista di consentimento non consente alcuna versione della famiglia, Claude Code esegue il subagent sul modello ereditato. Se imposta CLAUDE_CODE_SUBAGENT_MODEL, Claude Code prova prima quel modello, secondo le stesse regole.

Nelle sessioni interattive, Claude Code mostra un avviso che nomina il modello richiesto e il modello su cui viene eseguito il subagent, per entrambe le sostituzioni.

Per verificare su quale modello è in esecuzione un subagent, esegui /tasks. Claude Code indica il modello nella riga del subagent e aggiunge l'eventuale livello di sforzo impostato per quel subagent. Richiede Claude Code v2.1.242 o successivo.

Un parametro model della singola invocazione si applica anche quando il subagent viene ripreso o riceve un messaggio di follow-up, quindi il subagent rimane su quel modello.

A partire da v2.1.198, i subagent ereditano anche la configurazione extended thinking della conversazione principale: se il thinking è attivo nella sua sessione, è attivo per il subagent, e se è spento, rimane spento. Non c'è un'impostazione di thinking per subagent. Prima di v2.1.198, i subagent venivano eseguiti con extended thinking disabilitato indipendentemente dall'impostazione della conversazione principale.

Esegui ogni subagent su un modello

CLAUDE_CODE_SUBAGENT_MODEL è un predefinito, quindi la definizione di un subagent o un modello che Claude passa ha comunque la precedenza su di esso. Per applicare un modello a ogni subagent, compagno di squadra, e agente workflow, imposti anche CLAUDE_CODE_SUBAGENT_MODEL_FORCE su 1. Richiede Claude Code v2.1.257 o successivo.

• Se imposta entrambe le variabili, i subagent vengono eseguiti sul modello in CLAUDE_CODE_SUBAGENT_MODEL.
• Se imposti solo CLAUDE_CODE_SUBAGENT_MODEL_FORCE, i subagent vengono eseguiti sul modello della conversazione principale, tranne il subagent integrato Explore, che viene eseguito sul modello indicato per esso in Subagent integrati.

Ad esempio, per eseguire ogni subagent su Haiku, imposti entrambe le variabili nel blocco env di un file di impostazioni:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Per controllare che l'impostazione abbia avuto effetto, esegua /tasks mentre un subagent è in esecuzione. La riga del subagent mostra il modello su cui viene eseguito.

Mentre CLAUDE_CODE_SUBAGENT_MODEL_FORCE è attiva, Claude Code ignora il campo model nelle definizioni dei subagent, e Claude non può passare un modello quando avvia un subagent. Questi subagent vengono comunque eseguiti sul modello della conversazione principale:

• Un fork
• Una skill che viene eseguita in un subagent con model: inherit

Scegliere un livello di sforzo

Per eseguire un subagent con un proprio livello di sforzo, imposta il campo effort nella sua definizione.

Quando chiedi a Claude di eseguire un subagent non fork a uno specifico livello di sforzo, Claude può anche passare un parametro effort per quella invocazione. Il parametro sovrascrive il campo effort e resta in vigore quando il subagent viene ripreso. La variabile d'ambiente CLAUDE_CODE_EFFORT_LEVEL ha la precedenza su entrambi. Il parametro della singola invocazione richiede Claude Code v2.1.292 o successivo.

Quando un subagent non ha un campo o un parametro effort

Sul modello della conversazione principale, il subagent viene eseguito al livello che scegli nella sessione, ad esempio con /effort, o che imposti con --effort. Su un altro modello, quel livello non si applica. Per sceglierne il livello, imposta il campo effort.

Controlli le capacità del subagent

Può controllare cosa possono fare i subagent attraverso l'accesso agli strumenti, le modalità di autorizzazione e le regole condizionali.

Strumenti disponibili

I subagent ereditano gli strumenti integrati e gli strumenti MCP disponibili nella conversazione principale, ristretti da due filtri: il primo rimuove un breve elenco di strumenti da ogni subagent, e il secondo riduce il set di strumenti integrati per i subagent che vengono eseguiti in background, che è il predefinito. Su macOS, Linux e WSL, un subagent può anche ricevere gli strumenti Glob e Grep quando la conversazione principale non li ha, come descritto in Comportamento dello strumento Glob. Forks saltano entrambi i filtri e ricevono il pool di strumenti esatto della conversazione principale. Il primo filtro rimuove questi strumenti, anche quando elencati nel campo tools:

• Agent, quando il subagent è al limite di profondità; in un fork lo strumento rimane elencato ma restituisce un errore invece di generare
• AskUserQuestion
• EndConversation, che può terminare solo la conversazione principale; consulti Comportamento dello strumento EndConversation
• EnterPlanMode
• ExitPlanMode, a meno che la permissionMode del subagent non sia plan
• ScheduleWakeup
• WaitForMcpServers
• Workflow

Il secondo filtro si applica ai subagent in esecuzione in background. A parte Agent e ExitPlanMode, che seguono le condizioni del primo filtro ovunque il subagent venga eseguito, un subagent in background mantiene ogni strumento MCP ma solo questi strumenti integrati: Read, Grep, Glob, LSP, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage, e Artifact, più SubagentHandback per un subagent che segnala attraverso di esso. Claude Code rimuove ogni altro strumento integrato da un subagent in background, sia ereditato che elencato nel campo tools, quindi la stessa definizione può risolvere in strumenti diversi in foreground e background. La rimozione non segnala alcun errore a meno che non lasci l'elenco tools risolvere a nulla.

Prima di v2.1.280, i subagent in background non potevano utilizzare LSP.

ListAgents segue questi filtri come qualsiasi strumento integrato: un subagent in foreground lo eredita nelle sessioni dove la messaggistica tra sessioni è abilitata, e un subagent in background non lo mantiene.

I compagni di squadra nei team di agenti mantengono inoltre gli strumenti delle attività e gli strumenti cron: TaskCreate, TaskGet, TaskList, TaskUpdate, CronCreate, CronDelete e CronList. In una sessione senza gli strumenti Task, Claude Code non fornisce gli strumenti delle attività nemmeno ai subagent, anche quando il subagent esegue un modello diverso. Un compagno di squadra in-process segue la tua sessione allo stesso modo. Per scoprire se un compagno di squadra in un riquadro diviso ha gli strumenti delle attività, consulta Disponibilità dello strumento Task.

Limita gli strumenti che un subagent può usare

Per limitare gli strumenti, usa il campo tools come allowlist o il campo disallowedTools come denylist. Se sono impostati entrambi, viene applicato prima disallowedTools, poi tools viene risolto rispetto agli strumenti rimanenti. Uno strumento elencato in entrambi viene rimosso.

Questo esempio usa tools per consentire solo Read, Grep, Glob e Bash. Il subagent non può modificare file, scrivere file né utilizzare strumenti MCP:

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

Questo esempio usa disallowedTools per ereditare il pool di strumenti del subagent tranne Write e Edit. Il subagent mantiene Bash, strumenti MCP e il resto del suo pool:

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

Quando nulla nell'elenco tools si risolve in uno strumento, ad esempio perché ogni voce è scritta in modo errato o indica uno strumento non disponibile per i subagent, Claude Code di solito si rifiuta di avviare il subagent e lo strumento Agent restituisce un errore che indica le voci non risolte; consulta Agent would be spawned with zero tools per il messaggio e per come correggere ogni voce.

I campi tools e disallowedTools accettano anche voci per un intero server MCP:

Questo esempio rimuove ogni strumento del server MCP github, mantenendo tra gli strumenti del subagent quelli degli altri server e gli strumenti integrati:

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

Una voce disallowedTools con uno specificatore, come Bash(git push *), comunque rimuove lo strumento intero dal subagent, non solo i comandi corrispondenti. Per mantenere Bash e bloccare comandi specifici, aggiunga una regola di negazione Bash come Bash(git push *) a permissions.deny nelle sue impostazioni. La regola si applica alla conversazione principale e ai subagent.

Nomi di server MCP che contengono un doppio underscore

Se un subagent non riceve nessuno degli strumenti di un server MCP il cui nome contiene __, come reports__v2, controlla le voci mcp__ del subagent:

• In tools: scrivi mcp__ seguito dal nome completo del server e da __*, come in mcp__reports__v2__*. Senza il __* finale, mcp__reports__v2 non corrisponde a nessuno degli strumenti di quel server.
• In disallowedTools: cerca mcp__reports o mcp__reports__*, le voci che negano un server chiamato reports. Con una qualsiasi di queste voci, il subagent perde anche tutti gli strumenti di reports__v2, perché anche i nomi di quegli strumenti iniziano con mcp__reports__. Per negare solo gli strumenti del server reports, elencali invece uno per uno, ad esempio mcp__reports__run_query.

Limiti quali subagent possono essere generati

Quando un agente viene eseguito come thread principale con claude --agent, può generare subagent utilizzando lo strumento Agent. Per limitare quali tipi di subagent può generare, usi la sintassi Agent(agent_type) nel campo tools.

[!NOTE]

Nella versione 2.1.63, lo strumento Task è stato rinominato in Agent. I riferimenti Task(...) esistenti nelle impostazioni e nelle definizioni degli agenti continuano a funzionare come alias.

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

Questo è un allowlist: solo i subagent worker e researcher possono essere generati. Se l'agente tenta di generare qualsiasi altro tipo, la richiesta fallisce e l'agente vede solo i tipi consentiti nel suo prompt. Per bloccare agenti specifici mentre consente tutti gli altri, usi permissions.deny invece.

Per consentire la generazione di qualsiasi subagent senza restrizioni, usi Agent senza parentesi:

tools: Agent, Read, Bash

Se Agent è completamente omesso dall'elenco tools, l'agente non può generare alcun subagent con lo strumento Agent.

La sintassi allowlist Agent(agent_type) si applica solo a un agente eseguito come thread principale con claude --agent. In una definizione di subagent, elencare Agent in tools consente a quel subagent di generare subagent di sua proprietà mentre il limite di profondità lo consente, ma qualsiasi elenco di tipi all'interno delle parentesi viene ignorato.

Limiti i server MCP a un subagent

Usi il campo mcpServers per dare a un subagent accesso ai server MCP che non sono disponibili nella conversazione principale. I server inline definiti qui vengono connessi quando il subagent inizia, soggetti alla regola di fiducia per la cartella del file dell'agente, e disconnessi quando finisce. I riferimenti stringa condividono la connessione della sessione principale.

[!NOTE]

Il campo mcpServers si applica in entrambi i contesti in cui un file agente può essere eseguito:

• Come subagent, generato tramite lo strumento Agent o un @-mention
• Come sessione principale, avviato con --agent o l'impostazione agent

Quando l'agente è la sessione principale, le definizioni di server inline si connettono all'avvio insieme ai server da .mcp.json e ai file di impostazioni, secondo la stessa regola di fiducia per la cartella del file dell'agente. In /mcp, un server remoto (HTTP o SSE) che ha utilizzato prima può mostrare lo stato cached invece; Claude Code lo connette quando Claude chiama per la prima volta uno dei suoi strumenti.

Ogni voce nell'elenco è una definizione di server inline o una stringa che fa riferimento a un server MCP già configurato nella sua sessione:

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

Le definizioni inline utilizzano lo stesso schema delle voci del server .mcp.json, con chiave il nome del server, e supportano i tipi stdio, http, sse e ws.

Per mantenere un server MCP fuori dalla conversazione principale e evitare che le descrizioni dei suoi strumenti consumino contesto lì, lo definisca inline qui piuttosto che in .mcp.json. Il subagent ottiene gli strumenti; la conversazione principale no.

Le restrizioni MCP che si applicano alla sessione principale coprono anche i server dichiarati nel frontmatter del subagent:

• --strict-mcp-config e --bare
• Configurazione MCP gestita aziendale
• Policy allowedMcpServers e deniedMcpServers

Quando una di queste blocca un server, Claude Code lo salta e mostra un avviso che indica i server bloccati.

Le restrizioni delle impostazioni gestite si applicano a ogni subagent indipendentemente da come è definito. --strict-mcp-config non filtra i server che passi inline tramite --agents o l'opzione agents dell'SDK, poiché si tratta di input esplicito del chiamante.

Fiducia richiesta per i server MCP inline

Claude Code carica un server MCP inline da un file di agente nella directory .claude/agents/ del tuo progetto, o nella .claude/agents/ di una directory --add-dir, solo dopo che hai concesso la fiducia alla cartella da cui proviene il file dell'agente. Prima della v2.1.238, Claude Code caricava questi server senza verificare la fiducia.

• Fiducia che non conta: la fiducia di una cartella principale, e la fiducia automatica che una sessione -p o SDK ottiene per hook nei file di impostazioni
• Fino ad allora: Claude Code salta ogni server inline in quel file agente e scrive la chiave esatta projects["<path>"].hasTrustDialogAccepted per ~/.claude.json nel log di debug
• Directory --add-dir: una directory al di fuori del repository dell'area di lavoro fidata ha bisogno della sua voce di fiducia, poiché i suoi file .claude/agents/ non ereditano la fiducia dell'area di lavoro

Claude Code carica due tipi di server senza controllare la fiducia per la cartella da cui il file agente proviene:

• Un nome che fa riferimento a un server che ha già configurato
• Un server inline in un file agente da ~/.claude/agents/, in uno che passa con --agents o l'opzione SDK agents, o in uno che le impostazioni gestite forniscono

Modalità di autorizzazione

Imposti permissionMode per scegliere la modalità di autorizzazione in cui viene eseguito un subagent. Usi i valori di configurazione delle modalità, quindi la modalità Manual è default. Se la lascia non impostata, il subagent eredita la modalità di autorizzazione della conversazione principale.

La modalità di autorizzazione della conversazione principale decide se Claude Code utilizza il valore che imposta:

• Quando la conversazione principale è in bypassPermissions, acceptEdits, o auto mode, il subagent viene eseguito in quella stessa modalità e Claude Code ignora il permissionMode che imposta. Sotto auto mode, il classificatore valuta le chiamate di strumenti del subagent con le regole di blocco e consentimento della conversazione principale. Quando il subagent finisce, il classificatore esamina anche il suo lavoro e il suo rapporto finale prima che il rapporto venga consegnato, come Come auto mode gestisce i subagent descrive.

  Se un subagent chiede un permesso mentre la conversazione principale è in bypassPermissions, verifica se la sua chiamata allo strumento rientra tra le azioni che nessuna modalità approva automaticamente.

• Quando la conversazione principale è in modalità plan, il subagent rimane in plan mode qualunque permissionMode tu imposti, a meno che non venga eseguito come compagno di squadra di un team di agenti secondo le regole dei team di agenti. Se imposti dontAsk, il subagent inoltre non ti chiede nulla: un'azione per cui il plan mode ti chiederebbe l'approvazione viene invece negata.

• Quando la conversazione principale è in modalità default o dontAsk, il subagent viene eseguito nella modalità di permesso che imposti. Mantiene invece la modalità di permesso della conversazione principale in questi casi:

  • Imposti bypassPermissions. L'eccezione per bypassPermissions richiede Claude Code v2.1.267 o successivo.
  • Imposti auto e la modalità auto non è disponibile per il subagent, ad esempio quando un file di impostazioni imposta disableAutoMode o il modello del subagent non supporta la modalità auto.

permissionMode accetta questi valori, e manual come alias per default:

Precarichi skills nei subagent

Usi il campo skills per iniettare il contenuto della skill nel contesto del subagent all'avvio. Questo dà al subagent conoscenza del dominio senza richiedere che scopra e carichi le skills durante l'esecuzione.

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

Il contenuto completo di ogni skill elencata viene iniettato nel contesto del subagent all'avvio, fino ai primi 32 nomi distinti dell'elenco. Questo campo controlla quali skill vengono precaricate, non a quali skill il subagent può accedere: senza di esso, il subagent può comunque individuare e invocare skill di progetto, utente e plugin tramite lo strumento Skill durante l'esecuzione. Per impedire del tutto a un subagent di invocare skill, ometti Skill dall'elenco tools o aggiungilo a disallowedTools.

Non puoi precaricare skill che impostano disable-model-invocation: true, poiché il precaricamento attinge dallo stesso insieme di skill che Claude può invocare. Questo include la skill inclusa /verify, che Claude non può eseguire di propria iniziativa.

Se una skill elencata è mancante o disabilitata, ad esempio dalla politica della sua organizzazione, Claude Code la salta e registra un avviso nel log di debug.

[!NOTE]

Questo è l'inverso di eseguire una skill in un subagent. Con skills in un subagent, il subagent controlla il prompt di sistema e carica il contenuto della skill. Con context: fork in una skill, il contenuto della skill viene iniettato nell'agente che specifica. In entrambi i casi il subagent inizia senza la sua cronologia di conversazione.

Abiliti memoria persistente

Il campo memory dà al subagent una directory persistente che sopravvive tra le conversazioni. Il subagent utilizza questa directory per costruire conoscenza nel tempo, come modelli di base di codice, intuizioni di debug e decisioni architettoniche.

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

Scelga un ambito in base a quanto ampiamente la memoria dovrebbe applicarsi:

La memoria del subagent fa parte della memoria automatica: se disattiva la memoria automatica, con l'impostazione autoMemoryEnabled o CLAUDE_CODE_DISABLE_AUTO_MEMORY, il campo memory non ha effetto e il subagent si avvia senza le istruzioni di memoria o l'accesso allo strumento di memoria descritto di seguito.

Quando la memoria è abilitata:

• Il prompt di sistema del subagent include istruzioni per leggere e scrivere nella directory di memoria.
• Il prompt di sistema del subagent include anche le prime 200 righe o 25KB di MEMORY.md nella directory di memoria, a seconda di quale sia minore, con istruzioni per curare MEMORY.md se supera quel limite.
• Gli strumenti Read, Write e Edit vengono automaticamente abilitati in modo che il subagent possa gestire i suoi file di memoria.

Suggerimenti per la memoria persistente

• project è l'ambito predefinito consigliato. Lo rende condivisibile tramite controllo della versione.

• Chieda al subagent di consultare la sua memoria prima di iniziare il lavoro: "Review this PR, and check your memory for patterns you've seen before."

• Chieda al subagent di aggiornare la sua memoria dopo aver completato un'attività: "Now that you're done, save what you learned to your memory." Nel tempo, questo costruisce una base di conoscenza che rende il subagent più efficace.

• Includa istruzioni di memoria direttamente nel file markdown del subagent in modo che mantenga proattivamente la sua stessa base di conoscenza:

  Update your agent memory as you discover codepaths, patterns, library
  locations, and key architectural decisions. This builds up institutional
  knowledge across conversations. Write concise notes about what you found
  and where.
  

Regole condizionali con hooks

Per un controllo più dinamico sull'utilizzo degli strumenti, usi gli hook PreToolUse per convalidare le operazioni prima che vengono eseguite. Questo è utile quando ha bisogno di consentire alcune operazioni di uno strumento mentre ne blocca altre.

Questo esempio crea un subagent che consente solo query di database di sola lettura. L'hook PreToolUse esegue lo script specificato in command prima di ogni comando Bash:

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

Claude Code passa l'input dell'hook come JSON tramite stdin ai comandi dell'hook. Lo script di convalida legge questo JSON, estrae il comando Bash e esce con codice 2 per bloccare le operazioni di scrittura:

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

Su macOS e Linux, renda lo script eseguibile, o l'hook fallisce invece di bloccare qualsiasi cosa:

chmod +x ./scripts/validate-readonly-query.sh

Per testare la regola, chieda al subagent di eseguire un'istruzione UPDATE: lo script esce con codice 2, Claude Code blocca il comando, e il subagent vede il messaggio Blocked: Only SELECT queries are allowed.

Consulti Hook input per lo schema di input completo e exit codes per come i codici di uscita influenzano il comportamento. Su Windows, scriva gli script dell'hook in PowerShell e aggiunga shell: powershell alla voce dell'hook come mostrato in running hooks in PowerShell.

Disabiliti subagent specifici

Può impedire a Claude di utilizzare subagent specifici aggiungendoli all'array deny nelle sue impostazioni. Usi il formato Agent(subagent-name) dove subagent-name corrisponde al campo name del subagent.

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

Questo funziona sia per i subagent integrati che personalizzati. Può anche usare il flag CLI --disallowedTools:

claude --disallowedTools "Agent(Explore)"

Consulti la documentazione Permissions per più dettagli sulle regole di autorizzazione.

Definisca hook per i subagent

I subagent possono definire hook che vengono eseguiti durante il ciclo di vita del subagent. Ci sono due modi per configurare gli hook:

• Nel frontmatter del subagent: definisca hook che vengono eseguiti solo mentre quel subagent è attivo
• In settings.json: definisca hook a livello di sessione che si attivano anche all'interno dei subagent. Gli eventi degli strumenti come PreToolUse e PostToolUse si attivano per le chiamate di strumenti del subagent allo stesso modo che nella conversazione principale, e SubagentStart e SubagentStop si attivano quando un subagent inizia o finisce

Gli hook da file di impostazioni, impostazioni di politica gestita e plugin si applicano tutti all'interno dei subagent, quindi un hook PreToolUse in settings.json si attiva anche prima di ogni strumento che un subagent utilizza.

Hook nel frontmatter del subagent

Definisca gli hook direttamente nel file markdown del subagent. Questi hook vengono eseguiti solo mentre quel subagent specifico è attivo e vengono puliti quando finisce.

[!NOTE]

Gli hook nel frontmatter si attivano quando l'agente viene generato come subagent tramite lo strumento Agent o un @-mention, e quando l'agente viene eseguito come principale della sessione tramite --agent o l'impostazione agent. Nel caso della sessione principale, vengono eseguiti insieme a qualsiasi hook definito in settings.json.

Per consentire l'esecuzione degli hook nel frontmatter di un subagent a livello di progetto, accetta la finestra di dialogo di fiducia del workspace per la cartella che contiene il file dell'agente. Gli hook dei subagent a livello utente in ~/.claude/agents/ e delle definizioni che passi con --agents vengono eseguiti senza questo passaggio. Se hai aggiunto una cartella con --add-dir da fuori del repository del tuo workspace attendibile, concedi la fiducia a quella cartella separatamente: i suoi hook in .claude/agents/ non ereditano la concessione del workspace.

Finché non concedi la fiducia alla cartella, il subagent viene comunque eseguito, ma Claude Code salta i suoi hook del frontmatter e registra nel log di debug un errore che spiega come concedere la fiducia alla cartella. È una regola più restrittiva di quella per gli hook nei file di impostazioni: la fiducia in una cartella superiore non è sufficiente, e una sessione -p non conta come attendibile. Cosa viene eseguito prima di concedere la fiducia a una cartella confronta le due regole.

Tutti gli hook events sono supportati. Gli eventi più comuni per i subagent sono:

Questo esempio convalida i comandi Bash con l'hook PreToolUse ed esegue un linter dopo le modifiche ai file con PostToolUse:

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

Quando l'agente viene invocato come subagent, gli hook Stop nel frontmatter vengono automaticamente convertiti in eventi SubagentStop.

Hook a livello di progetto per gli eventi dei subagent

Configuri gli hook in settings.json che rispondono agli eventi del ciclo di vita dei subagent nella sessione principale.

Entrambi gli eventi supportano matcher per indirizzare tipi di agenti specifici per nome. Il valore del matcher è il name del frontmatter dell'agente per i subagent a livello di progetto e utente, o l'identificatore con ambito del plugin come my-plugin:db-agent per subagent plugin. Un nome con ambito contiene un due punti, quindi viene valutato come un'espressione regolare non ancorata; ancoratelo con ^ e $, come in ^my-plugin:db-agent$, per corrispondere solo a quell'agente.

Questo esempio esegue uno script di configurazione solo quando il subagent db-agent inizia e uno script di pulizia quando qualsiasi subagent si ferma:

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

Consulti Hooks per il formato di configurazione dell'hook completo.

Lavorare con i subagent

Comprendere la delega automatica

Claude delega automaticamente le attività in base alla descrizione dell'attività nella tua richiesta, al campo description nelle configurazioni dei subagent e al contesto attuale. Per incoraggiare la delega proattiva, includi frasi come "use proactively" nel campo description del tuo subagent.

Mantieni le descrizioni brevi: Claude Code mostra un avviso all'avvio quando le descrizioni combinate dei tuoi subagent superano il limite di 15.000 token, e continua comunque a caricare ogni subagent.

Se il subagent è incluso in un plugin, puoi misurare con quanta affidabilità Claude gli delega le attività su prompt realistici invece di verificarne uno alla volta: claude plugin eval esegue ogni prompt con e senza il plugin e valuta i risultati.

Invocare i subagent esplicitamente

Quando la delega automatica non basta, puoi richiedere tu stesso un subagent. Tre modalità vanno da un suggerimento occasionale a un'impostazione predefinita per l'intera sessione:

• Linguaggio naturale: nomina il subagent nel tuo prompt; Claude decide se delegare
• @-mention: garantisce che il subagent venga eseguito per un'attività
• Per l'intera sessione: l'intera sessione viene eseguita come quel subagent tramite il flag --agent o l'impostazione agent

Per il linguaggio naturale non c'è una sintassi speciale. Nomina il subagent e Claude in genere delega:

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

Menziona il subagent con @. Digita @ e scegli il subagent dal typeahead, nello stesso modo in cui menzioni i file con @. Questo garantisce che venga eseguito quel subagent specifico invece di lasciare la scelta a Claude:

@"code-reviewer (agent)" look at the auth changes

Il tuo messaggio completo va comunque a Claude, che scrive il prompt dell'attività del subagent in base a ciò che hai chiesto. L'@-mention controlla quale subagent Claude invoca, non quale prompt riceve.

I subagent forniti da un plugin abilitato compaiono nel typeahead con il loro nome con ambito, come my-plugin:code-reviewer o my-plugin:review:security quando il plugin organizza gli agenti in sottocartelle. Anche i subagent in background con nome attualmente in esecuzione nella sessione compaiono nel typeahead, con il loro stato accanto al nome.

Puoi anche digitare la menzione manualmente senza usare il selettore: @agent-<name> per i subagent locali, oppure @agent- seguito dal nome con ambito per i subagent dei plugin, ad esempio @agent-my-plugin:code-reviewer. Mentre digiti in questa forma, il typeahead mostra corrispondenze di file anziché agenti. La menzione dell'agente viene comunque risolta quando invii.

Esegui l'intera sessione come un subagent. Passa --agent <name> per avviare una sessione in cui il thread principale stesso assume le restrizioni sugli strumenti e il modello di quel subagent:

claude --agent code-reviewer

A meno che il prompt dell'agente non sia vuoto, il prompt di sistema di un subagent personalizzato sostituisce completamente il prompt di sistema predefinito di Claude Code, nello stesso modo di --system-prompt. I file CLAUDE.md e la memoria del progetto continuano a essere caricati attraverso il normale flusso di messaggi, anche quando la definizione dell'agente imposta omitClaudeMd. Se esegui la sessione con -p come un agente personalizzato che ha un proprio prompt, la sessione si avvia anche senza lo snapshot dello stato Git.

Il nome dell'agente compare come @<name> nell'intestazione di avvio, così puoi verificare che sia attivo.

Questo funziona con i subagent integrati e personalizzati, e la scelta persiste quando riprendi la sessione: Claude Code ripristina le restrizioni sugli strumenti e il modello dell'agente insieme alla conversazione. Se l'agente non esiste più quando riprendi, la sessione continua con gli strumenti predefiniti e mostra un avviso che nomina l'agente. Per il prompt di sistema in entrambi i casi, consulta Flag del prompt di sistema nelle conversazioni riprese.

Per un subagent fornito da un plugin, puoi passare solo il nome dell'agente e Claude Code lo trova:

claude --agent security-reviewer

Se più plugin forniscono agenti con lo stesso nome, passa il nome con ambito per disambiguare:

claude --agent my-plugin:security-reviewer

Se il plugin colloca l'agente in una sottocartella della sua directory agents/, includi la sottocartella nel nome con ambito, ad esempio claude --agent my-plugin:review:security.

Per renderlo il predefinito per ogni sessione in un progetto, imposta agent in .claude/settings.json:

{
  "agent": "code-reviewer"
}

Se sono presenti entrambi, il flag CLI ha la precedenza sull'impostazione.

Eseguire i subagent in primo piano o in background

I subagent possono essere eseguiti in primo piano o in background:

• I subagent in primo piano bloccano la conversazione principale fino al completamento. Le richieste di permesso ti vengono inoltrate man mano che si presentano.
• I subagent in background vengono eseguiti in parallelo mentre continui a lavorare. Quando un subagent in background arriva a una chiamata a uno strumento che richiede un permesso, Claude Code mostra la richiesta nella tua sessione principale e indica il subagent che la sta facendo. Approva per lasciare che il subagent continui, oppure premi Esc per negare quella singola chiamata allo strumento senza fermare il subagent.

Quali subagent vengono eseguiti in background

Senza alcuna configurazione, un subagent che Claude avvia dalla tua conversazione principale parte in background.

• claude -p e l'Agent SDK: Claude può attendere, a sua discrezione o quando glielo chiedi.
• Sessione interattiva nel terminale, sessioni di VS Code e dell'app desktop sulla tua macchina: per permettere a Claude di attendere un subagent, disattiva la modalità fork, che è attiva per impostazione predefinita.

Per una skill con context: fork, Claude Code segue invece le regole descritte in Eseguire le skill in un subagent, indipendentemente dal fatto che la modalità fork sia attiva.

Permettere a Claude di attendere un subagent

1. Disattiva la modalità fork impostando CLAUDE_CODE_FORK_SUBAGENT su 0, ad esempio in settings.json:

   {
     "env": {
       "CLAUDE_CODE_FORK_SUBAGENT": "0"
     }
   }
   

2. Esegui di nuovo claude dalla tua shell, oppure apri una nuova conversazione in VS Code.

3. Chiedi a Claude di attendere quando ti serve prima un risultato, ad esempio "esegui il subagent reviewer e attendi il suo rapporto".

Per continuare a lavorare mentre Claude attende, premi Ctrl+B nel terminale oppure fai clic su Run in background in VS Code.

Se, invece di disattivare la modalità fork, imposti la variabile d'ambiente CLAUDE_CODE_DISABLE_BACKGROUND_TASKS su 1, Claude attende che i subagent terminino prima di continuare. Anche i comandi in background sono disattivati, e Ctrl+B non sposta nulla in background.

Strumenti, permessi e risultati dei subagent in background

I subagent in background vengono eseguiti con un set di strumenti integrati più ridotto rispetto ai subagent in primo piano, ad eccezione dei fork della conversazione e dei subagent in primo piano ripresi.

I subagent in background mostrano ogni richiesta di permesso nella tua sessione principale. Quando rispondi a una di queste richieste con una scelta che vale oltre quella singola chiamata allo strumento, come un permesso concesso per il resto della sessione, Claude Code applica la tua risposta all'intera sessione, inclusa la tua conversazione principale.

Un subagent in background può lasciare un comando Bash o PowerShell in background in esecuzione oltre la fine del suo turno. Quando quel comando termina, Claude Code invia una notifica al subagent.

I risultati di un subagent in background arrivano a Claude come notifica di completamento in un turno successivo. Claude attende quella notifica prima di riportare i risultati del subagent e, se chiedi prima informazioni sull'avanzamento, riferisce che il subagent è ancora in esecuzione.

Subagent terminati nel pannello e nell'elenco delle attività

Claude Code rimuove la riga di un subagent in background dal pannello dei subagent sotto l'input del prompt in uno di due modi, a seconda di come è terminato il subagent:

• Quando un subagent termina con successo, Claude Code rimuove subito la sua riga e, tranne che in modalità screen reader, mostra /tasks to see subagents nel footer per 30 secondi. Durante questi 30 secondi, esegui /tasks e premi Enter sul subagent per aprirne la trascrizione. Prima della v2.1.232, Claude Code manteneva la riga per 30 secondi dopo la fine del subagent, come per uno non riuscito, e non mostrava alcun suggerimento nel footer.
• Quando un subagent fallisce o lo fermi, Claude Code mantiene la sua riga per 30 secondi. Per rimuovere la riga prima, selezionala e premi x.

Un subagent in background completato resta elencato in /tasks, contrassegnato come completato e ordinato sotto il lavoro in esecuzione, per gli stessi 30 secondi del suggerimento nel footer. La sua vista di dettaglio resta aperta quando il subagent termina. I subagent che falliscono o che fermi escono dall'elenco. Prima della v2.1.208, un subagent completato usciva dall'elenco nel momento in cui terminava e la sua vista di dettaglio si chiudeva.

Nomi dei subagent

Se avvii una sessione con i team di agenti abilitati, Claude può dare un nome a un subagent passando un parametro name nella chiamata allo strumento Agent. Può farlo di propria iniziativa, senza chiedertelo prima. Il nome rende il subagent indirizzabile: Claude può inviargli messaggi o riprenderlo per nome dopo che ha terminato.

In una sessione interattiva con i team di agenti abilitati, un subagent che Claude avvia dalla conversazione principale con un name viene invece avviato come membro del team, a meno che la chiamata non sia un fork o non passi isolation nella chiamata stessa. Un valore isolation nel frontmatter del subagent non lo impedisce, e il membro del team viene quindi eseguito nella directory di lavoro della sessione principale. Consulta Come Claude avvia i team di agenti.

Errori API nei subagent

Quando qualcosa interrompe la risposta di un subagent durante lo streaming e la risposta parziale contiene testo ma nessuna chiamata a uno strumento, Claude Code chiede al subagent di continuare invece di terminare l'esecuzione. Questo avviene anche nelle sessioni interattive. L'esecuzione termina con l'errore solo quando queste continuazioni sono esaurite.

Un subagent la cui esecuzione termina con un errore API, come un limite di utilizzo o un errore del server ripetuto, segnala quel fallimento a Claude. Ciò che Claude riceve dipende da dove è stato eseguito il subagent:

• Primo piano: se un rate limit, un sovraccarico o un errore del server interrompe un subagent che ha già prodotto output testuale, lo strumento Agent restituisce quell'output parziale con una nota che indica che il subagent è stato interrotto e non ha completato la sua attività. Un subagent che non ha prodotto nulla, o il cui unico output erano chiamate agli strumenti, fallisce con Agent terminated early due to an API error, seguito dal dettaglio dell'errore.
• Background: il subagent viene contrassegnato come non riuscito, e il messaggio che Claude riceve quando termina indica l'errore API e include l'ultimo output del subagent, così il lavoro parziale non va perso.

Se il rapporto di un subagent inizia con la riga seguente, il subagent ha terminato su un modello di fallback:

⚠ This agent switched to <model> because its earlier model could not be used.

Quando configuri una catena di modelli di fallback e un subagent incontra un errore coperto dalla catena, come la non disponibilità del suo modello, Claude Code passa il subagent al primo modello della catena che accetta la richiesta. Il subagent continua a lavorare invece di terminare con l'errore.

Quando l'errore API sottostante si risolve, chiedi a Claude di riprovare l'attività o di riprendere il subagent.

Scansione dell'output dei subagent

Claude Code analizza il rapporto finale di ogni subagent prima che Claude lo legga. Un subagent potrebbe aver letto file, pagine web o output di comandi che non hai mai esaminato, e il testo proveniente da queste fonti può contenere istruzioni rivolte alla conversazione principale. La scansione non rimuove né riformula mai nulla; apporta due tipi di modifiche che potresti notare in un rapporto:

• Inserimento di backslash: la scansione inserisce un backslash nel testo che imita l'output di Claude Code stesso, come un tag <system-reminder> o una riga che inizia con Human: o Assistant:, in modo che l'imitazione venga letta come testo normale invece di essere scambiata per parte della conversazione.
• Riga marcatore: la scansione antepone una riga che inizia con [harness: subagent output matched instruction-shaped pattern(s): quando il rapporto imita un tag come <system-reminder> o menziona impostazioni dei permessi come bypassPermissions o --dangerously-skip-permissions. Le menzioni di impostazioni dei permessi ricevono la riga marcatore, ma il testo stesso resta com'è scritto.

La scansione non valuta se il contenuto sia dannoso e non cambia ciò che un'istruzione in un rapporto può fare: una chiamata a uno strumento che il rapporto induce Claude a effettuare passa comunque attraverso i controlli dei permessi e il sandboxing della sessione. Non sostituisce la limitazione di ciò a cui un subagent può accedere.

Un rapporto che torna a Claude come risultato del subagent arriva anche sotto un'intestazione che lo contrassegna come output del subagent. L'intestazione dichiara che le istruzioni o le affermazioni di approvazione all'interno del rapporto sono parole del subagent e non hanno alcuna autorità da parte tua.

Il rapporto di un subagent in background arriva all'interno di una notifica di completamento, contrassegnata come evento automatico anziché come un tuo messaggio.

Schemi comuni

Isolare le operazioni ad alto volume

Uno degli usi più efficaci dei subagent è isolare le operazioni che producono grandi quantità di output. L'esecuzione di test, il recupero di documentazione o l'elaborazione di file di log possono consumare molto contesto. Delegandole a un subagent, l'output dettagliato resta nel contesto del subagent e solo il riepilogo pertinente torna alla tua conversazione principale.

Use a subagent to run the test suite and report only the failing tests with their error messages

Eseguire ricerche in parallelo

Per indagini indipendenti, avvia più subagent che lavorino contemporaneamente:

Research the authentication, database, and API modules in parallel using separate subagents

Ogni subagent esplora la propria area in modo indipendente, poi Claude sintetizza i risultati. Funziona meglio quando i percorsi di ricerca non dipendono l'uno dall'altro.

[!WARNING]

Quando i subagent terminano, i loro risultati tornano alla tua conversazione principale. Eseguire molti subagent che restituiscono ciascuno risultati dettagliati può consumare molto contesto, e ogni subagent consuma token propri durante l'esecuzione.

Per il lavoro che deve continuare in parallelo o che non entra in una singola finestra di contesto, eseguilo in sessioni separate e lascia che Claude passi i risultati tra di esse.

Concatenare i subagent

Per workflow in più passaggi, chiedi a Claude di usare i subagent in sequenza. Ogni subagent completa la sua attività e restituisce i risultati a Claude, che poi passa il contesto pertinente al subagent successivo.

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

Scegliere tra subagent e conversazione principale

Usa la conversazione principale quando:

• L'attività richiede scambi frequenti o un perfezionamento iterativo
• Più fasi condividono molto contesto, come pianificazione, implementazione e test
• Stai facendo una modifica rapida e mirata
• La latenza è importante. Un subagent che non è un fork parte da zero e potrebbe aver bisogno di tempo per raccogliere il contesto

Usa i subagent quando:

• L'attività produce output dettagliato che non ti serve nel contesto principale
• Vuoi imporre restrizioni specifiche sugli strumenti o sui permessi
• Il lavoro è autonomo e può restituire un riepilogo

Valuta invece le skill quando vuoi prompt o workflow riutilizzabili che vengano eseguiti nel contesto della conversazione principale anziché nel contesto isolato di un subagent.

Per una domanda su qualcosa che è già nella tua conversazione, usa /btw invece di un subagent. Non ha accesso agli strumenti, e la risposta non viene aggiunta alla cronologia.

Permettere ai subagent di avviare i propri subagent

Per impostazione predefinita, un subagent può avviare subagent propri, fino a tre livelli sotto la conversazione principale. Al limite di profondità, Claude Code toglie lo strumento Agent a ogni subagent tranne che a un fork, quindi un subagent al limite svolge da solo il lavoro delegato e restituisce un unico riepilogo. Un fork al limite mantiene Agent nell'elenco di strumenti ereditato, ma lo strumento restituisce un errore invece di avviare un subagent.

I subagent annidati sono adatti a un'attività delegata che a sua volta si divide in sottoattività parallele, come un subagent revisore che avvia un verificatore per ogni problema trovato. Per impostazione predefinita, il subagent che li avvia attende il resoconto di ciascun subagent annidato:

• Sessione interattiva nel terminale: solo il riepilogo del subagent di primo livello torna a te, perché un subagent che avvia subagent in background attende i loro risultati prima di terminare.
• claude -p e l'Agent SDK: il subagent che li avvia attende finché la modalità fork è attiva. Se disattivi la modalità fork, i subagent annidati partono invece in background. Il subagent che li avvia non attende un subagent annidato in background, che invia il proprio resoconto alla tua conversazione principale se termina dopo il subagent che lo ha avviato.

Per cambiare il limite, imposta CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH sul numero di livelli di subagent che vuoi sotto la tua conversazione principale. Ad esempio, questa voce in settings.json limita l'annidamento a due livelli:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

Con questo valore, i tuoi subagent possono delegare a un secondo livello di subagent propri, e quel secondo livello non può delegare ulteriormente. Imposta 1 per disattivare l'annidamento.

Un subagent annidato si configura nello stesso modo di uno di primo livello e viene risolto dagli stessi ambiti. Per impedire a un singolo subagent di avviarne altri mentre l'annidamento è attivo, come un revisore che deve restare in sola lettura, ometti Agent dal suo elenco tools oppure aggiungilo a disallowedTools.

Nel terminale, Claude Code mostra i subagent annidati come un albero nel pannello dei subagent sotto l'input del prompt e contrassegna ogni riga che ha ancora discendenti nel pannello con il loro conteggio (+N). Apri una riga per vedere i subagent allo stesso livello e i figli diretti di quel subagent, con un percorso che risale fino a main.

Limite di subagent simultanei

Due limiti controllano l'uso dei subagent, ciascuno con la propria variabile: questo impedisce a Claude di avviare altri subagent quando ne sono in esecuzione troppi, mentre il limite di profondità stabilisce fino a che livello i subagent possono annidarsi. Non c'è limite al numero totale di subagent che Claude può avviare nel corso di una sessione.

Per impostazione predefinita, quando in una sessione sono in esecuzione 20 subagent, l'avvio di un altro con lo strumento Agent fallisce con Concurrent subagent limit reached, e l'errore indica a Claude di non riprovare. L'avvio torna a riuscire quando il numero di subagent in esecuzione scende sotto il limite. Per cambiare il limite, imposta CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS su un qualsiasi numero intero positivo. Le sessioni con ultracode attivo sono esenti: lì il limite non viene applicato. Richiede Claude Code v2.1.217 o successivo.

Il limite blocca solo i subagent che Claude avvia con lo strumento Agent, ma altre esecuzioni occupano gli stessi posti:

• Un fork all'interno della sessione che avvii con /subtask occupa un posto mentre è in esecuzione e non viene mai bloccato dal limite.
• Riprendere un subagent che ha già terminato occupa un nuovo posto senza verificare il limite, quindi le riprese possono portare il numero di subagent in esecuzione oltre il limite.

Gli agenti eseguiti da altre funzionalità, come gli agenti dei workflow e i membri dei team di agenti, seguono invece limiti propri.

Gestire il contesto dei subagent

Cosa viene caricato all'avvio

Ogni subagent parte con una finestra di contesto nuova e isolata. Non vede la cronologia della tua conversazione, le skill che hai già invocato né i file che Claude ha già letto. Claude compone un messaggio di delega che riassume l'attività, e il subagent lavora a partire da lì. L'eccezione è un fork, che eredita la conversazione padre invece di partire da zero.

Il contesto iniziale di un subagent non fork contiene:

• Prompt di sistema: il prompt dell'agente stesso più i dettagli sull'ambiente che Claude Code aggiunge, non il prompt di sistema di Claude Code. I subagent personalizzati definiscono il proprio nel corpo markdown o nel campo prompt. Gli agenti integrati hanno prompt predefiniti.
• Messaggio dell'attività: il prompt di delega che Claude scrive quando passa il lavoro.
• File CLAUDE.md: ogni livello della gerarchia CLAUDE.md caricato dalla conversazione principale, inclusi ~/.claude/CLAUDE.md, le regole del progetto, CLAUDE.local.md, i file di policy gestiti ed eventuali file AGENTS.md caricati come istruzioni del progetto. Gli agenti integrati Explore e Plan li saltano. Un subagent la cui definizione imposta omitClaudeMd carica solo i file di policy gestiti, oppure nessuno quando la definizione proviene dalle impostazioni gestite.
• Stato Git: uno snapshot che Claude Code legge dal tuo repository all'avvio del subagent. Per un subagent nel proprio worktree di quel repository, lo snapshot mostra il branch, lo stato e i commit recenti del worktree. Assente al di fuori di un repository Git o quando lo snapshot è disattivato; consulta includeGitInstructions. Explore e Plan lo saltano in ogni caso.
• Skill precaricate: il contenuto completo di ogni skill indicata nel campo skills dell'agente. Gli agenti integrati non precaricano skill.
• Elenco degli agenti fratelli: un promemoria di sistema che elenca main e ogni altro agente con nome nella sessione, ciascuno un valore to valido per SendMessage. L'elenco compare solo quando gli strumenti del subagent includono SendMessage e almeno un altro agente ha un nome, sia che Claude gliel'abbia dato al momento dell'avvio, sia che venga eseguito come membro di un team di agenti. È uno snapshot acquisito all'avvio del subagent, quindi gli agenti che ricevono un nome in seguito non compaiono.

Per avviare uno dei tuoi subagent senza i file CLAUDE.md utente, di progetto e locali, imposta omitClaudeMd: true nel suo frontmatter o nel JSON di --agents. Per Explore, Plan e i subagent con omitClaudeMd, il CLAUDE.md di una sottodirectory e le regole con ambito di percorso corrispondenti vengono comunque caricati quando il subagent lavora con file in quella posizione.

La conversazione principale dispone comunque del tuo CLAUDE.md completo quando legge i risultati di questi subagent, quindi la maggior parte delle regole non ha bisogno di arrivare al subagent stesso. Se una regola deve arrivarci, come "ignora la directory vendor/", ripetila nel prompt che dai a Claude quando delega.

Non puoi cambiare quali subagent ricevono lo stato Git. Solo Explore e Plan lo saltano.

Alcuni elementi dello stato della conversazione principale non arrivano mai a un subagent non fork:

• Stile di output: un subagent esegue il proprio prompt di sistema, quindi il tuo stile di output non influenza le sue risposte, tranne che in un fork.
• Memoria automatica: la memoria automatica della conversazione principale non viene caricata. Per dare a un subagent una memoria persistente propria, usa il campo memory.
• Dimensione della finestra di contesto: la finestra di contesto di un subagent è dimensionata in base al suo modello, non a quello del padre. Delegare a un modello con una finestra più piccola dà a quel subagent la finestra più piccola.

Riprendere i subagent

Ogni invocazione di un subagent crea una nuova istanza invece di continuarne una precedente. Per proseguire il lavoro di un subagent esistente invece di ricominciare, chiedi a Claude di riprenderlo.

I subagent ripresi conservano l'intera cronologia della conversazione, incluse tutte le chiamate agli strumenti, i risultati e il ragionamento precedenti. Se il subagent ha avviato subagent in background propri, quella cronologia include i risultati che hanno consegnato mentre era in esecuzione. Prima della v2.1.304, un subagent a cui Claude inviava un messaggio o che riprendeva subito dopo la sua conclusione poteva dimenticare il suo lavoro più recente.

• Quando un subagent termina, Claude riceve il suo ID agente.
• Gli agenti integrati Explore e Plan sono monouso e non restituiscono alcun ID agente, quindi Claude non può riprenderli. Usa general-purpose o un subagent personalizzato quando devi proseguire il lavoro.
• Quando un subagent si ferma al limite maxTurns, Claude Code contrassegna l'output restituito come parziale e Claude può riprendere il subagent per fargli proseguire il lavoro.

Claude usa lo strumento SendMessage con l'ID o il nome dell'agente come campo to per riprenderlo. SendMessage non richiede che i team di agenti siano abilitati; lo richiedono solo i messaggi strutturati del protocollo dei team come shutdown_request e plan_approval_response. Oltre ai subagent e ai membri del team, nelle sessioni in cui la messaggistica tra sessioni è abilitata, Claude può usare lo stesso strumento per inviare messaggi alle tue altre sessioni di Claude Code, su questa macchina o su altre.

Per riprendere un subagent, chiedi a Claude di continuare il lavoro precedente:

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

Quando Claude invia un messaggio a un subagent completato con lo strumento SendMessage, il subagent riprende in background senza una nuova invocazione di Agent. Lo stesso vale per un subagent che Claude ha fermato con lo strumento TaskStop, una volta che la sua esecuzione interrotta è terminata. L'esecuzione ripresa mantiene il set di strumenti della prima esecuzione del subagent e può continuare a leggere la cache del prompt riscaldata dall'esecuzione originale.

Anche un subagent che dispone dello strumento SendMessage può inviare quel messaggio. In una sessione interattiva, l'agente ripreso riferisce quindi al subagent che lo ha ripreso, non alla tua conversazione principale. Quel subagent attende il risultato prima di concludere il proprio lavoro. Quando un subagent invia un messaggio a un agente a cui riferisce, come chi lo ha avviato, Claude Code riprende quell'agente senza reindirizzarne i risultati.

Un subagent che hai fermato tu stesso, con x in /tasks o con una richiesta SDK stop_task, non riprende automaticamente. Se Claude gli invia un messaggio, il messaggio viene rifiutato e a Claude viene comunicato che l'agente è stato annullato.

Finché la riga di quel subagent è ancora nel pannello dei subagent, scrivi nella sua trascrizione per riprenderlo tu stesso. Dopodiché, un messaggio di Claude può di nuovo riprenderlo automaticamente.

La ripresa avvia una nuova esecuzione dell'agente con lo stesso ID, quindi un subagent che era già fallito o completato risulta di nuovo in esecuzione nell'elenco delle attività e negli eventi delle attività dell'Agent SDK.

SendMessage verifica che un nome si riferisca ancora allo stesso agente raggiunto in precedenza nella conversazione. Se un agente più recente ha preso quel nome, come un agente in background riavviato che lo ha riutilizzato, Claude Code rifiuta l'invio invece di consegnarlo all'agente sbagliato, e l'errore indica quale agente raggiunge ora quel nome, così Claude può cambiare destinatario. Per raggiungere l'agente precedente mentre è ancora in esecuzione, Claude lo indirizza tramite l'ID agente ricevuto quando lo ha avviato. Il controllo è limitato alla conversazione corrente e si azzera con /clear.

Un subagent tratta i messaggi dell'agente che lo ha avviato come normali indicazioni sull'attività, incluse le correzioni di rotta a metà lavoro, e agisce di conseguenza nei limiti delle proprie impostazioni dei permessi. Due limiti valgono indipendentemente da chi ha inviato il messaggio: nessun messaggio di alcun agente vale come tua approvazione per una richiesta di permesso in sospeso, e nessun messaggio di un agente può modificare le impostazioni dei permessi, il CLAUDE.md o la configurazione di un subagent. Solo il sistema dei permessi o i tuoi messaggi possono concedere l'approvazione.

Puoi anche chiedere a Claude l'ID agente se vuoi farvi riferimento esplicitamente, oppure trovare gli ID nei file di trascrizione in ~/.claude/projects/{project}/{sessionId}/subagents/. Ogni trascrizione è salvata come agent-{agentId}.jsonl.

Le trascrizioni dei subagent persistono indipendentemente dalla conversazione principale:

• Compattazione della conversazione principale: quando la conversazione principale viene compattata, le trascrizioni dei subagent non ne risentono. Sono salvate in file separati.
• Persistenza della sessione: le trascrizioni dei subagent persistono all'interno della loro sessione. Puoi riprendere un subagent dopo aver riavviato Claude Code riprendendo la stessa sessione.
• Pulizia automatica: Claude Code elimina le trascrizioni dei subagent dopo il periodo di conservazione cleanupPeriodDays, di 30 giorni per impostazione predefinita, secondo le regole di pulizia della conservazione.

Inviare un messaggio a un subagent per nome dopo un riavvio

[!NOTE]

Per un subagent avviato come membro del team, consulta invece le limitazioni dei team di agenti.

Se Claude non riesce a inviare un messaggio a un subagent per nome dopo che hai riavviato Claude Code e ripreso la sessione, fornisci invece a Claude l'ID agente del subagent. I nomi che Claude ha assegnato dalla conversazione principale dopo la sua ultima compattazione sopravvivono al riavvio. Un nome assegnato prima di quella compattazione no. Per trovare l'ID corrispondente a un nome, cerca quel nome nei file agent-{agentId}.meta.json in ~/.claude/projects/{project}/{sessionId}/subagents/.

Dopo un messaggio inviato tramite ID, il nome del subagent torna a funzionare, a meno che un agente più recente non abbia preso quel nome. Prima della v2.1.299, nessun nome sopravviveva a un riavvio, e un invio per nome veniva rifiutato anche quando l'ID agente funzionava ancora.

Compattazione automatica

I subagent supportano la compattazione automatica. La compattazione si attiva man mano che la finestra di contesto del subagent stesso si riempie, e CLAUDE_AUTOCOMPACT_PCT_OVERRIDE si applica anche ai subagent. Consulta le variabili d'ambiente per sapere quando l'override ha effetto.

Gli eventi di compattazione vengono registrati nei file di trascrizione dei subagent:

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

Il valore preTokens indica quanti token erano utilizzati prima della compattazione.

Impostare la finestra di compattazione automatica per un singolo subagent

Per far sì che un subagent si compatti prima di quanto farebbe altrimenti, imposta autoCompactWindow nel suo frontmatter su un numero di token compreso tra 100000 e 1000000. Se imposti CLAUDE_CODE_AUTO_COMPACT_WINDOW, il subagent usa invece la finestra di quella variabile e il campo non ha effetto, a meno che Claude Code non ignori il valore della variabile. Richiede Claude Code v2.1.296 o successivo.

Questo frontmatter imposta autoCompactWindow su 200.000 token per un subagent che legge file di log lunghi:

---
name: log-reader
description: Reads long log files and reports the errors it finds
autoCompactWindow: 200000
---

Scrivi il valore come un semplice intero, ad esempio 200000, perché nel frontmatter Claude Code legge 200k come 200, che è al di fuori dell'intervallo consentito. Il subagent viene comunque caricato e compattato come se il campo fosse assente. Per verificare se Claude Code ha ignorato il tuo valore, esegui claude --debug nella tua shell e cerca invalid autoCompactWindow nel log di debug.

Se il valore rientra nell'intervallo e continui a non vedere alcun cambiamento, verifica queste cause:

• Il valore non è inferiore alla finestra di compattazione automatica che il subagent erediterebbe altrimenti: per compattare prima, imposta un valore inferiore a quella finestra.
• Esegui l'intera sessione come questo subagent con --agent o con l'impostazione agent: in quel caso il campo non ha effetto. Per impostare la finestra della sessione, consulta Impostare la finestra di compattazione automatica.

Esegui il fork della conversazione corrente

[!NOTE]

Quando la vista agenti è disattivata, /subtask non è disponibile e /fork avvia invece il subagent fork; altrimenti /fork copia l'intera sessione in una nuova sessione in background.

Un fork è un subagent che eredita l'intera conversazione fino a quel momento invece di partire da zero. In questo modo viene meno l'isolamento dell'input che i subagent altrimenti forniscono: un fork vede lo stesso prompt di sistema, gli stessi strumenti, lo stesso modello e la stessa cronologia dei messaggi della sessione principale, quindi puoi affidargli un'attività secondaria senza dover spiegare di nuovo la situazione. Le chiamate agli strumenti del fork restano comunque fuori dalla tua conversazione e torna solo il suo risultato finale, così la tua finestra di contesto principale rimane pulita. Usa un fork quando qualsiasi altro subagent richiederebbe troppo contesto per essere utile, oppure quando vuoi provare diversi approcci in parallelo partendo dallo stesso punto.

Claude può avviare un fork autonomamente mentre la modalità fork è attiva, come lo è per impostazione predefinita. Per interrompere i fork, consulta Disattiva la modalità fork.

Puoi avviare tu stesso un fork con /subtask seguito da un'attività, indipendentemente dal fatto che la modalità fork sia attiva. Claude Code assegna al fork un nome basato sulle prime parole dell'attività. L'esempio seguente esegue il fork della conversazione per scrivere una bozza dei casi di test mentre tu continui con l'implementazione nella sessione principale:

/subtask draft unit tests for the parser changes so far

Il fork appare in un pannello sotto il tuo prompt e viene eseguito in background mentre continui a lavorare. Al termine, il suo risultato arriva come messaggio nella tua conversazione principale. La sezione successiva descrive i controlli del pannello per osservare e guidare i fork durante l'esecuzione.

Osserva e guida i fork in esecuzione

I fork in esecuzione appaiono in un pannello sotto l'input del prompt, con una riga per la sessione principale e una per ciascun fork.

Quando un fork termina correttamente, Claude Code rimuove la sua riga. Claude Code mantiene per 30 secondi la riga di un fork che non è riuscito o che hai interrotto, come per qualsiasi altro subagent in background. Prima della v2.1.232, Claude Code manteneva per 30 secondi anche la riga di un fork terminato.

Usa questi tasti per interagire con il pannello:

Con la trascrizione di un fork o di un subagent aperta, i messaggi di follow-up e le skill vanno a quell'agente. In Claude Code v2.1.314 o successiva, /btw risponde a partire dalla trascrizione aperta. Gli altri comandi integrati vanno alla tua conversazione principale, con queste tutele:

• /compact, /clear e /rewind agiscono sulla conversazione principale, quindi Claude Code ti chiede conferma prima di eseguirne uno da questa vista.
• /model e /fast impostano il modello e la modalità veloce della conversazione principale, non quelli dell'agente visualizzato, quindi non vengono eseguiti da questa vista. Un avviso te ne spiega il motivo.

Per fare in modo che l'agente visualizzato legga il tuo messaggio prima che termini il lavoro che sta aspettando, invialo con Ctrl+Enter o Ctrl+X Ctrl+S. Qualsiasi comando shell o subagent che l'agente sta aspettando e che può essere spostato in background viene spostato lì e continua a essere eseguito. Quando l'agente sta scrivendo una risposta, o sta aspettando un lavoro che non può essere spostato in background, continua e legge il tuo messaggio una volta terminato. Richiede Claude Code v2.1.286 o successiva.

In cosa i fork differiscono dagli altri subagent

Un fork eredita tutto ciò che la sessione principale ha nel momento in cui viene generato. Qualsiasi altro subagent parte da zero dalla sua definizione.

Poiché il prompt di sistema e le definizioni degli strumenti di un fork sono identici a quelli del genitore, la sua prima richiesta riutilizza la cache del prompt del genitore. Grazie a questo riutilizzo, un fork costa meno di un subagent nuovo per le attività che richiedono lo stesso contesto.

Quando Claude genera un fork tramite lo strumento Agent, può passare isolation: "worktree" in modo che le modifiche ai file del fork vengano scritte in un worktree git separato invece che nel tuo checkout. Un fork non può generare altri fork.

Disattiva la modalità fork

La modalità fork consente a Claude di avviare un fork autonomamente. Per impedire a Claude di avviare fork:

• Blocca solo i fork: aggiungi "Agent(fork)" a permissions.deny nelle tue impostazioni.
• Disattiva la modalità fork: imposta CLAUDE_CODE_FORK_SUBAGENT su 0, seguendo i passaggi in Lascia che Claude attenda un subagent.

Mentre la modalità fork è attiva, Claude inoltre non può attendere un subagent nelle sessioni interattive del terminale, di VS Code o desktop sulla tua macchina. La modalità fork è attiva per impostazione predefinita a partire da Claude Code v2.1.302, e in una sessione interattiva del terminale a partire dalla v2.1.232.

Subagent di esempio

Questi esempi dimostrano modelli efficaci per la costruzione di subagent. Li usi come punti di partenza, o generi una versione personalizzata con Claude.

[!TIP]

Best practices:

• Progetti subagent focalizzati: ogni subagent dovrebbe eccellere in un'attività specifica
• Scriva descrizioni che individuino un subagent: Claude utilizza la descrizione per decidere quando delegare. Renda ogni descrizione abbastanza specifica da instradare al subagent giusto, e mantenga l'insieme combinato entro il budget di descrizione di 15.000 token
• Limiti l'accesso agli strumenti: conceda solo le autorizzazioni necessarie per la sicurezza e la focalizzazione
• Archivi nel controllo della versione: condivida i subagent di progetto con il suo team

Code reviewer

Un subagent di sola lettura che esamina il codice senza modificarlo. Questo esempio mostra come progettare un subagent focalizzato con accesso limitato agli strumenti che esclude Edit e Write, e un prompt dettagliato che specifica esattamente cosa cercare e come formattare l'output.

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

Debugger

Un subagent che può sia analizzare che correggere i problemi. A differenza del revisore di codice, questo include Edit perché correggere i bug richiede la modifica del codice. Il prompt fornisce un flusso di lavoro chiaro dalla diagnosi alla verifica.

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

Data scientist

Un subagent specifico del dominio per il lavoro di analisi dei dati. Questo esempio mostra come creare subagent per flussi di lavoro specializzati al di fuori dei tipici compiti di codifica. Imposta esplicitamente model: sonnet per un'analisi più capace.

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

Database query validator

Un subagent che consente l'accesso a Bash ma convalida i comandi per consentire solo query SQL di sola lettura. Questo esempio mostra come usare gli hook PreToolUse per la convalida condizionale quando ha bisogno di un controllo più fine di quello che il campo tools fornisce.

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

Claude Code passa l'input dell'hook come JSON tramite stdin ai comandi dell'hook. Lo script di convalida legge questo JSON, estrae il comando in esecuzione e lo controlla rispetto a un elenco di operazioni di scrittura SQL. Se viene rilevata un'operazione di scrittura, lo script esce con codice 2 per bloccare l'esecuzione e restituisce un messaggio di errore a Claude tramite stderr.

Crei lo script di convalida in qualsiasi punto del suo progetto. Il percorso deve corrispondere al campo command nella sua configurazione dell'hook:

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

Su macOS e Linux, renda lo script eseguibile:

chmod +x ./scripts/validate-readonly-query.sh

Su Windows, scriva lo script di convalida in PowerShell e aggiunga shell: powershell alla voce dell'hook. Consulti esecuzione degli hook in PowerShell.

L'hook riceve JSON tramite stdin con il comando Bash in tool_input.command. Il codice di uscita 2 blocca l'operazione e alimenta il messaggio di errore a Claude. Consulti Hooks per i dettagli sui codici di uscita e Hook input per lo schema di input completo.

Il prompt di sistema dice al subagent di rifiutare le richieste di scrittura, quindi l'hook è una protezione: se il subagent tenta comunque una scrittura, Claude Code blocca il comando e il subagent vede il messaggio Blocked: Write operations not allowed. Use SELECT queries only..

Passaggi successivi

Ora che comprende i subagent, esplori queste funzionalità correlate:

• Distribuisca subagent con i plugin per condividere i subagent tra team o progetti
• Esegua Claude Code a livello di programmazione con l'Agent SDK per CI/CD e automazione
• Usi i server MCP per dare ai subagent accesso a strumenti e dati esterni