[hooks] userpromptsubmit - hook before user's prompt is executed by eternal-openai · Pull Request #14626 · openai/codex

eternal-openai · 2026-03-13T20:28:09Z

this allows blocking the user's prompts from executing, and also prevents them from entering history
handles the edge case where you can both prevent the user's prompt AND add n amount of additionalContexts
refactors some old code into common.rs where hooks overlap functionality
refactors additionalContext being previously added to user messages, instead we use developer messages for them
handles queued messages correctly

Sample hook for testing - if you write "[block-user-submit]" this hook will stop the thread:

example run

› sup


• Running UserPromptSubmit hook: reading the observatory notes

UserPromptSubmit hook (completed)
  warning: wizard-tower UserPromptSubmit demo inspected: sup
  hook context: Wizard Tower UserPromptSubmit demo fired. For this reply only, include the exact
phrase 'observatory lanterns lit' exactly once near the end.

• Just riding the cosmic wave and ready to help, my friend. What are we building today? observatory
  lanterns lit


› and [block-user-submit]


• Running UserPromptSubmit hook: reading the observatory notes

UserPromptSubmit hook (stopped)
  warning: wizard-tower UserPromptSubmit demo blocked the prompt on purpose.
  stop: Wizard Tower demo block: remove [block-user-submit] to continue.

.codex/config.toml

[features]
codex_hooks = true

.codex/hooks.json

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 .codex/hooks/user_prompt_submit_demo.py",
            "timeoutSec": 10,
            "statusMessage": "reading the observatory notes"
          }
        ]
      }
    ]
  }
}

.codex/hooks/user_prompt_submit_demo.py

#!/usr/bin/env python3

import json
import sys
from pathlib import Path


def prompt_from_payload(payload: dict) -> str:
    prompt = payload.get("prompt")
    if isinstance(prompt, str) and prompt.strip():
        return prompt.strip()

    event = payload.get("event")
    if isinstance(event, dict):
        user_prompt = event.get("user_prompt")
        if isinstance(user_prompt, str):
            return user_prompt.strip()

    return ""


def main() -> int:
    payload = json.load(sys.stdin)
    prompt = prompt_from_payload(payload)
    cwd = Path(payload.get("cwd", ".")).name or "wizard-tower"

    if "[block-user-submit]" in prompt:
        print(
            json.dumps(
                {
                    "systemMessage": (
                        f"{cwd} UserPromptSubmit demo blocked the prompt on purpose."
                    ),
                    "decision": "block",
                    "reason": (
                        "Wizard Tower demo block: remove [block-user-submit] to continue."
                    ),
                }
            )
        )
        return 0

    prompt_preview = prompt or "(empty prompt)"
    if len(prompt_preview) > 80:
        prompt_preview = f"{prompt_preview[:77]}..."

    print(
        json.dumps(
            {
                "systemMessage": (
                    f"{cwd} UserPromptSubmit demo inspected: {prompt_preview}"
                ),
                "hookSpecificOutput": {
                    "hookEventName": "UserPromptSubmit",
                    "additionalContext": (
                        "Wizard Tower UserPromptSubmit demo fired. "
                        "For this reply only, include the exact phrase "
                        "'observatory lanterns lit' exactly once near the end."
                    ),
                },
            }
        )
    )
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

…sion_start to also use developer message for this

jif-oai · 2026-03-17T09:53:36Z

codex-rs/hooks/src/engine/dispatcher.rs

    turn_id: Option<String>,
    parse: fn(&ConfiguredHandler, CommandRunResult, Option<String>) -> ParsedHandler<T>,
 ) -> Vec<ParsedHandler<T>> {
    let results = join_all(


This still launches every handler concurrently, so a blocking user-prompt-submit hook cannot prevent later handlers from running/injecting context. That broke the pre-submit stop semantics + conflicts with the reported Sync execution mode

I'm under the impression that the code matches the spec here -- the spec doesn't have a concept of sequential sync, all hooks are run in parallel all the time (to save time, etc). What sync vs async means is that async hooks are run purely in the background, i.e. the thread doesn't wait for them to complete (we haven't implemented this yet). Sync means that we block the loop until all sync hooks complete. Agree that the naming in the code could be a bit more clear, but I'm leaning towards leaving this as-is

jif-oai · 2026-03-17T10:06:20Z

codex-rs/core/src/codex.rs

+        for pending_input in accepted_pending_input {
+            record_pending_input(&sess, &turn_context, pending_input).await;
+        }
+        record_additional_contexts(&sess, &turn_context, blocked_pending_input_contexts).await;


If a later queued prompt is blocked after an earlier queued prompt was accepted, this injects the blocked prompt’s context into the accepted follow-up request?

Yes, that was a detail that I was paying attention to. The spec indeed wants us to accept additionalContext regardless of block, so: if queued prompt A is accepted, queued prompt B is blocked, and B returns additionalContext, we record A, then record B’s additional context, then build the next sampling request. So yes, B’s context can influence the follow-up request that contains A

Basically the mechanics of additionalContext is that it's added no matter what, if the hooks sets it

jif-oai · 2026-03-17T10:07:08Z

codex-rs/hooks/src/engine/dispatcher.rs

                _ => false,
            },
-            HookEventName::Stop => true,
+            HookEventName::UserPromptSubmit | HookEventName::Stop => true,


UserPromptSubmit matchers are parsed and validated, but this makes them unconditional at runtime. Either honor matchers or reject them in config

Great catch, addressing...

UserPromptSubmit matchers were already ignored at runtime, but discovery was still parsing/validating/storing them, which meant an invalid matcher could still warn or prevent registration. I changed discovery to ignore matchers for UserPromptSubmit (and Stop) as well

This matches what the spec wants:

UserPromptSubmit, Stop, [...] don’t support matchers and always fire on every occurrence. If you add a matcher field to these events, it is silently ignored.

sayan-oai · 2026-03-17T21:22:16Z

codex-rs/core/src/hook_runtime.rs

+    let request = codex_hooks::SessionStartRequest {
+        session_id: sess.conversation_id,
+        cwd: turn_context.cwd.clone(),
+        transcript_path: sess.current_rollout_path().await,


is the file at the current_rollout_path guaranteed to exist at this point? it seems like it's only materialized when the prompt is recorded below by record_user_prompt_and_emit_turn_item

Thanks! Fixed it so that we make sure to materialize the transcript before the hook runs

havent looked into this too deeply, but i want to be sure we aren't reverting intentional work. it seems from this pr that defering the materialization until the first UserMessage was intentional-- is it ok to basically undo that?

Yeah @etraut-openai would love to have your thoughts here, but @sayan-oai I guess it's not exactly a revert, because this only runs if hooks require it -- and I'm not sure how to get around that requirement without breaking the spec. I'm also contemplating how closely we want to match the transcript style that's used in the industry, since ours is fairly different of course -- so maybe one day this becomes a different transcript mechanism altogether

sayan-oai · 2026-03-17T21:24:37Z

codex-rs/core/src/tasks/mod.rs

+                    PendingInputHookDisposition::Blocked {
+                        additional_contexts,
+                    } => {
+                        record_additional_contexts(self, &turn_context, additional_contexts).await;


the similar pending_input loop in run_turn seems to break + requeue remaining items on Blocked, but this one seems to continue. why are they different?

@charley-oai, why do we drain all pending items on task_finished and persisting them in conversation history? I see this pr. Just curious if this is behavior we want to continue with prompt-submission turn hooks.

Yeah, thank you Sayan & Charley for helping me understand and untangle this. I think the reef that I hit surfing through here is that:

Previously this was introduced to handle a kind of weird race between turn ending & queued messages coming in. So my read here is that we wanted to at least persist those loose-hanging prompts into history, then if the model ever started up that thread again, it would catch em?

But my little catch-22 here is that this mechanism would bypass hooks by doing so

So it sounds like we need to either (a) make sure this race can't happen in a different way, like automatically starting the next real turn or (b) make some kind of new concept of queue persistence so that the next time the thread gets started, it'll run through the normal hook processing pipeline. But let me know if I'm catching the wave wrong

Yep @eternal-openai that's exactly right

Alright, thanks @charley-oai -- I'm going to descope that from this PR then and come back to fixing this issue in its own PR, seems like it would be a bit much

sayan-oai · 2026-03-18T04:02:19Z

codex-rs/core/src/codex.rs

-    let response_item: ResponseItem = initial_input_for_turn.clone().into();
    sess.record_user_prompt_and_emit_turn_item(turn_context.as_ref(), &input, response_item)
        .await;
+    record_additional_contexts(&sess, &turn_context, additional_contexts).await;


developer messages are dropped on remote compaction, so additional context will disappear. is it ok for this to disappear from model history?

Hmm, thanks for telling me about that! I'll think about it some more, but my instinct is that that's okay:

various hooks are likely to run again after compaction

developers can use pre/post compaction hooks to ensure what they want gets reinserted

yeah i think this is non-blocking; we can see if the model becomes confused.

developers can use pre/post compaction hooks to ensure what they want gets reinserted

fair, but i dont think many users will be aware of the quirks of dev messages and the compaction lifecycle :)

sayan-oai

thanks for digging into the details to make sure this lands well!

eternal-openai marked this pull request as ready for review March 13, 2026 21:20

eternal-openai force-pushed the eternal/hooks-userpromptsubmit branch 5 times, most recently from 0a31f07 to f91c2e5 Compare March 16, 2026 06:32

etraut-openai added the oai PRs contributed by OpenAI employees label Mar 16, 2026

RousselPaul mentioned this pull request Mar 16, 2026

feat: Codex support integration RousselPaul/masko-code#5

Open

eternal-openai requested review from jif-oai, pakrym-oai and sayan-oai March 16, 2026 22:14

github-actions bot mentioned this pull request Mar 17, 2026

📊 AI CLI 工具社区动态日报 2026-03-17 gsscsd/big_model_radar#50

Open

eternal-openai added 8 commits March 16, 2026 21:00

hooks: add UserPromptSubmit hook event

cac2145

common utils & making sure blocked prompts don't make it into history

4522c8b

handle user prompt submit block with additionalContext & refactor ses…

3b44100

…sion_start to also use developer message for this

tui-app-server: handle UserPromptSubmit hook label

a515e28

core: preserve queued input after hook stop

a098a66

core: preserve hook semantics for queued prompts

48da0a3

hooks: fix argument comment lint

6aa94eb

hooks: format stop handler selection

8003348

eternal-openai force-pushed the eternal/hooks-userpromptsubmit branch from 2902d26 to 8003348 Compare March 17, 2026 04:03

jif-oai reviewed Mar 17, 2026

View reviewed changes

codex: address PR review feedback (#14626)

3e303ba

sayan-oai reviewed Mar 17, 2026

View reviewed changes

core: materialize hook transcripts before invocation

23138d0

sayan-oai reviewed Mar 18, 2026

View reviewed changes

sayan-oai approved these changes Mar 18, 2026

View reviewed changes

eternal-openai merged commit 6fef421 into main Mar 18, 2026
33 checks passed

eternal-openai deleted the eternal/hooks-userpromptsubmit branch March 18, 2026 05:09

github-actions bot locked and limited conversation to collaborators Mar 18, 2026

Conversation

eternal-openai commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sayan-oai Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sayan-oai left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

eternal-openai commented Mar 13, 2026 •

edited

Loading

sayan-oai Mar 17, 2026 •

edited

Loading