Hooks per subagent e team di Claude Code

I hook per subagent e team di Claude Code devono essere collocati nel livello che rappresenta davvero la regola. I settings hook si applicano anche alle tool call dei subagent; i hook nel frontmatter di un agente supportato valgono durante la sua attività. Per gli agenti distribuiti in un plugin c’è un’eccezione decisiva: il campo frontmatter hooks viene ignorato e i controlli vanno definiti al livello del plugin. Subagents e componenti plugin.

Una fine risposta, una fine agente e un task segnato completato sono fatti differenti. Il controllo deve osservare il fatto che corrisponde al requisito, identificare il ruolo e leggere una prova pertinente. Registrare lo stesso script ovunque può produrre duplicazioni o una verifica nel momento sbagliato. La guida ai Claude Code Hooks introduce i contratti generali.

Fonti verificate il 9 ottobre 2026. Le configurazioni e i casi di team sono proposte ipotetiche non eseguite, con nomi sintetici. Non viene attribuita a una delega automatica la capacità di certificare tutte le modifiche di un progetto.

Dove deve vivere una regola del team?

Una regola comune, come un limite sui percorsi modificabili, può appartenere ai settings del progetto o al livello amministrativo appropriato. Una condizione dedicata a un ruolo può vivere nella definizione dell’agente quando quella forma la supporta. Un componente distribuito dentro un plugin segue il contratto del plugin. La provenienza è quindi parte del comportamento, non un dettaglio organizzativo.

Decidi prima chi deve essere soggetto alla regola: tutti gli agenti, un ruolo specifico o soltanto un task. Una regola per tutti non dovrebbe dipendere dal fatto che ogni autore ricordi di copiarla nel frontmatter. Una regola di un ruolo non dovrebbe bloccare indiscriminatamente agenti che non dispongono degli strumenti necessari a soddisfarla.

La documentazione dei settings descrive policy e sorgenti della configurazione. Settings di Claude Code. Per la distribuzione in gruppo, Mods per team e sicurezza completa il percorso: autorizzare un plugin non garantisce che ogni processo che avvia sia sandboxato.

Quali dati permettono di identificare il subagent?

Gli input dei hook possono includere agent_id e agent_type per identificare l’attività del subagent. Gli eventi SubagentStart e SubagentStop riguardano la sua partenza e conclusione, mentre i tool event continuano a descrivere le singole chiamate. Il ruolo aiuta a filtrare; l’identificatore aiuta ad attribuire una prova alla singola esecuzione. Input comuni.

Un nome di ruolo non basta a certificare il lavoro. Un agente chiamato “verificatore” può non aver eseguito la suite pertinente. Il controllo deve leggere quale comando è stato eseguito, quale stato è stato verificato e quale risultato è stato ottenuto. La denominazione è una convenzione, la prova è un fatto distinto.

Evita di usare l’identità per ampliare privilegi senza ragione. Un ruolo può avere bisogno di strumenti limitati; il suo hook dovrebbe restringere una responsabilità, non concedere un’autorizzazione generale. Per la parte preventiva consulta PreToolUse per file e comandi.

Un evento di partenza con un ruolo sintetico

La registrazione seguente mostra soltanto come filtrare SubagentStart su un ruolo ipotetico project-checker. Il comando produce una riga su stdout, catturata nel log di debug: è uno smoke test del matcher, non un messaggio aggiunto al contesto del subagent. Non inizializza servizi e non avvia altri agenti. Il ruolo deve esistere nella configurazione reale; lo snippet non è stato eseguito in questa guida. SubagentStart.

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "project-checker",
        "hooks": [
          {
            "type": "command",
            "command": "printf 'Ruolo di verifica avviato: leggere il contratto del task.\\n'"
          }
        ]
      }
    ]
  }
}

Questo output serve a osservare l’esecuzione nel log, non orienta il subagent. Per aggiungere contesto con SubagentStart la reference richiede hookSpecificOutput.additionalContext, insieme a hookEventName. Se il ruolo deve verificare un modulo, serve inoltre un documento del task che indichi quali prove raccogliere e quali file può leggere o modificare. Non stampare nel log transcript o credenziali del progetto.

Per una prova, usa un ruolo incluso e uno escluso dal matcher. Controlla nel log di debug che la riga sia prodotta soltanto per il ruolo incluso, senza aspettarti un avviso nella UI o un’istruzione al subagent. Se il nome non corrisponde, debug dei Hooks aiuta a controllare evento e identità effettiva prima di cambiare la logica.

Che cosa cambia per i hook nel frontmatter?

Per gli agenti che supportano questa forma, i hook frontmatter sono attivi durante l’esecuzione dell’agente. Stop viene convertito nel comportamento relativo a SubagentStop, secondo la documentazione. Il team deve quindi capire quale conclusione sta verificando e non assumere che sia la risposta finale del coordinatore. Hooks per subagents.

La durata locale al ruolo è utile per un controllo dedicato, ma non sostituisce una policy comune ai tool. Se il requisito deve valere prima di ogni scrittura, collocarlo soltanto nel ruolo di review lascia fuori il resto del workflow. La matrice di responsabilità deve elencare chi esegue ogni classe di operazione.

La documentazione indica inoltre regole di fiducia per gli agenti di progetto, cambiate rispetto a versioni storiche. Prima di copiare un esempio vecchio, verifica il comportamento della versione installata. La pagina ufficiale dei subagent è la fonte del contratto corrente, non una testimonianza che quella configurazione abbia già funzionato sul computer del lettore.

Perché gli agenti plugin ignorano hooks nel frontmatter?

La pagina dei componenti plugin elenca campi della definizione degli agenti che non vengono applicati in quel contesto, fra cui hooks. È un confine esplicito della configurazione. Copiare la definizione di un agente locale dentro un plugin può quindi mantenere il testo del campo senza mantenere il suo effetto. Frontmatter fields in plugin agents.

Il controllo va spostato nei hook del plugin, con il filtro adatto al ruolo. Il packaging deve rendere questa responsabilità visibile: manifest, definizione dell’agente, registrazione dei hook e test sintetici vanno letti insieme. Non basta vedere il campo nel file per concludere che sia eseguito.

Per comprendere la confezione di un plugin, Mods di Claude: cosa sono distingue le sue possibili funzioni. Installare Mods e plugin aiuta a verificare scope e versione caricata. Il luogo effettivo della configurazione conta più della somiglianza dei file sorgenti.

TaskCompleted, SubagentStop e TeammateIdle: che cosa verificano?

SubagentStop riguarda la fine del subagent. TaskCompleted riguarda il momento in cui un task viene segnato come completato. TeammateIdle riguarda un compagno di agent team che sta per diventare inattivo. Il controllo deve essere collegato alla condizione osservata e al contratto di quell’evento. TaskCompleted e TeammateIdle.

Un task piccolo può essere concluso mentre il progetto resta aperto. Un verificatore può terminare riportando un fallimento, che è comunque un risultato utile. La policy deve conservare queste differenze, invece di usare “finito” per tutto.

Come definire un contratto di delega verificabile?

Ogni delega dovrebbe indicare obiettivo, scope dei file, strumenti necessari, criteri di risultato e limite. Per una review, l’output può essere una lista di problemi dimostrabili con riferimenti al codice. Per QA, può essere comando, esito e blocchi. Per implementazione, serve anche sapere quali file appartengono al ruolo e quali possono essere modificati da altri.

Un hook può controllare la presenza e coerenza di questi elementi, ma non deve affidarsi soltanto a parole chiave. Una frase “test eseguiti” può essere presente senza un risultato. Una prova strutturata deve riferirsi al modulo e alla versione del contenuto. Se il coordinatore applica nuovi edit dopo la delega, può servire una nuova verifica.

PostToolUse per formatter e test descrive la raccolta del feedback durante il lavoro. SessionStart e compaction spiega perché lo stato della delega deve vivere in file aggiornabili, oltre a un messaggio che potrebbe essere sintetizzato.

Come progettare un validator dedicato senza promettere troppo?

Un validator può controllare un input circoscritto: percorso incluso nello scope, risultato di un comando o struttura di un documento. Deve dichiarare cosa non controlla. Un esempio su query read-only non deve diventare una promessa che una regex impedisca ogni scrittura su un database. La protezione reale richiede anche privilegi nel backend.

Quando il controllo richiama un tool esterno, verifica disponibilità e autenticazione prima di inserirlo nella delega. Hooks e MCP distingue il tool osservato dal tool usato come handler. Il ruolo non deve inventare un risultato di scanner quando la connessione non è disponibile.

Il verificatore termina con una prova incompleta

Il task richiede un test integrato, ma il servizio locale non è disponibile. Il ruolo deve restituire i controlli conclusi, quello non eseguito e il prerequisito mancante. Il coordinatore conserva la distinzione e non traduce la fine del subagent in una validazione positiva del task.

Qual è il rischio di ricorsione fra agenti e hook?

Un hook che genera un agente può attivare altri eventi; se la stessa regola genera ancora agenti, nasce una catena non intenzionale. Anche una review può diventare infinita se ogni revisore chiede un altro revisore. La documentazione SDK segnala questo rischio per callback che invocano ulteriori agenti. Agent SDK Hooks.

Definisci un limite esplicito e un controllo sull’origine del lavoro. Non limitarti a cambiare il nome del nuovo agente: il problema è la dipendenza circolare del processo. Per una condizione di fine risposta, Stop hook senza loop descrive stop_hook_active e richieste di continuazione finite.

Il coordinatore dovrebbe poter distinguere una verifica richiesta dal task originale da una verifica generata automaticamente. Questo aiuta a leggere latenza, output e blocchi senza attribuire all’AI una necessità che nasce soltanto dalla configurazione. Un processo autonomo utile sa anche terminare con un impedimento ben descritto.

Settings hook e callback SDK sono intercambiabili?

No. Nel SDK i hook sono callback configurate nelle opzioni del programma. I settings hook seguono il contratto di Claude Code e i componenti plugin hanno un altro percorso di distribuzione. Le versioni e i linguaggi del SDK possono esporre eventi differenti; non copiare uno snippet Python o TypeScript presupponendo che corrisponda a un file JSON di settings. SDK Hooks reference.

Se stai costruendo un’applicazione che orchestra agenti, la responsabilità delle callback appartiene anche al codice dell’orchestratore. Il programma deve sapere quali settings carica, come tratta il risultato e quali strumenti rende disponibili. Un hook presente nel repository non dimostra che il SDK lo abbia caricato.

La distinzione aiuta anche nella diagnosi. Un problema in un callback non si risolve necessariamente con /hooks; un problema in un settings file non si risolve cambiando la firma di una funzione SDK. Identifica prima il livello, poi la prova adatta a quel livello.

Due team italiani con responsabilità separate

Esempio ipotetico, non testato: una software house di Trento delega implementazione e verifica di un modulo a due ruoli distinti. L’autore modifica soltanto i file assegnati; il verificatore legge il diff e avvia i controlli pertinenti. Il task non viene considerato validato perché il verificatore termina: serve il suo esito. Se l’autore modifica nuovamente il modulo, il coordinatore valuta quali prove ripetere.

Esempio ipotetico, non testato: uno studio tecnico di Pescara confeziona un agente di analisi in un plugin interno. L’autore inizialmente copia un frontmatter con hooks; la documentazione mostra che quel campo viene ignorato per gli agenti plugin. Il team definisce quindi la registrazione nei hook del plugin, prepara un caso incluso e uno escluso e verifica la versione effettivamente caricata, usando soltanto documenti fittizi.

I casi non dimostrano vantaggi quantitativi. Mostrano due errori prevenibili: confondere termine dell’agente e prova riuscita, oppure confondere presenza del campo e sua applicazione nel packaging.

Come mantenere il workflow quando cresce il team?

Conserva una matrice con ruolo, file, strumenti, evento di controllo e prova finale. Aggiornala quando un agente cambia responsabilità o quando il plugin viene distribuito in un altro scope. Gli errori frequenti sono hook duplicati, ruoli senza prerequisiti, prove riferite a file superati e controlli che si invocano reciprocamente.

Una prova con dati sintetici dovrebbe includere ruolo previsto, ruolo escluso, risultato positivo, fallimento e controllo non disponibile. Il team deve sapere chi legge l’esito e chi decide la prossima azione. La delega non cancella questa responsabilità: la rende più distribuita e quindi più importante da documentare.

La progettazione di agenti AI può partire da un singolo ruolo con output verificabile e crescere soltanto quando il processo lo richiede. Un workflow delegato funziona bene quando ogni evento ha un significato preciso, ogni prova appartiene a un task e la conclusione complessiva è una decisione basata su quei risultati.