Esempi - FailproofAI

Esempi pronti all’uso per scenari comuni. Ognuno mostra come installare e cosa aspettarsi.

Configurare i hook per Claude Code

Failproof AI si integra con Claude Code tramite il suo sistema di hook. Quando esegui failproofai policies --install, registra i comandi hook nel file settings.json di Claude Code che si attivano ad ogni chiamata di strumento.

Installa failproofai

npm install -g failproofai

Abilita tutte le policy integrate

failproofai policies --install

Verifica che gli hook siano registrati

cat ~/.claude/settings.json | grep failproofai

Dovresti vedere i record degli hook per gli eventi PreToolUse, PostToolUse, Notification e Stop.

Esegui Claude Code

claude

Le policy si eseguono automaticamente ad ogni chiamata di strumento. Prova a chiedere a Claude di eseguire sudo rm -rf / - sarà bloccato.

Configurare i hook per Agents SDK

Se stai sviluppando con Agents SDK, puoi utilizzare lo stesso sistema di hook programmaticamente.

Installa failproofai nel tuo progetto

npm install failproofai

Configura gli hook nel tuo agente

Passa i comandi hook quando crei il tuo processo agente. Gli hook si attivano allo stesso modo che in Claude Code - tramite JSON su stdin/stdout:

failproofai --hook PreToolUse   # chiamato prima di ogni strumento
failproofai --hook PostToolUse  # chiamato dopo ogni strumento

Scrivi una policy personalizzata per il tuo agente

import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "limit-to-project-dir",
  description: "Keep the agent inside the project directory",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    const path = String(ctx.toolInput?.file_path ?? "");
    if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) {
      return deny("Agent is restricted to the project directory");
    }
    return allow();
  },
});

Installa la policy personalizzata

failproofai policies --install --custom ./my-agent-policies.js

Blocca i comandi distruttivi

La configurazione più comune - evita che gli agenti causino danni irreversibili.

failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh

Cosa fa:

block-sudo - blocca tutti i comandi sudo
block-rm-rf - blocca l’eliminazione ricorsiva di file
block-force-push - blocca git push --force
block-curl-pipe-sh - blocca il reindirizzamento di script remoti verso la shell

Previeni la fuga di segreti

Impedisci agli agenti di vedere o divulgare credenziali nell’output degli strumenti.

failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens

Questi si attivano su PostToolUse - dopo che uno strumento viene eseguito, ripuliscono l’output prima che l’agente lo veda.

Ricevi avvisi su Slack quando gli agenti richiedono attenzione

Utilizza l’hook di notifica per inoltrare gli avvisi di inattività a Slack.

import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "slack-on-idle",
  description: "Alert Slack when the agent is waiting for input",
  match: { events: ["Notification"] },
  fn: async (ctx) => {
    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
    if (!webhookUrl) return allow();

    const message = String(ctx.payload?.message ?? "Agent is waiting");
    const project = ctx.session?.cwd ?? "unknown";

    try {
      await fetch(webhookUrl, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          text: `*${message}*\nProject: \`${project}\``,
        }),
        signal: AbortSignal.timeout(5000),
      });
    } catch {
      // never block the agent if Slack is unreachable
    }

    return allow();
  },
});

Installala:

SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js

Mantieni gli agenti su un branch

Previeni che gli agenti cambino branch o facciano push su quelli protetti.

import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "stay-on-branch",
  description: "Prevent the agent from checking out other branches",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = String(ctx.toolInput?.command ?? "");
    if (/git\s+checkout\s+(?!-b)/.test(cmd)) {
      return deny("Stay on the current branch. Create a new branch with -b if needed.");
    }
    return allow();
  },
});

Richiedi test prima dei commit

Ricorda agli agenti di eseguire i test prima di fare commit.

import { customPolicies, allow, instruct } from "failproofai";

customPolicies.add({
  name: "test-before-commit",
  description: "Remind the agent to run tests before committing",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = String(ctx.toolInput?.command ?? "");
    if (/git\s+commit/.test(cmd)) {
      return instruct("Run tests before committing. Use `npm test` or `bun test` first.");
    }
    return allow();
  },
});

Proteggi un repository di produzione

Effettua il commit di una config a livello di progetto in modo che ogni sviluppatore del tuo team ottenga le stesse policy. Crea .failproofai/policies-config.json nel tuo repository:

{
  "enabledPolicies": [
    "block-sudo",
    "block-rm-rf",
    "block-force-push",
    "block-push-master",
    "block-env-files",
    "sanitize-api-keys",
    "sanitize-jwt"
  ],
  "policyParams": {
    "block-push-master": {
      "protectedBranches": ["main", "release", "production"]
    }
  }
}

Quindi fai il commit:

git add .failproofai/policies-config.json
git commit -m "Add failproofai team policies"

Ogni membro del team che ha failproofai installato raccoglierà automaticamente queste regole.

Costruisci uno standard di qualità a livello organizzativo con policy di convenzione

La configurazione più efficace: effettua il commit di .failproofai/policies/ nel tuo repository con policy personalizzate per il tuo progetto. Ogni membro del team le ottiene automaticamente — nessun comando di installazione, nessun cambio di configurazione.

Crea la directory e aggiungi le policy

mkdir -p .failproofai/policies

// .failproofai/policies/team-policies.mjs
import { customPolicies, allow, deny, instruct } from "failproofai";

// Enforce your team's preferred package manager
// (or enable the built-in prefer-package-manager policy instead)
customPolicies.add({
  name: "enforce-bun",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = String(ctx.toolInput?.command ?? "");
    if (/\bnpm\b/.test(cmd)) return deny("Use bun instead of npm.");
    return allow();
  },
});

// Remind the agent to run tests before committing
customPolicies.add({
  name: "test-before-commit",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    if (/git\s+commit/.test(ctx.toolInput?.command ?? "")) {
      return instruct("Run tests before committing.");
    }
    return allow();
  },
});

Fai il commit su git

git add .failproofai/policies/
git commit -m "Add team quality policies"

Continua a migliorare

Man mano che il tuo team incontra nuovi problemi, aggiungi policy e fai push. Tutti ricevono l’aggiornamento al prossimo git pull. Queste policy diventano uno standard di qualità vivo che cresce con il tuo team.

Altri esempi

La directory examples/ nel repository contiene:

File	Cosa mostra
`policies-basic.js`	Policy per iniziare - blocca scritture di produzione, force-push, script reindirizzati
`policies-notification.js`	Avvisi Slack per notifiche di inattività e fine sessione
`policies-advanced/index.js`	Import transitivi, hook asincroni, ripulitura dell’output PostToolUse, gestione dell’evento Stop

​Configurare i hook per Claude Code

​Configurare i hook per Agents SDK

​Blocca i comandi distruttivi

​Previeni la fuga di segreti

​Ricevi avvisi su Slack quando gli agenti richiedono attenzione

​Mantieni gli agenti su un branch

​Richiedi test prima dei commit

​Proteggi un repository di produzione

​Costruisci uno standard di qualità a livello organizzativo con policy di convenzione

​Altri esempi