Claude Code Hooks : contrôler l'IA avec du Python simple

Pourquoi les hooks ?

Quand Claude Code génère du code, tu veux souvent lui imposer des règles : "pas de modifications en dehors de /app/src", "tout fichier Vue doit avoir setup lang=ts", "bloque les FormRequest, pousse vers les Data Classes". Sans les hooks, tu dois vérifier manuellement ou refuser tout en bloc. Avec les hooks, tu automatises la validation.

Trois patterns concrets

Valider la structure Vue

class VueValidator(HookHandler):
    def pre_tool_use(self, input: PreToolUseInput) -> PreToolUseResponse | None:
        if not input.file_path_matches('**/*.vue'):
            return None
        
        content = input.content or ''
        if '<script setup lang="ts">' not in content:
            return PreToolUseResponse.deny(
                "Vue doit utiliser <script setup lang=\"ts\">"
            )
        return PreToolUseResponse.allow()

Tu étends HookHandler, tu implémentes pre_tool_use(), tu retournes allow/deny/ask. Fini.

Confiner les contrôleurs Laravel

class ControllerValidator(HookHandler):
    def pre_tool_use(self, input: PreToolUseInput) -> PreToolUseResponse | None:
        if not input.file_path_matches('**/*Controller.php'):
            return None
        
        if not input.file_path_matches('**/app/Http/Controllers/**'):
            return PreToolUseResponse.deny(
                f"Les contrôleurs doivent être dans app/Http/Controllers/. "
                f"Trouvé: {input.file_path}"
            )
        return PreToolUseResponse.allow()

Journaliser les décisions

Chaque handler reçoit un HookLogger. Les journaux vont dans .claude/logs/{namespace}/hooks.jsonl — un objet JSON par ligne, avec timestamp, niveau, session ID, raison. Parfait pour comprendre pourquoi Claude a fait un truc ou non.

Points clés

Minimaliste : tu n'as que ce qu'il te faut. Pas de dépendances lourdes. Si tu veux appeler une IA pour la validation, tu importes ton SDK toi-même.

Type-safe : les inputs et outputs sont des dataclasses. Ton IDE te complète, les erreurs remontent à la compilation.

Multi-hook : un même script Python peut gérer PreToolUse, PostToolUse, UserPromptSubmit, SessionStart. Tu surcharges juste ce que tu dois.

Réactions fines : allow/deny/ask, et tu peux même modifier l'input avant qu'il n'arrive à Claude (with_updated_input).

Configuration

Tu déclares tes hooks dans .claude/settings.json :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{
          "type": "command",
          "command": "python3 /path/to/validator.py"
        }]
      }
    ]
  }
}

C'est ça. Claude passe par stdin, tu retournes la réponse sur stdout, la lib gère le reste.

Qui devrait l'utiliser ?

Si tu utilises Claude Code dans une équipe ou un projet avec des standards stricts (structure de dossiers, conventions de code, fichiers protégés), cette lib te sauve du temps de relecture manuelle. Tu écris une fois, ça roule à chaque suggestion de Claude.