Examples

title: Esempi description: “Come configurare gli hook per Claude Code e l’Agents SDK” icon: book-open

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

Configurazione degli 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 degli hook nel file settings.json di Claude Code che si attivano ad ogni chiamata di tool.

Installa failproofai

npm install -g failproofai

Abilita tutte le politiche integrate

failproofai policies --install

Verifica che gli hook siano registrati

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

Dovresti vedere voci di hook per gli eventi PreToolUse, PostToolUse, Notification e Stop.

Esegui Claude Code

claude

Le politiche ora si eseguono automaticamente ad ogni chiamata di tool. Prova a chiedere a Claude di eseguire sudo rm -rf / - verrà bloccato.

Configurazione degli hook per l’Agents SDK

Se stai sviluppando con l’Agents SDK, puoi utilizzare lo stesso sistema di hook a livello programmativo.

Installa failproofai nel tuo progetto

npm install failproofai

Configura gli hook nel tuo agente

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

failproofai --hook PreToolUse   # called before each tool
failproofai --hook PostToolUse  # called after each tool

Scrivi una politica 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 politica personalizzata

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

Blocca i comandi distruttivi

La configurazione più comune - impedisci agli agenti di causare danni irreversibili.

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

Quello che 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 piping di script remoti alla shell

Previeni la fuga di segreti

Impedisci agli agenti di vedere o divulgare credenziali nell’output dei tool.

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

Questi si attivano su PostToolUse - dopo che un tool è stato eseguito, scrubano l’output prima che l’agente lo veda.

Ricevi avvisi Slack quando gli agenti hanno bisogno di attenzione

Usa 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();
  },
});

Installalo:

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

Tieni gli agenti su un ramo

Impedisci agli agenti di cambiare ramo o fare push su rami 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 effettuare un 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

Esegui il commit di una configurazione a livello di progetto in modo che ogni sviluppatore del tuo team ottenga le stesse politiche. 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 esegui 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.

Crea uno standard di qualità a livello organizzativo con politiche di convenzione

La configurazione più impattante: esegui il commit di .failproofai/policies/ nel tuo repository con politiche 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 politiche

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

Esegui 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 nuove modalità di errore, aggiungi politiche e fai push. Ognuno ottiene l’aggiornamento al prossimo git pull. Queste politiche diventano uno standard di qualità vivente che cresce con il tuo team.

Altri esempi

La directory examples/ nel repository contiene:

File	Cosa mostra
`policies-basic.js`	Politiche di base - blocca scritture in produzione, force-push, script con pipe
`policies-notification.js`	Avvisi Slack per notifiche di inattività e fine della sessione
`policies-advanced/index.js`	Import transitivi, hook asincroni, scrubbing dell’output di PostToolUse, gestione degli eventi Stop

Per iniziare

Concetti chiave

CLI

Strumenti

Avanzato

Esempi

title: Esempi description: “Come configurare gli hook per Claude Code e l’Agents SDK” icon: book-open

Configurazione degli hook per Claude Code

Configurazione degli hook per l’Agents SDK

Blocca i comandi distruttivi

Previeni la fuga di segreti

Ricevi avvisi Slack quando gli agenti hanno bisogno di attenzione

Tieni gli agenti su un ramo

Richiedi test prima dei commit

Proteggi un repository di produzione

Crea uno standard di qualità a livello organizzativo con politiche di convenzione

Altri esempi

​title: Esempi description: “Come configurare gli hook per Claude Code e l’Agents SDK” icon: book-open

​Configurazione degli hook per Claude Code

​Configurazione degli hook per l’Agents SDK

​Blocca i comandi distruttivi

​Previeni la fuga di segreti

​Ricevi avvisi Slack quando gli agenti hanno bisogno di attenzione

​Tieni gli agenti su un ramo

​Richiedi test prima dei commit

​Proteggi un repository di produzione

​Crea uno standard di qualità a livello organizzativo con politiche di convenzione

​Altri esempi

title: Esempi description: “Come configurare gli hook per Claude Code e l’Agents SDK” icon: book-open

Configurazione degli hook per Claude Code

Configurazione degli hook per l’Agents SDK

Blocca i comandi distruttivi

Previeni la fuga di segreti

Ricevi avvisi Slack quando gli agenti hanno bisogno di attenzione

Tieni gli agenti su un ramo

Richiedi test prima dei commit

Proteggi un repository di produzione

Crea uno standard di qualità a livello organizzativo con politiche di convenzione

Altri esempi