Chapter 4 · Chapitre 4 · Ce que le hook reçoit et ce qu'il répond
4.2 Les codes de sortie : 0, 2 et les autres
Follow this course in your space: your progress is saved, and the community answers your questions.
Follow for freeTon script répond d'abord à Claude Code par son code de sortie, le nombre qu'il renvoie en se terminant. En Node, c'est process.exit(0) ou process.exit(2) ; en bash, exit 0 ou exit 2.

Exit 0 : pas d'objection
L'action suit son cours. Si ton script affiche un JSON valide sur stdout (la sortie standard, là où console.log écrit), c'est ce JSON qui décide (leçon suivante). Pour certains événements, comme SessionStart et UserPromptSubmit, le texte affiché est ajouté au contexte de Claude.
Exit 2 : bloquer ou prévenir
Ton message, écrit sur la sortie d'erreur (stderr, là où console.error écrit), est transmis.
- En PreToolUse, l'outil est bloqué et Claude reçoit ton message pour adapter son approche.
- En PostToolUse, l'outil a déjà tourné, mais Claude voit ton message. C'est ce que fait le hook de la vidéo quand le code est cassé.
- En Stop, Claude est renvoyé au travail au lieu de s'arrêter.
- Certains événements ne peuvent pas être bloqués. Par exemple, pour
SessionStart, la doc indique que le stderr est montré à toi seulement, pas à Claude. Elle liste le comportement de chaque événement.
Les autres codes
Tout autre code, 1 compris, est une erreur non bloquante : sur la plupart des événements, l'action continue et une notice d'erreur apparaît. Un script qui plante par accident ne bloque donc généralement rien, ce qui est rassurant mais peut masquer un problème. La conséquence est importante pour la sécurité : pour imposer une règle, utilise exit 2, jamais exit 1. La doc décrit aussi une option onFailure pour bloquer quand un hook échoue : vérifie son fonctionnement dans la doc avant de t'en servir.
Le piège classique
Écrire son message avec console.log (stdout) puis sortir avec le code 2. Claude Code attend le message de blocage sur stderr : en Node, utilise console.error. Et à l'inverse, un message écrit sur stderr avec un code 0 ne sert pas de message pour Claude.
Le modèle à copier
// Squelette d'un hook qui impose une règle
let entree = '';
for await (const morceau of process.stdin) entree += morceau;
const donnees = JSON.parse(entree);
const probleme = false; // remplace par ta vérification
if (probleme) {
console.error('Explique ici, en une phrase claire, ce qui ne va pas et quoi faire.');
process.exit(2); // bloque (PreToolUse) ou prévient Claude (PostToolUse)
}
process.exit(0); // pas d'objection
Écris le message pour Claude comme une consigne : ce qui coince et ce qu'il doit faire à la place. « Bloqué » tout seul ne l'aide pas ; « .env est protégé : modifie plutôt .env.example » lui permet de rebondir.
Si ça coince
- Ton blocage ne bloque pas. Ton script sort avec 1 au lieu de 2, ou plante avant d'arriver au
process.exit(2). - Claude ne voit pas ton message. Il est sur stdout : passe à
console.error. - Le hook bloque tout, tout le temps. Une condition toujours vraie. Teste les trois cas de la leçon 4.4.
- Ton exit 2 sur SessionStart n'arrête rien. Cet événement ne peut pas bloquer : le message n'est montré qu'à toi.
À retenir
- 0 = pas d'objection ; 2 = blocage, avec le message sur stderr ; autre code = erreur non bloquante.
- Pour imposer une règle :
exit 2, jamaisexit 1. - En PostToolUse, exit 2 ne défait rien mais prévient Claude.
- Message de blocage = consigne claire pour Claude, sur stderr.