Pièges courants des hooks

Votre hook fonctionne sur votre machine. Vous le commitez, un collègue récupère la branche, et rien ne se déclenche chez lui — ou pire, Claude Code se plaint d’une commande introuvable à chaque appel d’outil. Quand vous travaillez avec les hooks, il y a un piège important à connaître, et c’est celui-là : la gestion des chemins.

Le problème des chemins absolus

La documentation de Claude Code recommande d’utiliser des chemins absolus (plutôt que relatifs) pour les scripts de hooks. La raison est de sécurité : cette recommandation aide à atténuer les attaques par interception de chemin et plantation de binaires. Avec un chemin relatif, la commande réellement exécutée dépend du répertoire courant et de ce qui s’y trouve, si bien qu’un fichier déposé au bon endroit par un tiers pourrait être lancé à la place du vôtre. Un chemin absolu, lui, désigne un fichier et un seul, sans ambiguïté.

Cependant, cette recommandation rend beaucoup plus difficile le partage des fichiers settings.json entre développeurs. La raison est simple : le chemin absolu vers les scripts de hooks sur votre machine sera probablement différent de celui sur la machine d’un collègue, ne serait-ce que parce que vous ne rangez pas vos projets au même endroit. Votre /Users/vous/dev/projet/hooks/read_hook.js n’existe nulle part chez lui. Vous voilà donc pris entre deux exigences également légitimes, la sécurité poussant vers l’absolu et le travail en équipe vers le relatif.

La solution : fichier template avec placeholder

L’issue consiste à ne plus commiter le fichier réel, mais la recette qui permet de le fabriquer sur chaque poste. Vous versionnez un fichier settings.example.json dans lequel la partie variable du chemin est remplacée par un placeholder $PWD :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Grep",
        "hooks": [
          {
            "type": "command",
            "command": "node $PWD/hooks/read_hook.js"
          }
        ]
      }
    ]
  }
}

Puis vous ajoutez un script d’initialisation, par exemple scripts/init-claude.js, dont le travail tient en trois opérations :

Lit le fichier settings.example.json
Remplace les placeholders $PWD par le chemin absolu réel du projet
Copie le résultat dans .claude/settings.local.json

Le fichier produit contient donc bien des chemins absolus, conformes à la recommandation de sécurité, mais il n’a jamais été écrit à la main ni transporté d’une machine à l’autre. Chaque poste génère le sien, à partir de son propre répertoire de travail.

Mise en pratique

Reste à faire en sorte que personne n’ait à penser à lancer ce script. Le plus simple est de l’accrocher à la commande d’installation que tout le monde exécute déjà en arrivant sur le projet :

{
  "scripts": {
    "setup": "npm install && node scripts/init-claude.js"
  }
}

Chaque développeur qui lance le setup obtient ainsi automatiquement un fichier settings.local.json avec les bons chemins absolus pour sa machine. Le nouvel arrivant clone le dépôt, lance npm run setup, et ses hooks sont actifs dès sa première session sans qu’on lui ait rien expliqué.

Cette organisation repose sur une répartition claire des rôles entre les fichiers. Le template settings.example.json, avec ses placeholders, est commité et vit dans le dépôt comme n’importe quelle source. Le settings.local.json, lui, ne doit jamais être commité puisqu’il contient des chemins spécifiques à une machine — ajoutez-le à votre .gitignore si ce n’est pas déjà fait. Entre les deux, le script de setup fait le pont et automatise la génération.

Un dernier réflexe, valable bien au-delà de ce piège : redémarrez Claude Code après toute modification des fichiers de paramètres. Les hooks sont lus au démarrage de la session, et un template correctement généré ne produira aucun effet tant que la session en cours n’aura pas été relancée.