Políticas personalizadas

Las políticas personalizadas te permiten definir reglas para cualquier comportamiento del agente: aplicar convenciones del proyecto, prevenir desviaciones, bloquear operaciones destructivas, detectar agentes atascados o integrarte con Slack, flujos de aprobación y más. Utilizan el mismo sistema de eventos de hook y las mismas decisiones allow, deny, instruct que las políticas integradas.

Ejemplo rápido

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

customPolicies.add({
  name: "no-production-writes",
  description: "Block writes to paths containing 'production'",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
    const path = ctx.toolInput?.file_path ?? "";
    if (path.includes("production")) {
      return deny("Writes to production paths are blocked");
    }
    return allow();
  },
});

Instálalo:

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

Dos formas de cargar políticas personalizadas

Opción 1: Basada en convenciones (recomendada)

Coloca archivos *policies.{js,mjs,ts} en .failproofai/policies/ y se cargarán automáticamente, sin necesidad de flags ni cambios de configuración. Funciona como los git hooks: basta con añadir el archivo y ya está.

# Nivel de proyecto — incluido en git, compartido con el equipo
.failproofai/policies/security-policies.mjs
.failproofai/policies/workflow-policies.mjs

# Nivel de usuario — personal, aplica a todos los proyectos
~/.failproofai/policies/my-policies.mjs

Cómo funciona:

Se analizan tanto el directorio del proyecto como el del usuario (unión — no gana el primero en alcance)
Los archivos se cargan en orden alfabético dentro de cada directorio. Usa prefijos como 01-, 02- para controlar el orden
Solo se cargan los archivos que coincidan con *policies.{js,mjs,ts}; los demás se ignoran
Cada archivo se carga de forma independiente (fallo abierto por archivo)
Funciona junto con --custom explícito y las políticas integradas

Las políticas por convención son la forma más sencilla de establecer un estándar de calidad para tu organización. Incluye .failproofai/policies/ en git y todos los miembros del equipo recibirán las mismas reglas automáticamente, sin configuración individual. A medida que el equipo detecte nuevos modos de fallo, añade una política y haz push. Con el tiempo, esto se convierte en un estándar de calidad vivo que mejora con cada contribución.

Opción 2: Ruta de archivo explícita

# Instalar con un archivo de políticas personalizado
failproofai policies --install --custom ./my-policies.js

# Reemplazar la ruta del archivo de políticas
failproofai policies --install --custom ./new-policies.js

# Eliminar la ruta de políticas personalizada de la configuración
failproofai policies --uninstall --custom

La ruta absoluta resuelta se almacena en policies-config.json como customPoliciesPath. El archivo se carga de nuevo en cada evento de hook; no hay caché entre eventos.

Usar ambas opciones juntas

Las políticas por convención y el archivo --custom explícito pueden coexistir. Orden de carga:

Archivo customPoliciesPath explícito (si está configurado)
Archivos de convención del proyecto ({cwd}/.failproofai/policies/, alfabético)
Archivos de convención del usuario (~/.failproofai/policies/, alfabético)

API

Importación

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

`customPolicies.add(hook)`

Registra una política. Llámalo tantas veces como necesites para definir múltiples políticas en el mismo archivo.

customPolicies.add({
  name: string;                         // obligatorio - identificador único
  description?: string;                 // se muestra en la salida de `failproofai policies`
  match?: { events?: HookEventType[] }; // filtrar por tipo de evento; omitir para coincidir con todos
  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
});

Funciones de decisión

Función	Efecto	Cuándo usarla
`allow()`	Permite la operación sin mostrar mensajes	La acción es segura y no necesita notificación
`deny(message)`	Bloquea la operación	El agente no debe realizar esta acción
`instruct(message)`	Añade contexto sin bloquear	Proporciona contexto adicional al agente para que siga el camino correcto

deny(message) — el mensaje aparece ante Claude con el prefijo "Blocked by failproofai:". Un solo deny interrumpe toda evaluación posterior. instruct(message) — el mensaje se añade al contexto de Claude para la llamada a la herramienta actual. Todos los mensajes instruct se acumulan y se entregan juntos.

Puedes añadir orientación adicional a cualquier mensaje deny o instruct mediante el campo hint en policyParams, sin necesidad de modificar el código. Esto funciona también para políticas personalizadas (custom/), de convención de proyecto (.failproofai-project/) y de convención de usuario (.failproofai-user/). Consulta Configuración → hint para más detalles.

Mensajes allow informativos

allow(message) permite la operación y envía un mensaje informativo a Claude. El mensaje se entrega como additionalContext en la respuesta stdout del handler del hook, el mismo mecanismo que usa instruct, pero con un significado diferente: es una actualización de estado, no una advertencia.

Función	Efecto	Cuándo usarla
`allow(message)`	Permite y envía contexto a Claude	Confirmar que una verificación pasó o explicar por qué se omitió

Casos de uso:

Confirmaciones de estado: allow("All CI checks passed.") — informa a Claude de que todo está en orden
Explicaciones de fallo abierto: allow("GitHub CLI not installed, skipping CI check.") — indica a Claude por qué se omitió una verificación para que tenga el contexto completo
Los mensajes múltiples se acumulan: si varias políticas devuelven allow(message), todos los mensajes se unen con saltos de línea y se entregan juntos

customPolicies.add({
  name: "confirm-branch-status",
  match: { events: ["Stop"] },
  fn: async (ctx) => {
    const cwd = ctx.session?.cwd;
    if (!cwd) return allow("No working directory, skipping branch check.");

    // ... check branch status ...
    if (allPushed) {
      return allow("Branch is up to date with remote.");
    }
    return deny("Unpushed changes detected.");
  },
});

Campos de `PolicyContext`

Campo	Tipo	Descripción
`eventType`	`string`	`"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"`
`toolName`	`string \| undefined`	La herramienta que se está llamando (p. ej. `"Bash"`, `"Write"`, `"Read"`)
`toolInput`	`Record<string, unknown> \| undefined`	Los parámetros de entrada de la herramienta
`payload`	`Record<string, unknown>`	Payload completo del evento raw de Claude Code
`session`	`SessionMetadata \| undefined`	Contexto de sesión (ver a continuación)

Campos de `SessionMetadata`

Campo	Tipo	Descripción
`sessionId`	`string`	Identificador de sesión de Claude Code
`cwd`	`string`	Directorio de trabajo de la sesión de Claude Code
`transcriptPath`	`string`	Ruta al archivo de transcripción JSONL de la sesión

Tipos de eventos

Evento	Cuándo se dispara	Contenido de `toolInput`
`PreToolUse`	Antes de que Claude ejecute una herramienta	La entrada de la herramienta (p. ej. `{ command: "..." }` para Bash)
`PostToolUse`	Después de que una herramienta finaliza	La entrada de la herramienta + `tool_result` (la salida)
`Notification`	Cuando Claude envía una notificación	`{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` — los hooks siempre deben devolver `allow()`, no pueden bloquear notificaciones
`Stop`	Cuando la sesión de Claude termina	Vacío

Orden de evaluación

Las políticas se evalúan en este orden:

Políticas integradas (en orden de definición)
Políticas personalizadas explícitas de customPoliciesPath (en orden de .add())
Políticas de convención del proyecto .failproofai/policies/ (archivos en orden alfabético, orden de .add() dentro de cada archivo)
Políticas de convención del usuario ~/.failproofai/policies/ (archivos en orden alfabético, orden de .add() dentro de cada archivo)

El primer deny interrumpe todas las políticas siguientes. Todos los mensajes instruct se acumulan y se entregan juntos.

Importaciones transitivas

Los archivos de políticas personalizadas pueden importar módulos locales usando rutas relativas:

// my-policies.js
import { isBlockedPath } from "./utils.js";
import { checkApproval } from "./approval-client.js";

customPolicies.add({
  name: "approval-gate",
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
    return approved ? allow() : deny("Approval required for this command");
  },
});

Se resuelven todas las importaciones relativas alcanzables desde el archivo de entrada. Esto se implementa reescribiendo las importaciones from "failproofai" a la ruta real de dist y creando archivos .mjs temporales para garantizar la compatibilidad con ESM.

Filtrado por tipo de evento

Usa match.events para limitar cuándo se activa una política:

customPolicies.add({
  name: "require-summary-on-stop",
  match: { events: ["Stop"] },
  fn: async (ctx) => {
    // Solo se activa cuando la sesión finaliza
    // ctx.session.transcriptPath contiene el registro completo de la sesión
    return allow();
  },
});

Omite match completamente para que se active en todos los tipos de eventos.

Manejo de errores y modos de fallo

Las políticas personalizadas son de fallo abierto: los errores nunca bloquean las políticas integradas ni hacen que el handler del hook falle.

Fallo	Comportamiento
`customPoliciesPath` no configurado	No se ejecutan políticas personalizadas explícitas; las políticas de convención y las integradas continúan normalmente
Archivo no encontrado	Advertencia registrada en `~/.failproofai/hook.log`; las integradas continúan
Error de sintaxis/importación (explícito)	Error registrado en `~/.failproofai/hook.log`; las políticas personalizadas explícitas se omiten
Error de sintaxis/importación (convención)	Error registrado; ese archivo se omite, los demás archivos de convención siguen cargándose
`fn` lanza un error en tiempo de ejecución	Error registrado; ese hook se trata como `allow`; los demás hooks continúan
`fn` tarda más de 10s	Timeout registrado; se trata como `allow`
Directorio de convención no existente	No se ejecutan políticas de convención; sin error

Para depurar errores en políticas personalizadas, monitorea el archivo de log:

tail -f ~/.failproofai/hook.log

Ejemplo completo: múltiples políticas

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

// Evitar que el agente escriba en el directorio secrets/
customPolicies.add({
  name: "block-secrets-dir",
  description: "Prevent agent from writing to secrets/ directory",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
    const path = ctx.toolInput?.file_path ?? "";
    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
    return allow();
  },
});

// Mantener al agente en el camino correcto: verificar los tests antes de hacer commit
customPolicies.add({
  name: "remind-test-before-commit",
  description: "Keep the agent on track: verify tests pass before committing",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = ctx.toolInput?.command ?? "";
    if (/git\s+commit/.test(cmd)) {
      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
    }
    return allow();
  },
});

// Prevenir cambios de dependencias no planificados durante el período de congelación
customPolicies.add({
  name: "dependency-freeze",
  description: "Prevent unplanned dependency changes during freeze period",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();
    const cmd = ctx.toolInput?.command ?? "";
    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
    }
    return allow();
  },
});

export { customPolicies };

Ejemplos

El directorio examples/ contiene archivos de políticas listos para usar:

Archivo	Contenido
`examples/policies-basic.js`	Cinco políticas iniciales que cubren los modos de fallo más comunes del agente
`examples/policies-advanced/index.js`	Patrones avanzados: importaciones transitivas, llamadas asíncronas, limpieza de salida y hooks de fin de sesión
`examples/convention-policies/security-policies.mjs`	Políticas de seguridad basadas en convenciones (bloquear escrituras en .env, prevenir reescritura del historial de git)
`examples/convention-policies/workflow-policies.mjs`	Políticas de flujo de trabajo basadas en convenciones (recordatorios de tests, auditoría de escrituras de archivos)

Usar los ejemplos con archivo explícito

failproofai policies --install --custom ./examples/policies-basic.js

Usar los ejemplos basados en convenciones

# Copiar al nivel de proyecto
mkdir -p .failproofai/policies
cp examples/convention-policies/*.mjs .failproofai/policies/

# O copiar al nivel de usuario
mkdir -p ~/.failproofai/policies
cp examples/convention-policies/*.mjs ~/.failproofai/policies/

No se necesita ningún comando de instalación; los archivos se detectan automáticamente en el siguiente evento de hook.

Primeros pasos

Conceptos principales

CLI

Herramientas

Avanzado

Ejemplos

Políticas personalizadas

Ejemplo rápido

Dos formas de cargar políticas personalizadas

Opción 1: Basada en convenciones (recomendada)

Opción 2: Ruta de archivo explícita

Usar ambas opciones juntas

API

Importación

`customPolicies.add(hook)`

Funciones de decisión

Mensajes allow informativos

Campos de `PolicyContext`

Campos de `SessionMetadata`

Tipos de eventos

Orden de evaluación

Importaciones transitivas

Filtrado por tipo de evento

Manejo de errores y modos de fallo

Ejemplo completo: múltiples políticas

Ejemplos

Usar los ejemplos con archivo explícito

Usar los ejemplos basados en convenciones

​Ejemplo rápido

​Dos formas de cargar políticas personalizadas

​Opción 1: Basada en convenciones (recomendada)

​Opción 2: Ruta de archivo explícita

​Usar ambas opciones juntas

​API

​Importación

​customPolicies.add(hook)

​Funciones de decisión

​Mensajes allow informativos

​Campos de PolicyContext

​Campos de SessionMetadata

​Tipos de eventos

​Orden de evaluación

​Importaciones transitivas

​Filtrado por tipo de evento

​Manejo de errores y modos de fallo

​Ejemplo completo: múltiples políticas

​Ejemplos

​Usar los ejemplos con archivo explícito

​Usar los ejemplos basados en convenciones

Ejemplo rápido

Dos formas de cargar políticas personalizadas

Opción 1: Basada en convenciones (recomendada)

Opción 2: Ruta de archivo explícita

Usar ambas opciones juntas

API

Importación

`customPolicies.add(hook)`

Funciones de decisión

Mensajes allow informativos

Campos de `PolicyContext`

Campos de `SessionMetadata`

Tipos de eventos

Orden de evaluación

Importaciones transitivas

Filtrado por tipo de evento

Manejo de errores y modos de fallo

Ejemplo completo: múltiples políticas

Ejemplos

Usar los ejemplos con archivo explícito

Usar los ejemplos basados en convenciones