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. 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.

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 e 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 saltano i vostri file CLAUDE.md e lo stato git della sessione principale per mantenere la ricerca veloce ed economica. Ogni altro subagent integrato e subagent personalizzato carica entrambi. Per la suddivisione completa di ciò che raggiunge un subagent, consultate cosa si carica all'avvio.

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.

Quickstart: crea il suo primo subagent

I subagent sono file Markdown con frontmatter YAML. Per crearne uno, chieda a Claude di scriverlo per lei, oppure scriva il file manualmente.

A partire dalla v2.1.198, il comando /agents non apre più la procedura guidata di creazione interattiva; eseguirlo stampa un promemoria per chiedere a Claude o modificare direttamente .claude/agents/. I file subagent, i campi frontmatter e le posizioni .claude/agents/ e ~/.claude/agents/ rimangono invariati; solo la procedura guidata del terminale è stata rimossa.

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

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.

---
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.

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

Ora ha un subagent che può utilizzare in qualsiasi progetto sulla sua macchina per analizzare le basi di codice e suggerire miglioramenti.

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

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. A partire da v2.1.178, 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.

Mantenga i valori name univoci in tutto l'albero: se due file all'interno dello stesso .claude/agents/, incluse le sue sottocartelle, dichiarano lo stesso nome, Claude Code carica solo uno di essi, scelto dall'ordine di lettura del filesystem piuttosto che da una precedenza documentata. Tra le directory di progetto annidate, la definizione più vicina alla directory di lavoro vince, come descritto sopra. Il controllo di configurazione /doctor segnala i file nello stesso ambito che condividono un nome e propone di rinominare o rimuovere tutti tranne uno. Prima di v2.1.205, /doctor apriva una schermata di diagnostica che elencava i duplicati e mostrava quale definizione era attiva.

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:

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."
}
}'

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."
}
}
'@

Il flag --agents accetta JSON con un campo prompt più questi campi frontmatter: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, initialPrompt, memory, effort, background, e isolation. Usi prompt per il prompt di sistema, equivalente al corpo markdown nei subagent basati su file. Ogni chiave di primo livello nel JSON è il nome dell'agente. Non inizi un nome con -.

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.

Le definizioni di subagent da uno qualsiasi di questi ambiti sono anche disponibili per agent teams: quando genera un compagno di squadra, può fare riferimento a un tipo di subagent e Claude Code applica parti di quella definizione al compagno di squadra. Consulti agent teams per quali parti si applicano in ogni modalità di visualizzazione.

Scriva file subagent

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

---
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 suo worktree. Un comando la cui directory di lavoro si risolve nel suo checkout principale, ad esempio perché la directory del worktree è stata rimossa mentre il subagent era in esecuzione, fallisce con un errore. Prima di v2.1.203, tale comando potrebbe essere eseguito nel checkout principale.

Questo controllo della directory di lavoro copre l'intero repository contenente la directory da cui ha avviato Claude Code. Quando la sua sessione viene eseguita in un worktree collegato di sua proprietà, il controllo copre anche il checkout principale da cui quel worktree è collegato. Prima di v2.1.210, il controllo copriva solo la directory di avvio stessa. Un comando la cui directory di lavoro si risolveva altrove nello stesso repository, come la radice del repository quando ha avviato Claude Code da una sottodirectory di monorepo, veniva eseguito lì invece di fallire.

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.

Campi frontmatter supportati

I seguenti campi possono essere utilizzati nel frontmatter YAML. Solo name e description sono obbligatori.

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 - o contiene :: Claude Code salta il file e scrive un errore nel log di debug. Consulti la riga name nella tabella sopra.
• 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 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. 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

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.

L'impostazione della variabile su inherit è la stessa che lasciarla non impostata. Prima di v2.1.196, quel valore forzava i subagent sul modello della conversazione principale e ignorava le altre fonti.

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 controllare quale modello sta eseguendo un subagent, esegua /tasks. Claude Code nomina il modello sulla riga del subagent, e aggiunge il livello di sforzo quando la definizione del subagent, o la skill da cui ha fatto il fork, imposta effort. Richiede Claude Code v2.1.242 o successivo.

Un parametro model per invocazione si applica anche quando il subagent viene ripreso o inviato un messaggio di follow-up, quindi il subagent rimane su quel modello. Prima di v2.1.211, la ripresa eliminava il valore per invocazione e il subagent tornava al campo model della sua definizione o, senza uno, al modello della conversazione principale.

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 imposta solo CLAUDE_CODE_SUBAGENT_MODEL_FORCE, i subagent vengono eseguiti sul modello della conversazione principale.

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 è attivo, Claude Code ignora il campo model di ogni definizione di subagent, inclusi i subagent Explore e Plan integrati, e Claude non può passare un modello quando avvia un subagent. Due tipi di subagent vengono comunque eseguiti sul modello della conversazione principale:

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

Quando imposta solo CLAUDE_CODE_SUBAGENT_MODEL_FORCE, il subagent Explore integrato mantiene il suo limite di modello.

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
• TaskOutput
• 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, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage, e Artifact. 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.

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 in agent teams inoltre mantengono gli strumenti di 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 di attività ai subagent nemmeno quando il subagent esegue un modello diverso. Un compagno di squadra in-process segue la sua sessione allo stesso modo, mentre un compagno di squadra nel suo riquadro diviso viene eseguito come un processo Claude Code separato, quindi il suo modello decide.

Per limitare gli strumenti, usi il campo tools come allowlist o il campo disallowedTools come denylist. Questo esempio usa tools per consentire solo Read, Grep, Glob e Bash. Il subagent non può modificare file, scrivere file o utilizzare alcuno strumento 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
---

Se entrambi sono impostati, disallowedTools viene applicato per primo, quindi tools viene risolto rispetto al pool rimanente. Uno strumento elencato in entrambi viene rimosso.

Quando nulla nell'elenco tools si risolve in uno strumento, ad esempio perché ogni voce è errata o nomina uno strumento che non è disponibile per i subagent, Claude Code di solito rifiuta di avviare il subagent e lo strumento Agent restituisce un errore che nomina le voci non risolte; consulti Agent would be spawned with zero tools per il messaggio e come correggere ogni voce. Prima di v2.1.208, quel subagent si avviava senza strumenti e potrebbe restituire un risultato vuoto o confuso.

Entrambi i campi accettano modelli a livello di server MCP oltre ai nomi esatti degli strumenti: mcp__<server> o mcp__<server>__* concede o rimuove ogni strumento dal server denominato. In disallowedTools, mcp__* rimuove anche ogni strumento MCP da qualsiasi server. Questo esempio rimuove ogni strumento dal server MCP github mentre mantiene gli strumenti da altri server e gli strumenti integrati nel suo pool:

---
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.

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.

---
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.

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.

Claude Code carica un server inline da un file agente nella directory .claude/agents/ del suo progetto, o in una directory .claude/agents/ di una directory --add-dir, solo dopo che ha fiducia della cartella da cui il file agente proviene. Prima di v2.1.238, Claude Code caricava questi server senza controllare 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

A partire da v2.1.153, 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
• Politiche allowedMcpServers e deniedMcpServers

Quando uno di questi blocca un server, Claude Code lo salta e mostra un avviso che nomina 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 passa inline tramite --agents o l'opzione SDK agents, poiché si tratta di input esplicito del chiamante.

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à della conversazione principale, che inizia come auto mode su piani Pro, Max e Team a meno che le sue impostazioni o la sua organizzazione non la cambino.

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 la conversazione principale è in modalità default, dontAsk, o plan, il subagent viene eseguito nella modalità di autorizzazione che imposta, tranne bypassPermissions. Un subagent che dichiara bypassPermissions mantiene la modalità della conversazione principale. L'eccezione bypassPermissions richiede Claude Code v2.1.267 o successivo.

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. Questo campo controlla quali skills vengono precaricate, non quali skills il subagent può accedere: senza di esso, il subagent può comunque scoprire e invocare skills di progetto, utente e plugin tramite lo strumento Skill durante l'esecuzione. Per impedire a un subagent di invocare skills interamente, ometta Skill dall'elenco tools o aggiunga a disallowedTools.

Non può precaricare skills che impostano disable-model-invocation: true, poiché il precaricamento attinge dallo stesso insieme di skills che Claude può invocare. Questo include la skill /verify in bundle: solo lei può eseguirla, quindi non può essere precaricata nemmeno.

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.

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.

Per consentire agli hook del frontmatter di un subagent a livello di progetto di essere eseguiti, accetti la finestra di dialogo di fiducia dell'area di lavoro per la cartella che contiene il file dell'agente. Gli hook dai subagent a livello di utente in ~/.claude/agents/ e dalle definizioni che passa con --agents vengono eseguiti senza questo passaggio. Se ha aggiunto una cartella con --add-dir da fuori del repository dell'area di lavoro fidata, ha fiducia di quella cartella separatamente: i suoi hook .claude/agents/ non ereditano la concessione dell'area di lavoro.

Fino a quando non ha fiducia della cartella, il subagent viene comunque eseguito, ma Claude Code salta i suoi hook del frontmatter e registra un errore nel log di debug spiegando come avere fiducia della cartella. Questa è una regola più ristretta di quella per gli hook nei file di impostazioni: avere fiducia di una cartella principale non è sufficiente, e una sessione -p non conta come fidata. Cosa viene eseguito prima di avere fiducia di una cartella confronta i due. Prima di v2.1.218, gli hook del frontmatter potevano essere eseguiti da cartelle che non aveva fiducia, incluso nelle sessioni non interattive.

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 $TOOL_INPUT"
  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" }
        ]
      }
    ]
  }
}

Un matcher con trattini come db-agent corrisponde esattamente su Claude Code v2.1.195 o successivo. Nelle versioni precedenti viene valutato come un'espressione regolare non ancorata e si attiva anche per qualsiasi tipo di agente che lo contiene, come prod-db-agent; ancoratelo come ^db-agent$ su quelle versioni.

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

Lavori con i subagent

Comprenda la delegazione automatica

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

Mantenga le descrizioni brevi: Claude Code mostra un avviso di avvio quando le descrizioni combinate dei suoi subagent superano il limite di 15.000 token, e continua a caricare ogni subagent.

Invochi i subagent esplicitamente

Quando la delegazione automatica non è sufficiente, può richiedere un subagent lei stesso. Tre modelli escalation da un suggerimento una tantum a un predefinito a livello di sessione:

• Linguaggio naturale: nomini il subagent nel suo prompt; Claude decide se delegare
• @-mention: garantisce che il subagent viene eseguito per un'attività
• A livello di sessione: l'intera sessione utilizza il prompt di sistema, le restrizioni di strumenti e il modello di quel subagent tramite il flag --agent o l'impostazione agent

Per il linguaggio naturale, non c'è sintassi speciale. Nomini il subagent e Claude generalmente delega:

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

@-mention il subagent. Digiti @ e scelga il subagent dal typeahead, nello stesso modo in cui @-mention i file. Questo assicura che quel subagent specifico viene eseguito piuttosto che lasciare la scelta a Claude:

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

Il suo messaggio completo va ancora a Claude, che scrive il prompt dell'attività del subagent in base a quello che ha chiesto. L'@-mention controlla quale subagent Claude invoca, non quale prompt riceve.

I subagent forniti da un plugin abilitato appaiono 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. I subagent in background denominati attualmente in esecuzione nella sessione appaiono anche nel typeahead, mostrando il loro stato accanto al nome.

Può anche digitare la mention manualmente senza usare il picker: @agent-<name> per i subagent locali, o @agent- seguito dal nome con ambito per i subagent plugin, ad esempio @agent-my-plugin:code-reviewer. Mentre digita questo modulo il typeahead mostra corrispondenze di file piuttosto che agenti. La mention dell'agente si risolve comunque quando invia.

Esegua l'intera sessione come un subagent. Passi --agent <name> per avviare una sessione in cui il thread principale stesso assume il prompt di sistema, le restrizioni di strumenti e il modello di quel subagent:

claude --agent code-reviewer

Il prompt di sistema del subagent sostituisce completamente il prompt di sistema predefinito di Claude Code, nello stesso modo in cui --system-prompt fa. I file CLAUDE.md e la memoria del progetto continuano a caricarsi attraverso il flusso di messaggi normale. Il nome dell'agente appare come @<name> nell'intestazione di avvio in modo che possa confermare che è attivo.

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

Per un subagent fornito da un plugin, può passare solo il nome dell'agente e Claude Code lo troverà:

claude --agent security-reviewer

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

claude --agent my-plugin:security-reviewer

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

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

{
  "agent": "code-reviewer"
}

Il flag CLI sostituisce l'impostazione se entrambi sono presenti.

Esegua i subagent in primo piano o in background

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

• Subagent in primo piano bloccano la conversazione principale fino al completamento. I prompt di autorizzazione vengono passati a lei mentre si presentano.
• Subagent in background vengono eseguiti contemporaneamente mentre continua a lavorare. Quando un subagent in background raggiunge una chiamata di strumento che necessita di autorizzazione, Claude Code fa emergere il prompt nella sua sessione principale e nomina il subagent che sta chiedendo. Approvi per consentire al subagent di continuare, o premi Esc per negare quella singola chiamata di strumento senza fermare il subagent. Prima di v2.1.186, i subagent in background auto-negavano qualsiasi chiamata di strumento che avrebbe richiesto un prompt.

Per ogni subagent che Claude genera con lo strumento Agent, Claude Code sceglie primo piano o background dal primo di questi casi che si applica:

• Se un collega agent team in-process ha generato il subagent, Claude Code lo esegue in primo piano. Claude Code rifiuta con un errore di generare un subagent di un collega la cui definizione imposta background: true. Dove la modalità fork è disattivata e lei non ha disattivato i compiti in background, Claude Code rifiuta anche con un errore quando un collega imposta run_in_background: true.
• Se lei imposta CLAUDE_CODE_DISABLE_BACKGROUND_TASKS su 1, Claude Code esegue il subagent in primo piano, in ogni tipo di sessione e indipendentemente dal fatto che la modalità fork sia attiva.
• Dove la modalità fork è attiva, come lo è per impostazione predefinita in una sessione interattiva, Claude Code esegue il subagent in background, sia subagent fork che non-fork, e Claude non può chiedere il primo piano.
• Dove la modalità fork è disattivata, Claude esegue il subagent in background per impostazione predefinita e in primo piano quando ha bisogno del risultato prima di continuare. La modalità fork è disattivata in modalità non interattiva con -p e nell'Agent SDK a meno che lei non la attivi. Per mantenere un subagent particolare in background anche quando Claude vuole il risultato, imposti il suo campo frontmatter background su true.

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

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

I subagent in background fanno emergere ogni prompt di autorizzazione nella sua sessione principale. Quando risponde a uno di questi prompt con una scelta che dura oltre quella singola chiamata di strumento, come una concessione che dura per il resto della sessione, Claude Code applica la sua risposta all'intera sessione, inclusa la sua 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 al subagent una notifica.

I risultati di un subagent in background raggiungono Claude come una notifica di completamento in un turno successivo. Claude attende quella notifica prima di segnalare i risultati del subagent, e se chiede informazioni sul progresso per primo, segnala che il subagent è ancora in esecuzione. Prima di v2.1.211, Claude a volte segnalava risultati per un subagent in background che non aveva finito.

Può anche guidare questo lei stesso:

• Dove la modalità fork è disattivata, chieda a Claude di eseguire un'attività in background o in primo piano
• Premi Ctrl+B per mettere in background un'attività in esecuzione

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

• Quando un subagent termina con successo, Claude Code rimuove la sua riga immediatamente e, ad eccezione della modalità screen reader, mostra /tasks to see subagents nel footer per 30 secondi. Durante questi 30 secondi, esegua /tasks e premi Enter sul subagent per aprire la sua trascrizione. Prima di v2.1.232, Claude Code manteneva la riga per 30 secondi dopo che il subagent terminava, lo stesso di uno fallito, e non mostrava alcun suggerimento nel footer.
• Quando un subagent fallisce o lei lo ferma, Claude Code mantiene la sua riga per 30 secondi. Per cancellare la riga più velocemente, la selezioni e premi x.

Un subagent in background che si completa rimane 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 dettagliata rimane aperta quando il subagent termina. I subagent che falliscono o che lei ferma lasciano l'elenco. Prima di v2.1.208, un subagent completato lasciava l'elenco nel momento in cui terminava e la sua vista dettagliata si chiudeva.

Nomi dei subagent

Claude può dare a un subagent un nome passando un parametro name sulla chiamata dello strumento Agent, e può farlo da solo, senza chiedere prima a lei. Il nome rende il subagent indirizzabile: Claude può messaggiare o riprendere per nome dopo che termina.

In una sessione interattiva con agent teams abilitati, un subagent che Claude genera dalla conversazione principale con un name si avvia come collega invece, a meno che la chiamata non sia un fork o passi isolation sulla chiamata stessa. Un valore isolation nel frontmatter del subagent non lo impedisce, e il collega viene quindi eseguito nella directory di lavoro della sessione principale. Vedi Come Claude avvia agent teams.

Errori API nei subagent

Quando qualcosa interrompe la risposta di un subagent a metà flusso, e la risposta parziale contiene testo ma nessuna chiamata di strumento, Claude Code richiede al subagent di continuare piuttosto che terminare l'esecuzione. Questo accade anche nelle sessioni interattive. L'esecuzione termina sull'errore solo una volta che quelle continuazioni sono esaurite.

A partire da v2.1.199, un subagent la cui esecuzione termina con un errore API, come un limite di utilizzo o un errore server ripetuto, segnala quel fallimento a Claude invece di restituire il testo di errore come se fossero i risultati del subagent. Quello che Claude riceve dipende da dove è stato eseguito il subagent:

• Primo piano: se un limite di velocità, un sovraccarico o un errore server interrompe un subagent che ha già prodotto output di testo, lo strumento Agent restituisce quell'output parziale con una nota 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 di strumenti, fallisce con Agent terminated early due to an API error, seguito dal dettaglio dell'errore. In v2.1.199, un limite di velocità, un sovraccarico o un errore server che ha interrotto la forma solo-tool-calls ha restituito un risultato parziale vuoto contenente solo la nota di interruzione.
• Background: il subagent è contrassegnato come fallito, e il messaggio che Claude riceve quando termina nomina l'errore API e include l'ultimo output del subagent, quindi il lavoro parziale non viene perso.

Quando lei configura una catena di modelli di fallback e un subagent incontra un fallimento che la catena copre, come il suo modello non disponibile, Claude Code passa il subagent al primo modello nella catena che accetta la richiesta. Il subagent continua a lavorare invece di terminare sull'errore.

Una volta che l'errore API sottostante si risolve, chieda a Claude di riprovare l'attività o riprendere il subagent.

Scansione dell'output del subagent

Claude Code scansiona il rapporto finale di ogni subagent prima che Claude lo legga. Un subagent potrebbe aver letto file, pagine web o output di comando che lei non ha mai revisionato, e il testo da quelle fonti può contenere istruzioni rivolte alla conversazione principale. La scansione non rimuove o riformula mai nulla; apporta due tipi di cambiamento che potrebbe 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 si legga come testo ordinario 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 di autorizzazione come bypassPermissions o --dangerously-skip-permissions. Le menzioni di impostazioni di autorizzazione ottengono la riga marcatore, ma il testo stesso rimane come scritto.

La scansione non giudica se il contenuto è dannoso, e non cambia cosa un'istruzione in un rapporto può fare: una chiamata di strumento che il rapporto porta Claude a fare passa comunque attraverso i controlli di autorizzazione della sessione e il sandboxing. Non è un sostituto per limitare cosa un subagent può raggiungere.

Modelli comuni

Isoli operazioni ad alto volume

Uno degli usi più efficaci per i subagent è isolare le operazioni che producono grandi quantità di output. L'esecuzione di test, il recupero della documentazione o l'elaborazione di file di log possono consumare contesto significativo. Delegando questi a un subagent, l'output dettagliato rimane nel contesto del subagent mentre solo il riassunto rilevante ritorna alla sua conversazione principale.

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

Esegua ricerca parallela

Per indagini indipendenti, generi più subagent per lavorare simultaneamente:

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

Ogni subagent esplora la sua area in modo indipendente, quindi Claude sintetizza i risultati. Questo funziona meglio quando i percorsi di ricerca non dipendono l'uno dall'altro.

Per il lavoro che deve continuare a funzionare in parallelo o non si adatta a una finestra di contesto, eseguilo in sessioni separate e lascia che Claude passi i risultati tra di loro.

Concateni i subagent

Per flussi di lavoro multi-step, chieda a Claude di utilizzare i subagent in sequenza. Ogni subagent completa la sua attività e restituisce i risultati a Claude, che poi passa il contesto rilevante al subagent successivo.

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

Scelga tra subagent e conversazione principale

Usi la conversazione principale quando:

• L'attività necessita di frequenti scambi o raffinamento iterativo
• Più fasi condividono contesto significativo, come pianificazione, implementazione e test
• Sta facendo un cambio rapido e mirato
• La latenza è importante. Un subagent che non è un fork inizia da zero e potrebbe aver bisogno di tempo per raccogliere contesto

Usi subagent quando:

• L'attività produce output dettagliato che non ha bisogno nel suo contesto principale
• Vuole applicare restrizioni di strumenti o autorizzazioni specifiche
• Il lavoro è autonomo e può restituire un riassunto

Consideri Skills invece quando vuole prompt o flussi di lavoro riutilizzabili che vengono eseguiti nel contesto della conversazione principale piuttosto che nel contesto isolato del subagent.

Per una domanda su qualcosa già nella sua conversazione, usi /btw invece di un subagent. Vede il suo contesto completo ma non ha accesso agli strumenti, e la risposta non viene aggiunta alla cronologia.

Lasci che i subagent generino i loro propri subagent

Per impostazione predefinita, un subagent può generare subagent propri, fino a tre livelli sotto la conversazione principale. Al limite di profondità, Claude Code trattiene lo strumento Agent da ogni subagent ad eccezione di un fork, quindi un subagent al limite fa il suo lavoro delegato stesso e restituisce un riassunto. Un fork al limite mantiene Agent nel suo elenco di strumenti ereditato, ma lo strumento restituisce un errore invece di generare.

I subagent annidati si adattano a un'attività delegata che stessa si divide in sottoattività parallele, come un subagent revisore che invia un verificatore per ogni risultato, quindi l'output intermedio non raggiunge mai la sua conversazione principale. Solo il riassunto del subagent di livello superiore ritorna a lei.

Per cambiare il limite, imposti CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH al numero di livelli di subagent che vuole sotto la sua 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 suoi subagent possono delegare a un secondo livello dei loro, e quel secondo livello non può delegare ulteriormente. Imposti 1 per disattivare l'annidamento.

Un subagent annidato è configurato nello stesso modo di uno di livello superiore e si risolve dagli stessi ambiti. Per impedire a un subagent di generare mentre l'annidamento è attivo, come un revisore che dovrebbe rimanere di sola lettura, ometta Agent dal suo elenco tools o aggiunga a disallowedTools.

Claude Code mostra i subagent annidati come un albero nel pannello subagent sotto l'input del prompt e contrassegna ogni riga che ha ancora discendenti nel pannello con un conteggio (+N) di loro. Apra una riga per vedere i fratelli e i figli diretti di quel subagent con un percorso di ritorno a main.

Limite di subagent concorrenti

Due limiti controllano l'uso dei subagent, ognuno con la sua propria variabile: questo impedisce a Claude di generare più subagent mentre troppi sono in esecuzione, e il limite di profondità limita quanto profondamente i subagent si annidano. Non c'è limite al numero totale di subagent che Claude può generare durante una sessione.

Per impostazione predefinita, quando 20 subagent sono in esecuzione in una sessione, la generazione di un altro con lo strumento Agent fallisce con Concurrent subagent limit reached, e l'errore dice a Claude di non riprovare. La generazione ha successo di nuovo quando il conteggio in esecuzione scende sotto il limite. Per cambiare il limite, imposti CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS a qualsiasi numero intero positivo. Le sessioni con ultracode attivo sono esenti: il limite non viene applicato lì. Richiede Claude Code v2.1.217 o successivo.

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

• Un fork in-sessione che lei avvia con /subtask occupa uno slot mentre è in esecuzione e non è mai bloccato dal limite.
• Riprendere un subagent che ha già finito occupa uno slot fresco senza controllare il limite, quindi i ripresi possono spingere il conteggio in esecuzione oltre.

Gli agenti che altre funzionalità eseguono, come gli agenti workflow e i colleghi agent team, seguono i loro propri limiti invece.

Gestisca il contesto del subagent

Cosa si carica all'avvio

Ogni subagent inizia con una finestra di contesto fresca e isolata. Non vede la cronologia della sua conversazione, le skills che ha già invocato, o i file che Claude ha già letto. Claude compone un messaggio di delegazione che riassume l'attività, e il subagent lavora da lì. L'eccezione è un fork, che eredita la conversazione genitore invece di iniziare da zero.

Il contesto iniziale di un subagent non-fork contiene:

• System prompt: il prompt dell'agente stesso più i dettagli dell'ambiente che Claude Code aggiunge, non il prompt di sistema di Claude Code. I subagent personalizzati definiscono il loro nel corpo markdown o nel campo prompt. Gli agenti integrati hanno prompt predefiniti.
• Task message: il prompt di delegazione che Claude scrive quando consegna il lavoro.
• File CLAUDE.md: ogni livello della gerarchia CLAUDE.md che la conversazione principale carica, inclusi ~/.claude/CLAUDE.md, regole del progetto, CLAUDE.local.md e file di policy gestiti. Gli agenti Explore e Plan integrati saltano questo.
• Git status: uno snapshot preso all'inizio della sessione genitore. Assente quando la directory di lavoro non è un repository Git o quando includeGitInstructions è false. Explore e Plan lo saltano comunque.
• Preloaded skills: contenuto completo di qualsiasi skill denominata nel campo skills dell'agente. Gli agenti integrati non precaricano skills.
• Sibling roster: un promemoria di sistema che elenca main e ogni altro agente denominato nella sessione, ognuno un valore to valido per SendMessage. Richiede Claude Code v2.1.206 o successivo. L'elenco appare solo quando gli strumenti del subagent includono SendMessage e almeno un altro agente ha un nome, sia che Claude lo abbia denominato quando lo ha generato o che venga eseguito come un collega agent teams. È uno snapshot preso quando il subagent inizia, quindi gli agenti denominati successivamente non appaiono.

Explore e Plan sono gli unici subagent che omettono CLAUDE.md e git status. Non c'è un campo frontmatter o un'impostazione per-agente per cambiare quali agenti li saltano.

La conversazione principale legge i risultati di Explore e Plan con il contesto completo di CLAUDE.md, quindi la maggior parte delle regole non ha bisogno di raggiungere il subagent stesso. Se una regola deve, come "ignora la directory vendor/", la rienunci nel prompt che dà a Claude quando delega.

Alcuni stati della conversazione principale non raggiungono mai un subagent non-fork:

• Output style: un subagent esegue il suo prompt di sistema, quindi il suo output style non modella le sue risposte, ad eccezione di un fork.
• Auto memory: la auto memory della conversazione principale non viene caricata. Per dare a un subagent memoria persistente propria, usi il campo memory.
• Context window size: la finestra di contesto di un subagent è dimensionata dal suo modello, non da quella del genitore. Delegare a un modello con una finestra più piccola dà a quel subagent la finestra più piccola.

Riprenda i subagent

Ogni invocazione di subagent crea una nuova istanza piuttosto che continuare una precedente. Per continuare il lavoro di un subagent esistente invece di ricominciare, chieda a Claude di riprendere.

I subagent ripresi mantengono la loro cronologia di conversazione completa, incluse tutte le precedenti chiamate di strumenti, risultati e ragionamento. Se il subagent ha generato subagent in background propri, quella cronologia include i risultati che hanno consegnato mentre era in esecuzione. Il subagent riprende esattamente da dove si era fermato piuttosto che ricominciare da zero.

• Quando un subagent completa, Claude riceve il suo ID agente.
• Gli agenti integrati Explore e Plan sono una tantum e non restituiscono alcun ID agente, quindi Claude non può riprendere. Usi general-purpose o un subagent personalizzato quando ha bisogno di continuare il lavoro.
• Quando un subagent si ferma al suo limite maxTurns, Claude Code contrassegna l'output restituito come parziale. Per i subagent che restituiscono un ID agente, Claude Code nota anche nel risultato che Claude può messaggiare il subagent per continuare da dove si era fermato.

Claude utilizza lo strumento SendMessage con l'ID dell'agente o il nome come campo to per riprendere. SendMessage non richiede che agent teams siano abilitati; solo i messaggi strutturati del protocollo di team come shutdown_request e plan_approval_response lo fanno. Oltre ai subagent e ai colleghi, nelle sessioni dove la messaggistica tra sessioni è abilitata, Claude può usare lo stesso strumento per messaggiare le sue altre sessioni Claude Code, su questa macchina o oltre.

Per riprendere un subagent, chieda 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 a un subagent completato un messaggio con lo strumento SendMessage, il subagent riprende in background senza una nuova invocazione Agent. Lo stesso vale per un subagent che Claude ha fermato con lo strumento TaskStop, una volta che la sua esecuzione fermata è uscita. La ripresa mantiene il set di strumenti da dove il subagent è stato eseguito per la prima volta e può continuare a leggere la cache del prompt che l'esecuzione originale ha riscaldato.

Un subagent che ha lo strumento SendMessage può inviare anche quel messaggio. In una sessione interattiva, l'agente ripreso segnala quindi al subagent che lo ha ripreso, non alla sua conversazione principale. Quel subagent attende il risultato prima di terminare il suo lavoro. Quando un subagent messaggia un agente a cui segnala, come il suo lanciatore, Claude Code riprende quell'agente senza reindirizzare i suoi risultati.

Un subagent che lei ha fermato lei stesso, con x in /tasks o una richiesta SDK stop_task, non si auto-riprende. Se Claude gli invia un messaggio, il messaggio viene rifiutato e Claude viene detto che l'agente è stato annullato.

Mentre la riga di quel subagent è ancora nel pannello subagent, digiti nella sua trascrizione per riprendere lei stesso. Dopo, un messaggio da Claude può auto-riprendere di nuovo. Richiede Claude Code v2.1.191 o successivo.

Riprendere avvia una nuova esecuzione dell'agente con lo stesso ID, quindi un subagent che aveva già fallito o completato si mostra come in esecuzione di nuovo nell'elenco delle attività e negli eventi delle attività dell'Agent SDK. Prima di v2.1.205, continuava a mostrare il suo stato precedente fallito o completato mentre l'esecuzione ripresa stava funzionando.

A partire da v2.1.199, SendMessage verifica che un nome si riferisca ancora allo stesso agente che ha raggiunto in precedenza nella conversazione. Se un agente più recente ha preso il nome, come un agente in background ri-generato che lo ha riutilizzato, Claude Code rifiuta l'invio piuttosto che consegnarlo all'agente sbagliato, e l'errore segnala quale agente il nome raggiunge ora in modo che Claude possa reindirizzare. Per raggiungere l'agente precedente mentre è ancora in esecuzione, Claude lo indirizza per l'ID agente che ha ricevuto quando ha generato quell'agente. Il controllo è limitato alla conversazione attuale e si ripristina su /clear.

A partire da v2.1.198, un subagent tratta i messaggi dall'agente che lo ha lanciato come direzione di attività normale, incluse le correzioni di corso a metà attività, e agisce su di essi all'interno delle sue impostazioni di autorizzazione. Due limiti continuano a valere indipendentemente da chi ha inviato il messaggio: nessun messaggio da alcun agente conta come la sua approvazione per un prompt di autorizzazione in sospeso, e nessun messaggio di agente può cambiare le impostazioni di autorizzazione, CLAUDE.md o configurazione di un subagent. Solo il sistema di autorizzazione o i suoi stessi messaggi possono concedere l'approvazione.

Può anche chiedere a Claude l'ID agente se vuole fare riferimento ad esso esplicitamente, o trovare gli ID nei file di trascrizione in ~/.claude/projects/{project}/{sessionId}/subagents/. Ogni trascrizione è archiviata come agent-{agentId}.jsonl.

Le trascrizioni dei subagent persistono indipendentemente dalla conversazione principale:

• Compattazione della conversazione principale: quando la conversazione principale si compatta, le trascrizioni dei subagent non sono interessate. Sono archiviate in file separati.
• Persistenza della sessione: le trascrizioni dei subagent persistono all'interno della loro sessione. Può 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, 30 giorni per impostazione predefinita, seguendo le regole di pulizia della conservazione.

Auto-compattazione

I subagent supportano la compattazione automatica utilizzando la stessa logica della conversazione principale. La compattazione si attiva nelle stesse condizioni, e CLAUDE_AUTOCOMPACT_PCT_OVERRIDE si applica anche ai subagent. Consulti environment variables per 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 mostra quanti token sono stati utilizzati prima che si verificasse la compattazione.

Esegua il fork della conversazione corrente

Un fork è un subagent che eredita l'intera conversazione fino ad ora invece di iniziare da zero. Questo elimina l'isolamento dell'input che i subagent altrimenti forniscono: un fork vede lo stesso prompt di sistema, strumenti, modello e cronologia dei messaggi della sessione principale, in modo che possa assegnargli un'attività secondaria senza re-spiegare la situazione. Le proprie chiamate di strumenti del fork rimangono comunque fuori dalla sua conversazione e solo il suo risultato finale ritorna, in modo che la sua finestra di contesto principale rimanga pulita. Usi un fork quando un subagent denominato avrebbe bisogno di troppo background per essere utile, o quando vuole provare diversi approcci in parallelo dallo stesso punto di partenza.

Claude avvia un fork richiedendo il tipo di subagent fork tramite lo strumento Agent. Lei controlla se può farlo con la modalità fork, che è attivata per impostazione predefinita nelle sessioni interattive.

Può avviare un fork lei stesso con /subtask seguito da un'attività, indipendentemente dal fatto che la modalità fork sia attivata o meno. Nella versione da v2.1.161 a v2.1.211 il comando è /fork. Claude Code nomina il fork dalle prime parole dell'attività. L'esempio seguente esegue il fork della conversazione per redigere casi di test mentre continua con l'implementazione nella sessione principale:

/subtask draft unit tests for the parser changes so far

Il fork appare in un pannello sotto il suo prompt e viene eseguito in background mentre continua a lavorare. Quando finisce, il suo risultato arriva come messaggio nella sua conversazione principale. La sezione successiva copre i controlli del pannello per osservare e dirigere i fork mentre vengono eseguiti.

Osservi e dirija 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 ogni fork.

Quando un fork finisce con successo, Claude Code rimuove la sua riga. Claude Code mantiene la riga di un fork che non è riuscito o che Lei ha interrotto per 30 secondi, lo stesso che per qualsiasi altro subagent in background. Prima della versione v2.1.232, Claude Code manteneva la riga di un fork finito per 30 secondi anche.

Usi 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 skills vanno a quell'agente, ma i comandi incorporati continuano a essere eseguiti nella sua conversazione principale. A partire da v2.1.199, digitando /model o /fast in quella visualizzazione viene visualizzato un avviso che cambia il modello della conversazione principale o la modalità veloce, non quello dell'agente visualizzato, invece di eseguirlo silenziosamente.

Come i fork differiscono dai subagent non-fork

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

Poiché il prompt di sistema di un fork e le definizioni di strumenti sono identici al principale, la sua prima richiesta riutilizza la prompt cache del principale. Questo rende il fork più economico rispetto alla generazione di un subagent fresco per attività che necessitano dello 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 git worktree separato invece del suo checkout. Un fork non può generare ulteriori fork.

Attivi o disattivi la modalità fork

Claude Code attiva la modalità fork per impostazione predefinita nelle sessioni interattive e la lascia disattivata per impostazione predefinita in modalità non interattiva con -p e nell'Agent SDK. L'impostazione predefinita interattiva richiede Claude Code v2.1.232 o successivo. Nelle versioni precedenti, imposti CLAUDE_CODE_FORK_SUBAGENT su 1 per attivare la modalità fork.

Può dire che la modalità fork è attivata da come Claude Code gestisce lo strumento Agent:

• Claude può generare un fork richiedendo il tipo di subagent fork. Quando Claude non richiede un tipo, ottiene il subagent general-purpose, se la sessione ha ancora quel tipo. I subagent generati da una definizione, come Explore, funzionano come al solito.
• Claude Code esegue i subagent che Claude genera in background, sia i fork che i subagent non-fork, a parte i casi che rimangono in primo piano. Claude Code rimuove anche il parametro run_in_background dello strumento Agent, in modo che Claude non possa chiedere il primo piano.

Imposti la variabile di ambiente CLAUDE_CODE_FORK_SUBAGENT per ignorare le impostazioni predefinite:

• 1 attiva la modalità fork in modalità non interattiva e nell'Agent SDK
• 0 disattiva la modalità fork in ogni tipo di sessione

Per mantenere la modalità fork attivata ma impedire a Claude di generare fork, neghi il tipo di subagent fork con una regola Agent(fork). Claude Code continua a eseguire i subagent che Claude genera in background, a parte gli stessi casi che rimangono in primo piano.

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.

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