Anatomía de una Claw: 84 hooks como capa de orquestación

El primer hook tardó cuatro minutos en escribirse. Bloqueaba que el modelo sugiriera productos de OpenAI en un flujo de trabajo exclusivo de Anthropic. Dos meses después, ese único hook se había convertido en 84. Los 84 hooks se conectaban a 43 skills, 19 agentes especializados y 30 módulos de biblioteca. En algún momento, la colección dejó de ser un conjunto de scripts y se convirtió en una capa de orquestación.

Una “Claw” es una capa de orquestación construida sobre el CLI de un agente de IA, que se encarga de la programación de tareas, la gestión de contexto, el enrutamiento de herramientas y la aplicación de estándares de calidad. Crece de forma orgánica a partir de la resolución de fallos individuales, no de un diseño de arriba hacia abajo. La arquitectura se corresponde con cinco funciones que identificó Karpathy, y la separación entre planificación y ejecución emerge como una propiedad natural de los sistemas basados en hooks.

No lo diseñé así. Nadie se sienta y dice “voy a construir 15.000 líneas de infraestructura de agentes”. Resuelves un problema. Luego otro. Luego resuelves el problema de que los problemas interactúan entre sí. Para cuando notas la arquitectura, ya existe.

Andrej Karpathy también lo notó. En febrero de 2026 describió las “Claws” como una nueva capa computacional: orquestación, programación de tareas, gestión de contexto y enrutamiento de herramientas construidos sobre agentes LLM, del mismo modo en que los agentes se construyen sobre los LLM.¹ El encuadre cristalizó algo que los profesionales llevaban tiempo construyendo sin ponerle nombre. Este artículo es la anatomía de uno de esos sistemas: qué contiene, cómo creció, dónde funciona y dónde falla.

TL;DR

La capa “Claws” de Karpathy describe sistemas de orquestación construidos sobre CLIs de agentes. Yo construí uno de forma orgánica durante dos meses sobre Claude Code: 84 hooks repartidos en 15 tipos de eventos, 43 skills, 19 agentes y más de 30 módulos de biblioteca. El sistema se corresponde limpiamente con las cinco funciones de una Claw (orquestación, programación de tareas, gestión de contexto, enrutamiento de herramientas y aplicación de estándares de calidad) con una carencia notable: las definiciones declarativas de flujos de trabajo. Hallazgo clave: la separación entre planificación y ejecución emergió como una propiedad natural de la orquestación basada en hooks, no como un objetivo de diseño. La observación de Lattner de que “el juicio y la abstracción siguen siendo el núcleo mientras la IA automatiza la implementación” se traslada directamente a la arquitectura de hooks: los hooks de gobernanza ejercen el juicio, los hooks de automatización ejecutan la implementación.

La taxonomía de Claws

La descripción de Karpathy identifica cinco funciones que cumple una capa Claws. Cada función tiene un análogo directo en el sistema de hooks que construí sobre Claude Code durante los últimos dos meses.¹

La taxonomía es útil porque separa responsabilidades que los profesionales tienden a construir de forma enredada. Mis primeros hooks mezclaban la gestión de contexto con la aplicación de estándares de calidad. El hook de seguimiento de costos inyectaba contexto de presupuesto (gestión de contexto) y a la vez bloqueaba operaciones caras (aplicación de estándares). Separar eso en hooks distintos mejoró la fiabilidad, porque cada hook podía fallar de forma independiente sin romper la otra función.

El sistema completo

Los números a febrero de 2026:

La distribución de los hooks entre tipos de evento revela dónde se concentra la complejidad de la orquestación:

UserPromptSubmit es el que más peso carga, porque se dispara con cada mensaje del usuario. El despachador (prompt-dispatcher.sh) ejecuta nueve hooks de forma secuencial en cada prompt: filtrado de seguridad, analítica, seguimiento de uso, monitoreo del sistema, inyección de objetivos, bloqueo de estimaciones de tiempo, inyección de contexto, inyección de temas de memoria y monitoreo de la presión de contexto.²

Cada hook añade latencia. Nueve hooks secuenciales suman 200ms medidos por prompt. El despachador los ejecuta en secuencia (no en paralelo) porque las escrituras concurrentes de varios hooks sobre archivos JSON de estado compartidos provocaron corrupción de datos en las primeras pruebas. Dos hooks escribiendo en jiro.state.json a la vez producían un JSON truncado que rompía todos los hooks posteriores. La ejecución secuencial es más lenta, pero segura. La sobrecarga de 200ms es invisible para el usuario, porque el cuello de botella es la velocidad a la que escribe una persona, no la latencia de los hooks.

Cómo creció

El crecimiento no fue lineal. Siguió un patrón de ciclos de problema, solución e integración.

Fase 1: hooks de propósito único (semanas 1 y 2). Cada hook resolvía un problema. enforce-opus-model.sh bloqueaba las peticiones de modelos que no fueran Opus. no-time-estimates.sh eliminaba las estimaciones de esfuerzo de las respuestas. filter-sensitive.sh detectaba credenciales en las llamadas de herramientas. Estos hooks funcionaban de forma independiente. Ningún hook sabía de la existencia de otro.

Fase 2: problemas de coordinación (semanas 3 y 4). Los hooks empezaron a interferir entre sí. El filtro de credenciales bloqueaba llamadas legítimas a APIs. El que imponía el modelo entraba en conflicto con la generación de subagentes. La solución: despachadores. Un único punto de entrada (prompt-dispatcher.sh) reemplazó siete hooks individuales de UserPromptSubmit, controlando el orden de ejecución y compartiendo el estado mediante un pipe de stdin en caché.

Fase 3: capacidades compuestas (semanas 5 a 8). Los hooks individuales se compusieron en sistemas. El bucle de calidad conectó los hooks previos a la herramienta (que detectan problemas antes de que ocurran) con los hooks posteriores (que verifican los resultados después) a través de un archivo de estado compartido (jiro.state.json). El sistema de deliberación usó guardias de recursión, presupuestos de generación de agentes y protocolos de consenso para coordinar varios agentes sin caer en bucles infinitos. Ralph (el bucle de desarrollo autónomo) conectó los archivos de PRD con la generación de instancias de Claude, la verificación mediante pruebas y la revisión de código en un único pipeline orquestado.

Fase 4: autoconciencia (semana 9 en adelante). El sistema se volvió lo bastante grande como para necesitar herramientas que le permitieran entenderse a sí mismo. La búsqueda semántica sobre el sistema de hooks (la skill /find) permitió a los agentes descubrir hooks por su propósito y no por el nombre del archivo. El monitoreo de rendimiento (la skill /perf) rastreaba si la propia sobrecarga del sistema estaba degradando la máquina. Un monitor de presión de contexto avisaba cuando el contexto inyectado por la capa de orquestación consumía demasiada ventana de contexto del modelo.

La progresión desde hooks de propósito único hasta una infraestructura que se automonitorea refleja un patrón que Chris Lattner identificó en su reseña del proyecto Claude C Compiler: “El buen software depende del juicio, la comunicación y la abstracción clara. La IA ha amplificado esto.”³ La arquitectura del sistema de hooks revela la misma verdad. Los hooks valiosos no son los que automatizan tareas. Los hooks valiosos son los que codifican un juicio sobre cuándo y cómo deben automatizarse las tareas.

Hooks de juicio frente a hooks de automatización

La reseña de Lattner sobre el Claude C Compiler distinguía entre lo que la IA automatiza bien (la implementación) y lo que sigue siendo fundamentalmente humano (el juicio y la abstracción).³ Esa distinción se traslada directamente al sistema de hooks.

Los hooks de juicio deciden si algo debe ocurrir. Codifican política, no procedimiento.

Los hooks de automatización ejecutan acciones predeterminadas. Codifican procedimiento, no política.

Los hooks de juicio son más difíciles de escribir, más difíciles de probar y más valiosos. quality-gate.sh requirió siete modos de fallo con nombre, seis criterios de evidencia y un detector de lenguaje evasivo. inject-context.sh requirió cinco líneas de bash. Pero los dos son necesarios. Los hooks de automatización aportan los datos que evalúan los hooks de juicio. sysmon-snapshot.sh (automatización) alimenta con datos al monitor de rendimiento que decide si conviene recomendar una reducción del número de agentes (juicio).

La proporción importa. En una capa de orquestación sana, los hooks de juicio deberían superar en número a los de automatización. Si la mayoría de los hooks solo inyecta datos o registra métricas, el sistema automatiza bien pero gobierna mal. Un conteo verificado del sistema actual: 35 hooks de juicio y 44 de automatización, aproximadamente 4:5. La automatización sigue por delante. La proporción empezó en torno a 1:6 (casi todos eran hooks de inyección y de registro) y se desplazó hacia el juicio a lo largo de dos meses, a medida que se añadían restricciones de gobernanza tras encontrar fallos que la automatización pura no podía evitar. La proporción todavía no llega a la paridad, y eso en sí mismo es una señal útil: este sistema todavía gobierna menos de lo que automatiza.

Separación entre planificación y ejecución

El artículo de Boris Tane “How I use Claude Code” reunió 936 puntos en Hacker News describiendo un patrón de flujo de trabajo: separar la planificación de la ejecución.⁴ Planificas con una sesión de Claude (investigando, esbozando, diseñando) y luego ejecutas con una sesión nueva que recibe el plan como entrada estructurada. El patrón caló porque resuelve un problema real: la planificación y la ejecución compiten por el espacio de la ventana de contexto.

El sistema de hooks llegó a la misma separación por otro camino. El sistema de deliberación genera agentes especializados que investigan y debaten enfoques. La salida es un PRD (Documento de Requisitos de Producto) estructurado, con historias, criterios de aceptación y tipos de verificación. El bucle Ralph lee el PRD y genera instancias nuevas de Claude para implementar cada historia. Los agentes de planificación nunca implementan. Los agentes de implementación nunca planifican.

La separación no fue un objetivo de diseño. Emergió de dos restricciones independientes:

1. Presión sobre la ventana de contexto. Planificar exige leer muchos archivos y explorar opciones. Implementar exige un contexto enfocado en la tarea actual. Meter las dos cosas en la misma ventana de contexto significa que ninguna recibe espacio suficiente. Las sesiones separadas dan a cada fase todo el contexto.

2. Independencia de la verificación de calidad. Si el mismo agente planifica e implementa, no puede verificar de forma objetiva su propia implementación contra el plan. Un agente nuevo, que solo tiene el plan y el código, aporta una verificación independiente. El bucle Ralph lo impone: los agentes de implementación ejecutan las pruebas, pero tres agentes de revisión separados (corrección, seguridad y convenciones) verifican los resultados.

La convergencia entre el flujo manual de Tane y el sistema automatizado de hooks sugiere que la separación entre planificación y ejecución es una propiedad natural de los sistemas agénticos, y no solo una preferencia de quienes los usan. Cualquier sistema que gestione ventanas de contexto y verifique salidas acabará separando la planificación de la ejecución, porque la alternativa (hacer ambas cosas en un mismo contexto) produce peores resultados en las dos fases.

Dónde falla el sistema de hooks

La arquitectura tiene tres debilidades importantes que un framework de orquestación diseñado a propósito resolvería.

No hay definiciones declarativas de flujos de trabajo. Cada flujo está codificado de forma imperativa en scripts de bash. El bucle Ralph son 1.320 líneas de bash que codifican una secuencia concreta: leer el PRD, seleccionar la historia, reunir contexto, generar una instancia de Claude, ejecutar las pruebas, ejecutar las revisiones, manejar los fallos y actualizar el estado. Cambiar el flujo significa editar bash. Un sistema declarativo definiría los flujos como datos (YAML, JSON) que ejecuta un intérprete. Los flujos declarativos son más fáciles de modificar, componer y visualizar. Los scripts imperativos son más fáciles de escribir al principio, pero más difíciles de mantener a medida que crecen.

El orden de los hooks es frágil. El despachador de prompts ejecuta los hooks en una secuencia fija en el código. Mover memory-capsule-inject.sh antes de inject-context.sh rompería la inyección de cápsulas, porque depende del ID de sesión que resuelve inject-context.sh. Esas dependencias son implícitas (están codificadas en el orden del despachador) en lugar de explícitas (declaradas como dependencias entre hooks). Un sistema diseñado a propósito expresaría las dependencias de los hooks como un DAG y ordenaría la ejecución mediante un orden topológico.

No hay visualización de los flujos de trabajo. Con 84 hooks, entender la ruta completa de ejecución de cualquier acción del usuario obliga a leer el código del despachador y a rastrear las cadenas de hooks a mano. No existe una herramienta que muestre “cuando el usuario escribe un mensaje, estos 9 hooks se disparan en este orden, y el hook 3 llama a la función de biblioteca X, que escribe en el archivo de estado Y”. El sistema es observable a través de los logs, pero no a través de su estructura. Un framework de orquestación diseñado a propósito ofrecería un grafo visual de dependencias entre hooks, flujos de datos y rutas de ejecución.

Estas debilidades comparten una causa común: el sistema creció de forma orgánica resolviendo problemas individuales, en lugar de haber sido diseñado como una capa de orquestación coherente. El crecimiento orgánico produce sistemas que funcionan (los 84 hooks funcionan correctamente en producción) pero que cuesta razonar como un todo. La compensación es real: diseñar la capa de orquestación por adelantado habría dado mejor estructura pero peores capacidades, porque muchas capacidades (cápsulas de memoria, listas blancas de salida, presupuestos de generación de agentes) se inventaron como respuesta a fallos que no se podían haber previsto antes de que ocurrieran.

El harness se vuelve mainstream

Tres semanas después de que Karpathy le pusiera nombre a la capa, el concepto tiene un segundo nombre y una comunidad que crece.

Geoffrey Huntley propuso una definición formal: “Agent Harness: la capa de orquestación alrededor de un modelo de lenguaje que lo transforma de herramienta en compañero de equipo.”⁵ El encuadre es preciso. El harness no es el modelo. Tampoco son las herramientas que el modelo llama. Es el sistema que decide qué herramientas llamar, cuándo llamarlas y cómo evaluar si la llamada tuvo éxito. Todo sistema de agentes en producción construye esta capa. La mayoría la construye de forma implícita, dentro del código de la aplicación, mezclando la lógica de orquestación con la lógica de negocio. Ponerle nombre hace visible la arquitectura.

Las señales de la comunidad confirman que el patrón se está extendiendo. Pieter Levels contó que se pasó de forma permanente a ejecutar Claude Code en un servidor, tratándolo como infraestructura y no como una herramienta local.⁶ Anthropic lanzó Remote Control, que permite arrancar tareas desde la terminal y retomarlas en Claude.ai.⁷ Ben Cherny anunció /simplify y /batch como skills de primera parte.⁸ Cada una de esas piezas es una función de harness: ejecución persistente, orquestación remota y módulos de capacidad integrados. El CLI está creciendo hasta convertirse en el harness.

Mientras tanto, quienes lo usan a diario están construyendo sus propios componentes de harness. Un desarrollador publicó 22 comandos personalizados de Obsidian y Claude Code para montar un sistema operativo personal.⁹ Otro creó una skill de agente llamada “Visual Explainer” con comandos de barra complementarios.¹⁰ Los patrones coinciden: despachadores, skills, estado compartido, hooks basados en eventos. Nadie lee la guía de un framework antes de construir estos sistemas. Resuelven un problema, luego otro, y luego los problemas de que los problemas interactúan entre sí.

Dos proyectos recientes muestran hasta qué punto se han sofisticado los componentes de harness hechos por la comunidad. nah es una guardia de permisos consciente del contexto que se registra como hook de PreToolUse.¹⁴ Clasifica 20 tipos de acción distintos (escrituras de archivos, peticiones de red, generación de procesos, etc.) y aplica políticas por tipo. La herramienta detecta ataques de descomposición por pipes, en los que un agente encadena comandos inocuos para lograr una operación bloqueada. La arquitectura es un espejo de filter-sensitive.sh y recursion-guard.sh, los de este artículo, y alguien más llegó a ella por su cuenta resolviendo los mismos problemas de gobernanza.

Rudel ofrece analítica de sesiones ingiriendo los datos de sesión de Claude Code en ClickHouse.¹⁵ El análisis de 1.573 sesiones reveló que solo el 4% de los usuarios invoca skills y que el 26% de las sesiones se abandona en menos de 60 segundos. Los números confirman lo que la arquitectura del harness da a entender: la mayoría de los usuarios interactúa con los CLIs de agentes en la superficie. La capa de orquestación que describe este artículo representa la parte honda de una distribución de uso en la que la inmensa mayoría nunca sale de la orilla. La brecha entre lo que la herramienta puede hacer y lo que la mayoría le pide es justo el espacio que llena la infraestructura de harness.

Autoresearch: el harness como bucle de investigación

El propio proyecto autoresearch de Karpathy demuestra el patrón del harness en otro dominio.¹¹ El sistema apunta un modelo de lenguaje a un script de entrenamiento (train.py), corre un experimento de cinco minutos, evalúa el resultado contra una métrica fija (bits por byte de validación) y conserva las mejoras o descarta las regresiones. En dos días, el sistema corrió unos 700 experimentos y encontró unas 20 mejoras genuinas, reduciendo un 11% el tiempo de entrenamiento de GPT-2.

La arquitectura es idéntica al sistema de hooks descrito arriba. Un harness de evaluación fijo (prepare.py) equivale a los hooks de juicio: decide si el experimento tuvo éxito. El script de entrenamiento (train.py) equivale a los hooks de automatización: ejecuta las modificaciones del agente. La gestión de ramas de git (conservar si hay mejora, revertir si hay regresión) equivale a la gestión de estado del bucle Ralph. El log results.tsv equivale a la telemetría de sesión.

El patrón se transfiere porque el harness resuelve un problema que es independiente del dominio. Ya sea que el agente escriba código, optimice un bucle de entrenamiento o gestione un pipeline de contenido, necesita lo mismo: una forma de evaluar los resultados contra unos criterios, una forma de conservar o descartar cambios, una forma de mantener el estado entre iteraciones y una forma de correr de manera autónoma sin intervención humana. Esos cuatro requisitos producen la misma arquitectura, sin importar qué esté haciendo el agente en realidad.

Tobi Lütke, CEO de Shopify, adaptó autoresearch de forma interna. Su modelo pequeño optimizado por agentes superó a un modelo grande configurado a mano, lo que valida la idea de que la iteración autónoma guiada por un harness descubre configuraciones que a las personas no se les ocurre probar.¹²

La brecha de seguridad del harness

El harness resuelve la orquestación. No resuelve automáticamente la seguridad.

Un estudio sobre el refinamiento iterativo de código dirigido por LLM encontró que el 43,7% de las cadenas de iteración contenía más vulnerabilidades tras diez rondas de modificaciones del agente que el código base del que partían.¹³ La causa raíz era la deriva de especificación: a medida que el agente optimizaba la corrección funcional, iba retirando lógica defensiva y debilitando el manejo de excepciones. Peor todavía: añadir herramientas de análisis estático de seguridad (puertas SAST) al bucle de iteración aumentó la degradación latente del 12,5% al 20,8%. Los escáneres crearon una falsa sensación de seguridad que llevó al agente a ser menos cauto, no más.

El hallazgo sobre la degradación es directamente relevante para el diseño de harness. Los hooks de juicio que describe este artículo (quality-gate.sh, filter-sensitive.sh, recursion-guard.sh) atienden justo las dimensiones de calidad y seguridad que la automatización por sí sola degrada. El framework SCAFFOLD-CEGIS, que abordó el problema de la degradación, usó cuatro capas de verificación con puertas y logró una tasa de degradación latente del 2,1% con 100% de monotonía de seguridad.¹³ La arquitectura es paralela a la del sistema de hooks: capas de evaluación separadas, cada una comprobando una propiedad distinta, con puertas explícitas entre fases.

Otro trabajo corrobora el modelo de amenazas desde el lado de producción. La respuesta de Perplexity al NIST sobre seguridad de agentes de IA mapeó la superficie de ataque de los sistemas agénticos que operan a escala.¹⁶ Los vectores principales: inyección indirecta de prompts a través de canales de datos (páginas web, correos, salidas de herramientas), violaciones de la tríada CIA propias de los agentes (exfiltración de datos mediante llamadas de herramientas, manipulación de acciones mediante envenenamiento de contexto, agotamiento de recursos mediante generación recursiva) y CVEs reales de sistemas cercanos a los agentes. La arquitectura de defensa que recomiendan (filtrado a nivel de entrada, alineación a nivel de modelo y aplicación determinista mediante sandboxing y listas de permitidos) es un espejo del patrón de tres capas que emergió de forma orgánica en el sistema de hooks descrito aquí. Los hooks de automatización filtran las entradas. El modelo ejerce el juicio. Los hooks de gobernanza imponen restricciones deterministas que el modelo no puede anular.

La lección para quienes construyen esto: si tu harness solo automatiza y orquesta sin gobernar, la ejecución iterativa del agente introducirá regresiones de seguridad que el instrumental estándar no puede detectar. Los hooks de juicio no son sobrecarga. Son la razón por la que el sistema no se degrada.

Actualización, 3 de septiembre: el modo de fallo en la práctica

La brecha que describe este artículo en “La brecha de seguridad del harness” ya tiene una víctima documentada. El 19 de julio de 2026, Claude Code v2.1.204 estaba limpiando una caché en la computadora de Udaya Kumar P L, director honorario del Bengaluru Inscriptions 3D Digital Conservation Project de la Mythic Society, cuando, según su relato, “un error de comillas en un comando generado por IA convirtió la instrucción en ‘borrarlo todo’”. Lo que importa para el diseño de harness es lo que pasó después: “Cuando lo entendió e intentó matar el proceso, su sistema de seguridad bloqueó el intento. Dos veces […] La capa de seguridad permitió la destrucción.” Apagó la máquina a los cuatro minutos. Se perdieron cuatro o cinco programas y fotografías originales de inscripciones, piedras conmemorativas, templos y monedas reunidas durante una década, alrededor del 15% de los registros del proyecto, incluida una piedra que lleva una forma temprana del nombre Hebbal (750 d. C.). La copia en el NAS sobrevivió; el disco no. La Society está gastando Rs 15 lakh en un segundo NAS y en cinta fuera del sitio, y los voluntarios volverán a escanear unos 120 sitios. Más de un mes después, nadie de Anthropic se había puesto en contacto con él.¹⁷

Tres cosas de ese relato encajan con el argumento anterior. El paso destructivo no fue una decisión del modelo, sino un fallo de comillas del shell en un comando generado, exactamente la clase de cosa que existe para atrapar un hook de juicio en PreToolUse. El artículo no nombra ningún modo de permisos, así que no hay constancia de que nada de primera parte revisara ese comando; incluso en modo automático, el clasificador solo revisa por defecto los comandos de shell que coinciden con patrones de ejecución de código arbitrario. También dice que el agente sorteó un sandbox; el artículo no da detalle de qué tipo. Anthropic ya había lanzado una protección para el caso vecino: la v2.1.205, publicada el 8 de julio, hizo que el modo automático pregunte antes de ejecutar rm -rf sobre una variable que no puede resolver desde el contexto. La máquina estaba en la v2.1.204.¹⁹ La capa de seguridad hizo entonces su trabajo en la dirección equivocada: trató la propia remediación del agente como la acción peligrosa. Y lo que sobrevivió, sobrevivió gracias al único control que queda por completo fuera del harness, una copia de respaldo; el resto se vuelve a escanear a mano. Ahora existe al menos un registro no oficial para esta clase de sucesos; él señaló que no hay ninguno oficial. I Have Been Clawed, un archivo de incidentes de agentes y chatbots con enlaces a las fuentes y una lección adjunta a cada uno, 58 entradas al momento de escribir esto, siete de ellas de Claude Code, con la advertencia honesta en su propia portada de que las entradas son autoseleccionadas y están sesgadas por la viralidad, de modo que los conteos por herramienta miden la cultura de reporte, no la seguridad. Ya contenía tres entradas de Claude Code con esta misma forma antes de esta: un comando recursivo que borró archivos del usuario de un directorio home de WSL (21 de octubre de 2025), un directorio con una tilde literal que expuso el directorio home al borrado (28 de noviembre de 2025) y un comando de limpieza terminado en la ruta home que arrasó una Mac (7 de diciembre de 2025). En la práctica, esto es un patrón, no una anécdota.¹⁸

Qué deberías llevarte de todo esto

Si estás construyendo una capa de orquestación sobre el CLI de un agente, ya sea partiendo de la guía de Claude Code o desde cero, hay tres patrones de este sistema que se transfieren directamente.

Empieza por los despachadores, no por hooks individuales. La mayor mejora arquitectónica fue reemplazar siete hooks individuales de UserPromptSubmit por un único despachador que los ejecuta en secuencia. Si prevés más de tres hooks en cualquier tipo de evento, construye primero el despachador. Los 30 minutos que dedicas a escribir un despachador te ahorran horas de depurar errores de interacción entre hooks más adelante. El patrón mínimo:

#!/bin/bash
# dispatcher.sh — sequential hook execution with shared stdin
HANDLERS=("inject-context.sh" "track-usage.sh" "quality-gate.sh")
HOOK_DIR="$(dirname "$0")/handlers"
INPUT=$(cat)  # Cache stdin once (each handler gets the same input)

for handler in "${HANDLERS[@]}"; do
    [ -x "$HOOK_DIR/$handler" ] && echo "$INPUT" | "$HOOK_DIR/$handler"
done

Registra ese único despachador como tu punto de entrada de hooks. Ve añadiendo manejadores al arreglo a medida que los construyas. Cada manejador lee el mismo stdin en caché (la carga útil del evento de hook) y escribe en stdout de forma independiente.

Separa pronto el juicio de la automatización. Cuando escribas un hook nuevo, pregúntate: “¿este hook decide si algo debe ocurrir, o ejecuta una acción predeterminada?” Los hooks de juicio necesitan más pruebas, más manejo de casos límite y más iteración. Los hooks de automatización necesitan fiabilidad y rendimiento. Tratarlos igual lleva a hooks de juicio poco probados y a hooks de automatización sobredimensionados.

Deja que la separación entre planificación y ejecución emerja. No fuerces la separación el primer día. Construye lo más simple que funcione. Cuando notes que la ventana de contexto de tu agente está demasiado llena para la planificación y la implementación a la vez, sepáralas. Cuando notes que tu agente no puede verificar de forma objetiva su propio trabajo, añade agentes de revisión independientes. La separación se sentirá obvia cuando las restricciones la exijan.

El harness se está volviendo mainstream porque el patrón es inevitable. Llames a esa capa Claws, Agent Harness o simplemente “mi carpeta de hooks”, cualquier sistema que coordine agentes hacia unos objetivos convergerá en la misma arquitectura: despachadores para el orden, hooks de juicio para la gobernanza, hooks de automatización para la ejecución y archivos de estado para la continuidad. La filtración del código fuente de Claude Code confirmó que la propia arquitectura interna de Anthropic sigue esos mismos patrones: el modo coordinador está implementado enteramente como instrucciones del prompt de sistema, no como orquestación a nivel de código. El enfoque basado en hooks tiene una ventaja sobre los frameworks de orquestación diseñados a propósito: compromiso cero. Cada hook es independiente. Puedes adoptar un hook, diez hooks u ochenta y cuatro hooks. Puedes eliminar cualquier hook sin romper los demás (siempre que mantengas el despachador). No hay framework que aprender, ni dependencia que gestionar, ni runtime que operar. La capa de orquestación son solo archivos.

Preguntas frecuentes

¿Qué es un agent harness o capa “Claws”?

Una capa Claws (así la bautizó Andrej Karpathy en febrero de 2026) es el sistema de orquestación construido sobre el CLI de un agente que lo transforma de herramienta en compañero de equipo.¹ Cumple cinco funciones: orquestación (coordinar varios agentes), programación de tareas (determinar cuándo se ejecutan), gestión de contexto (mantener la información relevante entre turnos), enrutamiento de herramientas (dirigir las llamadas de herramientas a los manejadores adecuados) y aplicación de estándares de calidad (verificar que las salidas cumplan los estándares). Geoffrey Huntley formalizó la definición como “la capa de orquestación alrededor de un modelo de lenguaje.”⁵

¿Cómo funcionan los hooks de PreToolUse en Claude Code?

Los hooks de PreToolUse se disparan antes de cada llamada de herramienta (comandos de Bash, escrituras de archivos, ediciones de archivos, generación de subagentes) y reciben por stdin la carga útil de la llamada en formato JSON. El script del hook evalúa esa carga y devuelve una decisión: permitir, denegar o modificar. El modelo no puede saltarse los hooks, anularlos ni negociar con ellos, porque se ejecutan en el nivel de la infraestructura y no en el del prompt.² Un patrón de despachador ejecuta varios hooks de forma secuencial en cada evento, con un pipe de stdin en caché para que todos los manejadores reciban la misma entrada.

¿Cuál es la diferencia entre los hooks de juicio y los de automatización?

Los hooks de juicio deciden si algo debe ocurrir (política), mientras que los de automatización ejecutan acciones predeterminadas (procedimiento). Entre los de juicio están las puertas de calidad, los filtros de credenciales, las guardias de recursión y las puertas de costo. Entre los de automatización están la inyección de contexto, el seguimiento de uso, el monitoreo del sistema y los latidos de actividad.³ La proporción importa: un sistema con hooks casi todos de automatización automatiza bien pero gobierna mal. El sistema actual corre 35 hooks de juicio frente a 44 de automatización, y se desplaza hacia la gobernanza a medida que los fallos revelan lo que la automatización pura no puede evitar.

¿Por qué la separación entre planificación y ejecución emerge de forma natural en los sistemas de agentes?

Dos restricciones independientes fuerzan la separación. Primera: planificar exige leer muchos archivos y explorar opciones, mientras que implementar exige un contexto enfocado en la tarea actual, y meter las dos cosas en la misma ventana de contexto significa que ninguna recibe espacio suficiente. Segunda: si el mismo agente planifica e implementa, no puede verificar de forma objetiva su propio trabajo contra el plan.⁴ Cualquier sistema que gestione ventanas de contexto y verifique salidas acabará separando la planificación de la ejecución, porque la alternativa produce peores resultados en las dos fases.

¿Cómo empiezo a construir mi propio sistema de hooks?

Empieza por los despachadores, no por hooks individuales. Si prevés más de tres hooks en cualquier tipo de evento, construye un único despachador que ejecute los manejadores en secuencia a partir de un arreglo. Los 30 minutos que dedicas a escribir un despachador te ahorran horas de depurar errores de interacción entre hooks más adelante. Separa pronto el juicio de la automatización preguntándote “¿este hook decide si algo debe ocurrir, o ejecuta una acción predeterminada?”. Empieza por el tutorial de hooks de Claude Code y ve añadiendo hooks a medida que los fallos reales los exijan, en lugar de diseñar el sistema completo por adelantado.

Fuentes