Políticas personalizadas

Las políticas personalizadas convierten un patrón de fallos de tus trazas o auditorías en una decisión que se ejecuta mientras trabaja un agente. Una política puede permitir una acción, proporcionar orientación al agente o bloquear la acción antes de que cause otro incidente. Usa una política personalizada cuando el comportamiento dependa de tus herramientas, rutas, comandos, entornos o reglas de operación. Consulta primero el paquete de políticas de Failproof AI para no recrear un control que ya existe.

Crear una política personalizada

Panel de administración
CLI

Ve a Admin → editor de políticas, selecciona Nueva política y describe el fallo que deseas prevenir.
Añade el código fuente de la política, luego prueba coincidencias esperadas y no coincidencias seguras en el editor. Resuelve todos los errores de validación.
Guarda el borrador y selecciona Publicar versión para crear una versión inmutable.
Ve a Admin → enforcement, despliega la versión en una máquina de prueba en modo observe y verifica sus decisiones en Observe → policy antes de aplicarla.

Crea .failproofai/policies/checkout-policies.ts. El nombre del archivo debe terminar en policies.js, policies.mjs o policies.ts.
Registra una o más políticas con customPolicies.add().
Valida e instala el archivo con failproofai policies --install --custom ./.failproofai/policies/checkout-policies.ts --scope project.
Activa una acción que coincida y una acción segura. Ejecuta failproofai policies y luego examina las decisiones atribuidas en Observe → policy.

Empieza con una regla específica

Esta política bloquea comandos destructivos de Kubernetes únicamente cuando el comando apunta a producción. Todo lo que quede fuera de ese patrón de fallo exacto devuelve allow().

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

const DESTRUCTIVE_KUBECTL = /\bkubectl\s+(delete|replace)\b/i;
const PRODUCTION_TARGET = /(?:--context|--namespace|-n)\s+(prod|production)\b/i;

customPolicies.add({
  name: "block-destructive-production-kubectl",
  description: "Block destructive Kubernetes commands against production",
  match: { events: ["PreToolUse"] },
  fn: async ({ toolName, toolInput }) => {
    if (toolName !== "Bash") return allow();

    const command = String(toolInput?.command ?? "");
    if (!DESTRUCTIVE_KUBECTL.test(command)) return allow();
    if (!PRODUCTION_TARGET.test(command)) return allow();

    return deny(
      "Destructive production Kubernetes commands require the approved deployment workflow.",
    );
  },
});

Las buenas políticas son lo suficientemente específicas como para explicarlas en una sola frase. Evalúa la acción observable —no la intención que esperas que el agente tuviera— y devuelve allow() en cuanto la regla no aplique.

Elige una decisión

Helper	Resultado	Úsalo cuando
`allow(reason?)`	La operación continúa.	La política no aplica o la acción es segura.
`instruct(reason)`	La operación continúa con orientación cuando el harness lo soporta.	Quieres guiar al agente hacia un mejor enfoque sin imponer una restricción.
`deny(reason)`	La operación se bloquea cuando el evento y el harness admiten el bloqueo.	La acción no debe continuar.

Escribe el motivo pensando en el agente que debe recuperarse. Explica qué se detectó y qué debe hacer en su lugar.

No uses instruct() como límite de seguridad. La entrega de orientación varía según el harness del agente. Usa deny() cuando la acción deba prevenirse.

Objeto de política

customPolicies.add({
  name: "policy-name",
  description: "What this policy prevents",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => allow(),
});

Campo	Obligatorio	Descripción
`name`	Sí	Identificador estable de la política. Mantén los nombres únicos entre archivos.
`description`	No	Propósito legible que se muestra en los listados de políticas y en las decisiones.
`match.events`	No	Tipos de eventos que invocan la política. Omitir `match` la invoca para todos los eventos disponibles.
`fn`	Sí	Función síncrona o asíncrona que devuelve un resultado `allow`, `instruct` o `deny`.

Filtra las herramientas dentro de fn. match.toolNames no forma parte del tipo público de política personalizada.

Contexto de política

Cada política recibe un PolicyContext.

Campo	Tipo	Qué contiene
`eventType`	`HookEventType`	Evento normalizado que se está evaluando actualmente.
`toolName`	`string \| undefined`	Nombre canónico de la herramienta, como `Bash`, `Read`, `Write` o `Edit`.
`toolInput`	`Record<string, unknown> \| undefined`	Entrada canónica para la llamada de herramienta actual.
`payload`	`Record<string, unknown>`	Carga útil completa del evento normalizado.
`session`	`SessionMetadata \| undefined`	ID de sesión, directorio de trabajo, ruta del transcript, modo de permisos y metadatos del harness cuando están disponibles.
`cli`	`string \| undefined`	Harness del agente de origen, como `claude`, `codex` o `cursor`.
`params`	`Record<string, unknown>`	Parámetros de política integrados. Las políticas personalizadas reciben actualmente un objeto vacío.

Trata cada valor opcional como genuinamente opcional. Las versiones de agentes y los tipos de eventos no proporcionan siempre los mismos campos.

Entradas comunes de herramientas

Failproof AI normaliza las herramientas comunes entre los harnesses compatibles para que una política pueda usar generalmente una única forma de entrada.

Herramienta	Campos comunes
`Bash`	`command`
`Read`	`file_path`
`Write`	`file_path`, `content`
`Edit`	`file_path`, `old_string`, `new_string`
`Grep`	`pattern`, `path`

Usa coerción defensiva porque los valores de entrada de las herramientas están tipados como unknown:

const command = String(ctx.toolInput?.command ?? "");
const filePath = String(ctx.toolInput?.file_path ?? "");

Elige el evento

Evento	Cuándo se ejecuta	Uso típico
`PreToolUse`	Antes de que se ejecute una herramienta.	Bloquear o guiar comandos, escrituras, lecturas y acciones externas.
`PostToolUse`	Después de que una herramienta devuelva resultado.	Inspeccionar resultados antes de que lleguen al agente. Un deny bloquea todo el resultado; no redacta campos seleccionados.
`PermissionRequest`	Cuando el agente solicita permiso.	Aplicar reglas de permisos específicas de la organización.
`UserPromptSubmit`	Antes de que continúe un prompt enviado.	Rechazar instrucciones prohibidas o añadir orientación sobre el flujo de trabajo.
`Stop`	Cuando el agente intenta finalizar.	Requerir una condición de finalización alcanzable, como un paso de verificación local.
`SubagentStop`	Cuando un subagente intenta finalizar.	Supervisar el trabajo delegado antes de que vuelva al agente padre.
`SessionStart` / `SessionEnd`	En los límites de sesión.	Registrar o verificar el estado a nivel de sesión.

La disponibilidad de eventos y el comportamiento de bloqueo dependen del harness del agente. Consulta Harnesses de agentes antes de depender de un evento en una flota mixta.

Todos los nombres de eventos de política

SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure, Notification, SubagentStart, SubagentStop, TaskCreated, TaskCompleted, Stop, StopFailure, TeammateIdle, InstructionsLoaded, ConfigChange, CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove, PreCompact, PostCompact, Elicitation, ElicitationResult, UserPromptExpansion, PostToolBatch y Setup.

Patrones comunes de políticas

Bloquear escrituras en rutas protegidas

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

customPolicies.add({
  name: "block-generated-file-edits",
  description: "Require generated files to be changed through their generator",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();

    const filePath = String(ctx.toolInput?.file_path ?? "");
    if (!/(^|\/)(dist|generated)\//.test(filePath)) return allow();

    return deny("Edit the source and run the generator instead of changing generated output.");
  },
});

Proporcionar orientación sin bloquear

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

customPolicies.add({
  name: "prefer-reviewed-deploy-command",
  description: "Guide agents toward the reviewed deployment wrapper",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolName !== "Bash") return allow();

    const command = String(ctx.toolInput?.command ?? "");
    if (!/^kubectl\s+apply\b/.test(command.trim())) return allow();

    return instruct("Use ./scripts/deploy-reviewed instead of invoking kubectl directly.");
  },
});

Controlar la finalización de la sesión

import { execFileSync } from "node:child_process";
import { customPolicies, allow, deny } from "failproofai";

customPolicies.add({
  name: "require-clean-typecheck",
  description: "Require the project typecheck to pass before the agent finishes",
  match: { events: ["Stop"] },
  fn: async (ctx) => {
    const cwd = ctx.session?.cwd;
    if (!cwd) return allow();

    try {
      execFileSync("bunx", ["tsc", "--noEmit"], {
        cwd,
        stdio: "ignore",
        timeout: 8_000,
      });
      return allow();
    } catch {
      return deny("Fix the typecheck errors before finishing the task.");
    }
  },
});

Un evento Stop denegado puede hacer que el agente reintente. Solo condiciona la finalización a una condición que el agente pueda satisfacer en el entorno actual, y limita el tiempo de ejecución de cada subproceso o llamada de red.

Cargar archivos de política

Archivos por convención

Los archivos por convención se cargan automáticamente:

<project>/.failproofai/policies/security-policies.ts
~/.failproofai/policies/personal-policies.mjs

Los directorios de políticas del proyecto y del usuario se cargan ambos.
Los archivos se cargan en orden alfabético dentro de cada directorio.
Un archivo debe terminar en policies.js, policies.mjs o policies.ts.
Se admiten múltiples llamadas a customPolicies.add() en un mismo archivo.
Se admiten importaciones relativas desde módulos locales.
Las políticas del proyecto pueden incluirse en el repositorio para que las mismas reglas acompañen al código.

Archivos explícitos

Usa rutas explícitas cuando la validación o la configuración deba nombrar directamente el archivo de entrada:

failproofai policies --install \
  --custom ./security.policies.ts \
  --custom ./workflow.policies.ts \
  --scope project

Los archivos explícitos se cargan primero, seguidos de los archivos de convención del proyecto y luego los del usuario. Un archivo descubierto por ambas rutas se carga una sola vez.

Validar y probar

La validación ejecuta el módulo a través del cargador de producción y confirma que registra al menos una política.

failproofai policies --install \
  --custom ./.failproofai/policies/checkout-policies.ts \
  --scope project
failproofai policies

La validación detecta archivos faltantes, errores de sintaxis, importaciones no resueltas, excepciones en el nivel superior y tiempos de espera en la carga del módulo. No verifica que tu lógica de coincidencia sea correcta. Prueba al menos estos casos:

Una acción que deba coincidir y producir el motivo de política previsto.
Una acción cercana pero segura que deba devolver allow().
Campos de herramienta faltantes o mal formados.
Sintaxis de comando alternativa, rutas, comillas, mayúsculas/minúsculas y espacios en blanco.
Un subproceso o dependencia de red no disponible.

Atribuye el resultado a tu política personalizada en Observe → policy. Un test bloqueado no es suficiente si fue una política integrada diferente la que tomó la decisión.

Comportamiento en tiempo de ejecución

Las políticas integradas se evalúan antes que las políticas personalizadas.
El primer deny detiene la evaluación de las políticas restantes.
Múltiples resultados instruct pueden combinarse cuando ninguna política deniega el evento.
Una función de política tiene un límite de ejecución de 10 segundos.
Una excepción lanzada o un tiempo de espera agotado se registran y se tratan como allow().
Un archivo de convención que no se carga correctamente se omite; los demás archivos personalizados y las políticas integradas continúan.
La carga del módulo en el nivel superior también tiene un límite de 10 segundos.
El modo observe en la nube ejecuta la política pero registra una decisión que no sea allow sin aplicarla.

Mantén los módulos de política deterministas y rápidos. Evita llamadas de red o inicios de servidor en el nivel superior. Limita el trabajo dentro de fn, captura los fallos de dependencias y decide deliberadamente si ese fallo debe permitir o bloquear la operación.

Exportaciones de la API

Exportación	Propósito
`customPolicies.add(policy)`	Registrar una política personalizada al cargar el módulo.
`allow(reason?)`	Permitir la operación.
`instruct(reason)`	Permitir la operación y proporcionar orientación donde se admita.
`deny(reason)`	Bloquear la operación donde se admita.
`getCustomHooks()`	Devolver las políticas actualmente registradas en el registro del módulo.
`clearCustomHooks()`	Limpiar ese registro, principalmente para pruebas y cargadores.

TypeScript exporta PolicyContext, PolicyResult, CustomHook, PolicyDecision y PolicyFunction.

Implementar políticas personalizadas

Publica una versión, impleméntala en modo observe, verifica las decisiones y pasa a la aplicación.

Connect your agents

Reference

Políticas personalizadas

Crear una política personalizada

Empieza con una regla específica

Elige una decisión

Objeto de política

Contexto de política

Entradas comunes de herramientas

Elige el evento

Patrones comunes de políticas

Bloquear escrituras en rutas protegidas

Proporcionar orientación sin bloquear

Controlar la finalización de la sesión

Cargar archivos de política

Archivos por convención

Archivos explícitos

Validar y probar

Comportamiento en tiempo de ejecución

Exportaciones de la API

Implementar políticas personalizadas

​Crear una política personalizada

​Empieza con una regla específica

​Elige una decisión

​Objeto de política

​Contexto de política

​Entradas comunes de herramientas

​Elige el evento

​Patrones comunes de políticas

​Bloquear escrituras en rutas protegidas

​Proporcionar orientación sin bloquear

​Controlar la finalización de la sesión

​Cargar archivos de política

​Archivos por convención

​Archivos explícitos

​Validar y probar

​Comportamiento en tiempo de ejecución

​Exportaciones de la API

Implementar políticas personalizadas

Crear una política personalizada

Empieza con una regla específica

Elige una decisión

Objeto de política

Contexto de política

Entradas comunes de herramientas

Elige el evento

Patrones comunes de políticas

Bloquear escrituras en rutas protegidas

Proporcionar orientación sin bloquear

Controlar la finalización de la sesión

Cargar archivos de política

Archivos por convención

Archivos explícitos

Validar y probar

Comportamiento en tiempo de ejecución

Exportaciones de la API