Aller au contenu
Floskool

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

Leçon gratuite 6 minGroupe Claude Code & IA

Suis cette formation dans ton espace : ta progression est gardée, et la communauté répond à tes questions.

Suivre gratuitement

Les 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 : permissionDecision et additionalContext vont dans hookSpecificOutput. 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 de claude --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 deny n'a aucun effet. permissionDecision est au niveau supérieur : mets-le dans hookSpecificOutput, avec hookEventName.
  • 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.log de 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.
  • permissionDecision et additionalContext vont dans hookSpecificOutput.
  • Un allow ne contourne pas tes règles de refus.
  • Fabrique toujours le JSON avec JSON.stringify, et un seul mode par hook.