Los hooks de Codex necesitan revisión — Por qué un hook modificado deja de ejecutarse hasta que vuelves a confiar en él, y cómo un hook de SessionStart alimenta el contexto del proyecto en cada sesión (2026)

La documentación de OpenAI describe los hooks como "un marco de extensibilidad para Codex". Te permiten ejecutar scripts o herramientas MCP en puntos determinados de una conversación.

La documentación enumera ejemplos, como escanear prompts para bloquear claves de API pegadas accidentalmente, ejecutar una verificación de validación cuando se detiene un turno, y uno que trata directamente sobre la memoria: "Resumir chats para crear memorias persistentes automáticamente".

Los hooks se vinculan a eventos. Algunos de los principales son:

• SessionStart se ejecuta cuando comienza una sesión, incluso después de la compactación.
• PreToolUse y PostToolUse se ejecutan alrededor de las llamadas a herramientas.
• PreCompact y PostCompact se ejecutan alrededor de la compactación.
• UserPromptSubmit se ejecuta cuando envías un prompt.
• Stop se ejecuta cuando se detiene un turno.

Codex busca hooks en archivos hooks.json o en tablas [hooks] integradas en config.toml. La documentación menciona las cuatro ubicaciones más útiles: ~/.codex/hooks.json, ~/.codex/config.toml, y los mismos dos archivos bajo <repo>/.codex/. Los plugins habilitados también pueden incluir hooks.

Si más de una fuente tiene hooks, Codex carga todos los que coincidan. OpenAI afirma que las capas de mayor precedencia "no reemplazan a los hooks de menor precedencia".

La sección de revisión de la documentación de OpenAI explica el mecanismo en dos frases. "Antes de que un hook no gestionado pueda ejecutarse, Codex requiere que revises y confíes en la definición exacta del hook. Codex registra la confianza contra el hash actual del hook, por lo que los hooks nuevos o modificados se marcan para revisión y se omiten hasta que se confíe en ellos".

Las palabras clave son exacto y hash. Codex no te pregunta si confías en una ruta de archivo o en el nombre de un script. Te pregunta si confías en esta definición exacta. Por lo tanto, cualquiera de estos casos puede volver a poner un hook en revisión:

• Añadiste un nuevo hook. Nunca ha sido marcado como confiable.
• Editaste un hook. Una definición cambiada tiene un hash diferente.
• Un compañero de equipo cambió un hook de proyecto. Si el archivo .codex/hooks.json del repositorio cambió en un pull, la nueva versión necesita tu revisión.

Cuando los hooks necesitan revisión al inicio, la documentación dice que Codex "imprime una advertencia que te indica que abras /hooks". Hasta que lo hagas, esos hooks se omiten.

Esa es la parte que es fácil pasar por alto. Un hook omitido no detiene la sesión. Si el hook estaba cargando contexto, la sesión simplemente comienza sin él.

En la CLI, /hooks es el lugar para gestionarlos. La documentación de OpenAI dice que puedes usarlo "para inspeccionar las fuentes de los hooks, revisar hooks nuevos o modificados, confiar en hooks o desactivar hooks individuales no gestionados".

En la aplicación de escritorio, los hooks de plugins pueden revisarse seleccionando Review hooks en el composer, o abriendo Settings > Hooks.

Cuando revises, fíjate en qué ejecuta el hook y de dónde obtiene su entrada. La confianza es la decisión que permite que un script se ejecute dentro de tus sesiones, por lo que vale la pena leer el comando antes de aprobarlo, especialmente para los hooks de proyecto que no escribiste tú.

Dos tipos de hooks no pasan por esta revisión:

• Hooks gestionados. Los hooks de fuentes de sistema, MDM, nube o requirements.toml "se marcan como gestionados, confiables por política, y no pueden desactivarse desde el navegador de hooks del usuario".
• Bypass puntual. Para la automatización que ya veta las fuentes de hooks en otro lugar, Codex tiene un flag --dangerously-bypass-hook-trust que ejecuta los hooks habilitados sin confianza persistente para esa invocación. Como dice el nombre, es para casos muy específicos.

Los hooks están activados por defecto. Puedes desactivarlos por completo configurando hooks = false bajo [features] en config.toml.

A veces, un hook de proyecto no aparece para revisión porque Codex nunca lo cargó. Eso tiene que ver con la confianza del proyecto, no con la confianza del hook.

La documentación de hooks de OpenAI dice: "Los hooks locales del proyecto se cargan solo cuando la capa .codex/ del proyecto es confiable". Su página de conceptos básicos de configuración añade que si marcas un proyecto como no confiable, Codex "omite las capas .codex/ con alcance de proyecto, incluyendo la configuración local del proyecto, los hooks y las reglas". Los hooks de usuario y de sistema se siguen cargando.

Así que hay dos filtros para un hook en tu repositorio:

1. El proyecto tiene que ser confiable, para que Codex lea <repo>/.codex/.
2. El hook en sí tiene que ser confiable, en su hash actual.

Si clonaste un repositorio que incluye hooks y no pasa nada, comprueba el primer filtro antes que el segundo.

Los plugins pueden traer sus propios hooks. Por defecto, Codex busca hooks/hooks.json dentro del plugin, y un manifiesto de plugin puede apuntar a otro lugar. OpenAI dice que los hooks de plugins "utilizan el mismo flujo de revisión de confianza que otros hooks no gestionados".

Hay un detalle específico para los plugins. La documentación dice: "Si una actualización de plugin cambia un script incluido, Codex requiere una nueva revisión incluso si la definición del hook sigue siendo la misma".

Por lo tanto, una actualización de plugin puede volver a poner sus hooks en revisión incluso cuando nada en tu propia configuración haya cambiado. Si un hook de plugin deja de ejecutarse después de una actualización, /hooks es el primer lugar donde mirar.

Para el contexto, SessionStart es el evento al que hay que mirar primero. Se ejecuta cuando comienza una sesión, y lo que devuelve se añade para que el modelo lo vea.

La documentación de OpenAI dice que para SessionStart, "El texto plano en stdout se añade como contexto de desarrollador adicional". Un hook también puede devolver JSON con un campo additionalContext, y "Ese texto de additionalContext se añade como contexto de desarrollador adicional".

El evento le dice a tu hook cómo comenzó la sesión. El campo source puede ser startup, resume, clear, compact o fork. Puedes filtrar por eso para cargar diferentes contextos en diferentes casos.

El caso de compactación (compact) es el que hay que conocer para tareas largas. La documentación dice que después de que Codex compacta una sesión raíz, los hooks de SessionStart que coinciden con compact "se ejecutan antes de la siguiente solicitud al modelo". Esto incluye la compactación automática en medio de un turno. Así, un hook puede reafirmar los pocos hechos que una tarea larga no puede permitirse perder justo después de que un resumen reemplace la conversación anterior. Nuestra guía sobre los 500k de contexto de GPT-6.1 Sol en Codex cubre la compactación con más detalle.

Un detalle de sincronización: OpenAI señala que los hooks de SessionStart pueden ejecutarse antes de que un servidor MCP esté listo. Si eso sucede, no bloquean la sesión.

Un hook de SessionStart puede alimentar contexto en cada sesión, lo que hace tentador alimentar mucho. La documentación establece un límite y explica por qué.

Por defecto, Codex limita cada mensaje de salida de hook que ve el modelo a aproximadamente 2,500 tokens. Si un hook devuelve más, Codex guarda el texto completo en un archivo y le da al modelo una vista previa más corta con la ruta del archivo. OpenAI llama a esto desbordamiento (spilling).

Puedes elevar el umbral con additionalContextLimit en el manejador, pero la documentación advierte contra depender de ello: "El contexto de múltiples hooks y plugins se suma y puede degradar el rendimiento del modelo. Elevar additionalContextLimit aumenta ese riesgo".

También señala un punto de privacidad. Debido a que la salida de gran tamaño puede escribirse en el disco, dice que se debe evitar devolver secretos u otros datos sensibles en la salida del hook.

Por lo tanto, un buen hook de SessionStart carga un resumen corto y actual de lo que importa, no un documento completo. Para las convenciones que no cambian, AGENTS.md es el lugar estándar. Nuestra guía sobre cómo evitar que Codex omita tus reglas de AGENTS.md cubre cómo se cargan esos archivos.

Asumir que el hook está roto. Puede que simplemente esté esperando revisión después de un cambio.

Volver a confiar sin leer. La revisión existe porque los hooks ejecutan scripts en tus sesiones.

Editar el hook mientras se depura y olvidar volver a confiar. Cada edición cambia el hash.

Buscar hooks de proyecto en un proyecto no confiable. Codex omite la capa .codex/ del proyecto en ese caso.

Alimentar un documento completo a través de SessionStart. La salida grande se desborda al disco y solo llega una vista previa al modelo.

Paso 1: Abre /hooks y revisa lo que está pendiente

Inicia Codex y abre /hooks. Busca los hooks marcados para revisión, lee lo que ejecuta cada uno y confía en los que esperas. En la aplicación de escritorio, usa Review hooks o Settings > Hooks para los hooks de plugins.

Paso 2: Comprueba el filtro del proyecto

Si un hook de repositorio no aparece en absoluto, confirma que el proyecto es confiable. Codex carga <repo>/.codex/ solo para proyectos confiables.

Paso 3: Haz que el hook de SessionStart sea corto y estable

Haz que el hook devuelva un breve resumen a través de additionalContext, y haz que coincida con compact además de startup para que el resumen regrese después de la compactación. Mantén la definición del hook estable para que no vuelva a revisión cada vez que hagas un pequeño ajuste.

Un hook de SessionStart es un mecanismo de entrega. Decide cuándo llega el contexto a una sesión, no qué es ese contexto o dónde se guarda. Si el resumen que carga vive en los scripts de un repositorio o en los archivos de una máquina, solo estará tan actualizado como la última persona que lo editó, y solo estará disponible donde se ejecute ese hook. Nuestra guía sobre Codex memories v2 cubre la memoria local que Codex mantiene en tu máquina.

MemoryLake es una capa de memoria para mantener ese contexto de proyecto en un solo lugar que tú mantienes, disponible para los asistentes que conectes, como ChatGPT, Claude Code y Codex.

Tú mismo escribes las entradas, con tus propias palabras. No se lee nada de, ni se escribe en, ni se borra de tus hooks, tus archivos hooks.json o config.toml, tus archivos AGENTS.md, tus sesiones de Codex, tus memorias de Codex o el almacenamiento de cualquier proveedor. La revisión de hooks, la confianza y SessionStart funcionan de la manera que describe OpenAI.

Paso 1: Crea una clave de API

Inicia sesión y genera una clave desde el panel de control. La clave pertenece a tu espacio de trabajo de MemoryLake y es independiente de tu cuenta de OpenAI.

Paso 2: Sube tus primeras memorias

Comienza con el breve resumen con el que querrías que empezara una sesión: el objetivo del proyecto, las decisiones actuales y las restricciones. Una decisión por entrada, para que puedas actualizar una sin reescribir el resto.

Paso 3: Conecta tu IA y agentes

Conecta Codex y cualquier otro asistente que utilices. Las mismas entradas están disponibles en todas las sesiones y herramientas, y las actualizas en un solo lugar.

La primera diferencia es que hay menos lagunas silenciosas. El contexto en el que confías no está solo en un script que podría estar esperando revisión.

La segunda es un hook estable. Cuando el resumen vive en otro lugar, la definición del hook cambia con menos frecuencia, por lo que vuelve a revisión con menos frecuencia.

La tercera es la consistencia entre herramientas. Las mismas decisiones están disponibles en Codex y en los otros asistentes que conectes.

Espera una revisión después de cada cambio. La confianza está ligada al hash actual del hook.

Lee antes de confiar. Los hooks ejecutan scripts dentro de tus sesiones.

Confía primero en el proyecto. Los hooks de repositorio no se cargan en proyectos no confiables.

Vuelve a comprobar después de las actualizaciones de plugins. Un script incluido que haya cambiado necesita una nueva revisión.

Coincide con compact en SessionStart. Restaura lo esencial justo después de la compactación.

Mantén corta la salida del hook. La salida grande se desborda al disco y el contexto se acumula.

Deja los secretos fuera de la salida del hook. La salida de gran tamaño puede escribirse en el disco.

Que los hooks necesiten revisión significa que Codex encontró hooks nuevos o modificados en los que no se ha confiado en su versión actual. La documentación de OpenAI dice que Codex registra la confianza contra el hash de cada hook, por lo que los hooks nuevos o modificados se omiten hasta que confíes en ellos en /hooks. Los hooks de plugins siguen la misma regla, y una actualización de plugin que cambie un script incluido necesita una nueva revisión. Los hooks de proyecto también necesitan un proyecto confiable antes de cargarse.

El hook que más vale la pena configurar correctamente es SessionStart. Su salida se añade como contexto de desarrollador cuando comienza una sesión, y un hook que coincida con compact se ejecuta de nuevo después de la compactación. Mantén ese contexto corto, mantén el hook estable y consulta /hooks cada vez que algo que esperabas en una sesión no esté allí.