Benutzerdefinierte Richtlinien

Benutzerdefinierte Richtlinien verwandeln ein Fehlermuster aus Ihren Traces oder Audits in eine Entscheidung, die während der Arbeit eines Agenten ausgeführt wird. Eine Richtlinie kann eine Aktion erlauben, dem Agenten Hinweise geben oder die Aktion blockieren, bevor sie einen weiteren Vorfall verursacht. Verwenden Sie eine benutzerdefinierte Richtlinie, wenn das Verhalten von Ihren Tools, Pfaden, Befehlen, Umgebungen oder Betriebsregeln abhängt. Prüfen Sie zunächst das Failproof AI Policy-Paket, damit Sie keine vorhandene Kontrolle neu erstellen.

Benutzerdefinierte Richtlinie erstellen

Dashboard
CLI

Gehen Sie zu Admin → Policy-Editor, wählen Sie Neue Richtlinie und beschreiben Sie den Fehler, den Sie verhindern möchten.
Fügen Sie den Richtlinienquellcode hinzu und testen Sie im Editor erwartete Treffer sowie sichere Nicht-Treffer. Beheben Sie jeden Validierungsfehler.
Speichern Sie den Entwurf und wählen Sie Version veröffentlichen, um eine unveränderliche Version zu erstellen.
Gehen Sie zu Admin → Durchsetzung, stellen Sie die Version auf einem Testrechner im Beobachtungs-Modus bereit, und überprüfen Sie die Entscheidungen unter Beobachten → Richtlinie, bevor Sie sie durchsetzen.

Erstellen Sie .failproofai/policies/checkout-policies.ts. Der Dateiname muss auf policies.js, policies.mjs oder policies.ts enden.
Registrieren Sie eine oder mehrere Richtlinien mit customPolicies.add().
Validieren und installieren Sie die Datei mit failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project.
Lösen Sie eine passende Aktion und eine sichere Aktion aus. Führen Sie failproofai policies aus und prüfen Sie die zugeordneten Entscheidungen unter Beobachten → Richtlinie.

Mit einer engen Regel beginnen

Diese Richtlinie blockiert destruktive Kubernetes-Befehle nur dann, wenn der Befehl auf die Produktionsumgebung abzielt. Alles außerhalb dieses genauen Fehlermusters gibt allow() zurück.

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.",
    );
  },
});

Gute Richtlinien sind eng genug, um sie in einem Satz zu erklären. Treffen Sie die beobachtbare Aktion – nicht die Absicht, die Sie dem Agenten zuschreiben – und geben Sie allow() zurück, sobald die Regel nicht zutrifft.

Eine Entscheidung auswählen

Hilfsfunktion	Ergebnis	Verwenden, wenn
`allow(reason?)`	Die Operation wird fortgesetzt.	Die Richtlinie gilt nicht oder die Aktion ist sicher.
`instruct(reason)`	Die Operation wird mit Hinweisen fortgesetzt, sofern der Harness dies unterstützt.	Sie den Agenten zu einem besseren Vorgehen lenken möchten, ohne eine Invariante zu erzwingen.
`deny(reason)`	Die Operation wird blockiert, wenn Ereignis und Harness das Blockieren unterstützen.	Die Aktion darf nicht fortgesetzt werden.

Schreiben Sie die Begründung für den Agenten, der sich erholen muss. Erklären Sie, was erkannt wurde und was stattdessen getan werden sollte.

Verwenden Sie instruct() nicht für eine Sicherheitsgrenze. Die Zustellung von Hinweisen variiert je nach Agent-Harness. Verwenden Sie deny(), wenn die Aktion verhindert werden muss.

Policy-Objekt

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

Feld	Erforderlich	Beschreibung
`name`	Ja	Stabiler Bezeichner für die Richtlinie. Namen über Dateien hinweg eindeutig halten.
`description`	Nein	Menschenlesbare Beschreibung, die in Richtlinienübersichten und Entscheidungen angezeigt wird.
`match.events`	Nein	Ereignistypen, die die Richtlinie aufrufen. Wenn `match` weggelassen wird, wird sie für jedes verfügbare Ereignis aufgerufen.
`fn`	Ja	Synchrone oder asynchrone Funktion, die ein `allow`-, `instruct`- oder `deny`-Ergebnis zurückgibt.

Tools innerhalb von fn filtern. match.toolNames ist nicht Teil des öffentlichen benutzerdefinierten Richtlinientyps.

Richtlinienkontext

Jede Richtlinie empfängt einen PolicyContext.

Feld	Typ	Inhalt
`eventType`	`HookEventType`	Normalisiertes Ereignis, das aktuell ausgewertet wird.
`toolName`	`string \| undefined`	Kanonischer Tool-Name wie `Bash`, `Read`, `Write` oder `Edit`.
`toolInput`	`Record<string, unknown> \| undefined`	Kanonische Eingabe für den aktuellen Tool-Aufruf.
`payload`	`Record<string, unknown>`	Vollständige normalisierte Ereignis-Nutzlast.
`session`	`SessionMetadata \| undefined`	Sitzungs-ID, Arbeitsverzeichnis, Transcript-Pfad, Berechtigungsmodus und Harness-Metadaten, sofern verfügbar.
`cli`	`string \| undefined`	Quell-Agent-Harness, z. B. `claude`, `codex` oder `cursor`.
`params`	`Record<string, unknown>`	Eingebaute Richtlinienparameter. Benutzerdefinierte Richtlinien erhalten aktuell ein leeres Objekt.

Jeden optionalen Wert als tatsächlich optional behandeln. Agent-Versionen und Ereignistypen stellen nicht alle dieselben Felder bereit.

Häufige Tool-Eingaben

Failproof AI normalisiert gängige Tools über unterstützte Harnesses hinweg, sodass eine Richtlinie in der Regel eine einheitliche Eingabeform verwenden kann.

Tool	Häufige Felder
`Bash`	`command`
`Read`	`file_path`
`Write`	`file_path`, `content`
`Edit`	`file_path`, `old_string`, `new_string`
`Grep`	`pattern`, `path`

Defensive Typumwandlung verwenden, da Tool-Eingabewerte als unknown typisiert sind:

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

Ereignis auswählen

Ereignis	Zeitpunkt	Typische Verwendung
`PreToolUse`	Vor der Ausführung eines Tools.	Befehle, Schreibvorgänge, Lesevorgänge und externe Aktionen blockieren oder steuern.
`PostToolUse`	Nachdem ein Tool zurückgekehrt ist.	Ergebnisse prüfen, bevor sie den Agenten erreichen. Ein Deny blockiert das gesamte Ergebnis; es schwärzt keine einzelnen Felder.
`PermissionRequest`	Wenn der Agent eine Berechtigung anfordert.	Organisationsspezifische Berechtigungsregeln anwenden.
`UserPromptSubmit`	Bevor ein eingereichter Prompt fortgesetzt wird.	Verbotene Anweisungen ablehnen oder Workflow-Hinweise hinzufügen.
`Stop`	Wenn der Agent versucht, abzuschließen.	Eine erreichbare Abschlussbedingung erfordern, z. B. einen lokalen Verifizierungsschritt.
`SubagentStop`	Wenn ein Subagent versucht, abzuschließen.	Delegierte Arbeit prüfen, bevor sie an den übergeordneten Agenten zurückgegeben wird.
`SessionStart` / `SessionEnd`	An Sitzungsgrenzen.	Sitzungsweiten Zustand aufzeichnen oder prüfen.

Die Verfügbarkeit von Ereignissen und das Blockierverhalten hängen vom Agent-Harness ab. Lesen Sie Agent-Harnesses, bevor Sie sich auf ein Ereignis über eine gemischte Flotte hinweg verlassen.

Alle Richtlinienereignisnamen

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 und Setup.

Häufige Richtlinienmuster erstellen

Schreibvorgänge auf geschützte Pfade blockieren

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.");
  },
});

Nicht-blockierende Hinweise geben

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.");
  },
});

Sitzungsabschluss prüfen

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.");
    }
  },
});

Ein abgelehntes Stop-Ereignis kann dazu führen, dass der Agent es erneut versucht. Prüfen Sie nur eine Bedingung, die der Agent in der aktuellen Umgebung erfüllen kann, und begrenzen Sie jeden Unterprozess oder Netzwerkaufruf.

Richtliniendateien laden

Konventionsdateien

Konventionsdateien werden automatisch geladen:

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

Projekt- und Benutzer-Richtlinienverzeichnisse werden beide geladen.
Dateien werden alphabetisch innerhalb jedes Verzeichnisses geladen.
Eine Datei muss auf policies.js, policies.mjs oder policies.ts enden.
Mehrere customPolicies.add()-Aufrufe in einer Datei werden unterstützt.
Relative Importe aus lokalen Modulen werden unterstützt.
Projektrichtlinien können eingecheckt werden, sodass dieselben Regeln dem Repository folgen.

Explizite Dateien

Verwenden Sie explizite Pfade, wenn Validierung oder Konfiguration die Einstiegsdatei direkt benennen soll:

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

Explizite Dateien werden zuerst geladen, gefolgt von Projekt-Konventionsdateien und dann Benutzer-Konventionsdateien. Eine Datei, die über beide Pfade gefunden wird, wird nur einmal geladen.

Validieren und testen

Die Validierung führt das Modul durch den Produktionslader aus und bestätigt, dass es mindestens eine Richtlinie registriert.

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

Die Validierung erkennt fehlende Dateien, Syntaxfehler, ungelöste Importe, Top-Level-Ausnahmen und Modul-Lade-Timeouts. Sie beweist nicht, dass Ihre Match-Logik korrekt ist. Testen Sie mindestens diese Fälle:

Eine Aktion, die treffen muss und den vorgesehenen Richtliniengrund erzeugt.
Eine ähnliche, aber sichere Aktion, die allow() zurückgeben muss.
Fehlende oder fehlerhafte Tool-Felder.
Alternative Befehlssyntax, Pfade, Anführungszeichen, Groß-/Kleinschreibung und Leerzeichen.
Ein nicht verfügbarer Unterprozess oder eine Netzwerkabhängigkeit.

Ordnen Sie das Ergebnis unter Beobachten → Richtlinie Ihrer benutzerdefinierten Richtlinie zu. Ein blockierter Test reicht nicht aus, wenn eine andere eingebaute Richtlinie die Entscheidung getroffen hat.

Laufzeitverhalten

Eingebaute Richtlinien werden vor benutzerdefinierten Richtlinien ausgewertet.
Das erste deny stoppt die weitere Richtlinienauswertung.
Mehrere instruct-Ergebnisse können kombiniert werden, wenn keine Richtlinie das Ereignis ablehnt.
Eine Richtlinienfunktion hat eine Ausführungsfrist von 10 Sekunden.
Eine ausgelöste Ausnahme oder ein Timeout wird protokolliert und als allow() behandelt.
Eine Konventionsdatei, die nicht geladen werden kann, wird übersprungen; andere benutzerdefinierte Dateien und eingebaute Richtlinien werden weiter ausgeführt.
Das Top-Level-Modulladen hat ebenfalls eine Frist von 10 Sekunden.
Der Cloud-Beobachtungsmodus führt die Richtlinie aus, zeichnet aber eine Nicht-allow-Entscheidung auf, ohne sie durchzusetzen.

Richtlinienmodule deterministisch und schnell halten. Top-Level-Netzwerkaufrufe oder Server-Starts vermeiden. Arbeit innerhalb von fn begrenzen, Abhängigkeitsfehler abfangen und bewusst entscheiden, ob dieser Fehler die Operation erlauben oder blockieren soll.

API-Exporte

Export	Zweck
`customPolicies.add(policy)`	Benutzerdefinierte Richtlinie beim Laden des Moduls registrieren.
`allow(reason?)`	Operation erlauben.
`instruct(reason)`	Operation erlauben und Hinweise bereitstellen, sofern unterstützt.
`deny(reason)`	Operation blockieren, sofern unterstützt.
`getCustomHooks()`	Die aktuell im Modulregister registrierten Richtlinien zurückgeben.
`clearCustomHooks()`	Dieses Register leeren, hauptsächlich für Tests und Lader.

TypeScript exportiert PolicyContext, PolicyResult, CustomHook, PolicyDecision und PolicyFunction.