Exemples

Comment configurer des hooks pour Claude Code et le Agents SDK

Des exemples prêts à l’emploi pour les scénarios courants. Chacun montre comment installer et ce à quoi s’attendre.

---

​

Configurer des hooks pour Claude Code

Failproof AI s’intègre à Claude Code via son système de hooks. Lorsque vous exécutez failproofai policies --install, il enregistre des commandes de hook dans le fichier settings.json de Claude Code, qui se déclenchent à chaque appel d’outil.

1. Installer failproofai

   npm install -g failproofai
   
2. Activer toutes les politiques intégrées

   failproofai policies --install
   
3. Vérifier que les hooks sont enregistrés

   cat ~/.claude/settings.json | grep failproofai
   

   Vous devriez voir des entrées de hook pour les événements PreToolUse, PostToolUse, Notification et Stop.

4. Lancer Claude Code

   claude
   

   Les politiques s’exécutent désormais automatiquement à chaque appel d’outil. Essayez de demander à Claude d’exécuter sudo rm -rf / — la commande sera bloquée.

---

​

Configurer des hooks pour le Agents SDK

Si vous développez avec le Agents SDK, vous pouvez utiliser le même système de hooks de manière programmatique.

1. Installer failproofai dans votre projet

   npm install failproofai
   
2. Configurer les hooks dans votre agent

   Passez des commandes de hook lors de la création de votre processus d’agent. Les hooks se déclenchent de la même façon que dans Claude Code — via du JSON sur stdin/stdout :

   failproofai --hook PreToolUse   # appelé avant chaque outil
   failproofai --hook PostToolUse  # appelé après chaque outil
   
3. Écrire une politique personnalisée pour votre agent

   import { customPolicies, allow, deny } from "failproofai";
   
   customPolicies.add({
     name: "limit-to-project-dir",
     description: "Keep the agent inside the project directory",
     match: { events: ["PreToolUse"] },
     fn: async (ctx) => {
       const path = String(ctx.toolInput?.file_path ?? "");
       if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) {
         return deny("Agent is restricted to the project directory");
       }
       return allow();
     },
   });
   
4. Installer la politique personnalisée

   failproofai policies --install --custom ./my-agent-policies.js
   

---

​

Bloquer les commandes destructrices

La configuration la plus courante — empêcher les agents de causer des dommages irréversibles.

failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh

Ce que cela fait :

• block-sudo — bloque toutes les commandes sudo
• block-rm-rf — bloque la suppression récursive de fichiers
• block-force-push — bloque git push --force
• block-curl-pipe-sh — bloque l’exécution de scripts distants via un pipe vers le shell

---

​

Empêcher la fuite de secrets

Empêchez les agents de voir ou de divulguer des identifiants dans la sortie des outils.

failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens

Ces politiques se déclenchent sur PostToolUse — après l’exécution d’un outil, elles nettoient la sortie avant que l’agent ne la consulte.

---

​

Recevoir des alertes Slack lorsque les agents ont besoin d’attention

Utilisez le hook de notification pour transférer les alertes d’inactivité vers Slack.

import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "slack-on-idle",
  description: "Alert Slack when the agent is waiting for input",
  match: { events: ["Notification"] },
  fn: async (ctx) => {
    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
    if (!webhookUrl) return allow();

    const message = String(ctx.payload?.message ?? "Agent is waiting");
    const project = ctx.session?.cwd ?? "unknown";

    try {
      await fetch(webhookUrl, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          text: `*${message}*\nProject: \`${project}\``,
        }),
        signal: AbortSignal.timeout(5000),
      });
    } catch {
      // ne jamais bloquer l'agent si Slack est inaccessible
    }

    return allow();
  },
});

Installez-le :

SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js

---

​

Maintenir les agents sur une branche

Empêchez les agents de changer de branche ou de pousser vers des branches protégées.

import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "stay-on-branch",
  description: "Prevent the agent from checking out other branches",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = String(ctx.toolInput?.command ?? "");
    if (/git\s+checkout\s+(?!-b)/.test(cmd)) {
      return deny("Stay on the current branch. Create a new branch with -b if needed.");
    }
    return allow();
  },
});

---

​

Exiger des tests avant les commits

Rappeler aux agents d’exécuter les tests avant de faire un commit.

import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "test-before-commit",
  description: "Remind the agent to run tests before committing",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = String(ctx.toolInput?.command ?? "");
    if (/git\s+commit/.test(cmd)) {
      return instruct("Run tests before committing. Use `npm test` or `bun test` first.");
    }
    return allow();
  },
});

---

​

Verrouiller un dépôt de production

Commitez une configuration au niveau du projet afin que tous les développeurs de votre équipe bénéficient des mêmes politiques.

Créez .failproofai/policies-config.json dans votre dépôt :

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-force-push",
    "block-push-master",
    "block-env-files",
    "sanitize-api-keys",
    "sanitize-jwt"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "production"]
    }
  }
}

Puis commitez-le :

git add .failproofai/policies-config.json
git commit -m "Add failproofai team policies"

Chaque membre de l’équipe ayant failproofai installé récupérera automatiquement ces règles.

---

​

Établir un standard qualité à l’échelle de l’organisation avec des politiques de convention

La configuration la plus impactante : commitez .failproofai/policies/ dans votre dépôt avec des politiques adaptées à votre projet. Tous les membres de l’équipe les récupèrent automatiquement — sans commandes d’installation ni modifications de configuration.

1. Créer le répertoire et ajouter des politiques

   mkdir -p .failproofai/policies
   

   // .failproofai/policies/team-policies.mjs
   import { customPolicies, allow, deny, instruct } from "failproofai";
   
   // Enforce your team's preferred package manager
   // (or enable the built-in prefer-package-manager policy instead)
   customPolicies.add({
     name: "enforce-bun",
     match: { events: ["PreToolUse"] },
     fn: async (ctx) => {
       if (ctx.toolName !== "Bash") return allow();
       const cmd = String(ctx.toolInput?.command ?? "");
       if (/\bnpm\b/.test(cmd)) return deny("Use bun instead of npm.");
       return allow();
     },
   });
   
   // Remind the agent to run tests before committing
   customPolicies.add({
     name: "test-before-commit",
     match: { events: ["PreToolUse"] },
     fn: async (ctx) => {
       if (ctx.toolName !== "Bash") return allow();
       if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
         return instruct("Run tests before committing.");
       }
       return allow();
     },
   });
   
2. Commiter dans git

   git add .failproofai/policies/
   git commit -m "Add team quality policies"
   
3. Continuer à améliorer

   Au fil des nouveaux problèmes rencontrés par votre équipe, ajoutez des politiques et poussez-les. Tout le monde reçoit la mise à jour au prochain git pull. Ces politiques deviennent un standard qualité vivant qui évolue avec votre équipe.

---

​

Plus d’exemples

Le répertoire examples/ du dépôt contient :

Fichier	Ce qu’il illustre
policies-basic.js	Politiques de base — blocage des écritures en production, des force-push et des scripts piped
policies-notification.js	Alertes Slack pour les notifications d’inactivité et la fin de session
policies-advanced/index.js	Imports transitifs, hooks asynchrones, nettoyage de la sortie PostToolUse, gestion de l’événement Stop