---
格式版本: 2
标题: "Hooks | ChatGPT Learn"
原文链接: "https://developers.openai.com/codex/hooks"
发布日期: "2026-08-16"
发布时间校准状态: "found"
发布时间需复核: "否"
发布时间来源: "rule:local:strict_original_body"
发布时间证据: "Published Time: Sun, 16 Aug 2026 07:37:27 GMT"
发布时间校准原因: "规则确认唯一严格发布时间，来源 local:strict_original_body"
发布时间校准置信度: "high"
发布时间候选数量: 4
发布时间严格候选数量: 1
发布时间原页读取状态: "source template page reused from URL open"
发布时间未找到原因: ""
发布时间校准时间: "2026-08-17T00:06:37+08:00"
发布时间仲裁状态: "skipped"
发布时间仲裁尝试次数: 0
发布时间仲裁耗时毫秒: 0
发现时间: "2026-08-16T23:54:06+08:00"
入库时间: "2026-08-16T16:06:37.560Z"
来源平台: "固定入口"
搜索渠道: "fixed_url"
搜索词: "https://developers.openai.com/blog"
匹配关键词:
  - "deployment"
  - "performance"
  - "latency"
  - "throughput"
  - "AI"
相关厂家:
  - "OpenAI"
  - "Microsoft"
  - "AWS"
  - "Google"
  - "Oracle"
相关专家:
  []
内容类型: "网页"
抓取工具: "Jina Reader"
清洗工具: "Jina Reader Markdown + Defuddle/Readability 正文提取"
原始附件:
  []
AI优质: "否"
AI打分: 10
AI分档: "非优质"
AI质检状态: "不通过"
AI打分理由: "页面为OpenAI Codex文档导航页，仅包含API文档链接和界面导航，无任何与超节点/AI Rack/机柜级AI基础设施/供电/散热/互连/量产落地等相关内容，完全无关。"
AI质检模型: "ali-deepseek-v4-flash"
AI质检时间: "2026-08-17T00:06:43+08:00"
AI主题相关性: 0
AI来源权威性: 5
AI新颖性: 0
AI技术细节: 0
AI商业部署信号: 0
AI完整性: 5
AI摘要: "本文是 OpenAI Codex 的 Hooks 文档页面，属于 ChatGPT Learn 开发者文档，旨在为开发者提供 Hooks 功能的参考说明。"
AI摘要模型: "ali-deepseek-v4-flash"
AI摘要时间: "2026-09-07T03:26:38.832Z"
采集批次: "2026年8月16日20点37分10秒"
采集批次ID: "20260816-203710-016"
去重键: "https://developers.openai.com/codex/hooks"
---

Title: Hooks | ChatGPT Learn

URL Source: https://developers.openai.com/codex/hooks

Published Time: Sun, 16 Aug 2026 07:37:27 GMT

Markdown Content:
For the complete documentation index, see [llms.txt](https://developers.openai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL. 

[![Image 1: OpenAI Developers](https://developers.openai.com/OpenAI_Developers.svg)ChatGPT](https://developers.openai.com/)

[Home](https://developers.openai.com/)

[API](https://developers.openai.com/api/docs)

[Codex](https://learn.chatgpt.com/docs)

[Docs Guides, concepts, and product docs for Codex](https://learn.chatgpt.com/docs)[Use cases Example workflows and tasks teams can take on with ChatGPT or Codex](https://learn.chatgpt.com/use-cases)

[Docs](https://developers.openai.com/codex)

[Use cases](https://developers.openai.com/codex/use-cases)

[Resources](https://developers.openai.com/codex/resources)

[ChatGPT](https://developers.openai.com/chatgpt)

[Plugins Extend ChatGPT and Codex](https://developers.openai.com/plugins)[Workspace Agents Trigger published ChatGPT workspace agents](https://developers.openai.com/workspace-agents)[Commerce Build commerce flows in ChatGPT](https://developers.openai.com/commerce)[Ads Publish and measure ads in ChatGPT](https://developers.openai.com/ads)

[Resources](https://developers.openai.com/learn)

[Showcase Demo apps to get inspired](https://developers.openai.com/showcase)[Blog Learnings and experiences from developers](https://developers.openai.com/blog)[Cookbook Notebook examples for building with OpenAI models](https://developers.openai.com/cookbook)[Learn Docs, videos, and demo apps for building with OpenAI](https://developers.openai.com/learn)[Community Programs, meetups, and support for builders](https://developers.openai.com/community)

Start searching

[API Dashboard](https://platform.openai.com/login)

[Try ChatGPT](https://chatgpt.com/)

[Overview](https://developers.openai.com/codex)[Features](https://developers.openai.com/codex/features)[Configuration](https://developers.openai.com/codex/configuration)[Developers](https://developers.openai.com/codex/developers)[Security](https://developers.openai.com/codex/security-administration)[Administration](https://developers.openai.com/codex/administration)[Use Cases](https://developers.openai.com/codex/use-cases)[Resources](https://developers.openai.com/codex/resources)

## Search the docs

Search docs 

### Suggested

responses create reasoning_effort realtime prompt caching

Primary navigation

 API  Codex  ChatGPT  Docs  Use cases  Resources  Resources 

Search docs 

### Suggested

responses create reasoning_effort realtime prompt caching

 Overview  Models  Agents  Tools  Voice & Audio  Production  API reference 

Docs section Overview

*   [Home](https://developers.openai.com/api/docs)

### Get started

*   [Quickstart](https://developers.openai.com/api/docs/quickstart)
*   [Using GPT-5.6](https://developers.openai.com/api/docs/guides/latest-model)
*   [Key concepts](https://developers.openai.com/api/docs/concepts)

### Core concepts

*   [Responses API](https://developers.openai.com/api/docs/guides/migrate-to-responses)
*   [Conversation state](https://developers.openai.com/api/docs/guides/conversation-state)
*   [Background mode](https://developers.openai.com/api/docs/guides/background)
*   [Streaming](https://developers.openai.com/api/docs/guides/streaming-responses)
*   [WebSocket mode](https://developers.openai.com/api/docs/guides/websocket-mode)
*   [Multi-agent](https://developers.openai.com/api/docs/guides/responses-multi-agent)
*   [Webhooks](https://developers.openai.com/api/docs/guides/webhooks)
*   [File inputs](https://developers.openai.com/api/docs/guides/file-inputs)
*   [Compaction](https://developers.openai.com/api/docs/guides/compaction)
*   [Counting tokens](https://developers.openai.com/api/docs/guides/token-counting)

### SDKs and CLI

*   [OpenAI SDK](https://developers.openai.com/api/docs/libraries)
*   [OpenAI CLI](https://developers.openai.com/api/docs/libraries/openai-cli)

### Resources

*   [Changelog](https://developers.openai.com/api/docs/changelog)
*   [Deprecations](https://developers.openai.com/api/docs/deprecations)
*   [Supported countries](https://developers.openai.com/api/docs/supported-countries)
*   [OpenAI Crawlers](https://developers.openai.com/api/docs/bots)
*   [Terms and policies](https://openai.com/policies)

### Legacy APIs

*   
Agent Builder
    *   [Overview](https://developers.openai.com/api/docs/guides/agent-builder)
    *   [Migration guide](https://developers.openai.com/api/docs/guides/agent-builder/migrate-from-agent-builder)
    *   [Node reference](https://developers.openai.com/api/docs/guides/node-reference)
    *   [Safety in building agents](https://developers.openai.com/api/docs/guides/agent-builder-safety)

*   
Evals
    *   [Getting started](https://developers.openai.com/api/docs/guides/evaluation-getting-started)
    *   [Working with evals](https://developers.openai.com/api/docs/guides/evals)
    *   [Prompt optimizer](https://developers.openai.com/api/docs/guides/prompt-optimizer)
    *   [External models](https://developers.openai.com/api/docs/guides/external-models)
    *   [Best practices](https://developers.openai.com/api/docs/guides/evaluation-best-practices)
    *   [Graders](https://developers.openai.com/api/docs/guides/graders)

*   
Fine-tuning
    *   [Optimization cycle](https://developers.openai.com/api/docs/guides/model-optimization)
    *   [Supervised fine-tuning](https://developers.openai.com/api/docs/guides/supervised-fine-tuning)
    *   [Vision fine-tuning](https://developers.openai.com/api/docs/guides/vision-fine-tuning)
    *   [Direct preference optimization](https://developers.openai.com/api/docs/guides/direct-preference-optimization)
    *   [Reinforcement fine-tuning](https://developers.openai.com/api/docs/guides/reinforcement-fine-tuning)
    *   [RFT use cases](https://developers.openai.com/api/docs/guides/rft-use-cases)
    *   [Best practices](https://developers.openai.com/api/docs/guides/fine-tuning-best-practices)

*   
Assistants API
    *   [Migration guide](https://developers.openai.com/api/docs/assistants/migration)
    *   [Deep dive](https://developers.openai.com/api/docs/assistants/deep-dive)
    *   [Tools](https://developers.openai.com/api/docs/assistants/tools)

*   [Model catalog](https://developers.openai.com/api/docs/models)

### Choose a model

*   [Pricing](https://developers.openai.com/api/docs/pricing)
*   [Model selection](https://developers.openai.com/api/docs/guides/model-selection)

### Text and code

*   [Text generation](https://developers.openai.com/api/docs/guides/text)
*   [Code generation](https://developers.openai.com/api/docs/guides/code-generation)
*   [Structured output](https://developers.openai.com/api/docs/guides/structured-outputs)

### Prompting

*   [Overview](https://developers.openai.com/api/docs/guides/prompting)
*   [Prompt engineering](https://developers.openai.com/api/docs/guides/prompt-engineering)
*   [Citation formatting](https://developers.openai.com/api/docs/guides/citation-formatting)
*   [Migration guide](https://developers.openai.com/api/docs/guides/prompting/migrate-from-prompt-object)
*   [Prompt generation](https://developers.openai.com/api/docs/guides/prompt-generation)
*   [Frontend prompting](https://developers.openai.com/api/docs/guides/frontend-prompt)

### Reasoning

*   [Reasoning models](https://developers.openai.com/api/docs/guides/reasoning)
*   [Reasoning best practices](https://developers.openai.com/api/docs/guides/reasoning-best-practices)

### Images and video

*   [Images and vision](https://developers.openai.com/api/docs/guides/images-vision)
*   [Image generation](https://developers.openai.com/api/docs/guides/image-generation)
*   [Video generation](https://developers.openai.com/api/docs/guides/video-generation)

### Realtime and audio

*   [Audio and speech](https://developers.openai.com/api/docs/guides/audio)
*   [Overview](https://developers.openai.com/api/docs/guides/realtime)
*   [Voice agents](https://developers.openai.com/api/docs/guides/voice-agents)

### Specialized models

*   [Deep research](https://developers.openai.com/api/docs/guides/deep-research)
*   [Embeddings](https://developers.openai.com/api/docs/guides/embeddings)
*   [Moderation](https://developers.openai.com/api/docs/guides/moderation)

*   [Overview](https://developers.openai.com/api/docs/guides/agents)

### Agents SDK

*   [Quickstart](https://developers.openai.com/api/docs/guides/agents/quickstart)
*   [Agent definitions](https://developers.openai.com/api/docs/guides/agents/define-agents)
*   [Models and providers](https://developers.openai.com/api/docs/guides/agents/models)
*   [Running agents](https://developers.openai.com/api/docs/guides/agents/running-agents)
*   [Sandbox agents](https://developers.openai.com/api/docs/guides/agents/sandboxes)
*   [Orchestration](https://developers.openai.com/api/docs/guides/agents/orchestration)
*   [Guardrails](https://developers.openai.com/api/docs/guides/agents/guardrails-approvals)
*   [Results and state](https://developers.openai.com/api/docs/guides/agents/results)
*   [Integrations and observability](https://developers.openai.com/api/docs/guides/agents/integrations-observability)
*   [Evaluate agent workflows](https://developers.openai.com/api/docs/guides/agent-evals)

### ChatKit

*   [Overview](https://developers.openai.com/api/docs/guides/chatkit)
*   [Customize](https://developers.openai.com/api/docs/guides/chatkit-themes)
*   [Widgets](https://developers.openai.com/api/docs/guides/chatkit-widgets)
*   [Actions](https://developers.openai.com/api/docs/guides/chatkit-actions)
*   [Advanced integrations](https://developers.openai.com/api/docs/guides/custom-chatkit)

*   [Overview](https://developers.openai.com/api/docs/guides/tools)
*   [Function calling](https://developers.openai.com/api/docs/guides/function-calling)

### Search and retrieval

*   [Web search](https://developers.openai.com/api/docs/guides/tools-web-search)
*   [File search](https://developers.openai.com/api/docs/guides/tools-file-search)
*   [Retrieval](https://developers.openai.com/api/docs/guides/retrieval)

### Connect tools and data

*   [MCP and Connectors](https://developers.openai.com/api/docs/guides/tools-connectors-mcp)
*   [Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)

### Build tool workflows

*   [Skills](https://developers.openai.com/api/docs/guides/tools-skills)
*   [Tool search](https://developers.openai.com/api/docs/guides/tools-tool-search)
*   [Programmatic tool calling](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling)

### Computer and code

*   [Shell](https://developers.openai.com/api/docs/guides/tools-shell)
*   [Computer use](https://developers.openai.com/api/docs/guides/tools-computer-use)
*   [Apply Patch](https://developers.openai.com/api/docs/guides/tools-apply-patch)
*   [Local shell](https://developers.openai.com/api/docs/guides/tools-local-shell)
*   [Code interpreter](https://developers.openai.com/api/docs/guides/tools-code-interpreter)

### Media

*   [Image generation](https://developers.openai.com/api/docs/guides/tools-image-generation)

*   [Overview](https://developers.openai.com/api/docs/guides/realtime)

### Get started

*   [Voice agents](https://developers.openai.com/api/docs/guides/voice-agents)
*   [Live translation](https://developers.openai.com/api/docs/guides/realtime-translation)
*   [Realtime prompting guide](https://developers.openai.com/api/docs/guides/realtime-models-prompting)

### Audio

*   [Audio and speech](https://developers.openai.com/api/docs/guides/audio)
*   [Transcription](https://developers.openai.com/api/docs/guides/transcription)
*   [File transcription](https://developers.openai.com/api/docs/guides/speech-to-text)
*   [Realtime transcription](https://developers.openai.com/api/docs/guides/realtime-transcription)
*   [Speech generation](https://developers.openai.com/api/docs/guides/text-to-speech)

### Connection methods

*   [WebRTC](https://developers.openai.com/api/docs/guides/realtime-webrtc)
*   [WebSocket](https://developers.openai.com/api/docs/guides/realtime-websocket)
*   [SIP](https://developers.openai.com/api/docs/guides/realtime-sip)

### Sessions and operations

*   [Managing conversations](https://developers.openai.com/api/docs/guides/realtime-conversations)
*   [Voice activity detection](https://developers.openai.com/api/docs/guides/realtime-vad)
*   [Realtime with tools](https://developers.openai.com/api/docs/guides/realtime-mcp)
*   [Webhooks and server-side controls](https://developers.openai.com/api/docs/guides/realtime-server-controls)
*   [Managing costs](https://developers.openai.com/api/docs/guides/realtime-costs)

### Go live

*   [Production best practices](https://developers.openai.com/api/docs/guides/production-best-practices)
*   [Deployment checklist](https://developers.openai.com/api/docs/guides/deployment-checklist)

### Performance and quality

*   [Latency optimization](https://developers.openai.com/api/docs/guides/latency-optimization)
*   [Predicted Outputs](https://developers.openai.com/api/docs/guides/predicted-outputs)
*   [Fast mode](https://developers.openai.com/api/docs/guides/fast-mode)
*   [Accuracy optimization](https://developers.openai.com/api/docs/guides/optimizing-llm-accuracy)

### Cost and throughput

*   [Cost optimization](https://developers.openai.com/api/docs/guides/cost-optimization)
*   [Prompt caching](https://developers.openai.com/api/docs/guides/prompt-caching)
*   [Batch](https://developers.openai.com/api/docs/guides/batch)
*   [Flex processing](https://developers.openai.com/api/docs/guides/flex-processing)

### Safety and governance

*   [Safety best practices](https://developers.openai.com/api/docs/guides/safety-best-practices)
*   [Red teaming](https://developers.openai.com/api/docs/guides/red-teaming)
*   
[Safety checks](https://developers.openai.com/api/docs/guides/safety-checks)
    *   [Cybersecurity checks](https://developers.openai.com/api/docs/guides/safety-checks/cybersecurity)
    *   [Under 18 API Guidance](https://developers.openai.com/api/docs/guides/safety-checks/under-18-api-guidance)

*   [Content provenance](https://developers.openai.com/api/docs/guides/content-provenance)
*   [Your data](https://developers.openai.com/api/docs/guides/your-data)
*   [Permissions](https://developers.openai.com/api/docs/guides/rbac)

### Infrastructure and access

*   
[Terraform provider](https://developers.openai.com/api/docs/guides/terraform)
    *   [Overview](https://developers.openai.com/api/docs/guides/terraform)
    *   [Projects and access](https://developers.openai.com/api/docs/guides/terraform/projects-and-access)
    *   [Service accounts](https://developers.openai.com/api/docs/guides/terraform/service-accounts)
    *   [Rate limits and spend](https://developers.openai.com/api/docs/guides/terraform/rate-limits-and-spend)
    *   [Model, tool, and data controls](https://developers.openai.com/api/docs/guides/terraform/project-controls)
    *   [Import and reconciliation](https://developers.openai.com/api/docs/guides/terraform/import-and-reconcile)

*   [Private Link](https://developers.openai.com/api/docs/guides/private-link)
*   [IP allowlist](https://developers.openai.com/api/docs/guides/ip-allowlist)
*   
[Workload identity federation](https://developers.openai.com/api/docs/guides/workload-identity-federation)
    *   [X.509 certificates (beta)](https://developers.openai.com/api/docs/guides/workload-identity-federation/x509)
    *   [Kubernetes](https://developers.openai.com/api/docs/guides/workload-identity-federation/kubernetes)
    *   [AWS](https://developers.openai.com/api/docs/guides/workload-identity-federation/aws)
    *   [Microsoft Azure](https://developers.openai.com/api/docs/guides/workload-identity-federation/microsoft-azure)
    *   [Google Cloud](https://developers.openai.com/api/docs/guides/workload-identity-federation/google-cloud)
    *   [Oracle Cloud Infrastructure](https://developers.openai.com/api/docs/guides/workload-identity-federation/oracle-cloud)
    *   [GitHub Actions](https://developers.openai.com/api/docs/guides/workload-identity-federation/github-actions)
    *   [SPIFFE](https://developers.openai.com/api/docs/guides/workload-identity-federation/spiffe)

*   [IP egress ranges](https://developers.openai.com/api/docs/guides/ip-addresses)
*   [Amazon Bedrock](https://developers.openai.com/api/docs/guides/amazon-bedrock)

### Operations

*   [Rate limits](https://developers.openai.com/api/docs/guides/rate-limits)
*   [Spend limits](https://developers.openai.com/api/docs/guides/spend-limits)
*   [Admin APIs](https://developers.openai.com/api/docs/guides/admin-apis)
*   [Error codes](https://developers.openai.com/api/docs/guides/error-codes)

[Docs](https://learn.chatgpt.com/docs)[Use cases](https://learn.chatgpt.com/use-cases)

Docs section Docs

 Plugins  Workspace Agents  Commerce  Ads 

Docs section Select...

*   [Home](https://developers.openai.com/plugins)
*   [Quickstart](https://developers.openai.com/plugins/quickstart)

### Core concepts

*   [Plugin architecture](https://developers.openai.com/plugins/concepts/plugins)
*   [Skills](https://developers.openai.com/plugins/concepts/skills)
*   [MCP server](https://developers.openai.com/plugins/concepts/mcp-server)

### Plan

*   [Brainstorm use cases](https://developers.openai.com/plugins/plan/use-case)
*   [Define tools](https://developers.openai.com/plugins/plan/tools)

### Build

*   [Build an MCP server](https://developers.openai.com/plugins/build/mcp-server)
*   [Add UI to your MCP server (optional)](https://developers.openai.com/plugins/build/chatgpt-ui)
*   [Authenticate users](https://developers.openai.com/plugins/build/auth)
*   [Build skills](https://developers.openai.com/plugins/build/skills)
*   [Package your plugin](https://developers.openai.com/plugins/build/plugins)
*   [Examples](https://developers.openai.com/plugins/build/examples)

### Test and publish

*   [Connect and test your plugin](https://developers.openai.com/plugins/deploy/connect-chatgpt)
*   [Submit and publish](https://developers.openai.com/plugins/deploy/submission)
*   [Submission error reference](https://developers.openai.com/plugins/deploy/submission-errors)

### Conversion specs

*   [Restaurant reservation spec](https://developers.openai.com/plugins/guides/restaurant-reservation-conversion-spec)
*   [Get Quote spec](https://developers.openai.com/plugins/guides/local-services-request-quote-conversion-spec)
*   [Product checkout spec](https://developers.openai.com/plugins/guides/product-checkout-conversion-spec)

### Guides

*   [UI guidelines](https://developers.openai.com/plugins/concepts/ui-guidelines)
*   [Optimize Metadata](https://developers.openai.com/plugins/guides/optimize-metadata)
*   [Submit a Claude Code plugin](https://developers.openai.com/plugins/guides/submit-claude-plugin)
*   [Security & Privacy](https://developers.openai.com/plugins/guides/security-privacy)
*   [Troubleshooting](https://developers.openai.com/plugins/deploy/troubleshooting)

### Resources

*   [Changelog](https://developers.openai.com/plugins/changelog)
*   [Plugin guidelines](https://developers.openai.com/plugins/app-guidelines)
*   [MCP server review requirements](https://developers.openai.com/plugins/deploy/app-review)
*   [Plugin UI reference](https://developers.openai.com/plugins/reference)
*   [Checkout API reference](https://developers.openai.com/plugins/build/monetization)

*   [Home](https://developers.openai.com/workspace-agents)

### Get started

*   [Trigger workspace agent runs](https://developers.openai.com/workspace-agents/trigger-runs)
*   [Authenticate with Workspace Agent access tokens](https://developers.openai.com/workspace-agents/authentication)

*   [Home](https://developers.openai.com/commerce)

### Guides

*   [Get started](https://developers.openai.com/commerce/guides/get-started)
*   [Best practices](https://developers.openai.com/commerce/guides/best-practices)

### File Upload

*   [Overview](https://developers.openai.com/commerce/specs/file-upload/overview)
*   [Products](https://developers.openai.com/commerce/specs/file-upload/products)

### API

*   [Overview](https://developers.openai.com/commerce/specs/api/overview)
*   [Feeds](https://developers.openai.com/commerce/specs/api/feeds)
*   [Products](https://developers.openai.com/commerce/specs/api/products)
*   [Promotions](https://developers.openai.com/commerce/specs/api/promotions)

*   [Ads Overview](https://developers.openai.com/ads)

### Measurement

*   [Measurement Pixel](https://developers.openai.com/ads/measurement-pixel)
*   [Multiple Pixels (Advanced)](https://developers.openai.com/ads/multiple-pixels)
*   [Image Tag](https://developers.openai.com/ads/image-tag)
*   [Conversions API](https://developers.openai.com/ads/conversions-api)
*   [Supported Events](https://developers.openai.com/ads/supported-events)

### Advertiser API

*   [Overview](https://developers.openai.com/ads/api-overview)
*   [API Partner Setup](https://developers.openai.com/ads/api-partner-setup)
*   [Quickstart](https://developers.openai.com/ads/api-quickstart)
*   [Bulk API](https://developers.openai.com/ads/bulk-api)
*   [Product Feeds](https://developers.openai.com/ads/product-feeds)
*   [Delta Feeds API](https://developers.openai.com/ads/delta-feeds)
*   [Campaign Targeting](https://developers.openai.com/ads/campaign-targeting)
*   [Conversion-Optimized Campaigns](https://developers.openai.com/ads/conversion-optimized-campaigns)

### API Reference

*   [Authentication](https://developers.openai.com/ads/api-reference/authentication)
*   [Ad Account](https://developers.openai.com/ads/api-reference/ad-account)
*   [Campaigns](https://developers.openai.com/ads/api-reference/campaigns)
*   [Ad Groups](https://developers.openai.com/ads/api-reference/ad-groups)
*   [Ads](https://developers.openai.com/ads/api-reference/ads)
*   [Insights](https://developers.openai.com/ads/api-reference/insights)
*   [Files](https://developers.openai.com/ads/api-reference/files)
*   [Conversion Setup](https://developers.openai.com/ads/api-reference/conversion-setup)

 Overview  Features  Configuration  Developers  Security  Administration  Use Cases  Resources 

Docs section Developers

*   [Home](https://developers.openai.com/codex)

### Get started

*   [Quickstart](https://developers.openai.com/codex/quickstart)
*   [Use ChatGPT](https://developers.openai.com/codex/use-chatgpt)
*   [Get started with Work](https://developers.openai.com/codex/get-started-with-work)
*   [Import from another agent](https://developers.openai.com/codex/import)

### Foundations

*   [Prompting](https://developers.openai.com/codex/prompting)
*   [Personalize ChatGPT](https://developers.openai.com/codex/personalize)
*   [Skills & Plugins](https://developers.openai.com/codex/skills-and-plugins)
*   [Permissions](https://developers.openai.com/codex/permission-modes)

### Explore

*   [What's new](https://developers.openai.com/codex/whats-new)
*   [Models](https://developers.openai.com/codex/models)
*   [Pricing](https://developers.openai.com/codex/pricing)
*   [Glossary](https://developers.openai.com/codex/glossary)

### Available on

*   [ChatGPT desktop app](https://developers.openai.com/codex/app)
*   [Remote](https://developers.openai.com/codex/remote)
*   [ChatGPT on the web](https://developers.openai.com/codex/web)
*   [Codex CLI](https://developers.openai.com/codex/cli)
*   [Codex IDE extension](https://developers.openai.com/codex/ide)
*   [Codex cloud](https://developers.openai.com/codex/cloud)

### Releases

*   [Changelog](https://developers.openai.com/codex/changelog)
*   [Feature Maturity](https://developers.openai.com/codex/feature-maturity)
*   [Open Source](https://developers.openai.com/codex/open-source)

*   [Overview](https://developers.openai.com/codex/features)

### Workflows

*   [Projects and chats](https://developers.openai.com/codex/projects)
*   [Sites](https://developers.openai.com/codex/sites)
*   [Visualizations](https://developers.openai.com/codex/visualizations)
*   [Scheduled tasks](https://developers.openai.com/codex/automations)
*   [Long-running work](https://developers.openai.com/codex/long-running-work)
*   [Notifications](https://developers.openai.com/codex/notifications)
*   [Pets](https://developers.openai.com/codex/pets)
*   [Codex Micro](https://developers.openai.com/codex/features/codex-micro)

### Capabilities

*   [Browser](https://developers.openai.com/codex/browser)
*   [Computer use](https://developers.openai.com/codex/computer-use)
*   [Voice](https://developers.openai.com/codex/features/voice)
*   [Plugins](https://developers.openai.com/codex/plugins)
*   [Web search](https://developers.openai.com/codex/web-search)
*   [Image generation](https://developers.openai.com/codex/image-generation)
*   [Image inputs](https://developers.openai.com/codex/image-inputs)
*   [Appshots](https://developers.openai.com/codex/appshots)
*   [Chrome extension](https://developers.openai.com/codex/chrome-extension)
*   [Work with files](https://developers.openai.com/codex/artifacts-viewer)

### Reference

*   [Commands](https://developers.openai.com/codex/reference/commands)
*   [Slash commands](https://developers.openai.com/codex/reference/slash-commands)
*   [Settings](https://developers.openai.com/codex/reference/settings)
*   [Troubleshooting](https://developers.openai.com/codex/reference/troubleshooting)

*   [Overview](https://developers.openai.com/codex/configuration)

### Customization

*   [Overview](https://developers.openai.com/codex/customization/overview)
*   [Memories](https://developers.openai.com/codex/customization/memories)
*   [Computer History](https://developers.openai.com/codex/customization/computer-history)

### Config file

*   [Config Basics](https://developers.openai.com/codex/config-file/config-basic)
*   [Advanced Config](https://developers.openai.com/codex/config-file/config-advanced)
*   [Config Reference](https://developers.openai.com/codex/config-file/config-reference)
*   [Environment Variables](https://developers.openai.com/codex/config-file/environment-variables)
*   [Sample Config](https://developers.openai.com/codex/config-file/config-sample)

### Agent configuration

*   [AGENTS.md](https://developers.openai.com/codex/agent-configuration/agents-md)
*   [Subagents](https://developers.openai.com/codex/agent-configuration/subagents)
*   [Speed](https://developers.openai.com/codex/agent-configuration/speed)
*   [Rules](https://developers.openai.com/codex/agent-configuration/rules)

### Extend ChatGPT and Codex

*   [Record & Replay](https://developers.openai.com/codex/extend/record-and-replay)
*   [MCP](https://developers.openai.com/codex/extend/mcp)

### Linux

*   [Desktop app](https://developers.openai.com/codex/linux/linux-app)

### Windows

*   [Desktop app](https://developers.openai.com/codex/windows/windows-app)
*   [Windows sandbox](https://developers.openai.com/codex/windows/windows-sandbox)
*   [WSL](https://developers.openai.com/codex/windows/wsl)

*   [Overview](https://developers.openai.com/codex/developers)

### Development workflows

*   [Code review](https://developers.openai.com/codex/code-review)
*   [Integrated terminal](https://developers.openai.com/codex/integrated-terminal)

### Extend and automate

*   [Build skills](https://developers.openai.com/codex/build-skills)
*   [Build plugins](https://developers.openai.com/codex/build-plugins)
*   [Hooks](https://developers.openai.com/codex/hooks)

### Environments

*   [Modes](https://developers.openai.com/codex/environments/modes)
*   [Local environments](https://developers.openai.com/codex/environments/local-environment)
*   [Cloud environment](https://developers.openai.com/codex/environments/cloud-environment)
*   [Git worktrees](https://developers.openai.com/codex/environments/git-worktrees)

### Build with Codex

*   [Codex SDK](https://developers.openai.com/codex/codex-sdk)
*   [App Server](https://developers.openai.com/codex/app-server)
*   [MCP Server](https://developers.openai.com/codex/mcp-server)
*   [GitHub Action](https://developers.openai.com/codex/github-action)
*   [Non-interactive mode](https://developers.openai.com/codex/non-interactive-mode)

### Third-party integrations

*   [GitHub](https://developers.openai.com/codex/third-party/github)
*   [Slack](https://developers.openai.com/codex/third-party/slack)
*   [Linear](https://developers.openai.com/codex/third-party/linear)

### Reference

*   [CLI customization](https://developers.openai.com/codex/cli-customization)
*   [Developer commands](https://developers.openai.com/codex/developer-commands)
*   [Developer settings](https://developers.openai.com/codex/developer-settings)

*   [Overview](https://developers.openai.com/codex/security-administration)

### Permissions

*   [Profiles](https://developers.openai.com/codex/permissions)
*   [Sandboxing](https://developers.openai.com/codex/sandboxing)
*   [Auto-review](https://developers.openai.com/codex/sandboxing/auto-review)
*   [Agent approvals & security](https://developers.openai.com/codex/agent-approvals-security)
*   [Internet access](https://developers.openai.com/codex/cloud/internet-access)

### Codex Security

*   [Overview](https://developers.openai.com/codex/security)
*   
Codex Security plugin
    *   [Quickstart](https://developers.openai.com/codex/security/plugin)
    *   [Run a security scan](https://developers.openai.com/codex/security/plugin/scans)
    *   [Run a deep scan](https://developers.openai.com/codex/security/plugin/deep-scans)
    *   [Review code changes](https://developers.openai.com/codex/security/plugin/code-changes)
    *   [Use the Security workbench](https://developers.openai.com/codex/security/plugin/workbench)
    *   [Triage a backlog](https://developers.openai.com/codex/security/plugin/triage-backlog)
    *   [Fix findings](https://developers.openai.com/codex/security/plugin/fix-findings)
    *   [Propose security hardening](https://developers.openai.com/codex/security/plugin/security-hardening)
    *   [Write vulnerability reports](https://developers.openai.com/codex/security/plugin/vulnerability-reports)
    *   [Export and track findings](https://developers.openai.com/codex/security/plugin/export-findings)
    *   [Changelog](https://developers.openai.com/codex/security/plugin/changelog)

*   
Codex Security CLI
    *   [Quickstart](https://developers.openai.com/codex/security/cli)
    *   [Run bulk scans](https://developers.openai.com/codex/security/cli/bulk-scans)
    *   [Run scans in CI](https://developers.openai.com/codex/security/cli/ci)
    *   [Reference](https://developers.openai.com/codex/security/cli/reference)
    *   [FAQ](https://developers.openai.com/codex/security/cli/faq)

*   [TypeScript SDK](https://developers.openai.com/codex/security/sdk)
*   
Codex Security cloud
    *   [Setup](https://developers.openai.com/codex/security/setup)
    *   [Security Review](https://developers.openai.com/codex/security/security-review)
    *   [Improving the threat model](https://developers.openai.com/codex/security/threat-model)
    *   [FAQ](https://developers.openai.com/codex/security/faq)

### Cyber safety

*   [Models & Trusted Access](https://developers.openai.com/codex/cyber-safety)
*   [Recommended configuration](https://developers.openai.com/codex/cyber-safety/recommended-configuration)

*   [Overview](https://developers.openai.com/codex/administration)

### Getting started

*   [Admin rollout guide](https://developers.openai.com/codex/enterprise/admin-setup)
*   [ChatGPT Work Overview](https://developers.openai.com/codex/enterprise/chatgpt-work-overview)
*   [ChatGPT Work admin FAQ](https://developers.openai.com/codex/enterprise/work-admin-faq)

### Identity and authentication

*   [Authentication overview](https://developers.openai.com/codex/auth)
*   [Personal Access Tokens](https://developers.openai.com/codex/enterprise/access-tokens)
*   [Service accounts](https://developers.openai.com/codex/enterprise/service-accounts)

### Workspace access, policy, and models

*   [Groups and provisioning](https://developers.openai.com/codex/enterprise/groups-and-provisioning)
*   [Roles and workspace permissions](https://developers.openai.com/codex/enterprise/roles-and-workspace-permissions)
*   [GPTs and Sharing](https://developers.openai.com/codex/enterprise/gpts-and-sharing)
*   [Managed configuration](https://developers.openai.com/codex/enterprise/managed-configuration)
*   [Prisma AIRS](https://developers.openai.com/codex/enterprise/prisma-airs)
*   [HIPAA configuration](https://developers.openai.com/codex/hipaa-configuration)
*   [Workspace model availability](https://developers.openai.com/codex/enterprise/workspace-model-availability)

### Plugin and connector controls

*   [Plugin controls](https://developers.openai.com/codex/enterprise/apps-and-connectors)
*   [Skill controls](https://developers.openai.com/codex/enterprise/skills)

### Usage, governance, and compliance

*   [Governance](https://developers.openai.com/codex/enterprise/governance)
*   [Workspace analytics](https://developers.openai.com/codex/enterprise/workspace-analytics)
*   [Analytics API](https://developers.openai.com/codex/enterprise/analytics-api)
*   [Compliance API and audit events](https://developers.openai.com/codex/enterprise/compliance-api)

### Deployment and model providers

*   [Manage app updates](https://developers.openai.com/codex/enterprise/manage-app-updates)
*   [Windows app deployment](https://developers.openai.com/codex/enterprise/windows-deployment)
*   [Remote connections](https://developers.openai.com/codex/remote-connections)
*   [Amazon Bedrock](https://developers.openai.com/codex/amazon-bedrock)

*   [Explore use cases](https://developers.openai.com/codex/use-cases)
*   [Collections](https://developers.openai.com/codex/use-cases/collections)

*   [Home](https://developers.openai.com/codex/resources)
*   [Videos](https://developers.openai.com/codex/videos)
*   [Showcase](https://developers.openai.com/showcase)
*   [OpenAI Academy](https://openai.com/academy/)
*   [Online trainings](https://academy.openai.com/home/events)

### Community

*   [Codex Ambassadors](https://developers.openai.com/community/codex-ambassadors)
*   [Codex for Students](https://developers.openai.com/community/students)
*   [Codex for Open Source](https://developers.openai.com/community/codex-for-oss)
*   [Meetups](https://developers.openai.com/community/meetups)

### Blog

*   [Company blog](https://openai.com/news/)
*   [Developer blog](https://developers.openai.com/blog)

*   [Explore use cases](https://developers.openai.com/codex/use-cases)
*   [Collections](https://developers.openai.com/codex/use-cases/collections)

*   [Home](https://developers.openai.com/codex/resources)
*   [Videos](https://developers.openai.com/codex/videos)
*   [Showcase](https://developers.openai.com/showcase)
*   [OpenAI Academy](https://openai.com/academy/)
*   [Online trainings](https://academy.openai.com/home/events)

### Community

*   [Codex Ambassadors](https://developers.openai.com/community/codex-ambassadors)
*   [Codex for Students](https://developers.openai.com/community/students)
*   [Codex for Open Source](https://developers.openai.com/community/codex-for-oss)
*   [Meetups](https://developers.openai.com/community/meetups)

### Blog

*   [Company blog](https://openai.com/news/)
*   [Developer blog](https://developers.openai.com/blog)

[Showcase](https://developers.openai.com/showcase) Blog  Cookbook  Learn  Community 

Docs section Select...

*   [All posts](https://developers.openai.com/blog)

### Recent

*   [Custom Code Review rules for Codex](https://developers.openai.com/blog/custom-code-review-rules-for-codex)
*   [Mastering remote engineering work from your phone](https://developers.openai.com/blog/mastering-codex-remote-for-engineering)
*   [Making private MCP servers reachable without making them public](https://developers.openai.com/blog/connect-private-mcp-servers-to-openai-products)
*   [How Perplexity Brought Voice Search to Millions Using the Realtime API](https://developers.openai.com/blog/realtime-perplexity-computer)
*   [Designing delightful frontends with GPT-5.4](https://developers.openai.com/blog/designing-delightful-frontends-with-gpt-5-4)

### Topics

*   [General](https://developers.openai.com/blog/topic/general)
*   [API](https://developers.openai.com/blog/topic/api)
*   [Apps SDK](https://developers.openai.com/blog/topic/apps-sdk)
*   [Audio](https://developers.openai.com/blog/topic/audio)
*   [Codex](https://developers.openai.com/blog/topic/codex)

*   [Home](https://developers.openai.com/cookbook)

### Topics

*   [Agents](https://developers.openai.com/cookbook/topic/agents)
*   [Evals](https://developers.openai.com/cookbook/topic/evals)
*   [Multimodal](https://developers.openai.com/cookbook/topic/multimodal)
*   [Text](https://developers.openai.com/cookbook/topic/text)
*   [Guardrails](https://developers.openai.com/cookbook/topic/guardrails)
*   [Optimization](https://developers.openai.com/cookbook/topic/optimization)
*   [ChatGPT](https://developers.openai.com/cookbook/topic/chatgpt)
*   [Codex](https://developers.openai.com/cookbook/topic/codex)
*   [gpt-oss](https://developers.openai.com/cookbook/topic/gpt-oss)

### Contribute

*   [Cookbook on GitHub](https://github.com/openai/openai-cookbook)

*   [Home](https://developers.openai.com/learn)
*   [OpenAI Developers plugin](https://developers.openai.com/learn/developers-codex-plugin)
*   [Docs MCP](https://developers.openai.com/learn/docs-mcp)

### Categories

*   [Demo apps](https://developers.openai.com/learn/code)
*   [Videos](https://developers.openai.com/learn/videos)

### Topics

*   [Agents](https://developers.openai.com/learn/agents)
*   [Audio & Voice](https://developers.openai.com/learn/audio)
*   [Computer Use](https://developers.openai.com/learn/cua)
*   [Codex](https://developers.openai.com/learn/codex)
*   [Evals](https://developers.openai.com/learn/evals)
*   [gpt-oss](https://developers.openai.com/learn/gpt-oss)
*   [Fine-tuning](https://developers.openai.com/learn/fine-tuning)
*   [Image generation](https://developers.openai.com/learn/imagegen)
*   [Scaling](https://developers.openai.com/learn/scaling)
*   [Tools](https://developers.openai.com/learn/tools)
*   [Video generation](https://developers.openai.com/learn/videogen)

*   [Community](https://developers.openai.com/community)

### Programs

*   [Codex Ambassadors](https://developers.openai.com/community/codex-ambassadors)
*   [Codex for Students](https://developers.openai.com/community/students)
*   [Codex for Open Source](https://developers.openai.com/community/codex-for-oss)
*   [OpenAI for Startups](https://openai.com/business/why-openai/startups/)

### Events

*   [Meetups](https://developers.openai.com/community/meetups)

### Spaces

*   [Developer Forum](https://community.openai.com/)
*   [Discord](https://discord.com/invite/openai)
*   [Reddit](https://www.reddit.com/r/OpenAI/)
*   [X](https://x.com/OpenAIDevs)

[API Dashboard](https://platform.openai.com/login)

[Try ChatGPT](https://chatgpt.com/)

*   [Overview](https://developers.openai.com/codex/developers)

### Development workflows

*   [Code review](https://developers.openai.com/codex/code-review)
*   [Integrated terminal](https://developers.openai.com/codex/integrated-terminal)

### Extend and automate

*   [Build skills](https://developers.openai.com/codex/build-skills)
*   [Build plugins](https://developers.openai.com/codex/build-plugins)
*   [Hooks](https://developers.openai.com/codex/hooks)

### Environments

*   [Modes](https://developers.openai.com/codex/environments/modes)
*   [Local environments](https://developers.openai.com/codex/environments/local-environment)
*   [Cloud environment](https://developers.openai.com/codex/environments/cloud-environment)
*   [Git worktrees](https://developers.openai.com/codex/environments/git-worktrees)

### Build with Codex

*   [Codex SDK](https://developers.openai.com/codex/codex-sdk)
*   [App Server](https://developers.openai.com/codex/app-server)
*   [MCP Server](https://developers.openai.com/codex/mcp-server)
*   [GitHub Action](https://developers.openai.com/codex/github-action)
*   [Non-interactive mode](https://developers.openai.com/codex/non-interactive-mode)

### Third-party integrations

*   [GitHub](https://developers.openai.com/codex/third-party/github)
*   [Slack](https://developers.openai.com/codex/third-party/slack)
*   [Linear](https://developers.openai.com/codex/third-party/linear)

### Reference

*   [CLI customization](https://developers.openai.com/codex/cli-customization)
*   [Developer commands](https://developers.openai.com/codex/developer-commands)
*   [Developer settings](https://developers.openai.com/codex/developer-settings)

Copy Page

# Hooks

Run deterministic scripts during the Codex lifecycle

Copy Page

Hooks are an extensibility framework for Codex. They allow you to inject your own scripts into the agentic loop, enabling features such as:

*   Send the chat to a custom logging/analytics engine
*   Scan your team’s prompts to block accidentally pasting API keys
*   Summarize chats to create persistent memories automatically
*   Run a custom validation check when a chat turn stops, enforcing standards
*   Customize prompting when in a certain directory

Runtime behavior to keep in mind:

*   Matching hooks from multiple files all run.
*   Multiple matching command hooks for the same event are launched concurrently, so one hook can’t prevent another matching hook from starting.
*   Non-managed command hooks must be reviewed and trusted before they run.

Hooks run at different points in a conversation:

| When | Hooks |
| --- | --- |
| During a turn | `PreToolUse`, `PermissionRequest`, `PostToolUse`, `PreCompact`, `PostCompact`, `UserPromptSubmit`, `SubagentStop`, `Stop` |
| When a session or subagent starts | `SessionStart`, `SubagentStart` |
| When the main thread ends | `SessionEnd` (doesn’t run for subagents) |

## Where Codex looks for hooks

Codex discovers hooks next to active config layers in either of these forms:

*   `hooks.json`
*   inline `[hooks]` tables inside `config.toml`

Installed plugins can also bundle lifecycle config through their plugin manifest or a default `hooks/hooks.json` file. See [Build plugins](https://developers.openai.com/plugins/build/plugins#bundled-mcp-servers-and-lifecycle-hooks) for the plugin packaging rules.

In practice, the four most useful locations are:

*   `~/.codex/hooks.json`
*   `~/.codex/config.toml`
*   `<repo>/.codex/hooks.json`
*   `<repo>/.codex/config.toml`

If more than one hook source exists, Codex loads all matching hooks. Higher-precedence config layers don’t replace lower-precedence hooks. If a single layer contains both `hooks.json` and inline `[hooks]`, Codex merges them and warns at startup. Prefer one representation per layer.

Codex can also discover hooks bundled with enabled plugins. Plugin-bundled hooks load alongside other hook sources and use the same trust-review flow as other non-managed hooks.

Project-local hooks load only when the project `.codex/` layer is trusted. In untrusted projects, Codex still loads user and system hooks from their own active config layers.

## Review and trust hooks

Codex lists configured hooks before deciding which ones can run. Before a non-managed command hook can run, Codex requires you to review and trust the exact hook definition. Codex records trust against the hook’s current hash, so new or changed hooks are marked for review and skipped until trusted.

Use `/hooks` in the CLI to inspect hook sources, review new or changed hooks, trust hooks, or disable individual non-managed hooks. If hooks need review at startup, Codex prints a warning that tells you to open `/hooks`.

Managed hooks from system, MDM, cloud, or `requirements.toml` sources are marked as managed, trusted by policy, and can’t be disabled from the user hook browser.

For one-off automation that already vets hook sources outside Codex, pass `--dangerously-bypass-hook-trust` to run enabled hooks without requiring persisted hook trust for that invocation.

## Config shape

Hooks are organized in three levels:

*   A hook event such as `PreToolUse`, `PostToolUse`, `PreCompact`, `SubagentStart`, or `Stop`
*   A matcher group that decides when that event matches
*   One or more hook handlers that run when the matcher group matches

```
{
  "description": "Optional lifecycle hooks for this workspace.",
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/session_start.py",
            "statusMessage": "Loading session notes",
            "additionalContextLimit": 5000
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/session_end.py",
            "timeout": 3
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py\"",
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/permission_request.py\"",
            "statusMessage": "Checking approval request"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/post_tool_use_review.py\"",
            "statusMessage": "Reviewing Bash output"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/user_prompt_submit_data_flywheel.py\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/stop_continue.py\"",
            "timeout": 30
          }
        ]
      }
    ]
  }
}
```

Notes:

*   `description` is optional top-level metadata for a `hooks.json` file. It doesn’t change which hooks run.
*   `timeout` is in seconds.
*   If `timeout` is omitted, Codex uses `600` seconds for most hooks. 
    *   `SessionEnd` uses `1` second by default and supports up to `3` seconds.

*   `statusMessage` is optional.
*   `additionalContextLimit` sets how much `additionalContext` a command hook can send to the model before Codex saves the full text to disk and sends a shorter preview instead. See [Large hook output](https://developers.openai.com/codex/hooks#large-hook-output).
*   `commandWindows` is an optional Windows-only command override. In TOML, use `command_windows` or `commandWindows`.
*   Set `async` to `true` to [run a command hook in the background](https://developers.openai.com/codex/hooks#run-hooks-in-the-background).
*   Only `type: "command"` handlers run today. `prompt` and `agent` handlers are parsed but skipped.
*   Commands run with the session `cwd` as their working directory.
*   For repo-local hooks, prefer resolving from the git root instead of using a relative path such as `.codex/hooks/...`. Codex may be started from a subdirectory, and a git-root-based path keeps the hook location stable.

Equivalent inline TOML in `config.toml`:

```
[[hooks.SessionStart]]
matcher = "^compact$"

[[hooks.SessionStart.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/session_start.py"'
additionalContextLimit = 5000

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

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

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

[[hooks.PostToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/post_tool_use_review.py"'
timeout = 30
statusMessage = "Reviewing Bash output"
```

## Turn hooks off

Hooks are enabled by default. To turn them off in `config.toml`, set:

```
[features]
hooks = false
```

Use `hooks` as the canonical feature key. `codex_hooks` still works as a deprecated alias. Admins can force hooks off the same way in `requirements.toml` with `[features].hooks = false`.

## Managed hooks from `requirements.toml`

Enterprise-managed requirements can also define hooks inline under `[hooks]`. This is useful when admins want to enforce the hook configuration while delivering the actual scripts through MDM or another device-management system. To enforce managed hooks even for users who disabled hooks locally, pin `[features].hooks = true` in `requirements.toml` alongside `[hooks]`. To ignore user, project, session, and plugin hooks while still allowing administrator managed hooks, set `allow_managed_hooks_only = true`.

```
allow_managed_hooks_only = true

[features]
hooks = true

[hooks]
managed_dir = "/enterprise/hooks"
windows_managed_dir = 'C:\enterprise\hooks'

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

[[hooks.PreToolUse.hooks]]
type = "command"
command = "python3 /enterprise/hooks/pre_tool_use_policy.py"
command_windows = 'py -3 C:\enterprise\hooks\pre_tool_use_policy.py'
timeout = 30
statusMessage = "Checking managed Bash command"
```

Notes for managed hooks:

*   `managed_dir` is used on macOS and Linux.
*   `windows_managed_dir` is used on Windows.
*   Codex doesn’t distribute the scripts in `managed_dir`; your enterprise tooling must install and update them separately.
*   Managed hook commands should use absolute script paths under the configured managed directory.
*   `allow_managed_hooks_only = true` skips hooks from user, project, session, and plugin sources, but still loads managed hooks from `requirements.toml` and other managed config layers.

## Plugin-bundled hooks

When a plugin is enabled, Codex can load lifecycle hooks from that plugin alongside user, project, and managed hooks.

By default, Codex looks for `hooks/hooks.json` inside the plugin root. A plugin manifest can override that default with a `hooks` entry in `.codex-plugin/plugin.json`. The manifest entry can be a `./`-prefixed path, an array of `./`-prefixed paths, an inline hooks object, or an array of inline hooks objects.

```
{
  "name": "repo-policy",
  "hooks": "./hooks/hooks.json"
}
```

Manifest hook paths are resolved relative to the plugin root and must stay inside that root. If a manifest defines `hooks`, Codex uses those manifest entries instead of the default `hooks/hooks.json`.

Plugin hook commands receive these environment variables:

*   `PLUGIN_ROOT` is a Codex-specific extension that points to the installed plugin root.
*   `PLUGIN_DATA` is a Codex-specific extension that points to the plugin’s writable data directory.
*   Codex also sets `CLAUDE_PLUGIN_ROOT` and `CLAUDE_PLUGIN_DATA` for compatibility with existing plugin hooks.

Plugin hooks use the same event schema as other hooks. Installing or enabling a plugin doesn’t automatically trust its hooks; Codex skips plugin-bundled hooks until you review and trust the current hook definition.

## Matcher patterns

The `matcher` field is a regex string that filters when hooks fire. Use `"*"`, `""`, or omit `matcher` entirely to match every occurrence of a supported event.

Only some current Codex events honor `matcher`:

| Event | What `matcher` filters | Notes |
| --- | --- | --- |
| `PermissionRequest` | tool name | Support includes `Bash`, `apply_patch`*, and MCP tool names |
| `PostToolUse` | tool name | See [Tool coverage](https://developers.openai.com/codex/hooks#tool-coverage) |
| `PostCompact` | compaction trigger | Values are `manual` or `auto` |
| `PreCompact` | compaction trigger | Values are `manual` or `auto` |
| `PreToolUse` | tool name | See [Tool coverage](https://developers.openai.com/codex/hooks#tool-coverage) |
| `SessionEnd` | end reason | Currently only `other` |
| `SessionStart` | start source | Values are `startup`, `resume`, `clear`, and `compact` |
| `SubagentStart` | subagent type | Values depend on the subagent that starts |
| `SubagentStop` | subagent type | Values depend on the subagent that stops |
| `UserPromptSubmit` | not supported | Any configured `matcher` is ignored for this event |
| `Stop` | not supported | Any configured `matcher` is ignored for this event |

*For `apply_patch`, `matcher` values can also use `Edit` or `Write`.

Examples:

*   `Bash`
*   `^apply_patch$`
*   `Edit|Write`
*   `mcp__filesystem__read_file`
*   `mcp__filesystem__.*`
*   `startup|resume|clear|compact`
*   `manual|auto`

### Tool coverage

`PreToolUse` and `PostToolUse` can observe more than shell and MCP calls. Most local function tools use the same hook path, so you can match their tool name, inspect their JSON arguments, and, for `PreToolUse`, block or rewrite the call.

| Tool path | `PreToolUse` | `PostToolUse` | Notes |
| --- | --- | --- | --- |
| Shell commands | Yes | Yes | Match as `Bash`. |
| Unified exec (`exec_command`) | Yes | Yes | Match as `Bash`. A later `write_stdin` poll can deliver the original command’s `PostToolUse` when that command finishes. |
| `apply_patch` | Yes | Yes | Match as `apply_patch`, `Edit`, or `Write`. |
| MCP tools | Yes | Yes | Match the MCP tool name, such as `mcp__filesystem__read_file`. |
| Other local function tools | Yes | Yes | Match the function tool name, such as `update_plan`. `spawn_agent` also matches `Agent`. |
| Hosted tools, such as `WebSearch` | No | No | These don’t use the local function-tool hook path. |

`write_stdin` is transport for an existing unified-exec session. It doesn’t run `PreToolUse` again when it sends input or polls a command that already passed `PreToolUse`.

Some specialized tool paths can opt out of the default hook path. Treat tool hooks as a useful guardrail, not a complete enforcement boundary.

## Common input fields

Every command hook receives one JSON object on `stdin`.

These are the shared fields you will usually use:

| Field | Type | Meaning |
| --- | --- | --- |
| `session_id` | `string` | Current Codex session id. Subagent hooks use the parent session id. |
| `transcript_path` | `string | null` | Path to the session transcript file, if any |
| `cwd` | `string` | Working directory for the session |
| `hook_event_name` | `string` | Current hook event name |
| `model` | `string` | Codex-specific extension. Active model slug |

Turn-scoped hooks list `turn_id` as a Codex-specific extension in their event-specific tables.

`SessionStart`, `PreToolUse`, `PermissionRequest`, `PostToolUse`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, and `Stop` also include `permission_mode`, which describes the current permission mode as `default`, `acceptEdits`, `plan`, `dontAsk`, or `bypassPermissions`.

`transcript_path` points to a chat transcript for convenience, but the transcript format isn’t a stable interface for hooks and may change over time.

If you need the full wire format, see [Schemas](https://developers.openai.com/codex/hooks#schemas).

## Common output fields

`SessionStart`, `PreCompact`, `PostCompact`, `UserPromptSubmit`, `SubagentStop`, and `Stop` support these shared JSON fields. `SubagentStart` accepts the same shape for `systemMessage` and hook-specific context, but `continue: false` doesn’t stop the subagent:

```
{
  "continue": true,
  "stopReason": "optional",
  "systemMessage": "optional",
  "suppressOutput": false
}
```

| Field | Effect |
| --- | --- |
| `continue` | If `false`, marks that hook run as stopped |
| `stopReason` | Recorded as the reason for stopping |
| `systemMessage` | Surfaced as a warning in the UI or event stream |
| `suppressOutput` | Parsed today but not yet implemented |

Exit `0` with no output is treated as success and Codex continues.

`PreToolUse` and `PermissionRequest` support `systemMessage`, but `continue`, `stopReason`, and `suppressOutput` aren’t currently supported for those events. If a `PreToolUse` hook returns one of those unsupported fields, Codex marks that hook run as failed, reports the error, and continues the tool call.

`PostToolUse` supports `systemMessage`, `continue: false`, and `stopReason`. `suppressOutput` is parsed but not currently supported for that event.

### Large hook output

By default, Codex limits each model-visible hook-output message to roughly 2,500 tokens. If a hook returns more, Codex saves the full text under `<temp_dir>/hook_outputs/<session_id>/<uuid>.txt` and gives the model a head-and-tail preview with the saved-file path. This behavior is called **spilling**: Codex stores oversized output on disk and replaces it with a shorter, model-visible preview. If the file can’t be written, the model still receives a truncated preview.

Keep hook and plugin context concise. Context from multiple hooks and plugins adds up and can degrade model performance. Raising `additionalContextLimit` increases that risk. Avoid setting the limit to `0` unless the hook enforces a strict output cap; otherwise, a single hook can consume the entire context window.

For any command hook that returns `additionalContext`, set `additionalContextLimit` on the handler to customize the approximate token threshold:

```
{
  "type": "command",
  "command": "python3 ~/.codex/hooks/session_start.py",
  "additionalContextLimit": 5000
}
```

Omit `additionalContextLimit` to use the default `2500`-token threshold. Use a positive integer to select a different threshold, or `0` to pass the handler’s complete additional context directly to the model. Codex evaluates each matching handler independently. For events that can’t produce additional context, Codex ignores `additionalContextLimit` and reports a configuration warning.

The setting applies only to `additionalContext`. Tool feedback and continuation prompts keep the default limit.

Because oversized output can be written to disk, avoid returning secrets or other sensitive data in hook output.

## Run hooks in the background

By default, Codex waits for a command hook to finish before continuing the operation that triggered it. Set `async` to `true` to run a command hook in the background while Codex continues.

### Configure a background hook

Add `"async": true` to a command handler in `hooks.json`:

```
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/post_tool_use.py",
            "async": true,
            "timeout": 120
          }
        ]
      }
    ]
  }
}
```

For an inline hook in `config.toml`, set `async = true`:

```
[[hooks.PostToolUse]]
matcher = "Bash"

[[hooks.PostToolUse.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/post_tool_use.py"
async = true
timeout = 120
```

Background hooks use the same input, matcher, trust review, timeout, and [large-output handling](https://developers.openai.com/codex/hooks#large-hook-output) as synchronous command hooks. As with other command hooks, `timeout` is measured in seconds and defaults to `600`.

### How background hooks run

When a background hook finishes, Codex delivers supported informational output at the next safe point in the conversation:

*   If a turn is active, Codex waits for the current model request and tool calls to finish, then makes the output available to the next model request in that turn.
*   If no turn is active, Codex waits until the next user turn. Finishing a background hook doesn’t start a new turn.

Use the same event-specific JSON output as a synchronous hook. Codex adds `additionalContext` to the model’s context and surfaces `systemMessage` as a warning.

Background hooks can’t block, approve, rewrite, or otherwise control the operation that triggered them. Use synchronous hooks for tool policies, permission decisions, prompt rejection, or turn continuation.

### Limitations

*   Codex runs up to eight background hooks concurrently per session. Additional hooks wait until a running hook finishes.
*   Each matching invocation runs independently, and background hooks can finish in a different order than they started.
*   When the session ends, Codex cancels unfinished background hooks and discards output that hasn’t been delivered.
*   `SessionEnd` hooks always run synchronously.

## Hooks

### SessionStart

`matcher` is applied to `source` for this event.

Fields in addition to [Common input fields](https://developers.openai.com/codex/hooks#common-input-fields):

| Field | Type | Meaning |
| --- | --- | --- |
| `source` | `string` | How the session started: `startup`, `resume`, `clear`, or `compact` |

Plain text on `stdout` is added as extra developer context.

JSON on `stdout` supports [Common output fields](https://developers.openai.com/codex/hooks#common-output-fields) and this hook-specific shape:

```
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Load the workspace conventions before editing."
  }
}
```

That `additionalContext` text is added as extra developer context.

After Codex compacts a root session, `SessionStart` hooks that match `source: "compact"` run before the next model request. This also applies when automatic compaction happens in the middle of a turn: Codex delivers the hook’s additional context to the immediate continuation instead of waiting for a later user turn. If the hook returns `continue: false`, Codex ends the turn without sending another model request.

### SessionEnd

`SessionEnd` lets you run a command when a session ends, such as saving final notes or cleaning up files. It runs for the main thread when you archive or delete a conversation that’s still open, when Codex closes normally, or after a conversation has been idle and isn’t open in any connected client for 30 minutes. It won’t run for subagents.

Switching away from a conversation or calling `thread/unsubscribe` doesn’t end the session right away, so it won’t immediately run `SessionEnd`. Your hook can still read the session transcript while it runs.

`matcher` filters `reason` for this event. For now, `reason` is always `other`. You can omit `matcher` or use `other` to run on every `SessionEnd` event.

Fields in addition to [Common input fields](https://developers.openai.com/codex/hooks#common-input-fields):

| Field | Type | Meaning |
| --- | --- | --- |
| `reason` | `string` | Why the session ended: `other` |

For example, a `SessionEnd` command receives:

```
{
  "session_id": "thr_123",
  "transcript_path": "/workspace/.codex/rollout.jsonl",
  "cwd": "/workspace",
  "hook_event_name": "SessionEnd",
  "reason": "other"
}
```

`SessionEnd` hooks always run synchronously, even when `async` is `true`. They are advisory, so their output won’t steer Codex or keep the thread open. If a command times out or exits with an error, Codex reports it as a hook failure.

### SubagentStart

`matcher` is applied to `agent_type` for this event.

Fields in addition to [Common input fields](https://developers.openai.com/codex/hooks#common-input-fields):

| Field | Type | Meaning |
| --- | --- | --- |
| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |
| `agent_id` | `string` | Identifier for the subagent |
| `agent_type` | `string` | Subagent type or profile |
| `permission_mode` | `string` | Current permission mode |

Plain text on `stdout` is added as extra developer context for the subagent.

JSON on `stdout` supports `systemMessage` and this hook-specific shape:

```
{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "Review the repository test conventions first."
  }
}
```

That `additionalContext` text is added as extra developer context for the subagent. `continue: false` is parsed for compatibility, but it doesn’t stop the subagent from starting.

### PreToolUse

`PreToolUse` can intercept Bash, file edits performed through `apply_patch`, MCP tool calls, and other local function tools. See [Tool coverage](https://developers.openai.com/codex/hooks#tool-coverage) for the supported paths and exceptions.

`matcher` is applied to `tool_name` and matcher aliases. For file edits through `apply_patch`, `matcher` values can use `apply_patch`, `Edit`, or `Write`; hook input still reports `tool_name: "apply_patch"`.

Fields in addition to [Common input fields](https://developers.openai.com/codex/hooks#common-input-fields):

| Field | Type | Meaning |
| --- | --- | --- |
| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |
| `tool_name` | `string` | Canonical hook tool name, such as `Bash`, `apply_patch`, or an MCP name like `mcp__fs__read` |
| `tool_use_id` | `string` | Tool-call id for this invocation |
| `tool_input` | `JSON value` | Tool-specific input. `Bash` and `apply_patch` use `tool_input.command`. MCP and other local function tools send their arguments. |

Plain text on `stdout` is ignored.

JSON on `stdout` can use `systemMessage`. To deny a supported tool call, return this hook-specific shape:

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

Codex also accepts this older block shape:

```
{
  "decision": "block",
  "reason": "Destructive command blocked by hook."
}
```

You can also use exit code `2` and write the blocking reason to `stderr`.

To add model-visible context without blocking, return `hookSpecificOutput.additionalContext`:

```
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "additionalContext": "The pending command touches generated files."
  }
}
```

To rewrite a supported tool call without blocking, return `permissionDecision: "allow"` with `updatedInput`:

```
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "updatedInput": {
      "command": "echo rewritten"
    }
  }
}
```

For Bash commands and `apply_patch`, `updatedInput` must include a string `command` field. For MCP and other local function tools, `updatedInput` is the replacement arguments object. Return `updatedInput` only with `permissionDecision: "allow"`; other `updatedInput` shapes are reported as errors.

`permissionDecision: "ask"`, legacy `decision: "approve"`, `continue: false`, `stopReason`, and `suppressOutput` are parsed but not supported yet. Codex marks the hook run as failed, reports the error, and continues the tool call.

### PermissionRequest

`PermissionRequest` runs when Codex is about to ask for approval, such as a shell escalation or managed-network approval. It can allow the request, deny the request, or decline to decide and let the normal approval prompt continue. It doesn’t run for commands that don’t need approval.

`matcher` is applied to `tool_name` and matcher aliases. Current canonical values include `Bash`, `apply_patch`, and MCP tool names such as `mcp__server__tool`; `apply_patch` also matches `Edit` and `Write`.

Fields in addition to [Common input fields](https://developers.openai.com/codex/hooks#common-input-fields):

| Field | Type | Meaning |
| --- | --- | --- |
| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |
| `tool_name` | `string` | Canonical hook tool name, such as `Bash`, `apply_patch`, or an MCP name like `mcp__fs__read` |
| `tool_input` | `JSON value` | Tool-specific input. `Bash` and `apply_patch` use `tool_input.command` while MCP tools send all the arguments. |
| `tool_input.description` | `string | null` | Human-readable approval reason, when Codex has one |

Plain text on `stdout` is ignored.

Some tool inputs may include a human-readable description, but don’t rely on a `tool_input.description` field for every tool.

To approve the request, return:

```
{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow"
    }
  }
}
```

To deny the request, return:

```
{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "deny",
      "message": "Blocked by repository policy."
    }
  }
}
```

If multiple matching hooks return decisions, any `deny` wins. Otherwise, an `allow` lets the request proceed without surfacing the approval prompt. If no matching hook decides, Codex uses the normal approval flow.

Don’t return `updatedInput`, `updatedPermissions`, or `interrupt` for `PermissionRequest`; those fields are reserved for future behavior and fail closed today.

### PostToolUse

`PostToolUse` runs after supported tools produce output, including Bash, `apply_patch`, MCP tool calls, and other local function tools. For Bash, it also runs after commands that exit with a non-zero status. It can’t undo side effects from a tool that already ran. See [Tool coverage](https://developers.openai.com/codex/hooks#tool-coverage) for the supported paths and exceptions.

`matcher` is applied to `tool_name` and matcher aliases. For file edits through `apply_patch`, `matcher` values can use `apply_patch`, `Edit`, or `Write`; hook input still reports `tool_name: "apply_patch"`.

Fields in addition to [Common input fields](https://developers.openai.com/codex/hooks#common-input-fields):

| Field | Type | Meaning |
| --- | --- | --- |
| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |
| `tool_name` | `string` | Canonical hook tool name, such as `Bash`, `apply_patch`, or an MCP name like `mcp__fs__read` |
| `tool_use_id` | `string` | Tool-call id for this invocation |
| `tool_input` | `JSON value` | Tool-specific input. `Bash` and `apply_patch` use `tool_input.command`. MCP and other local function tools send their arguments. |
| `tool_response` | `JSON value` | Tool-specific output. MCP tools send the MCP call result. Other local function tools normally send their model-facing output. |

Plain text on `stdout` is ignored.

JSON on `stdout` can use `systemMessage` and this hook-specific shape:

```
{
  "decision": "block",
  "reason": "The Bash output needs review before continuing.",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "The command updated generated files."
  }
}
```

That `additionalContext` text is added as extra developer context.

For this event, `decision: "block"` doesn’t undo the completed Bash command. Instead, Codex records the feedback, replaces the tool result with that feedback, and continues the model from the hook-provided message.

You can also use exit code `2` and write the feedback reason to `stderr`.

To stop normal processing of the original tool result after the command has already run, return `continue: false`. Codex will replace the tool result with your feedback or stop text and continue from there.

`updatedMCPToolOutput` and `suppressOutput` are parsed but not supported yet. Codex marks the hook run as failed, reports the error, and continues normal processing of the tool result.

#### Tool calls from code mode

When a model uses code mode to call a tool from JavaScript, hook decisions apply to that nested call. `PreToolUse` can stop the tool before it runs or rewrite its input. A blocking `PostToolUse` can’t undo the tool’s side effects, but it can keep the original result from reaching the running script.

| Hook result | What code mode sees |
| --- | --- |
| `PreToolUse` blocks | The tool promise rejects before the tool runs. |
| `PreToolUse` returns `updatedInput` | The tool runs with the rewritten input and the promise resolves with that result. |
| `PostToolUse` returns `decision: "block"` or exits with code `2` | The tool runs, then the promise rejects with the hook reason. |
| `PostToolUse` returns `continue: false` | Codex uses the hook feedback for the model-visible result, but doesn’t reject the nested tool promise. |

### PreCompact

`PreCompact` runs before Codex compacts the chat. `matcher` is applied to `trigger`, whose values are `manual` and `auto`.

Fields in addition to [Common input fields](https://developers.openai.com/codex/hooks#common-input-fields):

| Field | Type | Meaning |
| --- | --- | --- |
| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |
| `trigger` | `string` | What triggered compaction: `manual` or `auto` |

Plain text on `stdout` is ignored.

JSON on `stdout` supports [Common output fields](https://developers.openai.com/codex/hooks#common-output-fields). If a matching `PreCompact` hook returns `continue: false`, Codex stops before compacting.

### PostCompact

`PostCompact` runs after Codex compacts the chat. `matcher` is applied to `trigger`, whose values are `manual` and `auto`.

Fields in addition to [Common input fields](https://developers.openai.com/codex/hooks#common-input-fields):

| Field | Type | Meaning |
| --- | --- | --- |
| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |
| `trigger` | `string` | What triggered compaction: `manual` or `auto` |

Plain text on `stdout` is ignored.

JSON on `stdout` supports [Common output fields](https://developers.openai.com/codex/hooks#common-output-fields). If a matching `PostCompact` hook returns `continue: false`, Codex stops after compacting.

### UserPromptSubmit

`matcher` isn’t currently used for this event.

Fields in addition to [Common input fields](https://developers.openai.com/codex/hooks#common-input-fields):

| Field | Type | Meaning |
| --- | --- | --- |
| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |
| `prompt` | `string` | User prompt that’s about to be sent |

Plain text on `stdout` is added as extra developer context.

JSON on `stdout` supports [Common output fields](https://developers.openai.com/codex/hooks#common-output-fields) and this hook-specific shape:

```
{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Ask for a clearer reproduction before editing files."
  }
}
```

That `additionalContext` text is added as extra developer context.

To block the prompt, return:

```
{
  "decision": "block",
  "reason": "Ask for confirmation before doing that."
}
```

You can also use exit code `2` and write the blocking reason to `stderr`.

### SubagentStop

`matcher` is applied to `agent_type` for this event.

Fields in addition to [Common input fields](https://developers.openai.com/codex/hooks#common-input-fields):

| Field | Type | Meaning |
| --- | --- | --- |
| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |
| `agent_id` | `string` | Identifier for the subagent |
| `agent_type` | `string` | Subagent type or profile |
| `agent_transcript_path` | `string | null` | Path to the subagent transcript file, if any |
| `stop_hook_active` | `boolean` | Whether this subagent was already continued |
| `last_assistant_message` | `string | null` | Latest subagent assistant message, if available |

`SubagentStop` expects JSON on `stdout` when it exits `0`. Plain text output is invalid for this event.

JSON on `stdout` supports [Common output fields](https://developers.openai.com/codex/hooks#common-output-fields). To ask Codex to continue the subagent flow, return:

```
{
  "decision": "block",
  "reason": "Run one more focused pass inside the subagent."
}
```

You can also use exit code `2` and write the continuation reason to `stderr`.

If any matching `SubagentStop` hook returns `continue: false`, that takes precedence over continuation decisions from other matching `SubagentStop` hooks.

### Stop

`matcher` isn’t currently used for this event.

Fields in addition to [Common input fields](https://developers.openai.com/codex/hooks#common-input-fields):

| Field | Type | Meaning |
| --- | --- | --- |
| `turn_id` | `string` | Codex-specific extension. Active Codex turn id |
| `stop_hook_active` | `boolean` | Whether this turn was already continued by `Stop` |
| `last_assistant_message` | `string | null` | Latest assistant message text, if available |

`Stop` expects JSON on `stdout` when it exits `0`. Plain text output is invalid for this event.

JSON on `stdout` supports [Common output fields](https://developers.openai.com/codex/hooks#common-output-fields). To keep Codex going, return:

```
{
  "decision": "block",
  "reason": "Run one more pass over the failing tests."
}
```

You can also use exit code `2` and write the continuation reason to `stderr`.

For this event, `decision: "block"` doesn’t reject the turn. Instead, it tells Codex to continue and automatically creates a new continuation prompt that acts as a new user prompt, using your `reason` as that prompt text.

If any matching `Stop` hook returns `continue: false`, that takes precedence over continuation decisions from other matching `Stop` hooks.

## Schemas

The linked `main` branch schemas may include hook fields that are not in the current release. Use this page as the release behavior reference.

If you need the exact current wire format, see the generated schemas in the [Codex GitHub repository](https://github.com/openai/codex/tree/main/codex-rs/hooks/schema/generated).

[Previous Build plugins](https://developers.openai.com/codex/build-plugins)

Ask AI

## Docs agent

Loading docs agent...