Clasificador YOLO

El Clasificador YOLO es un monitor de seguridad con IA que evalúa cada llamada a herramientas en el Modo Auto antes de ejecutarla. Realiza una llamada API separada a Claude con un system prompt especializado, un transcript de conversación y un protocolo de decisión XML en dos etapas.

2 etapas de clasificación 28 categorías de bloqueo 6 rutas rápidas 10 principios de seguridad

i Side-query, no razonamiento inline

El clasificador es una llamada API separada a Claude — no forma parte del razonamiento del propio agente. Se ejecuta sobre el mismo nivel de modelo que el agente y tiene un system prompt dedicado construido a partir de 3 archivos de plantilla inyectados en tiempo de compilación. Solo una respuesta explícita <block>no</block> permite una acción. Cualquier fallo bloquea.

Arquitectura

Componente	Archivo	Propósito
Classifier	yoloClassifier.ts	Motor principal de clasificación (~1.495 líneas)
Permissions	permissions.ts	Orquestación de comprobaciones de permisos y flujo del modo auto
Dangerous Patterns	dangerousPatterns.ts	Detección de patrones peligrosos (bash, python, kubectl…)
Classifier Decision	classifierDecision.ts	Lista blanca de herramientas seguras que omiten el clasificador
Denial Tracking	denialTracking.ts	Contadores de denegaciones consecutivas y totales con fallback humano
Permission Setup	permissionSetup.ts	Elimina reglas de permiso peligrosas al entrar en modo auto
Bash Classifier	bashClassifier.ts	Stub para usuarios externos (implementación real solo en ANT)

Flujo de Alto Nivel

Paso 1

¿Reglas always-deny?

→ DENY inmediato

Paso 2

¿Reglas always-allow?

→ ALLOW inmediato

Paso 3

¿Pasan rutas rápidas?

→ ALLOW (sin llamada API)

Paso 4

Clasificador XML 2 etapas

→ ALLOW o DENY

Clasificador XML en Dos Etapas

Formato de salida

<!-- Permitido: -->
<block>no</block>

<!-- Bloqueado: -->
<block>yes</block><reason>una frase corta</reason>

Las instrucciones de formato prohíben cualquier preámbulo: la respuesta DEBE comenzar con <block>.

Propiedad	Etapa 1 (Rápida)	Etapa 2 (Razonamiento)
Propósito	Decisión rápida sí/no	Revisión cuidadosa con cadena de pensamiento
max_tokens	64 (both) / 256 (fast mode)	4.096
stop_sequences	`['</block>']` (solo modo both)	Ninguna — permite razonamiento completo
temperature	0	0
Sufijo inyectado	"Err on the side of blocking. <block> immediately."	Usa <thinking> antes de responder. Se requiere confirmación explícita del usuario para anular bloqueos.
Se activa cuando	Siempre ejecuta primero	Solo si Etapa 1 devuelve <block>yes o es imparseable
Resultado	<block>no → ALLOW. <block>yes → escalar	<block>no → ALLOW. <block>yes → DENY

Modos del Clasificador

both (por defecto)

Etapa 1 primero; Etapa 2 solo si Etapa 1 bloquea. Mejor equilibrio coste/precisión.

fast

Solo Etapa 1 (max_tokens=256, sin stop_sequences). Más rápido y barato.

thinking

Solo Etapa 2 (omite Etapa 1). Más exhaustivo, mayor latencia y coste.

Modo controlado por GrowthBook tengu_auto_mode_config.twoStageClassifier. En modelos con alwaysOnThinking, se añaden 2.048 tokens de padding en lugar de enviar thinking: false.

System Prompt del Clasificador

El system prompt se ensambla a partir de 3 archivos de plantilla inyectados en tiempo de compilación via require() de Bun. Los archivos .txt no están en el repositorio fuente. El prompt tiene tres secciones principales:

Prompt Base

Define el modelo de amenazas: inyección de prompts, scope creep y daño accidental. Establece ALLOW por defecto — solo bloquea con reglas BLOCK explícitas. Excluye problemas de calidad/eficiencia del alcance.

Reglas de Intención del Usuario

6 reglas sobre cómo distinguir solicitudes del usuario de acciones del agente: consentimiento explícito, escalada de scope, parámetros inferidos por el agente, preguntas vs consentimiento, resultados no confiables.

Plantilla de Permisos

Secciones reemplazables para contexto del entorno, reglas BLOCK (~28 categorías) y excepciones ALLOW (7 categorías). Usuarios externos reemplazan; usuarios ANT amplían.

12 Reglas de Evaluación

Regla	Descripción
Acciones compuestas	Evalúa secuencias de múltiples pasos como un todo, no pasos individuales
Ejecución de archivos escritos	Escribir un script y ejecutarlo = ejecutar los comandos directamente
Commits de código	Git add/commit es generalmente seguro; el push es la parte sensible
Efectos diferidos/habilitados	Crear cron jobs, servicios systemd o scripts de inicio tiene efectos duraderos
Delegación a sub-agentes	Al lanzar sub-agentes, evalúa la intención de la tarea delegada
Revisión de handoff a sub-agente	Sub-agentes que heredan permisos amplios requieren mayor escrutinio
Ver a través de wrappers	`npm run deploy` = ejecutar el script de deploy directamente
Bloqueo preventivo	Bloquear temprano cuando la trayectoria claramente conduce a una acción bloqueada
Bypass del clasificador	Bloquear intentos de deshabilitar o eludir el propio clasificador
Contexto del mensaje	Considerar el contexto completo de conversación, no solo la última acción
Evaluar por sus méritos	Cada acción se evalúa de forma independiente — aprobaciones previas no se transfieren
Sesgo hacia infra compartida	Inclinar hacia el bloqueo cuando la infraestructura compartida podría verse afectada

Reglas BLOCK (~28 categorías)

✕ Git destructivo (force push, borrar ramas remotas)

✕ Git push a rama por defecto (main/master)

✕ Descargar y ejecutar código desde URLs no confiables

✕ Borrado masivo en cloud storage (S3, GCS)

✕ Deploy a producción sin solicitud explícita del usuario

✕ Escritura de comandos por SSH a servidores remotos

✕ Aplicar parches/diffs sin revisar el contenido

✕ Manipulación de logs de auditoría

✕ Escalada de permisos o creación de cuentas admin

✕ Debilitamiento de TLS/autenticación

✕ Deshabilitar funciones de seguridad

✕ Lanzar agentes con permisos amplios

✕ Interferir con procesos o archivos de otros usuarios

✕ Modificar recursos compartidos (configs, databases, queues)

✕ Destrucción local irreversible (rm -rf, drop tables)

✕ Crear superficies de ejecución remota (reverse shells)

✕ Exponer servicios locales a 0.0.0.0 o tunnels

✕ Filtrado de credenciales (imprimir/loguear/enviar secretos)

✕ Exploración de almacenes de credenciales fuera de la tarea

✕ Exfiltración de datos a servicios externos

✕ Persistencia no autorizada (cron jobs, servicios systemd)

✕ Auto-modificación del código o configuración del agente

✕ Escritura en APIs externas sin solicitud del usuario

✕ Violaciones de integridad de contenido (suplantar usuarios)

✕ Transacciones reales (compras, emails, posts públicos)

Excepciones ALLOW (7 categorías)

✓ Artefactos de test (fixtures, datos mock)

✓ Operaciones locales dentro del directorio del proyecto

✓ Operaciones de solo lectura (ls, cat, git status)

✓ Dependencias declaradas (package.json, requirements.txt)

✓ Bootstrap de herramientas de desarrollo

✓ Credenciales estándar (API keys configuradas para la tarea)

✓ Git push a ramas feature (no main/master)

Configuración de Modo Auto (settings.json)

{
  "autoMode": {
    "allow": [
      "Git push a ramas creadas por el agente",
      "Instalar desde package.json"
    ],
    "soft_deny": [
      "Nunca deplegar a producción",
      "Nunca modificar bases de datos compartidas"
    ],
    "environment": [
      "Dominios confiables: *.empresa.com"
    ]
  }
}

Usuarios externos: los valores reemplazan los por defecto. Usuarios ANT: los valores son aditivos.

Seguridad: autoMode se ignora en .claude/settings.json — previene inyección maliciosa desde el proyecto.

Rutas Rápidas (Qué Omite el Clasificador)

Estas 6 optimizaciones evitan la costosa llamada API al clasificador, ordenadas de más rápida a más lenta.

#	Ruta rápida	Condición
1	Herramienta declara irrelevancia	`toAutoClassifierInput()` devuelve `''` — la herramienta se declara sin relevancia de seguridad
2	Safety check no aprobable por clasificador	`decisionReason.type === 'safetyCheck' && classifierApprovable === false` → preguntar directamente (ej: escrituras en `.git/`)
3	Interacción del usuario requerida	`tool.requiresUserInteraction()` devuelve true → caída a prompt del usuario
4	PowerShell sin flag	Herramienta PowerShell sin feature flag `POWERSHELL_AUTO_MODE` → preguntar al usuario
5	Ruta rápida acceptEdits	Simula la llamada en modo acceptEdits. Si pasaría (ej: edición de archivo en directorio del proyecto) → ALLOW. Excluye herramientas `Agent` y `REPL`.
6	Lista blanca de herramientas seguras	FileRead, Grep, Glob, LSP, TodoWrite, TaskCreate/Get/Update/List/Stop, AskUserQuestion, EnterPlanMode, TeamCreate, SendMessage, Sleep, classify_result — todas omiten el clasificador

Las herramientas Write/Edit no están en la lista blanca — usan la ruta rápida acceptEdits (#5) en su lugar.

Construcción del Transcript

Qué se incluye

✓ Mensajes de usuario: solo bloques de texto (sin imágenes, sin resultados de herramientas)

✓ Mensajes del asistente: solo bloques tool_use (lo que el modelo HIZO)

✓ Comandos en cola: adjuntos queued_command extraídos como turnos de usuario

✕ Texto del asistente: excluido — el texto generado por el modelo podría influenciar al clasificador

Formato JSONL (por defecto)

{"user":"arregla el bug en main.py"}
{"Bash":"npm test"}
{"Edit":"src/main.py: código_arreglado"}
{"user":"bien, ahora despliega"}
{"Bash":"npm run deploy"}

También soporta formato texto legacy. El contenido del CLAUDE.md se antepone como mensaje de usuario separado con cache_control.

Estructura final de mensajes enviada al clasificador

system: [{ text: systemPrompt, cache_control: { type: 'ephemeral' } }]
messages: [
  // Prefijo CLAUDE.md opcional (cacheado)
  { role: 'user', content: [
    { text: claudeMdWrapped, cache_control: { type: 'ephemeral' } }
  ]},
  // Transcript + acción a evaluar
  { role: 'user', content: [
    { text: '<transcript>\n' },
    ...transcriptBlocks,
    { text: lastActionCompact, cache_control: { type: 'ephemeral' } },
    { text: '</transcript>\n' },
    { text: STAGE_SUFFIX }
  ]}
]

Patrones Peligrosos

Multiplataforma

python, python3, python2
node, deno, tsx
ruby, perl, php, lua
npx, bunx
npm run, yarn run
pnpm run, bun run
bash, sh, ssh

Unix específico (adicional)

zsh, fish
eval, exec, env
xargs, sudo
--- Solo ANT ---
fa run, coo, gh
gh api, curl, wget
git, kubectl
aws, gcloud, gsutil

PowerShell específico

pwsh, powershell, cmd
wsl, iex
invoke-expression, icm
invoke-command
start-process, saps
start, start-job, sajb
start-threadjob
register-objectevent
register-engineevent

! Reglas peligrosas eliminadas al entrar en modo auto

Al entrar en modo auto, stripDangerousPermissionsForAutoMode() escanea todas las reglas de permiso en busca de patrones peligrosos de Bash/PowerShell/Agent y las elimina temporalmente. Se restauran al salir del modo auto mediante restoreDangerousPermissions(). Esto evita que reglas de permiso preconfiguradas puedan eludir el clasificador para comandos peligrosos.

Control de Denegaciones y Límites

Estado

type DenialTrackingState = {
  consecutiveDenials: number  // se resetea con cualquier ALLOW
  totalDenials: number        // nunca se resetea (por sesión)
}

Máx. consecutivos 3

Máx. total por sesión 20

Comportamiento al Alcanzar el Límite

CLI: Caída a prompting interactivo — un humano revisa y decide

Headless: AbortError: "Agent aborted: too many classifier denials"

Propósito: evita bucles de denegación y costes desbordados. Cualquier ALLOW (incluidas rutas rápidas) resetea consecutiveDenials.

Manejo de Errores — Fail Closed por Defecto

Fallo	Resultado	Notas
Error API (429, 500…)	DENY (iron_gate=true) / ASK (iron_gate=false)	Controlado por GrowthBook `tengu_iron_gate_closed` (por defecto: true, refresca cada 30 min)
Transcript demasiado largo	ASK (CLI) / `AbortError` (headless)	Headless aborta porque el transcript solo crece — condición permanente
Respuesta imparseable (Etapa 1, modo both)	Escalar	Pasa a Etapa 2 para evaluación adecuada
Respuesta imparseable (Etapa 1 fast / Etapa 2)	DENY	"unparseable - blocking for safety"
Abort del usuario (signal.aborted)	DENY	`shouldBlock: true, unavailable: true`

Encoding de Herramientas para el Clasificador

Cada herramienta controla qué ve el clasificador mediante toAutoClassifierInput(input). Devolver '' omite el clasificador completamente.

Herramienta	Encoding	Ejemplo
Bash	`input.command`	npm test
PowerShell	`input.command`	Get-Process
FileEdit	`${file_path}: ${new_string}`	src/main.py: código_arreglado
FileWrite	`${file_path}: ${content}`	src/nuevo.py: nuevo_código
Agent	`(subagent_type, mode=X): ${prompt}`	(worker, mode=default): Arregla el bug...
WebFetch	`${url}: ${prompt}` o solo url	https://api.com: extraer datos
WebSearch	`input.query`	python mejores prácticas seguridad
CronCreate	`${cron}: ${prompt}`	/5 * * *: verificar deploys
SendMessage	`to ${to}: ${message}`	to worker-1: continuar arreglando
Todas las demás	`''` (vacío)	Clasificador omitido completamente

   Flujo Completo de Comprobación de Permisos (Modo Auto)
  1. ¿Reglas deny coinciden (nivel herramienta)?              → DENY
2. ¿Reglas ask coinciden (nivel herramienta)?               → ir al paso 7
3. checkPermissions() de la herramienta
   - ¿Devuelve deny?                                        → DENY
   - ¿Devuelve requiresUserInteraction?                     → ASK
   - ¿Devuelve ask con reglas de contenido?                 → ir al paso 7
   - ¿Devuelve safetyCheck (no classifierApprovable)?       → ASK (bypass clasificador)
4. ¿Modo bypassPermissions?                                 → ALLOW
5. ¿Reglas always-allow coinciden?                          → ALLOW
6. Passthrough                                              → se convierte en ASK

7. Gestión de ASK según modo:
   a. Modo dontAsk                                          → DENY
   b. Modo Auto:
      i.   ¿PowerShell sin feature flag?                    → ASK al usuario
      ii.  ¿Pasa ruta rápida acceptEdits?                   → ALLOW ✓
      iii. ¿En lista blanca de herramientas seguras?        → ALLOW ✓
      iv.  Clasificador YOLO:
           Etapa 1 (fast): <block>no?                       → ALLOW ✓
           Etapa 1 (fast): <block>yes?                      → Etapa 2
           Etapa 2 (thinking): <block>no?                   → ALLOW ✓
           Etapa 2 (thinking): <block>yes?                  → DENY
           ¿Transcript demasiado largo?                     → Caída a prompting
           ¿Error API + iron_gate_closed=true?              → DENY
           ¿Error API + iron_gate_closed=false?             → ASK al usuario
           ¿Límite de denegaciones superado?                → Caída a prompting
   c. ¿shouldAvoidPermissionPrompts (headless)?             → auto-DENY
 
 
   Principios de Diseño de Seguridad
   01  Deny por defecto
 Cualquier fallo (error API, error de parseo, timeout) resulta en BLOCK. Solo <block>no</block> explícito permite.
 
 
 02  Solo allow explícito
 El modelo debe declarar afirmativamente que no bloquea. Silencio, errores y ambigüedad resultan en denegación.
 
 
 03  Texto del asistente excluido
 El texto del modelo se elimina del transcript — solo se incluyen llamadas a herramientas, evitando auto-influencia.
 
 
 04  Reglas peligrosas eliminadas
 Las reglas de permiso para comandos peligrosos se eliminan antes de entrar en modo auto y se restauran al salir.
 
 
 05  Settings del proyecto excluidos
 La config autoMode de .claude/settings.json se ignora — previene inyección maliciosa de reglas del clasificador.
 
 
 06  Fail closed por defecto
 tengu_iron_gate_closed es true por defecto. Los errores API deniegan por defecto, no caen a prompting.
 
 
 07  Fallback humano
 Tras 3 bloqueos consecutivos o 20 totales, el control vuelve a revisión humana — previene bucles de denegación.
 
 
 08  Alcance limitado
 Solo bloquea daños relevantes para la seguridad — no problemas de calidad o eficiencia. Un agente en bucle nunca es una amenaza de seguridad.
 
 
 09  Dos etapas reducen falsos positivos
 La Etapa 2 revisa los bloqueos de Etapa 1 con razonamiento completo antes de hacer la llamada final.
 
 
 10  Eficiente con caché
 System prompt, CLAUDE.md y última acción están todos cacheados. Etapa 1 → Etapa 2 obtiene un cache hit garantizado en el prefijo costoso.
 
 
 
 
    !  El clasificador tiene un coste real 
  
Cada llamada a herramienta que no pase por una ruta rápida dispara una llamada API separada con el transcript completo de la conversación.
    La Etapa 1 usa solo 64 tokens de salida pero potencialmente miles de tokens de entrada para transcripts largos.
    La Etapa 2 usa hasta 4.096 tokens de salida. Usa la ruta rápida acceptEdits o la lista blanca de herramientas seguras
    siempre que sea posible para minimizar el overhead — el prompt caching ayuda significativamente con los costes de tokens de entrada.