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 un agente trabaja. Una política puede permitir una acción, proporcionar orientación al agente o denegar la acción antes de que provoque otro incidente. Usa una política personalizada cuando el comportamiento depende de tus herramientas, rutas, comandos, entornos o reglas operativas. Consulta primero el catálogo de políticas integradas para no recrear un control existente.

Crear una política personalizada

Dashboard
CLI

Ve a Admin → editor de políticas, selecciona Nueva política y describe el fallo que quieres 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 → cumplimiento, despliega la versión en una máquina de prueba en modo observación y verifica sus decisiones en Observar → política 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 e inspecciona las decisiones atribuidas en Observar → política.

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 explicarse en una sola frase. Evalúa la acción observable —no la intención que esperas que haya tenido el agente— y devuelve allow() en cuanto la regla no sea aplicable.

Elige una decisión

Función	Resultado	Úsala 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 donde el harness lo admita.	Quieres guiar al agente hacia un mejor enfoque sin imponer una restricción estricta.
`deny(reason)`	La operación se bloquea cuando el evento y el harness admiten el bloqueo.	La acción no debe ejecutarse.

Escribe la razón pensando en el agente que debe recuperarse. Explica qué se detectó y qué debería 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 ser prevenida.

Objeto de política

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

Campo	Requerido	Descripción
`name`	Sí	Identificador estable para la política. Mantén los nombres únicos entre archivos.
`description`	No	Propósito legible por humanos, mostrado en los listados de políticas y 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 herramientas dentro de fn. match.toolNames no forma parte del tipo público de política personalizada.

Contexto de la política

Toda política recibe un PolicyContext.

Campo	Tipo	Contenido
`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 a la herramienta actual.
`payload`	`Record<string, unknown>`	Carga útil completa del evento normalizado.
`session`	`SessionMetadata \| undefined`	ID de sesión, directorio de trabajo, ruta de transcripción, 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íticas integradas. 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 siempre proporcionan los mismos campos.

Entradas comunes de herramientas

Failproof AI normaliza las herramientas más comunes entre los harnesses compatibles, de modo que una política generalmente puede usar una sola 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 retorna.	Inspeccionar resultados antes de que lleguen al agente. Un deny bloquea el resultado completo; 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 de flujo de trabajo.
`Stop`	Cuando el agente intenta finalizar.	Exigir una condición de finalización alcanzable, como un paso de verificación local.
`SubagentStop`	Cuando un subagente intenta finalizar.	Controlar el trabajo delegado antes de que retorne al 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 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 impone condiciones que el agente pueda satisfacer en el entorno actual, y limita el tiempo de todo subproceso o llamada de red.

Cargar archivos de políticas

Archivos de convención

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

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

Se cargan tanto el directorio de políticas del proyecto como el del usuario.
Los archivos se cargan alfabéticamente dentro de cada directorio.
El nombre del 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 sigan al código.

Archivos explícitos

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

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 sin resolver, excepciones en el nivel superior y tiempos de espera de 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 esperado.
Una acción cercana pero segura que deba devolver allow().
Campos de herramienta faltantes o malformados.
Sintaxis de comandos 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 Observar → política. Una prueba bloqueada 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 políticas posteriores.
Múltiples resultados instruct pueden combinarse cuando ninguna política deniega el evento.
Una función de política tiene un plazo de ejecución de 10 segundos.
Una excepción lanzada o un tiempo de espera agotado se registra y se trata como allow().
Un archivo de convención que falla al cargar 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 plazo de 10 segundos.
El modo de observación en la nube ejecuta la política pero registra una decisión que no es allow sin aplicarla.

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

Exportaciones de la API

Exportación	Propósito
`customPolicies.add(policy)`	Registra una política personalizada cuando se carga el módulo.
`allow(reason?)`	Permite la operación.
`instruct(reason)`	Permite la operación y proporciona orientación donde sea compatible.
`deny(reason)`	Bloquea la operación donde sea compatible.
`getCustomHooks()`	Devuelve las políticas actualmente registradas en el registro del módulo.
`clearCustomHooks()`	Limpia 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 observación, 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 la 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 sesión

Cargar archivos de políticas

Archivos de 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 la 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 sesión

​Cargar archivos de políticas

​Archivos de 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 la 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 sesión

Cargar archivos de políticas

Archivos de convención

Archivos explícitos

Validar y probar

Comportamiento en tiempo de ejecución

Exportaciones de la API