Criteri personalizzati

I criteri personalizzati trasformano un pattern di errore dalle tue tracce o auditor in una decisione che si esegue mentre un agente lavora. Un criterio può consentire un’azione, fornire indicazioni all’agente o negare l’azione prima che causi un altro incidente. Utilizza un criterio personalizzato quando il comportamento dipende dai tuoi strumenti, percorsi, comandi, ambienti o regole operative. Consulta prima il Failproof AI policy pack per evitare di ricreare un controllo esistente.

Scrivi un criterio personalizzato

Dashboard
CLI

Vai a Admin → policy editor, seleziona New policy e descrivi l’errore che vuoi prevenire.
Aggiungi il codice del criterio, quindi testa i match previsti e i non-match 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 a 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 uno o più criteri 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

Questo criterio blocca i comandi Kubernetes distruttivi solo quando il comando è rivolto a produzione. Tutto al di fuori di quel pattern 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.",
    );
  },
});

I criteri validi sono abbastanza ristretti da poter essere spiegati in una sola frase. Fai corrispondere l’azione osservabile, non l’intento che speravi 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.	Il criterio non si applica o l’azione è sicura.
`instruct(reason)`	L’operazione continua con indicazioni dove lo supporta l’harness.	Vuoi indirizzare l’agente verso un approccio migliore senza applicare un invariante.
`deny(reason)`	L’operazione viene 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 usare instruct() per un confine di sicurezza. La distribuzione delle indicazioni varia in base all’harness dell’agente. Usa deny() quando l’azione deve essere prevenuta.

Oggetto criterio

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

Campo	Obbligatorio	Descrizione
`name`	Sì	Identificatore stabile del criterio. Mantieni i nomi univoci nei file.
`description`	No	Scopo leggibile mostrato negli elenchi dei criteri e nelle decisioni.
`match.events`	No	Tipi di evento che invocano il criterio. Omettere `match` lo 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 custom-policy pubblico.

Contesto del criterio

Ogni criterio 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 di sessione, directory di lavoro, percorso della trascrizione, modalità di autorizzazione e metadati dell’harness quando disponibili.
`cli`	`string \| undefined`	Harness dell’agente sorgente, come `claude`, `codex` o `cursor`.
`params`	`Record<string, unknown>`	Parametri del criterio integrati. I criteri personalizzati ricevono attualmente un oggetto vuoto.

Tratta ogni valore facoltativo come genuinamente facoltativo. Le versioni degli agenti e i tipi di evento non forniscono tutti gli stessi campi.

Input comuni degli strumenti

Failproof AI normalizza gli strumenti comuni tra gli harness supportati in modo che un criterio 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`

Usa una coercizione difensiva perché i valori di input dello strumento sono digitati come unknown:

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

Scegli l’evento

Evento	Quando si esegue	Uso tipico
`PreToolUse`	Prima che uno strumento si esegua.	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 autorizzazione.	Applica regole di autorizzazione specifiche dell’organizzazione.
`UserPromptSubmit`	Prima che un prompt inviato continui.	Rifiuta istruzioni vietate o aggiungi indicazioni di workflow.
`Stop`	Quando l’agente tenta di terminare.	Richiedi una condizione di completamento raggiungibile, come un passo di verifica locale.
`SubagentStop`	Quando un subagente tenta di terminare.	Blocca il lavoro delegato prima che ritorni al genitore.
`SessionStart` / `SessionEnd`	Ai confini della sessione.	Registra o verifica 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 affidarti a un evento in una flotta mista.

Tutti i nomi degli eventi del criterio

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.

Scrivi pattern comuni di criteri

Blocca scritture su 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 indicazioni non vincolanti

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

Blocca 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 all’agente. Blocca solo su una condizione che l’agente può soddisfare nell’ambiente corrente e delimita ogni chiamata di subprocess o di rete.

Carica i file dei criteri

File di convenzione

I file di convenzione si caricano automaticamente:

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

Sia le directory dei criteri del progetto che quelle dell’utente vengono caricate.
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 customPolicies.add() in un file.
Sono supportate le importazioni relative da moduli locali.
I criteri del progetto possono essere sottoposti a commit in modo che le stesse regole seguano il repository.

File espliciti

Usa percorsi espliciti quando la validazione o la configurazione deve nominare direttamente il file di ingresso:

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 dai file di convenzione dell’utente. Un file scoperto attraverso entrambi i percorsi viene caricato una sola volta.

Valida e testa

La validazione esegue il modulo attraverso il caricatore di produzione e conferma che registra almeno un criterio.

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

La validazione rileva file mancanti, errori di sintassi, importazioni non risolte, eccezioni di livello superiore e timeout di caricamento del modulo. Non prova che la tua logica di match sia corretta. Testa almeno questi casi:

Un’azione che deve corrispondere e produrre il motivo del criterio previsto.
Un’azione vicina ma sicura che deve restituire allow().
Campi dello strumento mancanti o malformati.
Sintassi alternative del comando, percorsi, virgolette, casing e spazi.
Una dipendenza di subprocess o rete non disponibile.

Attribuisci il risultato al tuo criterio personalizzato in Observe → policy. Un test bloccato non è sufficiente se un criterio integrato diverso ha preso la decisione.

Comportamento runtime

I criteri integrati vengono valutati prima dei criteri personalizzati.
Il primo deny interrompe l’ulteriore valutazione dei criteri.
Più risultati di instruct possono essere combinati quando nessun criterio nega l’evento.
Una funzione di criterio 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 criteri integrati continuano.
Il caricamento del modulo di livello superiore ha anche una scadenza di 10 secondi.
La modalità observe nel cloud esegue il criterio ma registra una decisione non-allow senza applicarla.

Mantieni i moduli di criterio deterministici e veloci. Evita chiamate di rete di livello superiore o avvio del server. Delimita il lavoro dentro fn, cattura i guasti di dipendenza e scegli deliberatamente se quel guasto dovrebbe consentire o negare l’operazione.

Esportazioni API

Esportazione	Scopo
`customPolicies.add(policy)`	Registra un criterio personalizzato quando il modulo si carica.
`allow(reason?)`	Consenti l’operazione.
`instruct(reason)`	Consenti l’operazione e fornisci indicazioni dove supportate.
`deny(reason)`	Blocca l’operazione dove supportato.
`getCustomHooks()`	Restituisce i criteri attualmente registrati nel registro del modulo.
`clearCustomHooks()`	Cancella quel registro, principalmente per test e caricatori.

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

Distribuisci criteri personalizzati

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

Connect your agents

Reference

Scrivi un criterio personalizzato

Inizia con una regola ristretta

Scegli una decisione

Oggetto criterio

Contesto del criterio

Input comuni degli strumenti

Scegli l’evento

Scrivi pattern comuni di criteri

Blocca scritture su percorsi protetti

Fornisci indicazioni non vincolanti

Blocca il completamento della sessione

Carica i file dei criteri

File di convenzione

File espliciti

Valida e testa

Comportamento runtime

Esportazioni API

Distribuisci criteri personalizzati

​Scrivi un criterio personalizzato

​Inizia con una regola ristretta

​Scegli una decisione

​Oggetto criterio

​Contesto del criterio

​Input comuni degli strumenti

​Scegli l’evento

​Scrivi pattern comuni di criteri

​Blocca scritture su percorsi protetti

​Fornisci indicazioni non vincolanti

​Blocca il completamento della sessione

​Carica i file dei criteri

​File di convenzione

​File espliciti

​Valida e testa

​Comportamento runtime

​Esportazioni API

Distribuisci criteri personalizzati

Scrivi un criterio personalizzato

Inizia con una regola ristretta

Scegli una decisione

Oggetto criterio

Contesto del criterio

Input comuni degli strumenti

Scegli l’evento

Scrivi pattern comuni di criteri

Blocca scritture su percorsi protetti

Fornisci indicazioni non vincolanti

Blocca il completamento della sessione

Carica i file dei criteri

File di convenzione

File espliciti

Valida e testa

Comportamento runtime

Esportazioni API