Hooks do Codex tornam o harness real

A partir do Codex 0.150.1 (27 de agosto de 2026), os hooks do Codex registram doze eventos de ciclo de vida, se recusam a executar qualquer hook não gerenciado até que você revise e confie na sua definição exata, e vêm habilitados por padrão. O recurso que chegou à disponibilidade geral no pacote de lançamento de 14 de maio, ao lado do app do ChatGPT para celular, amadureceu e virou uma superfície de governança: PreToolUse pode bloquear ou reescrever uma chamada de ferramenta antes de ela rodar, PermissionRequest pode decidir uma aprovação, PostToolUse pode substituir o resultado que o modelo vê, e Stop pode se recusar a deixar um turno terminar.²³

O Codex já não parece um assistente de programação que espera dentro de um terminal. Parece uma camada operacional que acompanha o trabalho entre máquinas, aprovações, projetos, chats, diffs, testes, capturas de tela, plugins, credenciais e ferramentas locais.⁴

Os hooks do Codex tornam o harness real. Quando o agente consegue trabalhar a partir de um celular, alcançar ambientes de desenvolvimento remotos e executar hooks de ciclo de vida, as equipes precisam de um sistema de controle em volta do modelo: evidência, aprovações, custódia de git, disciplina de fontes e bom gosto.

TL;DR

O Codex suporta o formato de fluxo de trabalho que as equipes de agentes vinham construindo em privado: trabalho de longa duração, execução remota, condução pelo celular, aprovações, hooks, credenciais com escopo e sinais de auditoria.²⁴⁵ O motor de hooks na 0.150.0 registra doze eventos, todo hook não gerenciado permanece ignorado até que você confie no seu hash atual, e os hooks carregam de arquivos hooks.json ou de tabelas [hooks] inline no config.toml.³⁷ A pergunta prática não é “como escrevemos prompts para o Codex?”. A pergunta prática é “o que o Codex precisa provar antes de confiarmos no resultado?”. As equipes devem usar hooks e configuração para codificar portões de revisão, limites de segurança, padrões de escrita pública e disciplina de release. Devem manter a maquinaria privada em privado e publicar apenas o padrão, os critérios de aceitação e o resultado verificado.

Principais aprendizados

Para equipes de engenharia: - Trate os hooks do Codex como infraestrutura de processo, não como decoração. O fluxo de revisão de confiança faz parte dessa infraestrutura, não é atrito a contornar. - Comece com evidência, aprovações, custódia de git e verificações de release antes de acrescentar automações engenhosas.

Para quem constrói ferramentas de agentes: - Construa em torno das superfícies reais do Codex: controle pelo celular, hosts de Remote SSH, modos de sandbox, políticas de aprovação, instruções de projeto, hooks, telemetria e controle de versão. - Porte os trabalhos a serem feitos, não os formatos antigos de slash commands.

Para quem escreve em público: - Use a documentação oficial em learn.chatgpt.com para o comportamento atual do Codex e confira o código-fonte do motor quando a documentação estiver atrás de um release. - Descreva a prática privada como análise do autor e deixe fora do texto público prompts privados, corpos de hooks, caminhos de arquivos, listas de fontes, credenciais e detalhes internos de pontuação.

De onde vieram os hooks do Codex?

A OpenAI publicou “Work with Codex from anywhere” (trabalhe com o Codex de qualquer lugar) em 14 de maio de 2026.¹ A entrada do changelog da documentação para essa data registra o pacote de lançamento: o Codex passou a ser utilizável no app do ChatGPT para celular ao conectá-lo a um Mac rodando o app do Codex, os hooks chegaram à disponibilidade geral e os tokens de acesso do Codex chegaram para automação confiável.² O Codex roda a partir do host conectado, então os mesmos projetos, arquivos, credenciais, plugins, skills e configurações ficam disponíveis a partir de um celular.²

As conexões remotas estendem o alcance para além de uma mesa. A capacidade de Remote SSH do anúncio aparece na documentação como hosts SSH: o app do ChatGPT para desktop pode adicionar projetos remotos a partir de um host SSH e rodar chats contra o sistema de arquivos e o shell remotos. O enquadramento é concreto: “Remote access uses the connected host’s projects, chats, files, credentials, permissions, plugins, Computer Use, browser setup, and local tools.” (o acesso remoto usa os projetos, chats, arquivos, credenciais, permissões, plugins, Computer Use, configuração de navegador e ferramentas locais do host conectado).⁴

Os hooks em si antecedem o lançamento como um experimento e cresceram além dele depois. A documentação os define como um framework de extensibilidade que executa scripts ou ferramentas MCP durante o loop agêntico, e nomeia trabalhos concretos: enviar chats para um motor de logging, bloquear chaves de API coladas por acidente, resumir chats em memórias persistentes, rodar uma checagem de validação quando um turno para e personalizar o prompting por diretório.³ Os hooks agora vêm habilitados por padrão; features.hooks no config.toml funciona como interruptor geral, e features.codex_hooks sobrevive apenas como um alias obsoleto.³⁶

Esses detalhes importam porque transformam o trabalho de agentes de uma troca de chat em operações governadas.

Como os hooks do Codex aparecem na configuração?

Um post sobre hooks deve mostrar um hook. O Codex descobre hooks ao lado das camadas de configuração ativas, mais utilmente ~/.codex/hooks.json, <repo>/.codex/hooks.json ou tabelas inline no config.toml de qualquer uma das camadas; quando existem várias fontes, todos os hooks correspondentes carregam e rodam.³ Um hooks.json mínimo com um portão de ferramenta e um portão de conclusão:

{
  "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"
          }
        ]
      }
    ]
  }
}

O mesmo formato escrito inline no 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"

Três níveis organizam todo hook: um evento, um grupo matcher que decide quando o evento se aplica e um ou mais handlers (command ou mcp_tool).³ Os eventos atuais, com a lista de doze entradas do motor como autoridade:³⁷

A documentação de hooks publicada ainda documenta onze desses eventos; ainda não tem uma seção de Interrupt. A entrada do changelog da 0.150.0 (#40511) e HOOK_EVENT_NAMES: [&str; 12] no código-fonte do motor em rust-v0.150.0 carregam o décimo segundo.²⁷ Quando uma página e o motor discordam, confie no motor.

Quais chamadas de ferramenta os hooks conseguem ver de fato?

Versões anteriores da documentação avisavam que PreToolUse cobria pouco além de chamadas de shell e MCP. A documentação atual amplia a superfície: “PreToolUse and PostToolUse can observe more than shell and MCP calls. Most local function tools use the same hook path,” (PreToolUse e PostToolUse podem observar mais do que chamadas de shell e MCP; a maioria das ferramentas de função locais usa o mesmo caminho de hooks), então um matcher pode nomear ferramentas como update_plan diretamente, e spawn_agent também corresponde como Agent.³ Comandos de shell correspondem como Bash, edições de arquivo do apply_patch correspondem como apply_patch, Edit ou Write, e ferramentas MCP correspondem a nomes como mcp__filesystem__read_file.³

As ferramentas hospedadas continuam de fora: WebSearch e seus pares nunca passam pelo caminho local de hooks de ferramentas de função.³ A documentação mantém uma ressalva suavizada que vale citar por inteiro: “Some specialized tool paths can opt out of the default hook path. Treat tool hooks as a useful guardrail, not a complete enforcement boundary.” (alguns caminhos de ferramenta especializados podem sair do caminho padrão de hooks; trate hooks de ferramenta como um guardrail útil, não como um limite completo de imposição).³ O sandboxing continua dono do limite duro; os hooks são donos da revisão e da condução dentro dele.

Como o Codex decide quais hooks podem rodar?

Hooks são código que conduz o agente, então o Codex governa os próprios hooks. O sistema de controle em volta do modelo começa aqui.

Antes de qualquer hook não gerenciado rodar, o Codex exige que você revise e confie na sua definição exata. A confiança é registrada contra o hash atual do hook, então um hook novo ou editado é marcado para revisão e ignorado até receber confiança de novo.³ O comando /hooks na CLI abre a superfície de revisão: inspecionar fontes de hooks, revisar hooks novos ou alterados, confiar neles ou desabilitar hooks individuais. Quando há hooks precisando de revisão na inicialização, o Codex imprime um aviso apontando para /hooks.³

Hooks gerenciados de fontes de sistema, MDM, nuvem ou requirements.toml ficam acima desse fluxo: são confiáveis por política e não podem ser desabilitados no navegador de hooks do usuário.³ Plugins ficam dentro dele: instalar ou habilitar um plugin não dá confiança aos hooks que ele traz, que permanecem ignorados até serem revisados como qualquer outro.³ Hooks locais de projeto só carregam quando a camada .codex/ do projeto é confiável; um projeto não confiável ainda carrega seus hooks de usuário e de sistema.³

A automação segue a mesma regra. Uma execução de codex exec não tem interface de revisão, então um hook sem confiança é ignorado em silêncio até que você confie nele primeiro em uma sessão interativa; a documentação ainda não diz isso, mas a superfície de revisão na inicialização do motor existe apenas na TUI interativa.⁷ Para pipelines que vetam as fontes de hooks em outro lugar, --dangerously-bypass-hook-trust roda os hooks habilitados sem confiança persistida por aquela única invocação.³ Confie deliberadamente ou veja seu portão não disparar: o harness decide qual código pode conduzir o agente antes de qualquer um deles rodar.

O que acontece quando um hook bloqueia, e quando é tarde demais?

O timing decide o que um hook ainda pode mudar. A maioria dos hooks roda de forma síncrona com timeout padrão de 600 segundos; SessionEnd e Interrupt têm padrão de um segundo e teto de três: SessionEnd dispara enquanto a sessão está sendo desmontada, e Interrupt dispara enquanto o usuário está esperando.³⁷

PreToolUse age antes de qualquer coisa acontecer, então segura as cartas mais fortes: negue a chamada ou reescreva-a retornando permissionDecision: "allow" com updatedInput. O formato de negação:

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

Código de saída 2 com a razão no stderr também bloqueia.³

PostToolUse age depois que a ferramenta rodou, então não consegue desfazer efeitos colaterais. Um decision: "block" substitui o resultado da ferramenta pelo seu feedback e continua o modelo a partir dessa mensagem, o que corrige o rumo sem fingir que o comando nunca aconteceu.³ Stop transforma uma recusa em continuação: bloqueie uma conclusão e o Codex segue trabalhando, com a sua razão como o novo prompt.³

Para checagens que nunca deveriam ficar no caminho crítico, defina async = true em um handler de comando. Hooks em segundo plano rodam enquanto o Codex continua, entregam a saída no próximo ponto seguro e explicitamente não podem bloquear, aprovar ou reescrever nada; mantenha síncronas as políticas de ferramenta, as decisões de permissão, a rejeição de prompt e a continuação de turno.³

O que mudou na 0.149 e na 0.150?

Dois releases estáveis no fim de agosto apertaram a história de governança.

O Codex CLI 0.149.0 (20 de agosto de 2026) aposentou a política de aprovação untrusted (#39630); uma configuração que ainda a nomeia agora falha com um erro acionável mandando remover o ajuste.²⁷ O Codex CLI 0.150.0 (26 de agosto de 2026) adicionou o evento de hook Interrupt (#40511): “New Interrupt hooks can run commands or MCP handlers when an active top-level turn is interrupted.” (novos hooks de Interrupt podem rodar comandos ou handlers MCP quando um turno ativo de nível superior é interrompido). Hooks de Interrupt nunca rodam para subagentes.²⁷ O mesmo release impediu projetos não confiáveis de fornecer instruções de AGENTS.md no nível do projeto (#39837), o que combina com a regra existente de que hooks locais de projeto só carregam de uma camada .codex/ confiável.²³

A direção é consistente: um diretório não confiável ganha cada vez menos autoridade sobre o agente que entra nele. Instruções, hooks e atalhos de aprovação agora passam por decisões explícitas de confiança.

Por que hooks importam mais do que o celular?

O acesso pelo celular muda onde o humano pode intervir. Os hooks mudam o que o sistema pode impor.

Um celular permite que um operador responda a uma pergunta longe da mesa. Um hook pode pegar o agente antes de uma ação arriscada, depois de uma edição de arquivo, antes da conclusão ou durante uma checagem de release. O celular resolve a latência. O hook resolve os padrões.

O Codex já tem superfícies de controle de primeira parte em torno de sandboxing e aprovações. A documentação de segurança combina o modo de sandbox, que define o que o agente pode tecnicamente fazer, com a política de aprovação, que define quando o Codex deve parar e perguntar antes de agir.⁵ O agente roda com o acesso à rede desligado por padrão, e o modo local padrão workspace-write mantém o acesso à rede desligado a menos que o usuário o habilite.⁵ Os hooks ficam ao lado desses controles como camada de revisão e condução, não como substituto do sandboxing.

Hooks podem tornar padrões locais executáveis:

O modelo pode esquecer uma regra. Um hook pode rodar a regra de novo no momento em que a regra importa.

O que pertence ao harness e não ao provedor?

Um harness de agente é a camada operacional em volta de um modelo: permissões, memória, ferramentas, hooks, checagens de fontes, portões de release, pacotes de revisão e disciplina de rollback. O termo pode soar privado ou rebuscado, mas o trabalho é simples. A camada transforma intenção em trabalho com prestação de contas.

O Codex agora expõe superfície oficial suficiente para tornar essa camada explícita. As conexões remotas carregam o ambiente do host. Modos de sandbox e políticas de aprovação definem limites de ação. Arquivos de configuração definem modelos, projetos, permissões, servidores MCP, skills, hooks, telemetria e recursos.⁶ A exportação por OpenTelemetry continua opt-in e desligada por padrão; quando habilitada, o Codex emite eventos estruturados cobrindo chats, requisições de API, atividade de stream, prompts do usuário (mascarados por padrão), decisões de aprovação de ferramentas e resultados de ferramentas.⁵⁸

Esse conjunto de superfícies cria uma divisão útil:

O provedor deve continuar melhorando o runtime. A equipe continua dona do julgamento.

O que as equipes devem codificar primeiro?

Comece com quatro portões. Eles pagam o aluguel de imediato.

Portão de evidência

O post de lançamento original do Codex enfatizava evidência verificável: logs de terminal, saídas de teste e passos rastreáveis durante a conclusão da tarefa.⁹ Torne essa expectativa inegociável. Uma conclusão significativa deve nomear os arquivos alterados, os comandos executados, o comportamento observado, as checagens que falharam e as lacunas restantes.

Para trabalho público, evidência inclui links de fontes e alinhamento entre afirmação e fonte. Para releases web, evidência inclui rotas renderizadas, metadados, schema, arquivos de descoberta, estado de deployment, frescor de cache e marcadores de mudança ao vivo. Para traduções, evidência inclui cobertura de locales, portões de qualidade, linhas de armazenamento ou arquivos de cache e status de revisão nativa quando exigido.

Portão de aprovação

Não use uma única postura de aprovação para toda ação. A tabela de combinações atual da documentação de aprovações vai do preset Auto (sandbox workspace-write com aprovações on-request) até navegação segura somente leitura, CI não interativo somente leitura, modo de revisão automática e acesso total perigoso.⁵ Uma linha está atrás da realidade: a política untrusted ainda aparece na página, mas a 0.149.0 a aposentou e configurações explícitas agora dão erro.²⁵ Para uma postura de sempre perguntar hoje, combine o sandbox read-only com aprovações on-request. Uma política local forte mantém o mesmo formato: leituras de baixo risco passam em silêncio, trabalho com efeitos colaterais recebe revisão, e trabalho destrutivo ou visível externamente recebe evidência explícita.

Portão de custódia de git

O trabalho de agente precisa de alças de rollback. A própria documentação de segurança do Codex diz que o Codex funciona melhor com controle de versão: mantenha o status limpo antes de delegar, faça commits com frequência, rode verificação direcionada, revise diffs e documente decisões nas mensagens de commit.⁵

Esse conselho deve virar processo. Faça commit depois de pontos de salvamento coerentes e verificados. Faça stage de caminhos exatos. Separe commits por preocupação reversível de forma independente. Pergunte antes de fazer push, a menos que o fluxo de release já conceda autoridade de publicação. Não varra arquivos sujos não relacionados para dentro de um commit só porque o agente os viu por acaso.

Portão de bom gosto

Programar com IA torna a implementação mais barata. Implementação mais barata aumenta o valor do bom gosto.

Bom gosto não significa preferência decorativa. Significa que o trabalho melhora o produto como um todo. Significa que o agente pode recusar um caminho tecnicamente possível que enfraquece o resultado. Significa que a escrita pública evita maquinaria privada, afirmações sem sustentação e enchimento. Significa que um patch local correto ainda pode falhar se o caminho visível ao usuário continuar quebrado.

Um portão de bom gosto deve perguntar:

O que o trabalho da Mozilla no Firefox prova?

O post da Mozilla de 7 de maio sobre o fortalecimento do Firefox com o Claude Mythos Preview mostra o mesmo ponto a partir de outra stack. A equipe diz que as primeiras tentativas de auditoria de código com LLMs mostraram promessa, mas tinham falsos positivos demais para escalar. Harnesses agênticos mudaram a economia porque conseguiam criar e rodar casos de teste reproduzíveis para testar dinamicamente hipóteses de bugs.¹⁰

A frase importante da Mozilla não é sobre o modelo sozinho. A equipe diz que a descoberta era necessária, mas não suficiente. O sistema útil precisava se integrar ao ciclo de vida completo dos bugs de segurança: alvos, deduplicação, rastreamento de bugs, triagem, correções e release.¹⁰ Os autores também dizem que o pipeline refletia a semântica, o ferramental e os processos da base de código do Firefox.¹⁰

Essa é a lição para o Codex. Modelos melhores importam. O sistema operacional em volta do modelo decide se o trabalho vira saída confiável.

O que deve ficar fora do texto público?

Um artigo público sobre o Codex não deve despejar o sistema de trabalho privado.

Mantenha isto fora do texto público:

• prompts privados e corpos de hooks;
• caminhos locais sensíveis;
• mapas exatos de fontes e detalhes internos de pontuação;
• identificadores de conta e manuseio de credenciais;
• atalhos privados de fluxo de trabalho;
• comportamento de plugins não lançados;
• qualquer coisa que ajude um estranho a reconstruir operações internas.

Publique o padrão no lugar disso: o que o portão protege, que evidência ele exige, que falha ele pega e como uma equipe pode implementar a ideia usando superfícies oficiais do Codex.

Essa linha protege a confiança. Também melhora a escrita. Maquinaria privada costuma soar como folclore. Critérios públicos de aceitação ajudam outras equipes a raciocinar sobre os próprios sistemas.

Como é um mapa mínimo de harness para o Codex?

Construa o menor mapa de controle que comprove trabalho útil.

Comece explícito. Rode uma tarefa real. Registre onde o portão ajudou e onde atrapalhou. Promova apenas as partes que melhoram o resultado visível ao usuário.

Resumo rápido

Hooks do Codex, Remote SSH, controle pelo celular, sandboxing, aprovações, configuração, telemetria e controle de versão apontam na mesma direção: agentes de programação precisam de sistemas operacionais em volta deles.²⁴⁵⁶ O agente pode escrever código. O harness decide o que conta como trabalho.

As melhores equipes não vão vencer produzindo o maior volume de saída de agente. Vão vencer tornando o trabalho de agente inspecionável, reversível, com fontes, com bom gosto e digno de release.

FAQ

O que são os hooks do Codex?

Os hooks do Codex executam scripts ou ferramentas MCP durante o loop agêntico, carregados de arquivos hooks.json ou de tabelas [hooks] inline no config.toml. A documentação nomeia os trabalhos com clareza: enviar chats para um motor de logging, bloquear chaves de API coladas por acidente, resumir chats em memórias persistentes, rodar validação quando um turno para e personalizar o prompting por diretório.³ O motor na 0.150.0 registra doze eventos, de PreToolUse, PermissionRequest e PostToolUse até Stop e o novo Interrupt; a página da documentação ainda lista onze enquanto se atualiza.³⁷

Por que os hooks do Codex importam?

Hooks permitem que as equipes coloquem padrões nos pontos de decisão em vez de depender só de prompts. Um hook pode checar evidência, qualidade de fontes, estado do git ou prontidão de release quando o agente age ou tenta terminar.

Por que meu hook não rodou?

A resposta usual é confiança. O Codex ignora qualquer hook não gerenciado cujo hash atual você não revisou, imprime um aviso na inicialização em sessões interativas e ignora em silêncio na automação com codex exec.⁷ Abra /hooks para revisar e confiar nele, ou passe --dangerously-bypass-hook-trust apenas em pipelines que vetam as fontes de hooks em outro lugar.³

O Codex no celular substitui o fluxo de trabalho local de agentes?

Não. O controle pelo celular permite conduzir o trabalho longe da mesa, mas o host conectado ainda fornece os projetos, chats, arquivos, credenciais, permissões, plugins e ferramentas locais.⁴ As equipes ainda precisam de política local, credenciais seguras, controle de versão e verificação.

O que um harness de Codex deve incluir primeiro?

Comece com instruções de projeto, postura de sandbox e aprovações, um limite de segredos, um portão de parada por evidência, custódia de git com caminhos exatos, verificação de fontes para afirmações públicas e um portão de release para trabalho visível ao usuário.

As equipes devem publicar seus hooks de Codex?

Publique padrões e critérios de aceitação, não corpos de hooks privados nem detalhes sensíveis de fluxo de trabalho. Um post público útil pode explicar o trabalho de um hook sem expor caminhos privados, mapas de fontes, prompts, credenciais ou regras de pontuação.

Referências