start of hooks engine by eternal-openai · Pull Request #13276 · openai/codex

eternal-openai · 2026-03-02T20:52:03Z

(Experimental)

This PR adds a first MVP for hooks, with SessionStart and Stop

The core design is:

hooks live in a dedicated engine under codex-rs/hooks
each hook type has its own event-specific file
hook execution is synchronous and blocks normal turn progression while running
matching hooks run in parallel, then their results are aggregated into a normalized HookRunSummary

On the AppServer side, hooks are exposed as operational metadata rather than transcript-native items:

new live notifications: hook/started, hook/completed
persisted/replayed hook results live on Turn.hookRuns
we intentionally did not add hook-specific ThreadItem variants

Hooks messages are not persisted, they remain ephemeral. The context changes they add are (they get appended to the user's prompt)

github-actions · 2026-03-02T20:52:12Z

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

eternal-openai · 2026-03-03T23:41:55Z

I have read the CLA Document and I hereby sign the CLA

jif-oai · 2026-03-06T14:36:55Z

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 means you run everything in parallel. So the ordering of the hooks is not respected, even for "Sync" hooks

That's on purpose based on my understanding of the existing spec. I'm unclear what sync hooks are

Would be good to make sure we don't miss something here

i have the same confusion. is sync vs. async whether they block the turn, rather than whether they're serialized? this should be clarified in docs/code, otherwise I'd think I could serialize hook execution (hook A formats, hook B runs tests given formatting finished).

As far as I'm aware, the mechanics are correct here:

Hooks execute in parallel to maximize overall processing speed

The agent loop waits for the hook to complete in the typical case

The spec supports doing async (i.e. hooks run in the background - we'll do that later)

codex-rs/exec/src/event_processor_with_human_output.rs

codex-rs/core/src/codex.rs

codex-rs/app-server-protocol/src/protocol/thread_history.rs

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

codex-rs/hooks/src/events/session_start.rs

eternal-openai · 2026-03-06T20:57:42Z

@jif-oai Thank you so much for the thorough review! Super helpful. I was trying to keep this as minimal as I could, focussed on laying the groundwork, so there's a bunch of stuff not fully implemented even for these two hooks. That'll come as a fast follow. But you've also identified a couple issue here, so I'm about to correct these 🙏

jif-oai

Looks better to me. I think we should discuss the sandboxing point

jif-oai · 2026-03-07T09:26:45Z

codex-rs/hooks/src/events/stop.rs

+                        should_block = true;
+                        block_reason = parsed.reason.clone();
+                        block_message_for_model = parsed.reason.clone();
+                        if let Some(reason) = parsed.reason {


How does it work if there is no reason? How is the model supposed to know what to do? What do you restart the turn on?

+1, restarting the turn with no additional context seems bad.

Totally agree, great catch, making a change to enforce that reason has to be there if stop-block is true (which is also part of the spec)

Stop hook (failed) warning: Wizard Tower Stop hook reviewed the completed reply (129 chars). error: hook returned decision "block" without a non-empty reason

Implemented. Also handling the exit code 2 with black stderr variant of the same issue

jif-oai · 2026-03-07T09:28:42Z

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

+        .stderr(Stdio::piped())
+        .kill_on_drop(true);
+
+    let mut child = match command.spawn() {


Discussion point on sandboxing here:
Hooks run outside of our sandboxing which, I think, come from the fact that a hook is user defined. But Stop hooks for example take the assistant message as input. So it means that in practice, a hook can execute something coming from the model. That sounds a bit dangerous to me. Any thoughts on this @bolinfest ?

Would love to get Bolin's thoughts, and yeah, hooks are inherently unsafe -- though I don't think it's on us to provide their security

codex-rs/core/src/codex.rs

jif-oai · 2026-03-07T09:30:48Z

codex-rs/hooks/src/events/stop.rs

+        }
+        None => match run_result.exit_code {
+            Some(0) => {
+                if let Some(parsed) = output_parser::parse_stop(&run_result.stdout) {


We shouldn't silently ignore if the JSON parsing fails

Great point, thank you, implemented

codex-rs/hooks/src/events/session_start.rs

sayan-oai

mostly behavioral questions. the overall structure makes sense to me.

sayan-oai · 2026-03-07T23:33:12Z

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(


i have the same confusion. is sync vs. async whether they block the turn, rather than whether they're serialized? this should be clarified in docs/code, otherwise I'd think I could serialize hook execution (hook A formats, hook B runs tests given formatting finished).

sayan-oai · 2026-03-07T23:35:25Z

codex-rs/hooks/src/events/session_start.rs

+                            });
+                        }
+                    }
+                } else if let Some(additional_context) = trimmed_non_empty(&run_result.stdout) {


do we want to inject stdout into model context if parsing fails? this also seems different than the behavior for stop hooks, which doesn't inject on parse failure (it seems to silently no-op).

Thank you, now treating malformed JSON-like output as an error, while preserving intentional plain text output

sayan-oai · 2026-03-07T23:36:51Z

codex-rs/hooks/src/events/session_start.rs

+                            additional_context_for_model = Some(additional_context);
+                        }
+                    }
+                    let _ = parsed.universal.suppress_output;


should we include suppress_output in the schema if we ignore it here and on Stop?

im assuming this is deferred, like clear. we should document this in code.

Yep, exactly

sayan-oai · 2026-03-07T23:39:45Z

codex-rs/core/src/codex.rs

+                            .await;
+                    }
+                    if stop_outcome.should_block {
+                        if stop_hook_active {


maybe this is aspirational/deferred, but is it possible to have a less coarse way of defending against infinite loops? instead of a bool, could we filter by unique reasons, or have a >1 limit? it seems plausible to want to have >1 stop hook run per turn. feel free to push back, not blocking.

Yes, that's coming in the next PR using the stop_hook_active mechanism

sayan-oai · 2026-03-07T23:42:09Z

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

+    }
+
+    #[test]
+    fn select_handlers_keeps_duplicate_stop_handlers() {


do we want to keep duplicated handlers? why not dedupe?

Yeah, I had it an earlier version of the PR, but jif pointed out that it's probably a mistake. If the user's config has duplicates defined, it could be for a valid usecase (the script does something different the second time) and generally I think respecting that is probably right. Though if you disagree, happy to put it back

eternal-openai · 2026-03-09T19:05:29Z

Appreciate the hardening pass, feels like we're close! Changes are made, please review once more 🙏

# Conflicts: # codex-rs/app-server-protocol/schema/typescript/EventMsg.ts # codex-rs/app-server-protocol/schema/typescript/ServerNotification.ts # codex-rs/app-server/src/bespoke_event_handling.rs # codex-rs/core/src/features.rs # codex-rs/exec/src/event_processor_with_human_output.rs

# Conflicts: # codex-rs/core/src/state/session.rs

# Conflicts: # codex-rs/core/src/codex_tests.rs

eternal-openai requested a review from bolinfest March 2, 2026 20:52

eternal-openai added 5 commits March 3, 2026 13:58

hooks: add rust-owned schema fixtures

69fe65f

protocol: add hook lifecycle types and turn hookRuns

37a973e

build: thread hookRuns through compile-only call sites

7482199

remove these constructors for now to avoid warnings

a89ffca

hooks: rename schema fixtures binary

62f660c

eternal-openai mentioned this pull request Mar 3, 2026

[Hooks] Schema changes only - AppServer protocol additions & Hooks I/O schema #13408

Closed

eternal-openai marked this pull request as ready for review March 3, 2026 23:42

github-actions bot added a commit that referenced this pull request Mar 3, 2026

@eternal-openai has signed the CLA in #13276

218d797

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

📊 AI CLI 工具社区动态日报 2026-03-04 duanyytop/agents-radar#70

Open

eternal-openai added 2 commits March 3, 2026 17:15

hooks: rebase runtime on top of hooks-1

30d7dad

No longer persist HookRunSummaries, ephemeral only

dbeba0c

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

eternal-openai force-pushed the eternal/start-of-hooks branch from ad59823 to dbeba0c Compare March 5, 2026 21:45

remove unneeded hooks feature gate seam

7808eba

eternal-openai requested a review from pakrym-oai March 5, 2026 22:13

jif-oai reviewed Mar 6, 2026

View reviewed changes

fix matcher behaviour and forward errors

efcd98b

eternal-openai force-pushed the eternal/start-of-hooks branch 2 times, most recently from 14b625c to efcd98b Compare March 6, 2026 23:24

eternal-openai added 3 commits March 6, 2026 15:33

Merge origin/main into hooks

7a1c604

app-server-protocol: regenerate hook schema fixtures after merge

91a004d

format

037dd2f

eternal-openai added 4 commits March 6, 2026 16:22

hooks: fix lint and bazel schema fixture failures

bdf7f84

ci/cd fix for legacy notification api shape

d86cd14

more linter fixes

3131777

fix ci/cd windows newline mismatch

4427e5b

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

📊 AI CLI 工具社区动态日报 2026-03-07 rollysys/agents-radar#47

Open

jif-oai reviewed Mar 7, 2026

View reviewed changes

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

📊 AI CLI 工具社区动态日报 2026-03-07 compasify/agents-radar#4

Open

sayan-oai reviewed Mar 7, 2026

View reviewed changes

This was referenced Mar 8, 2026

📊 AI CLI 工具社区动态日报 2026-03-08 duanyytop/agents-radar#95

Open

📊 Bản tin hàng ngày công cụ AI CLI 2026-03-08 compasify/agents-radar#9

Open

eternal-openai added 2 commits March 9, 2026 11:27

hooks: require feedback for stop blocking

05bb49c

hooks: better defense for json failures

88934a1

eternal-openai enabled auto-merge (squash) March 9, 2026 21:09

codex: fix CI failure on PR #13276

d477da5

sayan-oai approved these changes Mar 10, 2026

View reviewed changes

Merge remote-tracking branch 'origin/main' into hooks

b76677a

# Conflicts: # codex-rs/core/src/state/session.rs

This was referenced Mar 10, 2026

📊 AI CLI Tools Digest 2026-03-10 duanyytop/agents-radar#118

Open

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

Open

📊 AI CLI Tools Digest 2026-03-10 gsscsd/big_model_radar#8

Open

codex: fix CI failure on PR #13276

09c4ba3

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

📊 Bản tin hàng ngày công cụ AI CLI 2026-03-10 compasify/agents-radar#20

Open

etraut-openai mentioned this pull request Mar 10, 2026

Codex doesn't seem to work? karpathy/autoresearch#57

Open

eternal-openai added 3 commits March 9, 2026 19:40

Merge remote-tracking branch 'origin/main' into hooks

7262b5f

core: add request permission scopes

bd444aa

Merge remote-tracking branch 'origin/main' into hooks

f0255ec

# Conflicts: # codex-rs/core/src/codex_tests.rs

eternal-openai merged commit 244b2d5 into main Mar 10, 2026
31 checks passed

eternal-openai deleted the eternal/start-of-hooks branch March 10, 2026 04:11

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

Conversation

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

Uh oh!

github-actions bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

eternal-openai commented Mar 3, 2026

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eternal-openai commented Mar 6, 2026

jif-oai left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Uh oh!

sayan-oai left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

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

Uh oh!

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eternal-openai commented Mar 9, 2026

Uh oh!

Labels

4 participants

eternal-openai commented Mar 2, 2026 •

edited

Loading

github-actions bot commented Mar 2, 2026 •

edited

Loading

eternal-openai Mar 9, 2026 •

edited

Loading