Politiques personnalisées

Les politiques personnalisées vous permettent d’écrire des règles pour n’importe quel comportement d’agent : appliquer des conventions de projet, prévenir la dérive, bloquer les opérations destructives, détecter les agents bloqués, ou s’intégrer avec Slack, des workflows d’approbation, et plus encore. Elles utilisent le même système d’événements de hook et les mêmes décisions allow, deny, instruct que les politiques intégrées.

Exemple rapide

// my-policies.js
import { customPolicies, allow, deny, instruct } from "failproofai";

customPolicies.add({
  name: "no-production-writes",
  description: "Block writes to paths containing 'production'",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
    const path = ctx.toolInput?.file_path ?? "";
    if (path.includes("production")) {
      return deny("Writes to production paths are blocked");
    }
    return allow();
  },
});

Installation :

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

Deux façons de charger des politiques personnalisées

Option 1 : Par convention (recommandée)

Déposez des fichiers *policies.{js,mjs,ts} dans .failproofai/policies/ et ils sont chargés automatiquement — aucun indicateur ni modification de configuration nécessaire. Cela fonctionne comme les hooks git : déposez un fichier, ça marche tout de suite.

# Niveau projet — commité dans git, partagé avec l'équipe
.failproofai/policies/security-policies.mjs
.failproofai/policies/workflow-policies.mjs

# Niveau utilisateur — personnel, s'applique à tous les projets
~/.failproofai/policies/my-policies.mjs

Fonctionnement :

Les répertoires du projet et de l’utilisateur sont tous les deux analysés (union — pas de premier-scope-wins)
Les fichiers sont chargés par ordre alphabétique dans chaque répertoire. Préfixez avec 01-, 02- pour contrôler l’ordre
Seuls les fichiers correspondant à *policies.{js,mjs,ts} sont chargés ; les autres fichiers sont ignorés
Chaque fichier est chargé indépendamment (fail-open par fichier)
Fonctionne en parallèle avec les fichiers --custom explicites et les politiques intégrées

Les politiques de convention sont le moyen le plus simple d’établir un standard de qualité pour votre organisation. Commitez .failproofai/policies/ dans git et chaque membre de l’équipe reçoit automatiquement les mêmes règles — aucune configuration individuelle nécessaire. Au fur et à mesure que votre équipe découvre de nouveaux modes d’échec, ajoutez une politique et poussez-la. Ces politiques deviennent avec le temps un standard de qualité vivant qui s’améliore à chaque contribution.

Option 2 : Chemin de fichier explicite

# Installer avec un fichier de politiques personnalisées
failproofai policies --install --custom ./my-policies.js

# Remplacer le chemin du fichier de politiques
failproofai policies --install --custom ./new-policies.js

# Supprimer le chemin des politiques personnalisées de la configuration
failproofai policies --uninstall --custom

Le chemin absolu résolu est stocké dans policies-config.json sous la clé customPoliciesPath. Le fichier est rechargé à chaque événement de hook - il n’y a pas de mise en cache entre les événements.

Utiliser les deux ensemble

Les politiques de convention et le fichier --custom explicite peuvent coexister. Ordre de chargement :

Fichier customPoliciesPath explicite (si configuré)
Fichiers de convention du projet ({cwd}/.failproofai/policies/, alphabétique)
Fichiers de convention de l’utilisateur (~/.failproofai/policies/, alphabétique)

API

Import

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

`customPolicies.add(hook)`

Enregistre une politique. Appelez cette fonction autant de fois que nécessaire pour plusieurs politiques dans le même fichier.

customPolicies.add({
  name: string;                         // requis - identifiant unique
  description?: string;                 // affiché dans la sortie de `failproofai policies`
  match?: { events?: HookEventType[] }; // filtre par type d'événement ; omis pour correspondre à tous
  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
});

Fonctions d’aide aux décisions

Fonction	Effet	Utiliser quand
`allow()`	Autorise l’opération silencieusement	L’action est sûre, aucun message nécessaire
`deny(message)`	Bloque l’opération	L’agent ne doit pas effectuer cette action
`instruct(message)`	Ajoute du contexte sans bloquer	Fournir à l’agent un contexte supplémentaire pour rester sur la bonne voie

deny(message) - le message apparaît à Claude préfixé par "Blocked by failproofai:". Un seul deny court-circuite toute évaluation ultérieure. instruct(message) - le message est ajouté au contexte de Claude pour l’appel d’outil en cours. Tous les messages instruct sont accumulés et délivrés ensemble.

Vous pouvez ajouter des instructions supplémentaires à n’importe quel message deny ou instruct en ajoutant un champ hint dans policyParams — aucune modification de code nécessaire. Cela fonctionne également pour les politiques personnalisées (custom/), les politiques de convention de projet (.failproofai-project/) et les politiques de convention utilisateur (.failproofai-user/). Voir Configuration → hint pour plus de détails.

Messages allow informationnels

allow(message) autorise l’opération et envoie un message informationnel à Claude. Le message est délivré sous forme d’additionalContext dans la réponse stdout du gestionnaire de hook — le même mécanisme utilisé par instruct, mais sémantiquement différent : c’est une mise à jour de statut, pas un avertissement.

Fonction	Effet	Utiliser quand
`allow(message)`	Autorise et envoie du contexte à Claude	Confirmer qu’une vérification a réussi, ou expliquer pourquoi une vérification a été ignorée

Cas d’usage :

Confirmations de statut : allow("All CI checks passed.") — indique à Claude que tout est en ordre
Explications fail-open : allow("GitHub CLI not installed, skipping CI check.") — indique à Claude pourquoi une vérification a été ignorée pour qu’il dispose du contexte complet
Accumulation de plusieurs messages : si plusieurs politiques retournent chacune allow(message), tous les messages sont joints avec des sauts de ligne et délivrés ensemble

customPolicies.add({
  name: "confirm-branch-status",
  match: { events: ["Stop"] },
  fn: async (ctx) => {
    const cwd = ctx.session?.cwd;
    if (!cwd) return allow("No working directory, skipping branch check.");

    // ... check branch status ...
    if (allPushed) {
      return allow("Branch is up to date with remote.");
    }
    return deny("Unpushed changes detected.");
  },
});

Champs de `PolicyContext`

Champ	Type	Description
`eventType`	`string`	`"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"`
`toolName`	`string \| undefined`	L’outil appelé (ex. `"Bash"`, `"Write"`, `"Read"`)
`toolInput`	`Record<string, unknown> \| undefined`	Les paramètres d’entrée de l’outil
`payload`	`Record<string, unknown>`	Charge utile brute complète de l’événement provenant de Claude Code
`session`	`SessionMetadata \| undefined`	Contexte de session (voir ci-dessous)

Champs de `SessionMetadata`

Champ	Type	Description
`sessionId`	`string`	Identifiant de session Claude Code
`cwd`	`string`	Répertoire de travail de la session Claude Code
`transcriptPath`	`string`	Chemin vers le fichier de transcription JSONL de la session

Types d’événements

Événement	Quand il se déclenche	Contenu de `toolInput`
`PreToolUse`	Avant que Claude exécute un outil	L’entrée de l’outil (ex. `{ command: "..." }` pour Bash)
`PostToolUse`	Après la complétion d’un outil	L’entrée de l’outil + `tool_result` (la sortie)
`Notification`	Quand Claude envoie une notification	`{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - les hooks doivent toujours retourner `allow()`, ils ne peuvent pas bloquer les notifications
`Stop`	Quand la session Claude se termine	Vide

Ordre d’évaluation

Les politiques sont évaluées dans cet ordre :

Politiques intégrées (dans l’ordre de définition)
Politiques personnalisées explicites depuis customPoliciesPath (dans l’ordre des .add())
Politiques de convention du projet .failproofai/policies/ (fichiers alphabétiques, ordre des .add() à l’intérieur)
Politiques de convention de l’utilisateur ~/.failproofai/policies/ (fichiers alphabétiques, ordre des .add() à l’intérieur)

Le premier deny court-circuite toutes les politiques suivantes. Tous les messages instruct sont accumulés et délivrés ensemble.

Imports transitifs

Les fichiers de politiques personnalisées peuvent importer des modules locaux en utilisant des chemins relatifs :

// my-policies.js
import { isBlockedPath } from "./utils.js";
import { checkApproval } from "./approval-client.js";

customPolicies.add({
  name: "approval-gate",
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
    return approved ? allow() : deny("Approval required for this command");
  },
});

Tous les imports relatifs accessibles depuis le fichier d’entrée sont résolus. Ceci est implémenté en réécrivant les imports from "failproofai" vers le chemin dist réel et en créant des fichiers .mjs temporaires pour assurer la compatibilité ESM.

Filtrage par type d’événement

Utilisez match.events pour limiter le déclenchement d’une politique :

customPolicies.add({
  name: "require-summary-on-stop",
  match: { events: ["Stop"] },
  fn: async (ctx) => {
    // Se déclenche uniquement à la fin de la session
    // ctx.session.transcriptPath contient le journal complet de la session
    return allow();
  },
});

Omettez entièrement match pour se déclencher à chaque type d’événement.

Gestion des erreurs et modes de défaillance

Les politiques personnalisées sont fail-open : les erreurs ne bloquent jamais les politiques intégrées ni ne font planter le gestionnaire de hook.

Défaillance	Comportement
`customPoliciesPath` non défini	Aucune politique personnalisée explicite ne s’exécute ; les politiques de convention et les politiques intégrées continuent normalement
Fichier introuvable	Avertissement enregistré dans `~/.failproofai/hook.log` ; les politiques intégrées continuent
Erreur de syntaxe/import (explicite)	Erreur enregistrée dans `~/.failproofai/hook.log` ; les politiques personnalisées explicites ignorées
Erreur de syntaxe/import (convention)	Erreur enregistrée ; ce fichier ignoré, les autres fichiers de convention se chargent quand même
`fn` lève une exception à l’exécution	Erreur enregistrée ; ce hook traité comme `allow` ; les autres hooks continuent
`fn` prend plus de 10s	Timeout enregistré ; traité comme `allow`
Répertoire de convention manquant	Aucune politique de convention ne s’exécute ; aucune erreur

Pour déboguer les erreurs de politiques personnalisées, surveillez le fichier de log :

tail -f ~/.failproofai/hook.log

Exemple complet : plusieurs politiques

// my-policies.js
import { customPolicies, allow, deny, instruct } from "failproofai";

// Empêcher l'agent d'écrire dans le répertoire secrets/
customPolicies.add({
  name: "block-secrets-dir",
  description: "Prevent agent from writing to secrets/ directory",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
    const path = ctx.toolInput?.file_path ?? "";
    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
    return allow();
  },
});

// Maintenir l'agent sur la bonne voie : vérifier les tests avant de commiter
customPolicies.add({
  name: "remind-test-before-commit",
  description: "Keep the agent on track: verify tests pass before committing",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = ctx.toolInput?.command ?? "";
    if (/git\s+commit/.test(cmd)) {
      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
    }
    return allow();
  },
});

// Prévenir les changements de dépendances non planifiés pendant le gel
customPolicies.add({
  name: "dependency-freeze",
  description: "Prevent unplanned dependency changes during freeze period",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = ctx.toolInput?.command ?? "";
    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
    }
    return allow();
  },
});

export { customPolicies };

Exemples

Le répertoire examples/ contient des fichiers de politiques prêts à l’emploi :

Fichier	Contenu
`examples/policies-basic.js`	Cinq politiques de démarrage couvrant les modes d’échec courants des agents
`examples/policies-advanced/index.js`	Modèles avancés : imports transitifs, appels asynchrones, épuration des sorties et hooks de fin de session
`examples/convention-policies/security-policies.mjs`	Politiques de sécurité basées sur la convention (bloquer les écritures .env, empêcher la réécriture de l’historique git)
`examples/convention-policies/workflow-policies.mjs`	Politiques de workflow basées sur la convention (rappels de tests, audit des écritures de fichiers)

Utiliser les exemples de fichiers explicites

failproofai policies --install --custom ./examples/policies-basic.js

Utiliser les exemples basés sur la convention

# Copier au niveau du projet
mkdir -p .failproofai/policies
cp examples/convention-policies/*.mjs .failproofai/policies/

# Ou copier au niveau utilisateur
mkdir -p ~/.failproofai/policies
cp examples/convention-policies/*.mjs ~/.failproofai/policies/

Aucune commande d’installation nécessaire — les fichiers sont récupérés automatiquement lors du prochain événement de hook.

Démarrage

Concepts clés

CLI

Outils

Avancé

Exemples

Politiques personnalisées

Exemple rapide

Deux façons de charger des politiques personnalisées

Option 1 : Par convention (recommandée)

Option 2 : Chemin de fichier explicite

Utiliser les deux ensemble

API

Import

`customPolicies.add(hook)`

Fonctions d’aide aux décisions

Messages allow informationnels

Champs de `PolicyContext`

Champs de `SessionMetadata`

Types d’événements

Ordre d’évaluation

Imports transitifs

Filtrage par type d’événement

Gestion des erreurs et modes de défaillance

Exemple complet : plusieurs politiques

Exemples

Utiliser les exemples de fichiers explicites

Utiliser les exemples basés sur la convention

​Exemple rapide

​Deux façons de charger des politiques personnalisées

​Option 1 : Par convention (recommandée)

​Option 2 : Chemin de fichier explicite

​Utiliser les deux ensemble

​API

​Import

​customPolicies.add(hook)

​Fonctions d’aide aux décisions

​Messages allow informationnels

​Champs de PolicyContext

​Champs de SessionMetadata

​Types d’événements

​Ordre d’évaluation

​Imports transitifs

​Filtrage par type d’événement

​Gestion des erreurs et modes de défaillance

​Exemple complet : plusieurs politiques

​Exemples

​Utiliser les exemples de fichiers explicites

​Utiliser les exemples basés sur la convention

Exemple rapide

Deux façons de charger des politiques personnalisées

Option 1 : Par convention (recommandée)

Option 2 : Chemin de fichier explicite

Utiliser les deux ensemble

API

Import

`customPolicies.add(hook)`

Fonctions d’aide aux décisions

Messages allow informationnels

Champs de `PolicyContext`

Champs de `SessionMetadata`

Types d’événements

Ordre d’évaluation

Imports transitifs

Filtrage par type d’événement

Gestion des erreurs et modes de défaillance

Exemple complet : plusieurs politiques

Exemples

Utiliser les exemples de fichiers explicites

Utiliser les exemples basés sur la convention