Arquitectura

Este documento explica cómo funciona failproofai internamente: cómo el sistema de hooks intercepta las llamadas a herramientas del agente, cómo se carga y fusiona la configuración, cómo se evalúan las políticas y cómo el panel de control monitorea la actividad del agente.

Descripción general

failproofai tiene dos subsistemas independientes:

Manejador de hooks - Un subproceso CLI rápido que Claude Code invoca en cada llamada a herramienta del agente. Evalúa las políticas y devuelve una decisión.
Monitor de agentes (Panel de control) - Una aplicación web Next.js para monitorear sesiones del agente y gestionar políticas.

Ambos subsistemas comparten archivos de configuración en ~/.failproofai/ y el directorio .failproofai/ del proyecto, pero se ejecutan como procesos separados y se comunican únicamente a través del sistema de archivos.

Manejador de hooks

Integración con Claude Code

Cuando ejecutas failproofai policies --install, escribe entradas como esta en ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "failproofai --hook PreToolUse"
          }
        ]
      }
    ],
    "PostToolUse": [ ... ]
  }
}

Claude Code entonces invoca failproofai --hook PreToolUse como subproceso antes de cada llamada a herramienta, pasando un payload JSON por stdin.

Formato del payload

{
  "session_id": "abc123",
  "transcript_path": "/home/user/.claude/projects/myproject/sessions/abc123.jsonl",
  "cwd": "/home/user/myproject",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "sudo apt install nodejs" }
}

Para eventos PostToolUse, el payload también contiene tool_result con la salida de la herramienta. El manejador impone un límite de 1 MB en stdin. Los payloads que superen este límite se descartan y todas las políticas permiten implícitamente.

Formato de respuesta

Denegar (PreToolUse):

{
  "hookSpecificOutput": {
    "permissionDecision": "deny",
    "permissionDecisionReason": "Blocked by failproofai: sudo command blocked"
  }
}

Denegar (PostToolUse):

{
  "hookSpecificOutput": {
    "additionalContext": "Blocked by failproofai because: API key detected in output"
  }
}

Instruir (cualquier evento excepto Stop):

{
  "hookSpecificOutput": {
    "additionalContext": "Instruction from failproofai: Verify tests pass before committing."
  }
}

Instruir en evento Stop:

Código de salida: 2
El motivo se escribe en stderr (no en stdout)

Permitir:

Código de salida: 0
stdout vacío

Permitir con mensaje: allow(message) permite que una política envíe contexto informativo de vuelta a Claude incluso cuando la operación está permitida. El manejador de hooks escribe el siguiente JSON en stdout (no en un archivo de configuración — esta es la respuesta del manejador a Claude Code, igual que las respuestas de deny e instruct anteriores):

// Written to stdout by the hook handler process
{
  "hookSpecificOutput": {
    "additionalContext": "All CI checks passed on branch 'feat/my-feature'."
  }
}

Código de salida: 0 (la operación está permitida)
Cuando varias políticas devuelven allow con un mensaje, sus mensajes se unen con saltos de línea en una única cadena additionalContext
Si ninguna política proporciona un mensaje, stdout está vacío (igual que antes)

Pipeline de procesamiento

src/hooks/handler.ts implementa el pipeline completo:

stdin JSON
  → parsear payload (máx. 1 MB)
  → extraer metadatos de sesión (session_id, cwd, tool_name, tool_input, etc.)
  → readMergedHooksConfig(cwd)    ← fusiona configuración de proyecto + local + global
  → registrar políticas integradas habilitadas con parámetros resueltos
  → cargar políticas personalizadas desde customPoliciesPath (si está definido)
  → registrar políticas personalizadas en el registro de políticas
  → evaluar todas las políticas (primero las integradas, luego las personalizadas)
      → el primer deny cortocircuita la evaluación
      → las decisiones instruct se acumulan
      → los mensajes allow se acumulan
  → escribir decisión JSON en stdout
  → persistir evento en ~/.failproofai/hook-activity.jsonl
  → salir

Todo el proceso se ejecuta en menos de 100ms para payloads típicos sin llamadas a LLM.

Carga de configuración

src/hooks/hooks-config.ts implementa la carga de configuración en tres alcances.

[1] {cwd}/.failproofai/policies-config.json        ← proyecto  (mayor prioridad)
[2] {cwd}/.failproofai/policies-config.local.json  ← local
[3] ~/.failproofai/policies-config.json             ← global    (menor prioridad)

Lógica de fusión:

enabledPolicies - unión deduplicada de los tres archivos
policyParams - por clave de política, gana completamente el primer archivo que la define
customPoliciesPath - gana el primer archivo que la define
llm - gana el primer archivo que lo define

El panel de control web utiliza readHooksConfig() (solo global) para leer y escribir, ya que no se invoca con un cwd de proyecto.

Evaluación de políticas

src/hooks/policy-evaluator.ts ejecuta las políticas en orden. Para cada política:

Buscar el esquema params de la política (si tiene uno).
Leer policyParams[policy.name] de la configuración fusionada.
Combinar los valores proporcionados por el usuario sobre los valores por defecto del esquema para producir ctx.params.
Llamar a policy.fn(ctx) con el contexto resuelto.
Si el resultado es deny, detener inmediatamente y devolver esa decisión.
Si el resultado es instruct, acumular el mensaje y continuar.
Si el resultado es allow, continuar con la siguiente política.

Después de ejecutar todas las políticas:

Si se devolvió algún deny, emitir la respuesta de denegación.
Si se recopilaron respuestas instruct, emitir una única respuesta instruct con todos los mensajes unidos.
En caso contrario, emitir una respuesta allow (stdout vacío, salida 0).

Políticas integradas

src/hooks/builtin-policies.ts define las 39 políticas integradas como objetos BuiltinPolicyDefinition:

interface BuiltinPolicyDefinition {
  name: string;
  description: string;
  fn: (ctx: PolicyContext) => PolicyResult;
  match: {
    events: HookEventType[];
    tools?: string[];
  };
  defaultEnabled: boolean;
  category: string;
  beta?: boolean;
  params?: PolicyParamsSchema;
}

Las políticas que aceptan params declaran un PolicyParamsSchema con tipos y valores por defecto para cada parámetro. El evaluador de políticas inyecta los valores resueltos en ctx.params antes de llamar a fn. Las funciones de política leen ctx.params sin comprobaciones de nulidad porque los valores por defecto siempre se aplican primero. La coincidencia de patrones dentro de las políticas utiliza tokens de comando parseados (argv), no coincidencia de cadenas sin procesar. Esto evita que se omitan mediante inyección de operadores de shell (por ejemplo, un patrón para sudo systemctl status * no puede ser evadido añadiendo ; rm -rf / al comando).

Políticas personalizadas

src/hooks/custom-hooks-registry.ts implementa un registro respaldado por globalThis:

const REGISTRY_KEY = "__failproofai_custom_hooks__";

export const customPolicies = {
  add(hook: CustomHook): void { ... }
};

export function getCustomHooks(): CustomHook[] { ... }
export function clearCustomHooks(): void { ... }  // used in tests

src/hooks/custom-hooks-loader.ts carga el archivo de políticas del usuario:

Leer customPoliciesPath de la configuración; omitir si no está presente.
Resolver a ruta absoluta; comprobar que el archivo existe.
Reescribir todas las importaciones from "failproofai" a la ruta dist real para que customPolicies resuelva al mismo registro globalThis.
Reescribir recursivamente las importaciones locales transitivas para garantizar compatibilidad con ESM.
Escribir archivos .mjs temporales e importar el archivo de entrada con import().
Llamar a getCustomHooks() para recuperar los hooks registrados.
Limpiar todos los archivos temporales en un bloque finally.

Ante cualquier error (archivo no encontrado, error de sintaxis, fallo de importación), el error se registra en ~/.failproofai/hook.log y el cargador devuelve un array vacío. Las políticas integradas no se ven afectadas. Las políticas personalizadas se evalúan después de todas las políticas integradas. Un deny de una política personalizada sigue cortocircuitando las políticas personalizadas posteriores (pero en ese punto todos los integrados ya se han ejecutado).

Registro de actividad

Después de cada evento de hook, el manejador añade una línea JSONL a ~/.failproofai/hook-activity.jsonl:

{
  "timestamp": "2026-04-06T12:34:56.789Z",
  "sessionId": "abc123",
  "eventType": "PreToolUse",
  "toolName": "Bash",
  "policyName": "block-sudo",
  "decision": "deny",
  "reason": "sudo command blocked by failproofai",
  "durationMs": 12
}

Una línea por política que tomó una decisión distinta de allow. Las decisiones allow no se registran (para mantener el archivo pequeño).

Arquitectura del panel de control

El panel de control es una aplicación Next.js 16 que utiliza el App Router con React Server Components y Server Actions.

app/
  layout.tsx                  ← Layout raíz (tema, telemetría, navegación)
  projects/page.tsx           ← Componente de servidor: lista todos los proyectos de Claude
  project/[name]/page.tsx     ← Componente de servidor: lista sesiones de un proyecto
  project/[name]/session/
    [sessionId]/page.tsx      ← Componente de servidor: renderiza el visor de sesión
  policies/page.tsx           ← Componente de cliente: gestión de políticas + registro de actividad
  actions/
    get-hooks-config.ts       ← Leer configuración + lista de políticas
    update-hooks-config.ts    ← Activar/desactivar política
    update-policy-params.ts   ← Actualizar parámetros de política
    get-hook-activity.ts      ← Paginar/buscar en el registro de actividad
    install-hooks-web.ts      ← Instalar/eliminar hooks desde el navegador
  api/
    download/[project]/[session]/route.ts   ← Exportación de sesión por CLI (JSONL o JSON)

Flujo de datos:

Los componentes de página llaman a lib/projects.ts y lib/log-entries.ts para leer datos de proyectos/sesiones directamente desde el sistema de archivos (sin capa API para las lecturas).
La página de políticas utiliza Server Actions para todas las mutaciones (activar/desactivar, actualizar parámetros, instalar/eliminar).
El visor de sesión parsea el formato de transcripción JSONL de Claude y renderiza una línea de tiempo de mensajes y llamadas a herramientas.

Decisiones de diseño clave:

Sin base de datos: todo el estado persistente está en archivos planos (~/.failproofai/, ~/.claude/projects/).
Server Actions para mutaciones: no se necesita API REST para operaciones CRUD.
React Server Components para páginas de lectura: carga inicial más rápida, sin bundle de cliente para la obtención de datos.
Componentes de cliente solo donde se necesita interactividad (toggles de políticas, búsqueda de actividad, visor de logs).

Estructura de archivos

failproofai/
├── bin/
│   └── failproofai.mjs           # Enrutador CLI (hook / dashboard / install / etc.)
├── src/hooks/
│   ├── handler.ts                # Pipeline de eventos de hook
│   ├── builtin-policies.ts       # 39 definiciones de políticas
│   ├── policy-evaluator.ts       # Motor de ejecución de políticas
│   ├── policy-registry.ts        # Registro y búsqueda de políticas
│   ├── policy-types.ts           # Interfaces TypeScript
│   ├── hooks-config.ts           # Carga de configuración multi-alcance
│   ├── custom-hooks-registry.ts  # Registro de hooks respaldado por globalThis
│   ├── custom-hooks-loader.ts    # Cargador ESM para hooks JS del usuario
│   ├── manager.ts                # Operaciones de instalar / eliminar / listar
│   ├── install-prompt.ts         # Prompt interactivo de selección de políticas
│   ├── hook-logger.ts            # Registro en hook.log
│   ├── hook-activity-store.ts    # Persistir actividad en hook-activity.jsonl
│   └── llm-client.ts             # Cliente de API LLM (para políticas con IA)
├── app/                          # Panel de control Next.js (páginas + server actions)
├── lib/                          # Utilidades compartidas
│   ├── projects.ts               # Enumerar proyectos de Claude desde el sistema de archivos
│   ├── log-entries.ts            # Parsear el formato de transcripción JSONL de Claude
│   ├── paths.ts                  # Resolver rutas del sistema
│   └── ...
├── components/                   # Componentes de UI React compartidos
├── contexts/                     # Proveedores de contexto React (tema, auto-refresco, telemetría)
├── examples/                     # Archivos de hooks personalizados de ejemplo
└── __tests__/                    # Tests unitarios y E2E

Primeros pasos

Conceptos principales

CLI

Herramientas

Avanzado

Ejemplos

Descripción general

Manejador de hooks

Integración con Claude Code

Formato del payload

Formato de respuesta

Pipeline de procesamiento

Carga de configuración

Evaluación de políticas

Políticas integradas

Políticas personalizadas

Registro de actividad

Arquitectura del panel de control

Estructura de archivos

​Descripción general

​Manejador de hooks

​Integración con Claude Code

​Formato del payload

​Formato de respuesta

​Pipeline de procesamiento

​Carga de configuración

​Evaluación de políticas

​Políticas integradas

​Políticas personalizadas

​Registro de actividad

​Arquitectura del panel de control

​Estructura de archivos

Descripción general

Manejador de hooks

Integración con Claude Code

Formato del payload

Formato de respuesta

Pipeline de procesamiento

Carga de configuración

Evaluación de políticas

Políticas integradas

Políticas personalizadas

Registro de actividad

Arquitectura del panel de control

Estructura de archivos