Hooks do Codex: como colocar sua própria lógica no loop agêntico

Quando o prompt não é suficiente

A maioria das pessoas personaliza o Codex — o agente de codificação da OpenAI — por meio de prompts. Você descreve a tarefa, dá instruções e diz que tipo de resultado espera. Funciona bem na maioria dos casos, mas há situações em que só o prompt não resolve: quando você quer rodar a sua própria lógica em etapas específicas da execução.

Para isso existem os hooks do Codex. Neste guia, você vai entender onde eles se encaixam no loop agêntico e ver um caso prático completo de como criar uma porta de qualidade para uma pesquisa automatizada.

O que são hooks e o loop agêntico

Quando o Codex trabalha em uma tarefa, ele percorre um ciclo: analisa o problema, chama ferramentas e conclui. Em diferentes pontos desse ciclo, o Codex emite eventos com nomes específicos:

• SessionStart — emitido quando a sessão começa;
• PreToolUse — quando o Codex está prestes a chamar uma ferramenta;
• PostToolUse — depois que a ferramenta termina;
• Stop — quando o Codex está pronto para finalizar a resposta;
• SessionEnd — quando a sessão termina.

Um hook é o mecanismo que permite anexar sua própria lógica a esses eventos. Por exemplo, usar SessionStart para carregar contexto extra, PreToolUse para inspecionar um comando antes de executá-lo, ou Stop para validar o resultado final.

Ao configurar um hook, você precisa responder a três perguntas básicas: em que ponto do ciclo ele roda (evento), sob quais condições (matcher) e que ação ele executa (handler).

Caso prático: porta de qualidade em uma pesquisa profunda

Vamos construir um pequeno fluxo de pesquisa. O Codex recebe um tema, faz buscas na web e devolve três tendências importantes dos últimos 90 dias em um formato estruturado. Para demonstrar o conceito de hook, adicionamos uma verificação de qualidade logo antes de o Codex terminar.

Primeiro, definimos o que o hook deve checar: cada tendência precisa ter ao menos duas fontes; o resumo precisa de pelo menos dez fontes únicas; e essas fontes devem vir de pelo menos cinco domínios diferentes.

Como a verificação só faz sentido depois que o Codex preparou a resposta, usamos um hook de Stop. Criamos o script de validação em .codex/hooks/validate_research.py:

import json
import sys
from urllib.parse import urlparse

MIN_PER_TREND = 2
MIN_SOURCES = 10
MIN_DOMAINS = 5

event = json.load(sys.stdin)
brief = json.loads(event["last_assistant_message"])

errors = []
all_urls = set()

for number, trend in enumerate(brief["trends"], 1):
    urls = set(trend["sources"])
    all_urls.update(urls)
    if len(urls) < MIN_PER_TREND:
        errors.append(f"Trend {number} has fewer than {MIN_PER_TREND} sources.")

domains = {urlparse(u).netloc for u in all_urls}
if len(all_urls) < MIN_SOURCES:
    errors.append(f"Add at least {MIN_SOURCES} unique sources.")
if len(domains) < MIN_DOMAINS:
    errors.append(f"Use sources from at least {MIN_DOMAINS} unique domains.")

if errors:
    print(json.dumps({"decision": "block", "reason": "\n".join(errors)}))
else:
    print(json.dumps({"decision": "allow"}))

Quando o evento Stop é emitido, o Codex passa o last_assistant_message para o script, que analisa a resposta e aplica as checagens. Se algo falhar, o script retorna uma decisão de bloqueio. Para o evento Stop, “bloquear” não encerra a execução — apenas impede o Codex de finalizar, permitindo que ele use o feedback para melhorar a resposta na mesma rodada.

Depois, definimos o hook no arquivo .codex/hooks.json, dizendo ao Codex quando e como executá-lo:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 .codex/hooks/validate_research.py",
            "commandWindows": "python .codex\\hooks\\validate_research.py"
          }
        ]
      }
    ]
  }
}

No teste, o Codex produziu três tendências com sete fontes — cada tendência tinha fontes suficientes, mas o resumo não atingia as dez fontes exigidas. O hook de Stop entrou em ação: o Codex recebeu o feedback, adicionou mais fontes e, na rodada seguinte, entregou um resumo com 12 fontes de 10 domínios diferentes. Só então o hook permitiu a conclusão.

Quando usar cada tipo de hook

O mesmo raciocínio se aplica aos demais eventos do ciclo. Use SessionStart para carregar contexto no início, PreToolUse para inspecionar uma operação antes que aconteça, e PostToolUse para processar o resultado de uma chamada de ferramenta. A chave é sempre responder às três perguntas — ponto do ciclo, condição e ação — para adicionar lógica determinística em volta da execução do Codex.