Politiche personalizzate

Le politiche personalizzate trasformano un modello di errore dalle tue tracce o audit in una decisione che viene eseguita mentre un agente lavora. Una politica può consentire un’azione, fornire orientamento all’agente o negare l’azione prima che causi un altro incidente. Utilizza una politica personalizzata quando il comportamento dipende dai tuoi strumenti, percorsi, comandi, ambienti o regole operative. Controlla prima il catalogo delle politiche integrate per non ricreare un controllo già esistente.

Crea una politica personalizzata

Dashboard
CLI

Vai a Admin → policy editor, seleziona New policy e descrivi l’errore che vuoi prevenire.
Aggiungi il codice della politica, quindi testa i match previsti e i match non sicuri nell’editor. Risolvi ogni errore di validazione.
Salva la bozza e seleziona Publish version per creare una versione immutabile.
Vai a Admin → enforcement, distribuisci la versione su una macchina di test in modalità observe e verifica le sue decisioni in Observe → policy prima di applicarla.

Crea .failproofai/policies/checkout-policies.ts. Il nome del file deve terminare in policies.js, policies.mjs o policies.ts.
Registra una o più politiche con customPolicies.add().
Valida e installa il file con failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project.
Attiva un’azione corrispondente e un’azione sicura. Esegui failproofai policies, quindi ispeziona le decisioni attribuite in Observe → policy.

Inizia con una regola ristretta

Questa politica blocca i comandi Kubernetes distruttivi solo quando il comando ha come target la produzione. Tutto ciò che non rientra in quel modello di errore esatto restituisce 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.",
    );
  },
});

Le buone politiche sono abbastanza ristrette da spiegare in una frase. Adatta l’azione osservabile, non l’intenzione che speri avesse l’agente, e restituisci allow() non appena la regola non si applica.

Scegli una decisione

Helper	Risultato	Usalo quando
`allow(reason?)`	L’operazione continua.	La politica non si applica o l’azione è sicura.
`instruct(reason)`	L’operazione continua con orientamento dove supportato dall’harness.	Vuoi guidare l’agente verso un approccio migliore senza applicare un invariante.
`deny(reason)`	L’operazione è bloccata quando l’evento e l’harness supportano il blocco.	L’azione non deve procedere.

Scrivi il motivo per l’agente che deve recuperare. Spiega cosa è stato rilevato e cosa dovrebbe fare invece.

Non utilizzare instruct() per un confine di sicurezza. La consegna della guida varia a seconda dell’harness dell’agente. Utilizza deny() quando l’azione deve essere prevenuta.

Oggetto policy

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

Campo	Obbligatorio	Descrizione
`name`	Sì	Identificatore stabile per la politica. Mantieni i nomi unici tra i file.
`description`	No	Scopo leggibile mostrato negli elenchi di politiche e nelle decisioni.
`match.events`	No	Tipi di evento che invocano la politica. Omettere `match` la invoca per ogni evento disponibile.
`fn`	Sì	Funzione sincrona o asincrona che restituisce un risultato `allow`, `instruct` o `deny`.

Filtra gli strumenti dentro fn. match.toolNames non fa parte del tipo di politica personalizzata pubblico.

Contesto della politica

Ogni politica riceve un PolicyContext.

Campo	Tipo	Cosa contiene
`eventType`	`HookEventType`	Evento normalizzato attualmente in valutazione.
`toolName`	`string \| undefined`	Nome dello strumento canonico come `Bash`, `Read`, `Write` o `Edit`.
`toolInput`	`Record<string, unknown> \| undefined`	Input canonico per la chiamata dello strumento corrente.
`payload`	`Record<string, unknown>`	Payload dell’evento normalizzato completo.
`session`	`SessionMetadata \| undefined`	ID sessione, directory di lavoro, percorso della trascrizione, modalità di autorizzazione e metadati dell’harness se disponibili.
`cli`	`string \| undefined`	Harness agente di origine, come `claude`, `codex` o `cursor`.
`params`	`Record<string, unknown>`	Parametri delle politiche integrate. Le politiche personalizzate ricevono attualmente un oggetto vuoto.

Tratta ogni valore opzionale come genuinamente opzionale. Le versioni dell’agente e i tipi di evento non forniscono tutti gli stessi campi.

Input comuni degli strumenti

Failproof AI normalizza i comuni strumenti tra gli harness supportati in modo che una politica possa di solito utilizzare una sola forma di input.

Strumento	Campi comuni
`Bash`	`command`
`Read`	`file_path`
`Write`	`file_path`, `content`
`Edit`	`file_path`, `old_string`, `new_string`
`Grep`	`pattern`, `path`

Utilizza la coercizione difensiva perché i valori dell’input dello strumento sono tipizzati come unknown:

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

Scegli l’evento

Evento	Quando viene eseguito	Uso tipico
`PreToolUse`	Prima dell’esecuzione di uno strumento.	Blocca o guida comandi, scritture, letture e azioni esterne.
`PostToolUse`	Dopo che uno strumento restituisce.	Ispeziona i risultati prima che raggiungano l’agente. Un deny blocca l’intero risultato; non redige campi selezionati.
`PermissionRequest`	Quando l’agente richiede un’autorizzazione.	Applica regole di autorizzazione specifiche dell’organizzazione.
`UserPromptSubmit`	Prima che un prompt inviato continui.	Rifiuta istruzioni proibite o aggiungi orientamento del flusso di lavoro.
`Stop`	Quando l’agente tenta di terminare.	Richiedi una condizione di completamento raggiungibile, come un passo di verifica locale.
`SubagentStop`	Quando un sub-agente tenta di terminare.	Controlla il lavoro delegato prima che torni al padre.
`SessionStart` / `SessionEnd`	Ai confini della sessione.	Registra o controlla lo stato a livello di sessione.

La disponibilità dell’evento e il comportamento di blocco dipendono dall’harness dell’agente. Vedi Agent harnesses prima di fare affidamento su un evento su una flotta mista.

Tutti i nomi degli eventi di politica

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

Crea modelli di politica comuni

Blocca le scritture nei percorsi protetti

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

Fornisci orientamento senza blocco

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

Controlla il completamento della sessione

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 evento Stop negato può far ritentare l’agente. Controlla solo una condizione che l’agente può soddisfare nell’ambiente corrente e delimita ogni subprocess o chiamata di rete.

Carica i file di politica

File di convenzione

I file di convenzione si caricano automaticamente:

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

Le directory delle politiche di progetto e utente vengono caricate entrambe.
I file si caricano alfabeticamente all’interno di ogni directory.
Un file deve terminare in policies.js, policies.mjs o policies.ts.
Sono supportate più chiamate a customPolicies.add() in un file.
Sono supportati gli import relativi da moduli locali.
Le politiche di progetto possono essere commesse in modo che le stesse regole seguano il repository.

File espliciti

Utilizza percorsi espliciti quando la validazione o la configurazione deve nominare direttamente il file di entry:

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

I file espliciti si caricano per primi, seguiti dai file di convenzione del progetto e quindi dai file di convenzione dell’utente. Un file scoperto attraverso entrambi i percorsi viene caricato una volta.

Valida e testa

La validazione esegue il modulo attraverso il loader di produzione e conferma che registra almeno una politica.

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

La validazione rileva file mancanti, errori di sintassi, import non risolti, eccezioni di primo livello e timeout di caricamento del modulo. Non prova che la tua logica di corrispondenza sia corretta. Testa almeno questi casi:

Un’azione che deve corrispondere e produrre il motivo della politica previsto.
Un’azione vicina ma sicura che deve restituire allow().
Campi dello strumento mancanti o malformati.
Sintassi alternativi del comando, percorsi, quotazione, maiuscole/minuscole e spazi vuoti.
Una dipendenza subprocess o di rete non disponibile.

Attribuisci il risultato alla tua politica personalizzata in Observe → policy. Un test bloccato non è sufficiente se una politica integrata diversa ha preso la decisione.

Comportamento a runtime

Le politiche integrate vengono valutate prima delle politiche personalizzate.
Il primo deny interrompe l’ulteriore valutazione della politica.
Più risultati di instruct possono essere combinati quando nessuna politica nega l’evento.
Una funzione di politica ha una scadenza di esecuzione di 10 secondi.
Un’eccezione lanciata o un timeout viene registrato e trattato come allow().
Un file di convenzione che non riesce a caricarsi viene saltato; altri file personalizzati e le politiche integrate continuano.
Il caricamento del modulo di primo livello ha anche una scadenza di 10 secondi.
La modalità di osservazione cloud esegue la politica ma registra una decisione non-allow senza applicarla.

Mantieni i moduli di politica deterministici e veloci. Evita le chiamate di rete di primo livello o l’avvio del server. Delimita il lavoro all’interno di fn, cattura gli errori di dipendenza e scegli deliberatamente se quell’errore deve consentire o negare l’operazione.

Export dell’API

Export	Scopo
`customPolicies.add(policy)`	Registra una politica personalizzata al caricamento del modulo.
`allow(reason?)`	Permetti l’operazione.
`instruct(reason)`	Permetti l’operazione e fornisci orientamento dove supportato.
`deny(reason)`	Blocca l’operazione dove supportato.
`getCustomHooks()`	Restituisci le politiche attualmente registrate nel registro del modulo.
`clearCustomHooks()`	Cancella quel registro, principalmente per test e loader.

TypeScript export PolicyContext, PolicyResult, CustomHook, PolicyDecision e PolicyFunction.

Distribuisci politiche personalizzate

Pubblica una versione, distribuiscila in modalità observe, verifica le decisioni e passa all’enforcement.

Connect your agents

Reference

HTTP API

Politiche personalizzate

Crea una politica personalizzata

Inizia con una regola ristretta

Scegli una decisione

Oggetto policy

Contesto della politica

Input comuni degli strumenti

Scegli l’evento

Crea modelli di politica comuni

Blocca le scritture nei percorsi protetti

Fornisci orientamento senza blocco

Controlla il completamento della sessione

Carica i file di politica

File di convenzione

File espliciti

Valida e testa

Comportamento a runtime

Export dell’API

Distribuisci politiche personalizzate

​Crea una politica personalizzata

​Inizia con una regola ristretta

​Scegli una decisione

​Oggetto policy

​Contesto della politica

​Input comuni degli strumenti

​Scegli l’evento

​Crea modelli di politica comuni

​Blocca le scritture nei percorsi protetti

​Fornisci orientamento senza blocco

​Controlla il completamento della sessione

​Carica i file di politica

​File di convenzione

​File espliciti

​Valida e testa

​Comportamento a runtime

​Export dell’API

Distribuisci politiche personalizzate

Crea una politica personalizzata

Inizia con una regola ristretta

Scegli una decisione

Oggetto policy

Contesto della politica

Input comuni degli strumenti

Scegli l’evento

Crea modelli di politica comuni

Blocca le scritture nei percorsi protetti

Fornisci orientamento senza blocco

Controlla il completamento della sessione

Carica i file di politica

File di convenzione

File espliciti

Valida e testa

Comportamento a runtime

Export dell’API