Benutzerdefinierte Richtlinien

Benutzerdefinierte Richtlinien wandeln ein Fehlermuster aus Ihren Traces oder Audits in eine Entscheidung um, die während der Arbeit eines Agenten ausgeführt wird. Eine Richtlinie kann eine Aktion erlauben, dem Agenten Anleitung geben oder die Aktion blockieren, bevor sie zu einem weiteren Vorfall führt. Verwenden Sie eine benutzerdefinierte Richtlinie, wenn das Verhalten von Ihren Tools, Pfaden, Befehlen, Umgebungen oder Betriebsregeln abhängt. Prüfen Sie zunächst den integrierten Richtlinienkatalog, um keine bestehende Kontrolle neu zu erstellen.

Benutzerdefinierte Richtlinie erstellen

Dashboard
CLI

Gehen Sie zu Admin → Richtlinieneditor, wählen Sie Neue Richtlinie und beschreiben Sie den Fehler, den Sie verhindern möchten.
Fügen Sie den Richtliniencode hinzu und testen Sie erwartete Übereinstimmungen sowie sichere Nicht-Übereinstimmungen im Editor. Beheben Sie alle 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 Testgerät 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 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. Prüfen Sie die beobachtbare Aktion – nicht die vermutete Absicht des Agenten – und geben Sie allow() zurück, sobald die Regel nicht zutrifft.

Entscheidung wählen

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

Formulieren Sie den Grund für den Agenten, der sich erholen muss. Erklären Sie, was erkannt wurde und was stattdessen getan werden soll.

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

Richtlinienobjekt

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, die in Richtlinienübersichten und Entscheidungen angezeigt wird.
`match.events`	Nein	Ereignistypen, die die Richtlinie aufrufen. Ohne `match` 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 Bestandteil des öffentlichen Typs für benutzerdefinierte Richtlinien.

Richtlinienkontext

Jede Richtlinie erhält 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 Ereignisnutzlast.
`session`	`SessionMetadata \| undefined`	Sitzungs-ID, Arbeitsverzeichnis, Transcript-Pfad, Berechtigungsmodus und Umgebungsmetadaten, sofern verfügbar.
`cli`	`string \| undefined`	Quell-Agent-Umgebung, z. B. `claude`, `codex` oder `cursor`.
`params`	`Record<string, unknown>`	Parameter für integrierte Richtlinien. Benutzerdefinierte Richtlinien erhalten derzeit ein leeres Objekt.

Behandeln Sie jeden optionalen Wert als tatsächlich optional. Nicht alle Agent-Versionen und Ereignistypen liefern dieselben Felder.

Häufige Tool-Eingaben

Failproof AI normalisiert gängige Tools über unterstützte Umgebungen 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 ?? "");

Ereignis wä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; einzelne Felder werden nicht geschwärzt.
`PermissionRequest`	Wenn der Agent eine Berechtigung anfordert.	Organisationsspezifische Berechtigungsregeln anwenden.
`UserPromptSubmit`	Bevor ein gesendeter Prompt fortgesetzt wird.	Verbotene Anweisungen ablehnen oder Workflow-Anleitungen hinzufügen.
`Stop`	Wenn der Agent versucht, abzuschließen.	Eine erreichbare Abschlussbedingung erfordern, z. B. einen lokalen Verifikationsschritt.
`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.

Ereignisverfügbarkeit und Blockierungsverhalten hängen von der Agent-Umgebung ab. Lesen Sie Agent-Umgebungen, 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 Anleitung 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 kontrollieren

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. Stellen Sie die Bedingung nur dann auf, wenn der Agent sie in der aktuellen Umgebung erfüllen kann, und begrenzen Sie jeden Subprozess oder Netzwerkaufruf.

Richtliniendateien laden

Konventionsdateien

Konventionsdateien werden automatisch geladen:

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

Projekt- und Benutzerrichtlinienverzeichnisse 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 sollen:

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 es mindestens eine Richtlinie registriert.

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 nicht, dass Ihre Match-Logik korrekt ist. Testen Sie mindestens diese Fälle:

Eine Aktion, die übereinstimmen und den beabsichtigten Richtliniengrund erzeugen muss.
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 Subprozess oder eine Netzwerkabhängigkeit.

Ordnen Sie das Ergebnis Ihrer benutzerdefinierten Richtlinie unter Beobachten → Richtlinie zu. Ein blockierter Test reicht nicht aus, 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 weiter ausgeführt.
Das Laden von Modulen auf oberster Ebene hat ebenfalls eine Frist von 10 Sekunden.
Der Cloud-Beobachtungsmodus führt die Richtlinie aus, zeichnet jedoch eine Nicht-allow-Entscheidung auf, 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 dieser Fehler die Operation erlauben oder verweigern soll.

API-Exporte

Export	Zweck
`customPolicies.add(policy)`	Eine benutzerdefinierte Richtlinie registrieren, wenn das Modul geladen wird.
`allow(reason?)`	Die Operation erlauben.
`instruct(reason)`	Die Operation erlauben und Anleitung bereitstellen, wo unterstützt.
`deny(reason)`	Die Operation blockieren, wo unterstützt.
`getCustomHooks()`	Die aktuell im Modul-Registry registrierten Richtlinien zurückgeben.
`clearCustomHooks()`	Dieses Registry leeren, hauptsächlich für Tests und Loader.

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