Cours Vibe coding avec Claude Code · Module 15: Claude Code avancé

Des règles sans exception : les hooks

9 min de lecture
Dans cette leçon9

Une ligne du CLAUDE.md de Treasure Map dit : on ne modifie pas les migrations de prisma/migrations/, un changement de schéma est une nouvelle migration. Tu demandes à Claude de renommer une colonne, et il la corrige consciencieusement dans schema.prisma et aussi dans la migration enregistrée, car l'ancien nom s'y trouve aussi. Ta base a déjà exécuté cette migration, donc l'historique des migrations ne correspond plus à la base. La règle était écrite, mais écrire, c'est demander, et une demande n'est pas un verrou.

Ce que tu sais déjà

Dans la leçon 7_1, tu as fixé un hook PostToolUse avec le matcher Edit|Write, qui formate le fichier modifié, et tu l'as regardé dans /hooks. Dans la leçon 7_3, un hook Notification dans les réglages utilisateur sonnait quand Claude attendait ton accord. De la leçon 8_4, tu connais la règle deny pour .env, et de la leçon 14_3 l'ordre deny, ask, allow et la commande /permissions. Maintenant, le hook ne range pas après la modification : il se place devant elle et dit "non".

Demande, règle, hook

Tu peux écrire une règle de trois façons, et elles diffèrent par ce qui la garde :

  • Une ligne dans CLAUDE.md est du contexte pour le modèle. Claude la lit et l'applique le plus souvent, mais la documentation dit nettement qu'il n'y a aucune garantie d'obéissance stricte.
  • Une règle deny ou ask est un motif sur un outil et un chemin, que Claude Code garde dans tous les modes. Le refus est général, sans indication de ce qu'il faut faire à la place.
  • Un hook est ton propre programme, lancé à un moment précis du travail. Il peut vérifier n'importe quoi et répondre avec son propre message.

La documentation de la mémoire le conseille : si quelque chose doit se produire à un moment précis, par exemple avant chaque modification, écris un hook, pas une ligne dans CLAUDE.md. Les événements ont leur rythme : SessionStart une fois au début de la session, PreToolUse avant chaque appel d'outil, PostToolUse après, et Stop quand Claude termine sa réponse. Une interdiction doit agir avant l'écriture, donc tu choisis PreToolUse.

Demande pour Claude Code

Dans une session ouverte dans le dossier treasure-map, écris :

Ajoute à .claude/settings.json un hook PreToolUse pour les outils Edit et Write. Il doit lancer
le script .claude/hooks/proteger-fichiers.sh, qui se termine par le code 2 avec un message sur stderr
pour les fichiers .env* (sauf .env.example) et pour tout ce qui est dans prisma/migrations/.
Le message doit dire quoi faire à la place. Ne touche pas aux hooks existants.
C'est fini quand le script reçoit un JSON avec le chemin .env et se termine par le code 2.

La demande donne l'événement, les outils, le code de sortie et le test, donc elle ne laisse aucune place à la devinette.

Ce que Claude a écrit : le script

Ouvre .claude/hooks/proteger-fichiers.sh dans Cursor. Le hook reçoit la description de l'appel sous forme de JSON sur l'entrée standard : le nom de l'outil dans tool_name et les arguments dans tool_input, et pour Edit et Write le chemin complet dans file_path. La première ligne du script en extrait le chemin :

#!/bin/bash
# proteger-fichiers.sh : hook PreToolUse qui interdit de modifier les secrets et les migrations déjà enregistrées

FILE=$(jq -r '.tool_input.file_path // empty')

jq lit le JSON de l'entrée, et // empty donne un texte vide quand le champ n'existe pas, par exemple pour une commande Bash. Ensuite vient la décision :

case "$FILE" in
  */.env.example)
    exit 0
    ;;
  */.env*)
    echo "Bloqué : $FILE est un fichier de secrets. Les variables de .env sont définies par un humain ; ajoute le nom manquant à .env.example." >&2
    exit 2
    ;;
  */prisma/migrations/*)
    echo "Bloqué : $FILE est une migration déjà enregistrée. Modifie prisma/schema.prisma et demande une nouvelle migration." >&2
    exit 2
    ;;
esac

exit 0

case compare le chemin aux motifs un par un et prend le premier qui correspond, c'est pourquoi l'exception pour .env.example se trouve avant */.env*. Le code de sortie est la réponse. 2 bloque l'appel, et le texte écrit par >&2 sur stderr, Claude le reçoit comme raison. 0 veut dire "pas d'objection", pas "accord" : ensuite, ce sont les permissions habituelles qui décident. Le code 1, même s'il signifie une erreur sous Unix, ne bloque rien : la documentation l'appelle une erreur non bloquante et prévient qu'un hook qui garde une règle doit se terminer par le code 2. À la place du code 2, le script peut aussi se terminer par le code 0 et écrire un JSON avec permissionDecision réglé sur deny. Choisis une seule voie par hook ; le code 2 est plus simple, et c'est celui que je garde.

Ce que Claude a écrit : l'entrée dans les réglages

Dans .claude/settings.json, à côté de permissions de la leçon 14_3, une section hooks est apparue :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/proteger-fichiers.sh"],
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

La forme, tu la connais depuis la leçon 7_1. matcher avec Edit|Write est une liste exacte de noms d'outils : Edit modifie un morceau d'un fichier existant, et Write écrit tout le fichier, y compris un nouveau. ${CLAUDE_PROJECT_DIR} est le dossier du projet, donc le script sera trouvé même si Claude change de dossier de travail. Le champ args lance bash sans passer par un shell, donc un chemin avec une espace ne sera pas coupé en morceaux, et le script n'a pas besoin de chmod +x. onFailure: "block" inverse le comportement par défaut : sans lui, un hook qui ne démarre pas, parce que son chemin est faux, laisserait passer toutes les modifications.

L'essai en direct

Tu vérifies d'abord le script sans Claude, en lui donnant le JSON à la main :

echo '{"tool_input":{"file_path":"/x/treasure-map/.env"}}' | bash .claude/hooks/proteger-fichiers.sh; echo $?

Le terminal affichera le message "Bloqué : ..." et le nombre 2. Remplace le chemin par /x/treasure-map/lib/pins.ts, et tu verras seulement 0. Ensuite l'essai avec Claude : dans claude -p, avec l'écriture permise par --allowedTools "Write", nous avons demandé de créer .env.test et un nouveau fichier dans prisma/migrations/. La migration s'est arrêtée sur le hook, malgré l'accord pour Write :

PreToolUse:Write hook error: [bash ${CLAUDE_PROJECT_DIR}/.claude/hooks/proteger-fichiers.sh]: Bloqué : .../prisma/migrations/20261115120000_tags/migration.sql est une migration déjà enregistrée. Modifie prisma/schema.prisma et demande une nouvelle migration.

Claude a répété le message et n'a pas cherché d'autre chemin. .env.test avait été arrêté plus tôt par la règle Read(./.env.*) de la leçon 8_4, avec le "File is covered by a Read deny rule" général. Pour .env, le hook est donc une deuxième couche, et pour les migrations, le seul verrou. Dans la session, tape encore /hooks : ton hook se trouve sous PreToolUse avec la source dans les réglages du projet, et le hook Notification de la leçon 7_3, si tu l'as, avec la source dans les réglages utilisateur.

Ce que le hook ne voit pas

Un hook avec le matcher Edit|Write ne regarde que ces deux outils. Si Claude ajoute une ligne avec la commande echo DEBUG=1 >> .env ou modifie un fichier avec sed -i, le hook ne bouge pas. La documentation conseille d'ajouter une règle deny pour Edit, par exemple Edit(./prisma/migrations/**), car les règles Read et Edit couvrent aussi les commandes de fichiers reconnues dans Bash (cat, sed, tee) et les redirections >. Un script qui ouvre lui-même le fichier contournera cela aussi ; un mur au niveau du système, seul le sandbox le donne, et tu le découvriras dans la leçon 14_7.

Souviens-toi aussi qu'un hook est une commande qui agit avec tes permissions, y compris dans le dépôt de quelqu'un d'autre. Comme le disait la leçon 14_1, claude -p dans un projet cloné exécutera sans demander les hooks de son .claude/settings.json. Avant de lancer un script sur du code étranger, lis .claude/settings.json et .claude/hooks/, ou désactive les hooks pour une exécution avec le drapeau --settings '{"disableAllHooks": true}'. Des hooks peuvent aussi venir dans le frontmatter d'un skill et dans un plugin, et dans la leçon 14_8 un hook Stop renverra Claude au travail tant que les types ne correspondent pas.

La revue du capitaine

  1. Write dans le matcher. Une erreur typique de l'agent est "matcher": "Edit", parce que la tâche disait "avant la modification". Un nouveau fichier .env.local ou une nouvelle migration passent par Write et contournent le hook. Tu le reconnais dans le diff au seul Edit.
  2. Le code 2 et stderr. Chaque blocage se termine par exit 2, et le message passe par >&2. Sans la redirection, Claude recevra un blocage sans raison et devinera la suite.
  3. jq à bord. jq --version doit fonctionner. Sans jq, la variable FILE est vide, le script se termine par le code 0 et laisse tout passer, et onFailure ne le rattrape pas.
  4. L'essai. Un JSON donné à la main renvoie 2 pour .env et pour les migrations, et 0 pour .env.example et lib/pins.ts, et /hooks montre l'entrée.

Étape suivante

Ferme la brèche dans Bash pour la commande la plus dangereuse de Prisma :

Étends proteger-fichiers.sh : quand tool_input.command contient prisma migrate reset, termine
par le code 2 avec un message. Dans settings.json, ajoute un deuxième groupe avec le matcher Bash.
Vérifie le script avec un JSON donné à la main avant de demander le commit.

Ensuite demande un commit, par exemple "Hook qui protège les secrets et les migrations". Dans l'éditeur à côté, tu choisiras l'événement, le matcher, l'appel et le code de sortie, et le simulateur montrera si le hook se déclenche, ce qu'il reçoit en entrée et ce qui arrive à l'outil.

N'oublie pas : ce qui doit toujours arriver, tu ne l'écris pas dans le journal de bord, tu le cloues au pont.

Code de cette leçon : App.tsx
// Simulateur de hook : événement, matcher, appel d’outil, code de sortie et ce qui en découle
import { useState } from 'react';

export type Tool = 'Edit' | 'Write' | 'Bash';
export type HookEvent = 'PreToolUse' | 'PostToolUse';
export type ExitChoice = 'script' | '0' | '1' | '2';

export interface Call {
  tool: Tool;
  target: string;
}

export const ROOT = '/x/treasure-map/';

export const CALLS: Call[] = [
  { tool: 'Edit', target: '.env' },
  { tool: 'Write', target: '.env.local' },
  { tool: 'Edit', target: '.env.example' },
  { tool: 'Write', target: 'prisma/migrations/20261115120000_tags/migration.sql' },
  { tool: 'Edit', target: 'prisma/schema.prisma' },
  { tool: 'Edit', target: 'lib/pins.ts' },
  { tool: 'Bash', target: 'echo DEBUG=1 >> .env' },
];

export function matcherHits(matcher: string, tool: string): boolean {
  const m = matcher.trim();
  if (m === '' || m === '*') return true;
  if (/^[A-Za-z0-9_|, -]+$/.test(m)) {
    return m.split(/[|,]/).map((s) => s.trim()).includes(tool);
  }
  try {
    return new RegExp(m).test(tool);
  } catch {
    return false;
  }
}

function casePattern(pattern: string, value: string): boolean {
  const re = pattern.replace(/[.+?^$()[\]{}|\\]/g, (c) => '\\' + c).replace(/\*/g, '.*');
  return new RegExp('^' + re + '$').test(value);
}

export interface ScriptResult {
  code: number;
  stderr: string;
}

export function runScript(call: Call): ScriptResult {
  const file = call.tool === 'Bash' ? '' : ROOT + call.target;
  if (casePattern('*/.env.example', file)) return { code: 0, stderr: '' };
  if (casePattern('*/.env*', file)) {
    return { code: 2, stderr: 'Bloqué : ' + file + ' est un fichier de secrets. Les variables de .env sont définies par un humain ; ajoute le nom manquant à .env.example.' };
  }
  if (casePattern('*/prisma/migrations/*', file)) {
    return { code: 2, stderr: 'Bloqué : ' + file + ' est une migration déjà enregistrée. Modifie prisma/schema.prisma et demande une nouvelle migration.' };
  }
  return { code: 0, stderr: '' };
}

export function stdinFor(event: HookEvent, call: Call): string {
  const input = call.tool === 'Bash' ? { command: call.target } : { file_path: ROOT + call.target };
  return JSON.stringify({ hook_event_name: event, tool_name: call.tool, tool_input: input });
}

export interface Outcome {
  fired: boolean;
  code: number | null;
  blocked: boolean;
  text: string;
}

export function simulate(event: HookEvent, matcher: string, call: Call, exit: ExitChoice, onFailureBlock: boolean): Outcome {
  if (!matcherHits(matcher, call.tool)) {
    const gap = call.tool === 'Bash' && call.target.includes('.env')
      ? ' Cette brèche est comblée par une règle deny Edit, qui couvre aussi les redirections dans Bash.'
      : '';
    return { fired: false, code: null, blocked: false, text: 'Le hook ne s’est pas déclenché : le matcher "' + matcher + '" ne couvre pas l’outil ' + call.tool + '.' + gap };
  }
  const script = runScript(call);
  const code = exit === 'script' ? script.code : Number(exit);
  const note = call.tool === 'Bash' && exit === 'script'
    ? ' Le script ne lit que file_path, donc il laisse passer la commande Bash ; il faut une condition à part sur tool_input.command.'
    : '';
  if (event === 'PostToolUse') {
    if (code === 2) return { fired: true, code, blocked: false, text: 'L’outil a déjà agi. stderr arrive à Claude, mais ne défera pas la modification.' };
    return { fired: true, code, blocked: false, text: 'Un hook après coup ne bloque rien ; c’est ainsi que fonctionne le formatage de la leçon 7_1.' + note };
  }
  if (code === 2) {
    const reason = exit === 'script' ? script.stderr : '(ton message de stderr)';
    return { fired: true, code, blocked: true, text: 'Bloqué avant l’exécution, même si une règle allow laisserait passer. Claude reçoit : ' + reason };
  }
  if (code === 0) {
    return { fired: true, code, blocked: false, text: 'Pas d’objection, mais ce n’est pas un accord : les règles de permission et le mode décident ensuite.' + note };
  }
  return onFailureBlock
    ? { fired: true, code, blocked: true, text: 'Un code autre que 0 et 2 est une erreur du hook, et onFailure: "block" la transforme en blocage.' }
    : { fired: true, code, blocked: false, text: 'Le code ' + code + ' est une erreur non bloquante : l’outil continue. Seul le code 2 garde la règle.' };
}

export default function App() {
  const [event, setEvent] = useState<HookEvent>('PreToolUse');
  const [matcher, setMatcher] = useState('Edit|Write');
  const [index, setIndex] = useState(1);
  const [exit, setExit] = useState<ExitChoice>('script');
  const [onFailureBlock, setOnFailureBlock] = useState(true);
  const call = CALLS[index];
  const result = simulate(event, matcher, call, exit, onFailureBlock);

  return (
    <div className="min-h-screen space-y-4 bg-slate-950 p-4 text-slate-100">
      <h1 className="text-xl font-bold">Un hook à bord de Treasure Map</h1>
      <div className="grid gap-3 text-sm md:grid-cols-2">
        <label className="block">
          Événement{' '}
          <select className="rounded bg-slate-800 p-1" value={event} onChange={(e) => setEvent(e.target.value as HookEvent)}>
            <option value="PreToolUse">PreToolUse</option>
            <option value="PostToolUse">PostToolUse</option>
          </select>
        </label>
        <label className="block">
          matcher{' '}
          <input className="rounded bg-slate-800 p-1 font-mono" value={matcher} onChange={(e) => setMatcher(e.target.value)} />
        </label>
        <label className="block">
          Appel{' '}
          <select className="rounded bg-slate-800 p-1 font-mono" value={index} onChange={(e) => setIndex(Number(e.target.value))}>
            {CALLS.map((c, i) => (
              <option key={i} value={i}>{c.tool}: {c.target}</option>
            ))}
          </select>
        </label>
        <label className="block">
          Code de sortie{' '}
          <select className="rounded bg-slate-800 p-1" value={exit} onChange={(e) => setExit(e.target.value as ExitChoice)}>
            <option value="script">comme dans proteger-fichiers.sh</option>
            <option value="0">0</option>
            <option value="1">1</option>
            <option value="2">2</option>
          </select>
        </label>
      </div>
      <label className="flex items-center gap-2 text-sm">
        <input type="checkbox" checked={onFailureBlock} onChange={(e) => setOnFailureBlock(e.target.checked)} />
        onFailure: &quot;block&quot;
      </label>
      <section>
        <h2 className="font-semibold">Ce que le hook reçoit en entrée</h2>
        <pre className="overflow-x-auto whitespace-pre-wrap rounded bg-slate-900 p-2 font-mono text-xs">{stdinFor(event, call)}</pre>
      </section>
      <p role="status" className="rounded border border-slate-700 p-2 text-sm">
        <strong className={result.blocked ? 'text-rose-400' : result.fired ? 'text-emerald-400' : 'text-amber-400'}>
          {result.fired ? 'hook déclenché, code ' + result.code : 'hook non déclenché'}
        </strong>{' '}
        {result.text}
      </p>
    </div>
  );
}

Tu as repéré une erreur dans cette leçon ?

Teste tes connaissances

Réponds aux questions de cette leçon. Choisis une réponse pour voir tout de suite si elle est correcte.

  1. 1. CLAUDE.md dit qu'on ne modifie pas les migrations, et Claude a quand même corrigé un fichier de prisma/migrations/. Qu'est-ce qui l'arrêtera à chaque fois et lui dira quoi faire à la place ?

  2. 2. Un hook PreToolUse sans champ onFailure a écrit la raison sur stderr et s'est terminé par le code 1. Que deviendra la modification ?

Tâches pratiques dans le jeu

  • Tri horizontal

    Compose la ligne qui donne au script du hook un JSON avec le chemin .env et affiche son code de sortie :

  • Tri vertical

    Ordonne les événements des hooks dans l'ordre où ils se produisent pendant l'emploi d'un outil dans une session :

  1. QuestionQuiz : Ce qui fait respecter la règle
  2. QuestionQuiz : Code de sortie d'un hook
  3. Remets dans l'ordreTri : Tester un hook sans Claude
  4. Remets dans l'ordreTri : Événements du cycle de vie des hooks

Articles utiles