Chapter 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
Follow this course in your space: your progress is saved, and the community answers your questions.
Follow for freeLes 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.