Los hooks de Codex hacen real el harness

Desde Codex 0.150.1 (27 de agosto de 2026), los hooks de Codex registran doce eventos de ciclo de vida, se niegan a ejecutar cualquier hook no gestionado hasta que revises y confíes en su definición exacta, y vienen habilitados por defecto. La función que llegó a disponibilidad general en el paquete de lanzamiento del 14 de mayo junto a la app móvil de ChatGPT ha madurado hasta convertirse en una superficie de gobernanza: PreToolUse puede bloquear o reescribir una llamada a herramienta antes de que se ejecute, PermissionRequest puede decidir una aprobación, PostToolUse puede reemplazar el resultado que ve el modelo, y Stop puede negarse a dejar que un turno termine.²³

Codex ya no parece un asistente de programación que espera dentro de una terminal. Parece una capa operativa que sigue el trabajo a través de máquinas, aprobaciones, proyectos, chats, diffs, pruebas, capturas de pantalla, plugins, credenciales y herramientas locales.⁴

Los hooks de Codex hacen real el harness. Cuando el agente puede trabajar desde un teléfono, alcanzar entornos de desarrollo remotos y ejecutar hooks de ciclo de vida, los equipos necesitan un sistema de control alrededor del modelo: evidencia, aprobaciones, custodia de git, disciplina de fuentes y buen gusto.

TL;DR

Codex admite la forma de flujo de trabajo que los equipos de agentes venían construyendo en privado: trabajo de larga duración, ejecución remota, control móvil, aprobaciones, hooks, credenciales acotadas y señales de auditoría.²⁴⁵ El motor de hooks en 0.150.0 registra doce eventos, cada hook no gestionado permanece omitido hasta que confíes en su hash actual, y los hooks se cargan desde archivos hooks.json o tablas [hooks] en línea dentro de config.toml.³⁷ La pregunta práctica no es “¿cómo le damos prompts a Codex?”. La pregunta práctica es “¿qué debe demostrar Codex antes de que confiemos en el resultado?”. Los equipos deberían usar hooks y configuración para codificar puertas de revisión, límites de seguridad, estándares de escritura pública y disciplina de lanzamiento. Deberían mantener privada la maquinaria privada y publicar solo el patrón, los criterios de aceptación y el resultado verificado.

Conclusiones clave

Para equipos de ingeniería: - Trata los hooks de Codex como infraestructura de proceso, no como decoración. El flujo de revisión de confianza es parte de esa infraestructura, no fricción que haya que esquivar. - Empieza con evidencia, aprobaciones, custodia de git y verificaciones de lanzamiento antes de añadir automatización ingeniosa.

Para quienes construyen herramientas de agentes: - Construye alrededor de las superficies reales de Codex: control móvil, hosts de Remote SSH, modos de sandbox, políticas de aprobación, instrucciones de proyecto, hooks, telemetría y control de versiones. - Porta los trabajos por hacer, no las viejas formas de slash-commands.

Para quienes escriben en público: - Usa la documentación oficial en learn.chatgpt.com para el comportamiento actual de Codex, y consulta el código fuente del motor cuando la documentación se quede atrás de una versión. - Describe la práctica privada como análisis del autor, y deja fuera del texto público los prompts privados, los cuerpos de hooks, las rutas de archivos, las listas de fuentes, las credenciales y las interioridades de puntuación.

¿De dónde vienen los hooks de Codex?

OpenAI publicó “Work with Codex from anywhere” (trabaja con Codex desde cualquier lugar) el 14 de mayo de 2026.¹ La entrada del changelog de la documentación para esa fecha registra el paquete de lanzamiento: Codex pasó a poder usarse desde la app móvil de ChatGPT conectándola a una Mac que ejecuta la app de Codex, los hooks alcanzaron disponibilidad general, y llegaron los tokens de acceso de Codex para automatización de confianza.² Codex se ejecuta desde el host conectado, así que los mismos proyectos, archivos, credenciales, plugins, skills y configuración están disponibles desde un teléfono.²

Las conexiones remotas extienden el alcance más allá de un escritorio. La capacidad Remote SSH del anuncio aterriza en la documentación como hosts SSH: la app de escritorio de ChatGPT puede añadir proyectos remotos desde un host SSH y ejecutar chats contra el sistema de archivos y el shell remotos. El planteamiento es concreto: “Remote access uses the connected host’s projects, chats, files, credentials, permissions, plugins, Computer Use, browser setup, and local tools.” (el acceso remoto usa los proyectos, chats, archivos, credenciales, permisos, plugins, Computer Use, configuración de navegador y herramientas locales del host conectado).⁴

Los hooks en sí preceden al lanzamiento como experimento y lo desbordaron después. La documentación los define como un marco de extensibilidad que ejecuta scripts o herramientas MCP durante el bucle agéntico, y nombra trabajos concretos: enviar chats a un motor de registro, bloquear claves de API pegadas por accidente, resumir chats en memorias persistentes, ejecutar una verificación de validación cuando un turno se detiene y personalizar el prompting por directorio.³ Los hooks ahora vienen habilitados por defecto; features.hooks en config.toml funciona como interruptor de apagado, y features.codex_hooks sobrevive solo como alias obsoleto.³⁶

Esos detalles importan porque convierten el trabajo con agentes de un intercambio de chat en operaciones gobernadas.

¿Cómo se ven los hooks de Codex en la configuración?

Un artículo sobre hooks debería mostrar un hook. Codex descubre hooks junto a las capas de configuración activas, siendo lo más útil ~/.codex/hooks.json, <repo>/.codex/hooks.json o tablas en línea en el config.toml de cualquiera de las capas; cuando existen varias fuentes, todos los hooks coincidentes se cargan y ejecutan.³ Un hooks.json mínimo con una puerta de herramientas y una puerta de finalización:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^Bash$",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/pre_tool_use_policy.py",
            "timeout": 30,
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/evidence_gate.py"
          }
        ]
      }
    ]
  }
}

La misma forma escrita en línea en config.toml:

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/pre_tool_use_policy.py"
timeout = 30
statusMessage = "Checking Bash command"

Tres niveles organizan cada hook: un evento, un grupo matcher que decide cuándo aplica el evento, y uno o más manejadores (command o mcp_tool).³ Los eventos actuales, con la lista de doce entradas del motor como autoridad:³⁷

La documentación de hooks en vivo todavía documenta once de esos eventos; aún no tiene sección de Interrupt. La entrada del changelog de 0.150.0 (#40511) y HOOK_EVENT_NAMES: [&str; 12] en el código fuente del motor en rust-v0.150.0 aportan el duodécimo.²⁷ Cuando una página y el motor discrepan, confía en el motor.

¿Qué llamadas a herramientas pueden ver realmente los hooks?

Versiones anteriores de la documentación advertían que PreToolUse cubría poco más allá de las llamadas de shell y MCP. La documentación actual amplía la superficie: “PreToolUse and PostToolUse can observe more than shell and MCP calls. Most local function tools use the same hook path,” (pueden observar más que llamadas de shell y MCP; la mayoría de las herramientas de función locales usan la misma ruta de hooks), así que un matcher puede nombrar directamente herramientas como update_plan, y spawn_agent también coincide como Agent.³ Los comandos de shell coinciden como Bash, las ediciones de archivos de apply_patch coinciden como apply_patch, Edit o Write, y las herramientas MCP coinciden con nombres como mcp__filesystem__read_file.³

Las herramientas alojadas quedan fuera: WebSearch y sus pares nunca pasan por la ruta local de hooks de herramientas de función.³ La documentación mantiene una advertencia suavizada que vale la pena citar completa: “Some specialized tool paths can opt out of the default hook path. Treat tool hooks as a useful guardrail, not a complete enforcement boundary.” (algunas rutas de herramientas especializadas pueden excluirse de la ruta de hooks por defecto; trata los hooks de herramientas como una barandilla útil, no como un límite de aplicación completo).³ El sandboxing sigue siendo dueño del límite duro; los hooks son dueños de la revisión y el direccionamiento dentro de él.

¿Cómo decide Codex qué hooks pueden ejecutarse?

Los hooks son código que dirige al agente, así que Codex gobierna los propios hooks. El sistema de control alrededor del modelo empieza aquí.

Antes de que cualquier hook no gestionado se ejecute, Codex exige que revises y confíes en su definición exacta. La confianza se registra contra el hash actual del hook, de modo que un hook nuevo o editado queda marcado para revisión y omitido hasta que vuelvas a confiar en él.³ El comando /hooks en la CLI abre la superficie de revisión: inspecciona las fuentes de los hooks, revisa hooks nuevos o cambiados, confía en ellos o desactiva algunos individualmente. Cuando hay hooks que necesitan revisión al arrancar, Codex imprime una advertencia que apunta a /hooks.³

Los hooks gestionados provenientes de fuentes de sistema, MDM, nube o requirements.toml se sitúan por encima de ese flujo: son de confianza por política y no pueden desactivarse desde el navegador de hooks del usuario.³ Los plugins se sitúan dentro de él: instalar o habilitar un plugin no otorga confianza a sus hooks incluidos, que permanecen omitidos hasta ser revisados como cualquier otro.³ Los hooks locales de proyecto se cargan solo cuando la capa .codex/ del proyecto es de confianza; un proyecto sin confianza sigue cargando tus hooks de usuario y de sistema.³

La automatización siente la misma regla. Una ejecución de codex exec no tiene interfaz de revisión, así que un hook sin confianza se omite en silencio hasta que confíes en él primero en una sesión interactiva; la documentación aún no lo dice, pero la superficie de revisión al arranque del motor existe solo en la TUI interactiva.⁷ Para pipelines que examinan las fuentes de los hooks en otro lugar, --dangerously-bypass-hook-trust ejecuta los hooks habilitados sin confianza persistida durante esa única invocación.³ Confía deliberadamente o mira cómo tu puerta no se dispara: el harness decide qué código puede dirigir al agente antes de que nada de eso se ejecute.

¿Qué pasa cuando un hook bloquea, y cuándo es demasiado tarde?

El momento decide qué puede cambiar todavía un hook. La mayoría de los hooks se ejecutan de forma síncrona con un timeout por defecto de 600 segundos; SessionEnd e Interrupt tienen por defecto un segundo y un tope de tres: SessionEnd se dispara mientras la sesión se está desmontando, e Interrupt se dispara mientras el usuario espera.³⁷

PreToolUse actúa antes de que ocurra nada, así que tiene las cartas más fuertes: deniega la llamada, o reescríbela devolviendo permissionDecision: "allow" con updatedInput. La forma de denegación:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook."
  }
}

El código de salida 2 con la razón en stderr también bloquea.³

PostToolUse actúa después de que la herramienta se ejecutó, así que no puede deshacer efectos secundarios. Un decision: "block" reemplaza el resultado de la herramienta con tu retroalimentación y continúa el modelo desde ese mensaje, lo que corrige el rumbo sin fingir que el comando nunca ocurrió.³ Stop convierte un rechazo en una continuación: bloquea una finalización y Codex sigue trabajando, con tu razón como el nuevo prompt.³

Para verificaciones que nunca deberían sentarse en la ruta crítica, establece async = true en un manejador de comando. Los hooks en segundo plano se ejecutan mientras Codex continúa, entregan su salida en el siguiente punto seguro y explícitamente no pueden bloquear, aprobar ni reescribir nada; mantén síncronas las políticas de herramientas, las decisiones de permisos, el rechazo de prompts y la continuación de turnos.³

¿Qué mejoró en 0.149 y 0.150?

Dos versiones estables a finales de agosto endurecieron la historia de gobernanza.

Codex CLI 0.149.0 (20 de agosto de 2026) retiró la política de aprobación untrusted (#39630); una configuración que todavía la nombre ahora falla con un error accionable que te indica eliminar el ajuste.²⁷ Codex CLI 0.150.0 (26 de agosto de 2026) añadió el evento de hook Interrupt (#40511): “New Interrupt hooks can run commands or MCP handlers when an active top-level turn is interrupted.” (los nuevos hooks de Interrupt pueden ejecutar comandos o manejadores MCP cuando se interrumpe un turno activo de nivel superior). Los hooks de Interrupt nunca se ejecutan para subagentes.²⁷ La misma versión impidió que los proyectos sin confianza suministren instrucciones AGENTS.md a nivel de proyecto (#39837), lo que se empareja con la regla existente de que los hooks locales de proyecto se cargan solo desde una capa .codex/ de confianza.²³

La dirección es consistente: un directorio sin confianza obtiene cada vez menos autoridad sobre el agente que entra en él. Las instrucciones, los hooks y los atajos de aprobación fluyen ahora a través de decisiones explícitas de confianza.

¿Por qué los hooks importan más que el móvil?

El acceso móvil cambia dónde puede intervenir el humano. Los hooks cambian qué puede hacer cumplir el sistema.

Un teléfono permite a un operador responder una pregunta lejos del escritorio. Un hook puede atrapar al agente antes de una acción arriesgada, después de la edición de un archivo, antes de la finalización o durante una verificación de lanzamiento. El teléfono resuelve la latencia. El hook resuelve los estándares.

Codex ya tiene superficies de control de primera parte alrededor del sandboxing y las aprobaciones. La documentación de seguridad empareja el modo de sandbox, que define qué puede hacer técnicamente el agente, con la política de aprobación, que define cuándo Codex debe detenerse y preguntar antes de actuar.⁵ El agente se ejecuta con el acceso a la red desactivado por defecto, y el modo local por defecto workspace-write mantiene el acceso a la red apagado a menos que el usuario lo habilite.⁵ Los hooks se sitúan junto a esos controles como la capa de revisión y direccionamiento, no como un reemplazo del sandboxing.

Los hooks pueden hacer ejecutables los estándares locales:

El modelo puede olvidar una regla. Un hook puede volver a ejecutar la regla en el momento en que la regla importa.

¿Qué posee el harness que el proveedor no posee?

Un harness de agentes es la capa operativa alrededor de un modelo: permisos, memoria, herramientas, hooks, verificaciones de fuentes, puertas de lanzamiento, paquetes de revisión y disciplina de rollback. El término puede sonar privado u ornamentado, pero el trabajo es simple. La capa convierte la intención en trabajo auditable.

Codex ahora expone suficiente superficie oficial para hacer explícita esa capa. Las conexiones remotas llevan el entorno del host. Los modos de sandbox y las políticas de aprobación definen los límites de acción. Los archivos de configuración definen modelos, proyectos, permisos, servidores MCP, skills, hooks, telemetría y funciones.⁶ La exportación de OpenTelemetry sigue siendo opcional y está desactivada por defecto; cuando se habilita, Codex emite eventos estructurados que cubren chats, solicitudes a la API, actividad de stream, prompts del usuario (redactados por defecto), decisiones de aprobación de herramientas y resultados de herramientas.⁵⁸

Ese conjunto de superficies crea una división útil:

El proveedor debería seguir mejorando el runtime. El equipo sigue siendo dueño del criterio.

¿Qué deberían codificar primero los equipos?

Empieza con cuatro puertas. Pagan su renta de inmediato.

Puerta de evidencia

El post de lanzamiento original de Codex enfatizaba la evidencia verificable: registros de terminal, salidas de pruebas y pasos rastreables durante la finalización de tareas.⁹ Haz que esa expectativa sea innegociable. Una finalización significativa debería nombrar los archivos cambiados, los comandos ejecutados, el comportamiento observado, las verificaciones fallidas y las brechas restantes.

Para el trabajo público, la evidencia incluye enlaces a fuentes y alineación entre afirmación y fuente. Para lanzamientos web, la evidencia incluye rutas renderizadas, metadatos, schema, archivos de descubrimiento, estado del despliegue, frescura de caché y marcadores de cambio en vivo. Para traducciones, la evidencia incluye cobertura de locales, puertas de calidad, filas de almacenamiento o archivos de caché, y estado de revisión nativa cuando se requiere.

Puerta de aprobación

No uses una sola postura de aprobación para cada acción. La tabla de combinaciones actual de la documentación de aprobaciones va desde el preset Auto (sandbox workspace-write con aprobaciones on-request) hasta la navegación segura de solo lectura, la CI no interactiva de solo lectura, el modo de auto-revisión y el acceso completo peligroso.⁵ Una fila va rezagada respecto a la realidad: la política untrusted todavía aparece en la página, pero 0.149.0 la retiró y las configuraciones explícitas ahora dan error.²⁵ Para una postura de preguntar siempre hoy, combina el sandbox read-only con aprobaciones on-request. Una política local sólida mantiene la misma forma: las lecturas de bajo riesgo pasan en silencio, el trabajo con efectos secundarios recibe revisión, y el trabajo destructivo o visible externamente recibe evidencia explícita.

Puerta de custodia de git

El trabajo con agentes necesita asideros de rollback. La propia documentación de seguridad de Codex dice que Codex funciona mejor con control de versiones: mantén el status limpio antes de delegar, haz commits con frecuencia, ejecuta verificación dirigida, revisa los diffs y documenta las decisiones en los mensajes de commit.⁵

Ese consejo debería convertirse en proceso. Haz commit después de puntos de guardado coherentes y verificados. Prepara rutas exactas. Divide los commits por preocupación independientemente reversible. Pregunta antes de hacer push a menos que el flujo de lanzamiento ya otorgue autoridad de publicación. No arrastres archivos sucios no relacionados a un commit porque el agente los haya visto por casualidad.

Puerta de gusto

La programación con IA abarata la implementación. Una implementación más barata eleva el valor del gusto.

El gusto no significa preferencia decorativa. Significa que el trabajo mejora el producto completo. Significa que el agente puede rechazar un camino técnicamente posible que debilita el resultado. Significa que la escritura pública evita la maquinaria privada, las afirmaciones sin respaldo y el relleno. Significa que un parche local correcto todavía puede fallar si la ruta visible para el usuario sigue rota.

Una puerta de gusto debería preguntar:

¿Qué demuestra el trabajo de Mozilla en Firefox?

El post de Mozilla del 7 de mayo sobre endurecer Firefox con Claude Mythos Preview plantea el mismo punto desde otro stack. El equipo dice que los primeros intentos de auditoría de código con LLM mostraron promesa pero tenían demasiados falsos positivos para escalar. Los harnesses agénticos cambiaron la economía porque podían crear y ejecutar casos de prueba reproducibles para probar dinámicamente hipótesis de bugs.¹⁰

La frase importante de Mozilla no trata solo del modelo. El equipo dice que el descubrimiento era necesario pero no suficiente. El sistema útil tenía que integrarse con el ciclo de vida completo de los bugs de seguridad: objetivos, deduplicación, seguimiento de bugs, triaje, correcciones y lanzamiento.¹⁰ Los autores también dicen que el pipeline reflejaba la semántica del código, las herramientas y los procesos de Firefox.¹⁰

Esa es la lección para Codex. Los mejores modelos importan. El sistema operativo alrededor del modelo decide si el trabajo se convierte en salida confiable.

¿Qué debería quedar fuera del texto público?

Un artículo público sobre Codex no debería volcar el sistema de trabajo privado.

Mantén esto fuera del texto público:

• prompts privados y cuerpos de hooks;
• rutas locales sensibles;
• mapas exactos de fuentes e interioridades de puntuación;
• identificadores de cuentas y manejo de credenciales;
• atajos privados de flujo de trabajo;
• comportamiento de plugins no publicado;
• cualquier cosa que ayude a un extraño a reconstruir operaciones internas.

Publica el patrón en su lugar: qué protege la puerta, qué evidencia exige, qué fallo atrapa y cómo un equipo puede implementar la idea usando superficies oficiales de Codex.

Esa línea protege la confianza. También mejora la escritura. La maquinaria privada suele leerse como folclore. Los criterios de aceptación públicos ayudan a otros equipos a razonar sobre sus propios sistemas.

¿Cómo se ve un mapa mínimo de harness de Codex?

Construye el mapa de control más pequeño que demuestre trabajo útil.

Empieza explícito. Ejecuta una tarea real. Registra dónde ayudó la puerta y dónde estorbó. Promueve solo las partes que mejoran el resultado visible para el usuario.

Resumen rápido

Los hooks de Codex, Remote SSH, el control móvil, el sandboxing, las aprobaciones, la configuración, la telemetría y el control de versiones apuntan en la misma dirección: los agentes de programación necesitan sistemas operativos a su alrededor.²⁴⁵⁶ El agente puede escribir código. El harness decide qué cuenta como trabajo.

Los mejores equipos no ganarán produciendo la mayor cantidad de salida de agentes. Ganarán haciendo que el trabajo de los agentes sea inspeccionable, reversible, con fuentes, con gusto y digno de lanzarse.

Preguntas frecuentes

¿Qué son los hooks de Codex?

Los hooks de Codex ejecutan scripts o herramientas MCP durante el bucle agéntico, cargados desde archivos hooks.json o tablas [hooks] en línea en config.toml. La documentación nombra los trabajos con claridad: enviar chats a un motor de registro, bloquear claves de API pegadas por accidente, resumir chats en memorias persistentes, ejecutar validación cuando un turno se detiene y personalizar el prompting por directorio.³ El motor en 0.150.0 registra doce eventos, desde PreToolUse, PermissionRequest y PostToolUse hasta Stop y el nuevo Interrupt; la página de documentación todavía lista once mientras se pone al día.³⁷

¿Por qué importan los hooks de Codex?

Los hooks permiten a los equipos poner estándares en los puntos de decisión en lugar de depender solo de prompts. Un hook puede verificar evidencia, calidad de fuentes, estado de git o preparación de lanzamiento cuando el agente actúa o intenta terminar.

¿Por qué no se ejecutó mi hook?

La respuesta habitual es la confianza. Codex omite cualquier hook no gestionado cuyo hash actual no hayas revisado, imprime una advertencia al arranque en sesiones interactivas y omite en silencio en la automatización con codex exec.⁷ Abre /hooks para revisarlo y confiar en él, o pasa --dangerously-bypass-hook-trust solo en pipelines que examinan las fuentes de los hooks en otro lugar.³

¿Codex móvil reemplaza el flujo de trabajo local con agentes?

No. El control móvil permite a los usuarios dirigir el trabajo lejos del escritorio, pero el host conectado sigue suministrando los proyectos, chats, archivos, credenciales, permisos, plugins y herramientas locales.⁴ Los equipos siguen necesitando política local, credenciales seguras, control de versiones y verificación.

¿Qué debería incluir primero un harness de Codex?

Empieza con instrucciones de proyecto, postura de sandbox y aprobaciones, un límite de secretos, una puerta de detención por evidencia, custodia de git de rutas exactas, verificación de fuentes para las afirmaciones públicas y una puerta de lanzamiento para el trabajo visible al usuario.

¿Deberían los equipos publicar sus hooks de Codex?

Publica patrones y criterios de aceptación, no cuerpos privados de hooks ni detalles sensibles de flujo de trabajo. Un post público útil puede explicar el trabajo de un hook sin exponer rutas privadas, mapas de fuentes, prompts, credenciales ni reglas de puntuación.

Referencias