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 zuerst den Katalog der integrierten Richtlinien, um keine bereits vorhandene Kontrolle neu zu erstellen.

Eine benutzerdefinierte Richtlinie erstellen

Dashboard
CLI

Gehen Sie zu Admin → policy editor, wählen Sie New policy aus und beschreiben Sie den Fehler, den Sie verhindern möchten.
Fügen Sie den Richtlinienquellcode hinzu und testen Sie erwartete Treffer sowie unbedenkliche Nicht-Treffer im Editor. Beheben Sie alle Validierungsfehler.
Speichern Sie den Entwurf und wählen Sie Publish version, um eine unveränderliche Version zu erstellen.
Gehen Sie zu Admin → enforcement, deployen Sie die Version auf einem Testrechner im observe-Modus und überprüfen Sie die Entscheidungen unter Observe → policy, bevor Sie die Richtlinie 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 unbedenkliche Aktion aus. Führen Sie failproofai policies aus und prüfen Sie dann die zugeordneten Entscheidungen unter Observe → policy.

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 auf die beobachtbare Aktion – nicht auf die vermutete Absicht des Agenten – und geben Sie allow() zurück, sobald die Regel nicht zutrifft.

Eine Entscheidung wählen

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

Schreiben Sie den Grund für den Agenten, der sich erholen muss. Erläutern Sie, was erkannt wurde und was stattdessen getan werden soll.

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

Das 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 müssen dateiübergreifend eindeutig sein.
`description`	Nein	Lesbare Beschreibung des Zwecks, die in Richtlinienübersichten und Entscheidungen angezeigt wird.
`match.events`	Nein	Ereignistypen, die die Richtlinie aufrufen. Wird `match` weggelassen, wird sie für jedes verfügbare Ereignis aufgerufen.
`fn`	Ja	Synchrone oder asynchrone Funktion, die ein `allow`-, `instruct`- oder `deny`-Ergebnis zurückgibt.

Filtern Sie Tools innerhalb von fn. match.toolNames ist kein Teil des öffentlichen Typs für benutzerdefinierte Richtlinien.

Policy-Kontext

Jede Richtlinie erhält einen PolicyContext.

Feld	Typ	Inhalt
`eventType`	`HookEventType`	Normalisiertes Ereignis, das aktuell ausgewertet wird.
`toolName`	`string \| undefined`	Kanonischer Tool-Name, z. B. `Bash`, `Read`, `Write` oder `Edit`.
`toolInput`	`Record<string, unknown> \| undefined`	Kanonische Eingabe für den aktuellen Tool-Aufruf.
`payload`	`Record<string, unknown>`	Vollständiger normalisierter Ereignis-Payload.
`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>`	Parameter integrierter Richtlinien. Benutzerdefinierte Richtlinien erhalten derzeit ein leeres Objekt.

Behandeln Sie jeden optionalen Wert als tatsächlich optional. Nicht alle Agent-Versionen und Ereignistypen stellen 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`

Verwenden Sie defensive Typumwandlung, da Tool-Eingabewerte als unknown typisiert sind:

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

Das Ereignis wählen

Ereignis	Ausführungszeitpunkt	Typische Verwendung
`PreToolUse`	Vor der Ausführung eines Tools.	Befehle, Schreibzugriffe, Lesezugriffe 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; einzelne Felder werden nicht herausgefiltert.
`PermissionRequest`	Wenn der Agent eine Berechtigung anfordert.	Organisationsspezifische Berechtigungsregeln anwenden.
`UserPromptSubmit`	Bevor ein eingereichter Prompt fortgesetzt wird.	Unzulässige Anweisungen ablehnen oder Workflow-Hinweise hinzufügen.
`Stop`	Wenn der Agent versucht, die Arbeit abzuschließen.	Eine erreichbare Abschlussbedingung voraussetzen, z. B. einen lokalen Verifizierungsschritt.
`SubagentStop`	Wenn ein Subagent versucht, die Arbeit abzuschließen.	Delegierte Arbeit prüfen, bevor sie zum übergeordneten Agenten zurückkehrt.
`SessionStart` / `SessionEnd`	An Sitzungsgrenzen.	Zustand auf Sitzungsebene 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 bei einem gemischten Fleet auf ein Ereignis verlassen.

Alle Policy-Ereignisnamen

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

Schreibzugriffe 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 absichern

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. Sichern Sie nur Bedingungen ab, die der Agent in der aktuellen Umgebung erfüllen kann, und begrenzen Sie jeden Subprocess- 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 innerhalb jedes Verzeichnisses alphabetisch 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 die Validierung oder Konfiguration die Eingabedatei 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 über den Produktions-Loader aus und bestätigt, dass mindestens eine Richtlinie registriert wird.

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

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

Eine Aktion, die treffen muss und den beabsichtigten Richtliniengrund erzeugen soll.
Eine ähnliche, aber unbedenkliche Aktion, die allow() zurückgeben muss.
Fehlende oder fehlerhafte Tool-Felder.
Abweichende Befehlssyntax, Pfade, Anführungszeichen, Groß-/Kleinschreibung und Leerzeichen.
Ein nicht verfügbarer Subprocess oder eine nicht verfügbare Netzwerkabhängigkeit.

Ordnen Sie das Ergebnis Ihrer benutzerdefinierten Richtlinie unter Observe → policy zu. Ein blockierter Test ist nicht ausreichend, wenn eine andere integrierte Richtlinie die Entscheidung getroffen hat.

Laufzeitverhalten

Integrierte 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 integrierte Richtlinien werden weiterhin ausgeführt.
Das Laden von Modulen auf oberster Ebene hat ebenfalls eine Frist von 10 Sekunden.
Im Cloud-Observe-Modus wird die Richtlinie ausgeführt, aber eine Nicht-allow-Entscheidung wird aufgezeichnet, ohne sie durchzusetzen.

Halten Sie Richtlinienmodule deterministisch und schnell. Vermeiden Sie Netzwerkaufrufe oder Server-Starts auf oberster Ebene. Begrenzen Sie die Arbeit innerhalb von fn, fangen Sie Abhängigkeitsfehler ab und entscheiden Sie bewusst, ob ein solcher Fehler die Operation erlauben oder ablehnen soll.

API-Exporte

Export	Zweck
`customPolicies.add(policy)`	Eine benutzerdefinierte Richtlinie beim Laden des Moduls registrieren.
`allow(reason?)`	Die Operation erlauben.
`instruct(reason)`	Die Operation erlauben und Hinweise bereitstellen, sofern unterstützt.
`deny(reason)`	Die Operation blockieren, sofern unterstützt.
`getCustomHooks()`	Die aktuell im Modul-Registry registrierten Richtlinien zurückgeben.
`clearCustomHooks()`	Das Registry leeren, hauptsächlich für Tests und Loader.

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