Ejemplos

Cómo configurar hooks para Claude Code y el Agents SDK

Ejemplos listos para usar en escenarios comunes. Cada uno muestra cómo instalarlo y qué esperar.

---

​

Configurar hooks para Claude Code

Failproof AI se integra con Claude Code a través de su sistema de hooks. Cuando ejecutas failproofai policies --install, registra comandos de hook en el settings.json de Claude Code que se activan en cada llamada a una herramienta.

1. Instalar failproofai

   npm install -g failproofai
   
2. Habilitar todas las políticas integradas

   failproofai policies --install
   
3. Verificar que los hooks están registrados

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

   Deberías ver entradas de hook para los eventos PreToolUse, PostToolUse, Notification y Stop.

4. Ejecutar Claude Code

   claude
   

   Las políticas ahora se ejecutan automáticamente en cada llamada a una herramienta. Prueba pedirle a Claude que ejecute sudo rm -rf / — será bloqueado.

---

​

Configurar hooks para el Agents SDK

Si estás desarrollando con el Agents SDK, puedes usar el mismo sistema de hooks de forma programática.

1. Instalar failproofai en tu proyecto

   npm install failproofai
   
2. Configurar hooks en tu agente

   Pasa comandos de hook al crear el proceso de tu agente. Los hooks se activan de la misma manera que en Claude Code — mediante JSON por stdin/stdout:

   failproofai --hook PreToolUse   # se llama antes de cada herramienta
   failproofai --hook PostToolUse  # se llama después de cada herramienta
   
3. Escribir una política personalizada para tu 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. Instalar la política personalizada

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

---

​

Bloquear comandos destructivos

La configuración más habitual: evitar que los agentes causen daños irreversibles.

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

Qué hace cada uno:

• block-sudo — bloquea todos los comandos sudo
• block-rm-rf — bloquea la eliminación recursiva de archivos
• block-force-push — bloquea git push --force
• block-curl-pipe-sh — bloquea la ejecución de scripts remotos mediante pipe al shell

---

​

Prevenir la filtración de secretos

Impide que los agentes vean o filtren credenciales en la salida de las herramientas.

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

Estas políticas se activan en PostToolUse — después de que se ejecuta una herramienta, limpian la salida antes de que el agente la vea.

---

​

Recibir alertas en Slack cuando los agentes necesitan atención

Usa el hook de notificación para reenviar alertas de inactividad 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 {
      // nunca bloquear al agente si Slack no está disponible
    }

    return allow();
  },
});

Instálalo:

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

---

​

Mantener a los agentes en una rama

Evita que los agentes cambien de rama o hagan push a ramas 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();
  },
});

---

​

Requerir pruebas antes de los commits

Recuerda a los agentes que ejecuten las pruebas antes de hacer 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 un repositorio de producción

Incluye una configuración a nivel de proyecto en el repositorio para que todos los desarrolladores de tu equipo compartan las mismas políticas.

Crea .failproofai/policies-config.json en tu repositorio:

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

Luego haz commit:

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

Todos los miembros del equipo que tengan failproofai instalado adoptarán estas reglas automáticamente.

---

​

Construir un estándar de calidad para toda la organización con políticas de convención

La configuración más efectiva: incluye .failproofai/policies/ en tu repositorio con políticas adaptadas a tu proyecto. Todos los miembros del equipo las reciben automáticamente — sin comandos de instalación, sin cambios de configuración.

1. Crear el directorio y agregar políticas

   mkdir -p .failproofai/policies
   

   // .failproofai/policies/team-policies.mjs
   import { customPolicies, allow, deny, instruct } from "failproofai";
   
   // Imponer el gestor de paquetes preferido del equipo
   // (o habilitar la política integrada prefer-package-manager en su lugar)
   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();
     },
   });
   
   // Recordar al agente que ejecute las pruebas antes de hacer commit
   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. Hacer commit en git

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

   A medida que tu equipo encuentre nuevos problemas, agrega políticas y haz push. Todos reciben la actualización en su próximo git pull. Estas políticas se convierten en un estándar de calidad vivo que crece junto con tu equipo.

---

​

Más ejemplos

El directorio examples/ del repositorio contiene:

Archivo	Qué muestra
policies-basic.js	Políticas básicas — bloquear escrituras en producción, force-push y scripts mediante pipe
policies-notification.js	Alertas de Slack para notificaciones de inactividad y fin de sesión
policies-advanced/index.js	Importaciones transitivas, hooks asíncronos, limpieza de salida en PostToolUse y manejo del evento Stop