Chapitre 4 · Chapitre 4 · Ce que le hook reçoit et ce qu'il répond
4.3 Répondre en JSON pour plus de contrôle
Suis cette formation dans ton espace : ta progression est gardée, et la communauté répond à tes questions.
Suivre gratuitementLes codes de sortie permettent de bloquer ou de rester silencieux. Pour aller plus loin, ton script peut sortir avec 0 et afficher un objet JSON sur stdout.
Ajouter un message pour Claude (PostToolUse)
C'est ce que fait le hook de la vidéo après un formatage réussi :
{
"hookSpecificOutput": {
"hookEventName": "PostToolUse",
"additionalContext": "✓ menu.js vérifié et formaté par Prettier"
}
}
Ce texte est ajouté au contexte de Claude, à côté du résultat de l'outil. La doc précise qu'il lui arrive sous forme de rappel système, comme du texte simple. Claude sait ainsi que le fichier a changé de présentation et ne s'étonne pas de le retrouver reformaté.
Refuser une action en expliquant pourquoi (PreToolUse)
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Ce fichier contient des secrets : modifie plutôt .env.example"
}
}
Les valeurs principales sont deny, ask (afficher la demande d'autorisation habituelle) et allow. La doc en mentionne une quatrième, defer : lis sa description avant de l'utiliser. Même avec allow, la doc précise que les règles de refus de tes réglages continuent de s'appliquer : un hook ne peut pas assouplir ce que tes permissions interdisent.
Signaler un problème après coup (PostToolUse)
{ "decision": "block", "reason": "Les tests échouent : corrige avant de continuer" }
Ici, decision et reason sont au niveau supérieur, pas dans hookSpecificOutput. Claude voit la raison, mais l'outil a déjà tourné.
Fabriquer le JSON sans erreur
Ne construis jamais ce JSON en collant des morceaux de texte : un guillemet ou une barre oblique inverse dans un chemin Windows suffit à le casser. La doc recommande un encodeur JSON. En Node, c'est JSON.stringify :
console.log(JSON.stringify({
hookSpecificOutput: {
hookEventName: 'PreToolUse',
permissionDecision: 'deny',
permissionDecisionReason: `Fichier protégé : ${fichier}`,
},
}));
process.exit(0);
JSON.stringify échappe correctement les \ de C:\chemin\.env. Une concaténation à la main, non.
Deux erreurs fréquentes
- Un champ au mauvais niveau :
permissionDecisionetadditionalContextvont danshookSpecificOutput. Placés au niveau supérieur, ils sont ignorés sans erreur. Pour les repérer, la doc conseille de chercher « Hook JSON output had unrecognized keys » dans le journal declaude --debug. - Du texte avant le JSON : si ton profil shell affiche un message, la sortie ne commence plus par
{et le JSON est traité comme du texte. La doc conseille de chercher « Hook output does not start with { » dans le journal.
La doc conseille de choisir un seul mode par hook : exit 2 avec stderr, ou exit 0 avec JSON.
Si ça coince
- Ton
denyn'a aucun effet.permissionDecisionest au niveau supérieur : mets-le danshookSpecificOutput, avechookEventName. - Une notice parle de validation ou d'analyse JSON. Ton JSON est mal formé ou ne suit pas le format attendu, même avec exit 0. Utilise
JSON.stringify. - Ton JSON est ignoré, sans erreur. Un
console.logde débogage écrit avant lui. Envoie tes traces sur stderr. - Tu as mis exit 2 et un JSON. Choisis un seul mode : avec exit 2, le JSON n'est pas utilisé de la même façon. Vérifie la section « Exit code output » de la doc.
À retenir
- Exit 0 + JSON sur stdout = contrôle fin :
additionalContext,permissionDecision,decision. permissionDecisionetadditionalContextvont danshookSpecificOutput.- Un
allowne contourne pas tes règles de refus. - Fabrique toujours le JSON avec
JSON.stringify, et un seul mode par hook.