Codex CLI: UserPromptSubmit Hook for Prompt Interception and Augmentation
CodexCodex CLI 0.116.0 introduces the userpromptsubmit hook, expanding the hooks engine with a lifecycle event that fires the moment a user submits a prompt — before execution and before the prompt enters conversation history. Developers can use this hook to block prompts that fail custom validation, augment them with additional context, or enforce organizational policies at the input pipeline edge. The feature extends the existing hooks system (which already covers SessionStart and Stop events from 0.114.0) and brings Codex CLI closer to parity with hook systems in tools like Claude Code and Cursor.
Sources & Mentions
5 external resources covering this update
Prompt Interception at the Source: The userpromptsubmit Hook
Codex CLI 0.116.0 adds a new event to its growing hooks engine: userpromptsubmit. This hook fires at the moment a user submits a prompt — before the prompt is executed and before it is written into conversation history. The result is a powerful interception point that gives teams and individual developers fine-grained control over what actually enters the agent's processing pipeline.
What the Hook Enables
The userpromptsubmit hook supports two primary behaviors:
- Blocking prompts: A hook script can reject a prompt outright, preventing it from reaching the model. This is useful for enforcing content policies, blocking prompts that contain sensitive patterns (e.g., credentials, internal project names), or implementing approval workflows in team environments.
- Augmenting prompts: The hook can modify a prompt before execution — appending additional context, reformatting the request, injecting relevant file paths, or prepending system notes that should always accompany a certain type of task.
Because the hook fires before history is recorded, blocked or modified prompts leave no trace in the session log, keeping conversation history clean.
A Growing Hooks Ecosystem
The userpromptsubmit hook is the third addition to Codex CLI's hooks system. OpenAI introduced SessionStart and Stop hooks in version 0.114.0 (March 11, 2026), responding to long-running community requests for lifecycle extensibility. The userpromptsubmit hook continues that trajectory, adding coverage at the input layer of every agent interaction.
Community-built extensions have already started taking advantage of the hooks system. Projects like codex-hooks (which reuses Claude Code hook settings) and session-tracking tools built on SessionStart data demonstrate the demand for CLI extensibility. The userpromptsubmit hook opens a new surface area for similar integrations, particularly for teams that want to implement prompt governance without modifying core CLI configuration.
Broader Context
The addition of userpromptsubmit reflects a broader trend across AI coding tools: users want programmable pipelines, not just a static chat interface. By exposing prompt-level hooks, Codex CLI allows developers to build organizational standards directly into their local workflows — without relying on server-side filtering or model-level instructions that can be bypassed.
For teams operating under compliance requirements or those building shared Codex configurations for engineering organizations, this hook provides a meaningful new lever for enforcement and customization.