Stop hook: verifiche senza loop in Claude Code

Uno Stop hook può verificare una condizione quando Claude Code termina una risposta e, se necessario, chiedere di proseguire. È utile soltanto se la condizione ha una prova e un termine. “Il controllo del modulo deve essere concluso” è verificabile; “migliora ancora il progetto” non lo è. L’input include stop_hook_active, che serve a riconoscere una continuazione già provocata dal hook. Evento Stop.

La fine di una risposta non equivale alla consegna di un progetto. L’evento non certifica da solo test, review o pubblicazione. Il controllo deve sapere che cosa osservare e come gestire errori o prerequisiti mancanti. Nella guida ai Claude Code Hooks trovi il quadro generale; questa pagina si concentra sul rischio di continuazioni ripetute.

Fonti verificate il 9 ottobre 2026. Gli esempi sono ipotetici e gli snippet non sono stati eseguiti in questa guida. Non vengono dichiarati risultati di test né una copertura automatica delle consegne.

Quale condizione può controllare uno Stop hook?

Scegli una condizione legata alla consegna corrente. Può riguardare un risultato di verifica, una modifica fuori scope o un documento obbligatorio non aggiornato. Il criterio deve identificare la fonte della prova e lo stato al quale si riferisce. Un file con la parola “successo” non è sufficiente se può provenire da una modifica precedente.

Distinguere la prova dalla dichiarazione è essenziale. Il testo della risposta può dire “i test passano”, mentre il comando non è stato eseguito. Un controllo deterministico deve verificare un dato reale; una valutazione del testo può al massimo giudicare ciò che le è stato fornito. Sono responsabilità differenti, che non dovrebbero essere mescolate nello stesso nome di hook.

Per il feedback raccolto durante gli edit consulta PostToolUse per formatter e test. Lo Stop hook può verificare che un risultato pertinente sia disponibile alla fine, ma non trasforma retroattivamente una suite ancora in corso in una verifica completata.

Come nasce un loop di continuazione?

La sequenza problematica è semplice: Claude conclude, il hook chiede di continuare, Claude conclude di nuovo e lo stesso hook ripete la richiesta. Se la condizione non cambia oppure non può essere soddisfatta, il workflow consuma attività senza produrre una prova nuova. Può accadere anche con una richiesta apparentemente ragionevole, come eseguire test che dipendono da un servizio non disponibile.

stop_hook_active indica che la risposta è già dentro una continuazione generata dal hook. La reference documenta inoltre un limite di otto continuazioni consecutive. Questo limite è una protezione del prodotto; non dovrebbe essere il normale criterio di uscita della tua automazione. Stop decision control.

Un controllo dovrebbe decidere prima se è autorizzato a chiedere altro lavoro, poi valutare la condizione. Se aspetta di gestire il guard dopo una nuova richiesta di blocco, può ripetere l’errore. Anche il messaggio di continuazione deve essere preciso: attività finita, prova da raccogliere e modo di segnalare un impedimento reale.

Un guard minimo per la seconda conclusione

Il seguente script Python mostra soltanto il guard e una condizione su un segnale locale. Il file review.pending rappresenta una convenzione didattica del progetto: non è una prova di test. Lo script non è stato eseguito e va usato solo per capire il contratto. JSON di Stop.

import json
import os
import sys
from pathlib import Path

try:
    event = json.load(sys.stdin)
    if event.get("stop_hook_active"):
        sys.exit(0)
    root = Path(os.environ["CLAUDE_PROJECT_DIR"])
    pending = root / ".claude" / "review.pending"
    if pending.exists():
        print(json.dumps({
            "decision": "block",
            "reason": (
                "Leggi il criterio di review pendente e raccogli la prova. "
                "Se un prerequisito manca, dichiaralo nella risposta."
            )
        }))
except (ValueError, KeyError, OSError, AttributeError):
    print("Verifica finale non disponibile.", file=sys.stderr)
    sys.exit(1)

Il primo risultato può chiedere un’attività; il secondo lascia terminare. È una scelta conservativa dell’esempio, non un sistema completo di certificazione. Non suggerire di cancellare automaticamente il segnale per “far passare” il controllo: il significato del file e chi può aggiornarlo devono essere definiti nel progetto.

Un sistema reale dovrebbe usare uno stato di verifica strutturato e coerente con la revisione corrente. Il guard evita un tipo di ripetizione, ma non dimostra che il compito sia corretto. È importante conservare entrambe le affermazioni quando il controllo viene consegnato al team.

Dove registrare il controllo e come provarlo?

Una registrazione minima può richiamare lo script del progetto. Il contratto non richiede un matcher di tool perché Stop non riguarda il nome di una chiamata Edit o Bash. Integra questo blocco nei settings esistenti e verifica la presenza del controllo in /hooks. Configurazione dei Hooks.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/check_stop.py\""
          }
        ]
      }
    ]
  }
}

Per una prova diretta, prepara due input sintetici: uno con stop_hook_active falso e uno vero. Aggiungi un caso con segnale pendente e uno senza. Il risultato atteso deve indicare decisione, exit code e messaggio. Poi prova il percorso nella sessione, senza coinvolgere dati o servizi di produzione.

La presenza della registrazione non basta. Se il progetto richiede una verifica obbligatoria, osserva anche cosa accade quando Python non è disponibile o quando lo script riceve JSON malformato. Debug dei Hooks aiuta a separare errori dello script e comportamento dell’evento.

Script, prompt o agent: che differenza c’è?

Un command hook può confrontare dati deterministici e avviare un programma del progetto. Un prompt hook usa una singola valutazione di modello sul contesto ricevuto. Un agent hook può raccogliere informazioni attraverso ulteriori strumenti e letture; la documentazione lo indica come sperimentale. La scelta dipende dalla prova necessaria, non dal prestigio della forma più complessa. Prompt e agent hook.

Un modello può valutare una motivazione, ma non rende automaticamente vera la dichiarazione contenuta nella motivazione. Se il requisito è “test realmente eseguito”, occorre leggere il risultato del test. Se il requisito è “spiegazione comprensibile”, la valutazione del testo può essere pertinente.

Per una revisione più ampia puoi leggere Claude Opus per revisione del codice. La revisione resta una raccolta di evidenze sul codice, con limiti chiari, e non una promessa di assenza totale di problemi.

Come scrivere una richiesta di continuazione finita?

La richiesta dovrebbe identificare l’azione concreta: leggere un diff, raccogliere l’esito di un comando o correggere un errore specifico. Deve indicare cosa conta come prova e cosa fare se la condizione non è soddisfacibile. “Esegui la suite del modulo se i prerequisiti sono disponibili; altrimenti segnala quali mancano” produce un esito utile in entrambi i casi.

Non usare criteri assoluti come “nessun bug possibile” o “migliore soluzione”. Sono impossibili da verificare con un controllo finito. Anche “tutti i test” è ambiguo se il repository ha suite locali, integrate e dipendenti da servizi. Identifica quali controlli appartengono alla modifica e quali sono obbligatori prima della consegna.

La richiesta deve inoltre rispettare l’autorizzazione del lavoro: non trasformare una verifica finale in un invio automatico, una pubblicazione o un accesso a un sistema esterno. Se la prova richiede un’azione non disponibile, la risposta finale può descrivere esattamente il limite. Il loop non deve essere usato per aggirare una decisione umana.

Come gestire test in background e stato superato?

Una suite avviata in background può essere ancora in corso quando Claude conclude. Lo Stop hook deve distinguere uno stato pendente da un fallimento e da un successo. Non usare l’assenza di errori nel testo come prova che il processo sia finito. Il controllo deve conoscere il risultato del comando, oppure chiedere di raccoglierlo attraverso un percorso esplicito.

Se dopo la suite sono stati modificati file pertinenti, il suo risultato potrebbe non validare la versione corrente. Un progetto può conservare un identificatore della revisione, del diff o dello stato verificato, purché il criterio sia documentato. Un identificatore da solo non basta: va collegato al comando e al suo esito.

PostToolUse in background descrive la parte precedente del flusso. SessionStart e compaction aiuta a conservare lo stato quando la sessione riprende. Le due automazioni possono collaborare, ma devono leggere lo stesso significato di “verifica conclusa”.

Quando il blocco dipende da qualcosa fuori dal progetto?

Login mancante, database non raggiungibile, ambiente di test non avviato o decisione di business assente non si risolvono chiedendo più volte “continua”. Il hook deve produrre una categoria leggibile di impedimento. La risposta può indicare quale controllo è stato concluso, quale non è partito e cosa lo rende indisponibile.

Questo permette di finire le attività indipendenti. Se un test integrato non è disponibile, il progetto può comunque raccogliere unit test e review pertinenti, senza dichiarare completata l’integrazione. Il controllo finale non deve ridurre lo scope in silenzio, ma preservare l’esatta distinzione fra risultato verificato e parte mancante.

Una condizione che non deve generare un’altra iterazione

Il controllo richiede un servizio autenticato, ma la sessione non dispone del login necessario. La risposta deve registrare il prerequisito mancante e il controllo non eseguito. Ripetere la richiesta non fornisce l’autenticazione e non produce una prova aggiuntiva.

Se serve un avviso per richiamare l’utente a una decisione, usa le notifiche locali con un messaggio neutro. Un banner aiuta a vedere il momento, senza cambiare il significato del blocco.

Due controlli finali in realtà italiane

Esempio ipotetico, non testato: una software house di Bari modifica un calcolatore di preventivi. Prima della risposta finale vuole un esito dei test pertinenti e una lettura del diff. Lo Stop hook rileva una prova mancante e chiede una sola continuazione. Se la suite fallisce, Claude può correggere il problema e ripetere il controllo; se il runtime non è disponibile, la risposta dichiara l’impedimento invece di iterare senza fine.

Esempio ipotetico, non testato: una cooperativa di Modena sperimenta un generatore di report con dati fittizi. La consegna richiede verificare che il file di esempio sia creato e che la risposta riporti i limiti della demo. Un prompt hook può valutare la presenza dell’avvertenza nel testo, mentre l’esistenza del file richiede una prova separata. Il team non confonde la qualità della spiegazione con l’esecuzione riuscita del generatore.

I due casi chiariscono perché uno Stop hook deve avere una responsabilità riconoscibile. La stessa automazione non può certificare indistintamente correttezza di calcolo, disponibilità di un servizio e chiarezza di un report senza criteri e prove specifiche.

Quali errori trasformano la verifica in rumore?

I più frequenti sono non leggere stop_hook_active, chiedere attività impossibili, fidarsi della sola risposta testuale, usare risultati di una revisione precedente e aggiungere verificatori che invocano altri verificatori senza un limite. Un costo o una latenza di modello non vanno presentati come trascurabili senza una misura del workflow: prompt e agent hook producono lavoro aggiuntivo.

In un flusso delegato, Hooks per subagent e team distingue Stop, SubagentStop e TaskCompleted. La fine della risposta del coordinatore non deve essere utilizzata come sinonimo dell’esito di ogni task. Se il controllo chiama un servizio, HTTP Hooks aggiunge il tema degli errori e della decisione JSON.

L’esempio ufficiale Security guidance mostra verifiche distribuite in diversi momenti del lavoro. Leggilo con i suoi prerequisiti: un controllo aggiuntivo non sostituisce una pipeline del progetto e una review del cambiamento pronto per la consegna.

Chi può aggiornare la prova di completamento?

Se il controllo legge un file di stato, il progetto deve definire chi lo aggiorna e sulla base di quale risultato. L’agente non dovrebbe poter trasformare una verifica pendente in positiva soltanto per terminare la risposta. Un esito deve derivare dal comando o dalla review pertinenti.

Anche una prova valida può essere superata da un nuovo edit. Il criterio deve conoscere questa possibilità e dichiarare quando serve ripetere il controllo. La responsabilità del risultato rimane nel processo del progetto, non nel nome del file che contiene lo stato.

Come sapere se lo Stop hook è mantenibile?

Prepara una matrice con condizione soddisfatta, prova mancante, continuazione già attiva e prerequisito indisponibile. Per ogni caso descrivi cosa deve accadere e quale risultato deve essere mostrato. Una modifica al criterio richiede aggiornare questa matrice, non soltanto il prompt del hook.

Per un controllo piccolo, uno script chiaro può bastare. Quando servono strumenti o un’interfaccia nuova, confronta Mods di Claude prima di aggiungere complessità. Il meccanismo va scelto perché raccoglie la prova necessaria, non perché promette genericamente più autonomia.

La progettazione di agenti AI può includere criteri di completamento, limiti di iterazione e gestione dei blocchi. Un buon Stop hook rende la fine del lavoro più leggibile: domanda finita, prova disponibile e dichiarazione precisa di ciò che resta da verificare.