Exemplos

Como configurar hooks para Claude Code e o Agents SDK

Exemplos prontos para uso em cenários comuns. Cada um mostra como instalar e o que esperar.

---

​

Configurando hooks para Claude Code

Failproof AI se integra ao Claude Code por meio do seu sistema de hooks. Quando você executa failproofai policies --install, ele registra comandos de hook no settings.json do Claude Code que são disparados a cada chamada de ferramenta.

1. Instale o failproofai

   npm install -g failproofai
   
2. Ative todas as políticas integradas

   failproofai policies --install
   
3. Verifique se os hooks estão registrados

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

   Você deverá ver entradas de hook para os eventos PreToolUse, PostToolUse, Notification e Stop.

4. Execute o Claude Code

   claude
   

   As políticas agora são executadas automaticamente a cada chamada de ferramenta. Tente pedir ao Claude que execute sudo rm -rf / — o comando será bloqueado.

---

​

Configurando hooks para o Agents SDK

Se você está desenvolvendo com o Agents SDK, pode usar o mesmo sistema de hooks de forma programática.

1. Instale o failproofai no seu projeto

   npm install failproofai
   
2. Configure os hooks no seu agente

   Passe os comandos de hook ao criar o processo do seu agente. Os hooks disparam da mesma forma que no Claude Code — via stdin/stdout JSON:

   failproofai --hook PreToolUse   # chamado antes de cada ferramenta
   failproofai --hook PostToolUse  # chamado após cada ferramenta
   
3. Escreva uma política personalizada para o seu 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();
     },
   });
   
4. Instale a política personalizada

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

---

​

Bloquear comandos destrutivos

A configuração mais comum — impedir que agentes causem danos irreversíveis.

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

O que isso faz:

• block-sudo — bloqueia todos os comandos sudo
• block-rm-rf — bloqueia a exclusão recursiva de arquivos
• block-force-push — bloqueia git push --force
• block-curl-pipe-sh — bloqueia o redirecionamento de scripts remotos para o shell

---

​

Prevenir vazamento de segredos

Impede que agentes visualizem ou vazem credenciais na saída de ferramentas.

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

Essas políticas disparam no PostToolUse — após a execução de uma ferramenta, elas limpam a saída antes que o agente a veja.

---

​

Receber alertas no Slack quando agentes precisam de atenção

Use o hook de notificação para encaminhar alertas de inatividade ao 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 {
      // nunca bloqueie o agente se o Slack estiver inacessível
    }

    return allow();
  },
});

Instale:

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

---

​

Manter agentes em uma branch

Impede que agentes troquem de branch ou façam push em branches protegidas.

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

---

​

Exigir testes antes de commits

Lembra os agentes de executar os testes antes de fazer 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();
  },
});

---

​

Proteger um repositório de produção

Faça commit de uma configuração no nível do projeto para que todos os desenvolvedores do time utilizem as mesmas políticas.

Crie .failproofai/policies-config.json no seu repositório:

{
  "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"]
    }
  }
}

Em seguida, faça o commit:

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

Todo membro do time que tiver o failproofai instalado receberá essas regras automaticamente.

---

​

Construir um padrão de qualidade para toda a organização com políticas de convenção

A configuração de maior impacto: faça commit da pasta .failproofai/policies/ no seu repositório com políticas adaptadas ao seu projeto. Todos os membros do time as recebem automaticamente — sem comandos de instalação, sem alterações de configuração.

1. Crie o diretório e adicione as políticas

   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();
     },
   });
   
2. Faça commit no git

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

   À medida que o time encontrar novos pontos de falha, adicione políticas e faça push. Todos recebem a atualização no próximo git pull. Essas políticas se tornam um padrão de qualidade vivo que cresce junto com o time.

---

​

Mais exemplos

O diretório examples/ no repositório contém:

Arquivo	O que demonstra
policies-basic.js	Políticas iniciais — bloquear escritas em produção, force-push e scripts redirecionados
policies-notification.js	Alertas no Slack para notificações de inatividade e encerramento de sessão
policies-advanced/index.js	Importações transitivas, hooks assíncronos, limpeza de saída no PostToolUse e tratamento do evento Stop