Politiques personnalisées

Les politiques personnalisées transforment un schéma de défaillance issu de vos traces ou audits en une décision qui s’exécute pendant qu’un agent travaille. Une politique peut autoriser une action, fournir des instructions à l’agent, ou bloquer l’action avant qu’elle ne provoque un nouvel incident. Utilisez une politique personnalisée lorsque le comportement dépend de vos outils, chemins, commandes, environnements ou règles de fonctionnement. Consultez d’abord le catalogue de politiques intégrées pour ne pas recréer un contrôle existant.

Créer une politique personnalisée

Tableau de bord
CLI

Accédez à Admin → éditeur de politiques, sélectionnez Nouvelle politique et décrivez la défaillance que vous souhaitez prévenir.
Ajoutez le code source de la politique, puis testez les correspondances attendues et les non-correspondances sûres dans l’éditeur. Résolvez toutes les erreurs de validation.
Enregistrez le brouillon et sélectionnez Publier la version pour créer une version immuable.
Accédez à Admin → application, déployez la version sur une machine de test en mode observe, puis vérifiez ses décisions sous Observe → politique avant de l’appliquer.

Créez .failproofai/policies/checkout-policies.ts. Le nom de fichier doit se terminer par policies.js, policies.mjs ou policies.ts.
Enregistrez une ou plusieurs politiques avec customPolicies.add().
Validez et installez le fichier avec failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project.
Déclenchez une action correspondante et une action sûre. Exécutez failproofai policies, puis inspectez les décisions attribuées sous Observe → politique.

Commencer par une règle ciblée

Cette politique bloque les commandes Kubernetes destructrices uniquement lorsque la commande cible la production. Tout ce qui se trouve en dehors de ce schéma de défaillance précis retourne allow().

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

const DESTRUCTIVE_KUBECTL = /\bkubectl\s+(delete|replace)\b/i;
const PRODUCTION_TARGET = /(?:--context|--namespace|-n)\s+(prod|production)\b/i;

customPolicies.add({
  name: "block-destructive-production-kubectl",
  description: "Block destructive Kubernetes commands against production",
  match: { events: ["PreToolUse"] },
  fn: async ({ toolName, toolInput }) => {
    if (toolName !== "Bash") return allow();

    const command = String(toolInput?.command ?? "");
    if (!DESTRUCTIVE_KUBECTL.test(command)) return allow();
    if (!PRODUCTION_TARGET.test(command)) return allow();

    return deny(
      "Destructive production Kubernetes commands require the approved deployment workflow.",
    );
  },
});

Les bonnes politiques sont suffisamment ciblées pour être expliquées en une seule phrase. Correspondez à l’action observable — pas à l’intention que vous espérez que l’agent avait — et retournez allow() dès que la règle ne s’applique pas.

Choisir une décision

Aide	Résultat	À utiliser quand
`allow(reason?)`	L’opération continue.	La politique ne s’applique pas ou l’action est sûre.
`instruct(reason)`	L’opération continue avec des instructions là où le harnais le permet.	Vous souhaitez orienter l’agent vers une meilleure approche sans appliquer une contrainte.
`deny(reason)`	L’opération est bloquée lorsque l’événement et le harnais prennent en charge le blocage.	L’action ne doit pas se poursuivre.

Rédigez la raison à l’intention de l’agent qui doit se rétablir. Expliquez ce qui a été détecté et ce qu’il devrait faire à la place.

N’utilisez pas instruct() pour une limite de sécurité. La remise des instructions varie selon le harnais d’agent. Utilisez deny() lorsque l’action doit être empêchée.

Objet politique

customPolicies.add({
  name: "policy-name",
  description: "What this policy prevents",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => allow(),
});

Champ	Obligatoire	Description
`name`	Oui	Identifiant stable de la politique. Conservez des noms uniques entre les fichiers.
`description`	Non	Objectif lisible par l’humain, affiché dans les listes de politiques et les décisions.
`match.events`	Non	Types d’événements qui invoquent la politique. Omettre `match` l’invoque pour chaque événement disponible.
`fn`	Oui	Fonction synchrone ou asynchrone qui retourne un résultat `allow`, `instruct` ou `deny`.

Filtrez les outils à l’intérieur de fn. match.toolNames ne fait pas partie du type public de politique personnalisée.

Contexte de la politique

Chaque politique reçoit un PolicyContext.

Champ	Type	Ce qu’il contient
`eventType`	`HookEventType`	Événement normalisé en cours d’évaluation.
`toolName`	`string \| undefined`	Nom canonique de l’outil, par exemple `Bash`, `Read`, `Write` ou `Edit`.
`toolInput`	`Record<string, unknown> \| undefined`	Entrée canonique pour l’appel d’outil actuel.
`payload`	`Record<string, unknown>`	Charge utile complète de l’événement normalisé.
`session`	`SessionMetadata \| undefined`	ID de session, répertoire de travail, chemin du transcript, mode de permission et métadonnées du harnais lorsque disponibles.
`cli`	`string \| undefined`	Harnais d’agent source, tel que `claude`, `codex` ou `cursor`.
`params`	`Record<string, unknown>`	Paramètres de politique intégrés. Les politiques personnalisées reçoivent actuellement un objet vide.

Traitez chaque valeur optionnelle comme réellement optionnelle. Les versions d’agents et les types d’événements ne fournissent pas tous les mêmes champs.

Entrées d’outils courantes

Failproof AI normalise les outils courants à travers les harnais pris en charge, de sorte qu’une politique peut généralement utiliser une seule forme d’entrée.

Outil	Champs courants
`Bash`	`command`
`Read`	`file_path`
`Write`	`file_path`, `content`
`Edit`	`file_path`, `old_string`, `new_string`
`Grep`	`pattern`, `path`

Utilisez une coercition défensive car les valeurs d’entrée des outils sont typées comme unknown :

const command = String(ctx.toolInput?.command ?? "");
const filePath = String(ctx.toolInput?.file_path ?? "");

Choisir l’événement

Événement	Quand il s’exécute	Utilisation typique
`PreToolUse`	Avant l’exécution d’un outil.	Bloquer ou orienter les commandes, écritures, lectures et actions externes.
`PostToolUse`	Après le retour d’un outil.	Inspecter les résultats avant qu’ils n’atteignent l’agent. Un deny bloque l’intégralité du résultat ; il ne rédacte pas les champs sélectionnés.
`PermissionRequest`	Lorsque l’agent demande une permission.	Appliquer des règles de permission propres à l’organisation.
`UserPromptSubmit`	Avant qu’une invite soumise ne continue.	Rejeter les instructions interdites ou ajouter des instructions de flux de travail.
`Stop`	Lorsque l’agent tente de terminer.	Exiger une condition d’achèvement atteignable, comme une étape de vérification locale.
`SubagentStop`	Lorsqu’un sous-agent tente de terminer.	Contrôler le travail délégué avant qu’il ne retourne au parent.
`SessionStart` / `SessionEnd`	Aux limites de session.	Enregistrer ou vérifier l’état au niveau de la session.

La disponibilité des événements et le comportement de blocage dépendent du harnais d’agent. Consultez Harnais d’agents avant de vous appuyer sur un événement dans une flotte mixte.

Tous les noms d'événements de politique

SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure, Notification, SubagentStart, SubagentStop, TaskCreated, TaskCompleted, Stop, StopFailure, TeammateIdle, InstructionsLoaded, ConfigChange, CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove, PreCompact, PostCompact, Elicitation, ElicitationResult, UserPromptExpansion, PostToolBatch et Setup.

Créer des schémas de politiques courants

Bloquer les écritures vers des chemins protégés

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

customPolicies.add({
  name: "block-generated-file-edits",
  description: "Require generated files to be changed through their generator",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();

    const filePath = String(ctx.toolInput?.file_path ?? "");
    if (!/(^|\/)(dist|generated)\//.test(filePath)) return allow();

    return deny("Edit the source and run the generator instead of changing generated output.");
  },
});

Fournir des instructions non bloquantes

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

customPolicies.add({
  name: "prefer-reviewed-deploy-command",
  description: "Guide agents toward the reviewed deployment wrapper",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();

    const command = String(ctx.toolInput?.command ?? "");
    if (!/^kubectl\s+apply\b/.test(command.trim())) return allow();

    return instruct("Use ./scripts/deploy-reviewed instead of invoking kubectl directly.");
  },
});

Contrôler l’achèvement de session

import { execFileSync } from "node:child_process";
import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "require-clean-typecheck",
  description: "Require the project typecheck to pass before the agent finishes",
  match: { events: ["Stop"] },
  fn: async (ctx) => {
    const cwd = ctx.session?.cwd;
    if (!cwd) return allow();

    try {
      execFileSync("bunx", ["tsc", "--noEmit"], {
        cwd,
        stdio: "ignore",
        timeout: 8_000,
      });
      return allow();
    } catch {
      return deny("Fix the typecheck errors before finishing the task.");
    }
  },
});

Un événement Stop refusé peut amener l’agent à réessayer. Ne conditionnez l’achèvement qu’à une condition que l’agent peut satisfaire dans l’environnement actuel, et limitez chaque sous-processus ou appel réseau.

Charger des fichiers de politiques

Fichiers de convention

Les fichiers de convention se chargent automatiquement :

<project>/.failproofai/policies/security-policies.ts
~/.failproofai/policies/personal-policies.mjs

Les répertoires de politiques du projet et de l’utilisateur sont tous deux chargés.
Les fichiers se chargent par ordre alphabétique dans chaque répertoire.
Un fichier doit se terminer par policies.js, policies.mjs ou policies.ts.
Plusieurs appels customPolicies.add() dans un seul fichier sont pris en charge.
Les imports relatifs depuis des modules locaux sont pris en charge.
Les politiques de projet peuvent être committées afin que les mêmes règles suivent le dépôt.

Fichiers explicites

Utilisez des chemins explicites lorsque la validation ou la configuration doit nommer directement le fichier d’entrée :

failproofai policies --install \
  --custom ./security.policies.ts \
  --custom ./workflow.policies.ts \
  --scope project

Les fichiers explicites se chargent en premier, suivis des fichiers de convention du projet puis des fichiers de convention utilisateur. Un fichier découvert par les deux chemins n’est chargé qu’une seule fois.

Valider et tester

La validation exécute le module via le chargeur de production et confirme qu’il enregistre au moins une politique.

failproofai policies --install \
  --custom ./.failproofai/policies/checkout-policies.ts \
  --scope project
failproofai policies

La validation détecte les fichiers manquants, les erreurs de syntaxe, les imports non résolus, les exceptions de niveau supérieur et les délais d’expiration de chargement de module. Elle ne prouve pas que votre logique de correspondance est correcte. Testez au minimum ces cas :

Une action qui doit correspondre et produire la raison de politique prévue.
Une action proche mais sûre qui doit retourner allow().
Des champs d’outil manquants ou malformés.
Une syntaxe de commande alternative, des chemins, des guillemets, des casses et des espaces blancs.
Un sous-processus ou une dépendance réseau non disponible.

Attribuez le résultat à votre politique personnalisée sous Observe → politique. Un test bloqué n’est pas suffisant si c’est une autre politique intégrée qui a pris la décision.

Comportement à l’exécution

Les politiques intégrées sont évaluées avant les politiques personnalisées.
Le premier deny arrête l’évaluation des politiques suivantes.
Plusieurs résultats instruct peuvent être combinés lorsqu’aucune politique ne refuse l’événement.
Une fonction de politique dispose d’un délai d’exécution de 10 secondes.
Une exception levée ou un délai d’expiration est journalisé et traité comme allow().
Un fichier de convention qui échoue au chargement est ignoré ; les autres fichiers personnalisés et les politiques intégrées continuent.
Le chargement de module de niveau supérieur dispose également d’un délai de 10 secondes.
Le mode observe cloud exécute la politique mais enregistre une décision non-allow sans l’appliquer.

Conservez les modules de politiques déterministes et rapides. Évitez les appels réseau de niveau supérieur ou le démarrage de serveur. Limitez le travail à l’intérieur de fn, gérez les échecs de dépendances, et choisissez délibérément si cet échec doit autoriser ou refuser l’opération.

Exports API

Export	Objectif
`customPolicies.add(policy)`	Enregistrer une politique personnalisée lors du chargement du module.
`allow(reason?)`	Autoriser l’opération.
`instruct(reason)`	Autoriser l’opération et fournir des instructions là où c’est pris en charge.
`deny(reason)`	Bloquer l’opération là où c’est pris en charge.
`getCustomHooks()`	Retourner les politiques actuellement enregistrées dans le registre de modules.
`clearCustomHooks()`	Effacer ce registre, principalement pour les tests et les chargeurs.

TypeScript exporte PolicyContext, PolicyResult, CustomHook, PolicyDecision et PolicyFunction.

Déployer des politiques personnalisées

Publiez une version, déployez-la en mode observe, vérifiez les décisions et passez à l’application.

Connect your agents

Reference

Politiques personnalisées

Créer une politique personnalisée

Commencer par une règle ciblée

Choisir une décision

Objet politique

Contexte de la politique

Entrées d’outils courantes

Choisir l’événement

Créer des schémas de politiques courants

Bloquer les écritures vers des chemins protégés

Fournir des instructions non bloquantes

Contrôler l’achèvement de session

Charger des fichiers de politiques

Fichiers de convention

Fichiers explicites

Valider et tester

Comportement à l’exécution

Exports API

Déployer des politiques personnalisées

​Créer une politique personnalisée

​Commencer par une règle ciblée

​Choisir une décision

​Objet politique

​Contexte de la politique

​Entrées d’outils courantes

​Choisir l’événement

​Créer des schémas de politiques courants

​Bloquer les écritures vers des chemins protégés

​Fournir des instructions non bloquantes

​Contrôler l’achèvement de session

​Charger des fichiers de politiques

​Fichiers de convention

​Fichiers explicites

​Valider et tester

​Comportement à l’exécution

​Exports API

Déployer des politiques personnalisées

Créer une politique personnalisée

Commencer par une règle ciblée

Choisir une décision

Objet politique

Contexte de la politique

Entrées d’outils courantes

Choisir l’événement

Créer des schémas de politiques courants

Bloquer les écritures vers des chemins protégés

Fournir des instructions non bloquantes

Contrôler l’achèvement de session

Charger des fichiers de politiques

Fichiers de convention

Fichiers explicites

Valider et tester

Comportement à l’exécution

Exports API