Hooks

📝 Notes d'étude : Hooks et Mécanismes de Contrôle

⚙️ Définition et Rôle des Hooks

• Hook (Crochet) : Code déterministes exécuté à un point fixe dans le cycle de vie de Claude.
• Fonction : Transforme une règle passive en une action obligatoire que Claude ne peut ignorer.
• Objectif : Permet de garantir des actions (ex: formatage, vérification) même lors de sessions non surveillées.

⏱️ Événements Clés des Hooks

• pre-tool use : Déclenchement avant l'appel d'un outil (primitive d'application/d'application de règles).
• post-tool use : Déclenchement après un appel d'outil réussi (ex: auto-formatage, lint).
• stop : Déclenchement lorsque Claude souhaite terminer son tour.
• refuse : Déclenchement si les conditions requises ne sont pas remplies.
• subagent stop : Signal de fin pour un sous-agent.
• pre-compact / post-compact : Déclenchement avant et après la compaction de la conversation.
• session start : Initialise l'environnement. Utilisé avec le compact matcher pour réinjecté le contexte après compaction.
• instructions loaded : Déclenchement lors du chargement d'un fichier de règles (ex: Claude. md).

🛠️ Actions et Réponses (pre-tool use)

• Sortie JSON (Décision) :
• allow : Autorise l'appel.
• deny : Bloque l'appel.
• ask : Demande une clarification.
• defer : Utilisé uniquement pour les exécutions non interactives (pause/reprise).
• Modification de l'entrée : Permet de modifier l'objet d'entrée de l'outil (ex: supprimer des secrets d'une commande bash).
• Attention : Remplace l'intégralité de l'objet d'entrée ; il faut renvoyer les champs non modifiés.

🛑 Codes de Sortie (Hors JSON)

Les codes de sortie déterminent le comportement du système :

• 0 : Succès. Le standard output (stdout) est interprété par Claude.
• 1 : Erreur non bloquante. Claude exécute la commande malgré l'erreur.
• 2 : Erreur bloquante. Arrête l'exécution.

💡 Comportements Spécifiques

• Standard Output (stdout) : Le texte brut est généralement ignoré, sauf lors d'événements spécifiques (session start, etc. ).
• Standard Error (stderr) : Le code 2 est renvoyé à Claude comme contexte.
• Guardrails : Un hook pre-tool use peut effectuer une redaction (modifier l'entrée) au lieu de bloquer complètement une action dangereuse.
• Compaction : Le hook session start avec le compact matcher permet à Claude de reprendre le fil de la conversation après une compaction.

Takeaways

• Les Hooks sont du code déterministes exécutés à des points fixes dans le cycle de vie de Claude, transformant les règles passives en actions obligatoires.
• Le hook pre-tool use est le mécanisme principal pour contrôler les appels d'outils, utilisant une sortie JSON (allow, deny, ask, defer) pour déterminer le comportement.
• Les codes de sortie définissent le flux d'exécution : 0 pour le succès (stdout interprété), 1 pour une erreur non bloquante, et 2 pour une erreur bloquante.
• Les Hooks permettent des comportements avancés tels que la redaction de l'entrée (Guardrails) ou la réinitialisation du contexte après compaction via session start.