[hooks] add non-streaming (non-stdin style) shell-only PostToolUse support (#15531)

CHAINED PR - note that base is eternal/hooks-pretooluse-bash, not main
-- so the following PR should be first

Matching post-tool hook to the pre-tool functionality here:
https://github.com/openai/codex/pull/15211

So, PreToolUse calls for plain shell calls, allows blocking. This
PostToolUse call runs after the command executed

example run:

```
› as a test, run in parallel the following commands:
  - echo 'one'
  - echo '[block-pre-tool-use]'
  - echo '[block-post-tool-use]'


⚠ MCP startup incomplete (failed: notion, linear)

• Cruising through those three commands in parallel now, and I’ll share the exact outputs right after
  they land.

• Running PreToolUse hook: checking the observatory runes

• Running PreToolUse hook: checking the observatory runes

• Running PreToolUse hook: checking the observatory runes

PreToolUse hook (blocked)
  warning: wizard-tower PreToolUse demo blocked a Bash command on purpose.
  feedback: PreToolUse demo blocked the command. Remove [block-pre-tool-use] to continue.

PreToolUse hook (completed)
  warning: wizard-tower PreToolUse demo inspected Bash: echo 'one'

PreToolUse hook (completed)
  warning: wizard-tower PreToolUse demo inspected Bash: echo '[block-post-tool-use]'

• Ran echo '[block-post-tool-use]'
  └ [block-post-tool-use]

• Ran echo 'one'
  └ one

• Running PostToolUse hook: reading the observatory aftermath

• Running PostToolUse hook: reading the observatory aftermath

PostToolUse hook (blocked)
  warning: wizard-tower PostToolUse demo blocked the Bash follow-through on purpose.
  feedback: PostToolUse demo blocked the result after execution. Remove [block-post-tool-use] to
continue.

PostToolUse hook (completed)
  warning: wizard-tower PostToolUse demo inspected Bash: echo 'one'
  hook context: PostToolUse demo saw the Bash result. Response preview: one

──────────────────────────────────────────────────────────────────────────────────────────────────────

• Ran them in parallel. Little wave report:

  - echo 'one' completed and returned one.
  - echo '[block-pre-tool-use]' was blocked before execution by the PreToolUse hook.
  - echo '[block-post-tool-use]' ran, but its result was blocked afterward by the PostToolUse hook.

  The hook messages were:

  - PreToolUse demo blocked the command. Remove [block-pre-tool-use] to continue.
  - PostToolUse demo blocked the result after execution. Remove [block-post-tool-use] to continue.


› for the blocked messages (correctly blocked in this test) did the tool output land back into
  context?


• Yeah, from this run:

  - PreToolUse block: the command itself did not execute, so no command output landed in context. Only
    the block message did.
  - PostToolUse block: the command did execute, but the actual stdout did not come back into context.
    Only the post-tool block message did.

  So the blocked notifications landed in context, but the blocked command payloads themselves did not.
  Nice clean guardrail, aloha.
```

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

@@ -10,6 +10,8 @@ pub(crate) struct HooksFile {
 pub(crate) struct HookEvents {
     #[serde(rename = "PreToolUse", default)]
     pub pre_tool_use: Vec<MatcherGroup>,
+    #[serde(rename = "PostToolUse", default)]
+    pub post_tool_use: Vec<MatcherGroup>,
     #[serde(rename = "SessionStart", default)]
     pub session_start: Vec<MatcherGroup>,
     #[serde(rename = "UserPromptSubmit", default)]

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

@@ -7,6 +7,7 @@ use codex_config::ConfigLayerStackOrdering;
 use super::ConfiguredHandler;
 use super::config::HookHandlerConfig;
 use super::config::HooksFile;
+use super::config::MatcherGroup;
 use crate::events::common::matcher_pattern_for_event;
 use crate::events::common::validate_matcher_pattern;
 
@@ -70,63 +71,40 @@ pub(crate) fn discover_handlers(config_layer_stack: Option<&ConfigLayerStack>) -
             }
         };
 
-        for group in parsed.hooks.pre_tool_use {
-            append_group_handlers(
-                &mut handlers,
-                &mut warnings,
-                &mut display_order,
-                source_path.as_path(),
+        let super::config::HookEvents {
+            pre_tool_use,
+            post_tool_use,
+            session_start,
+            user_prompt_submit,
+            stop,
+        } = parsed.hooks;
+
+        for (event_name, groups) in [
+            (
                 codex_protocol::protocol::HookEventName::PreToolUse,
-                matcher_pattern_for_event(
-                    codex_protocol::protocol::HookEventName::PreToolUse,
-                    group.matcher.as_deref(),
-                ),
-                group.hooks,
-            );
-        }
-
-        for group in parsed.hooks.session_start {
-            append_group_handlers(
-                &mut handlers,
-                &mut warnings,
-                &mut display_order,
-                source_path.as_path(),
+                pre_tool_use,
+            ),
+            (
+                codex_protocol::protocol::HookEventName::PostToolUse,
+                post_tool_use,
+            ),
+            (
                 codex_protocol::protocol::HookEventName::SessionStart,
-                matcher_pattern_for_event(
-                    codex_protocol::protocol::HookEventName::SessionStart,
-                    group.matcher.as_deref(),
-                ),
-                group.hooks,
-            );
-        }
-
-        for group in parsed.hooks.user_prompt_submit {
-            append_group_handlers(
-                &mut handlers,
-                &mut warnings,
-                &mut display_order,
-                source_path.as_path(),
+                session_start,
+            ),
+            (
                 codex_protocol::protocol::HookEventName::UserPromptSubmit,
-                matcher_pattern_for_event(
-                    codex_protocol::protocol::HookEventName::UserPromptSubmit,
-                    group.matcher.as_deref(),
-                ),
-                group.hooks,
-            );
-        }
-
-        for group in parsed.hooks.stop {
-            append_group_handlers(
+                user_prompt_submit,
+            ),
+            (codex_protocol::protocol::HookEventName::Stop, stop),
+        ] {
+            append_matcher_groups(
                 &mut handlers,
                 &mut warnings,
                 &mut display_order,
                 source_path.as_path(),
-                codex_protocol::protocol::HookEventName::Stop,
-                matcher_pattern_for_event(
-                    codex_protocol::protocol::HookEventName::Stop,
-                    group.matcher.as_deref(),
-                ),
-                group.hooks,
+                event_name,
+                groups,
             );
         }
     }
@@ -199,6 +177,27 @@ fn append_group_handlers(
     }
 }
 
+fn append_matcher_groups(
+    handlers: &mut Vec<ConfiguredHandler>,
+    warnings: &mut Vec<String>,
+    display_order: &mut i64,
+    source_path: &Path,
+    event_name: codex_protocol::protocol::HookEventName,
+    groups: Vec<MatcherGroup>,
+) {
+    for group in groups {
+        append_group_handlers(
+            handlers,
+            warnings,
+            display_order,
+            source_path,
+            event_name,
+            matcher_pattern_for_event(event_name, group.matcher.as_deref()),
+            group.hooks,
+        );
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use std::path::Path;
@@ -309,4 +308,31 @@ mod tests {
         assert_eq!(handlers.len(), 1);
         assert_eq!(handlers[0].matcher.as_deref(), Some("*"));
     }
+
+    #[test]
+    fn post_tool_use_keeps_valid_matcher_during_discovery() {
+        let mut handlers = Vec::new();
+        let mut warnings = Vec::new();
+        let mut display_order = 0;
+
+        append_group_handlers(
+            &mut handlers,
+            &mut warnings,
+            &mut display_order,
+            Path::new("/tmp/hooks.json"),
+            HookEventName::PostToolUse,
+            matcher_pattern_for_event(HookEventName::PostToolUse, Some("Edit|Write")),
+            vec![HookHandlerConfig::Command {
+                command: "echo hello".to_string(),
+                timeout_sec: None,
+                r#async: false,
+                status_message: None,
+            }],
+        );
+
+        assert_eq!(warnings, Vec::<String>::new());
+        assert_eq!(handlers.len(), 1);
+        assert_eq!(handlers[0].event_name, HookEventName::PostToolUse);
+        assert_eq!(handlers[0].matcher.as_deref(), Some("Edit|Write"));
+    }
 }

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

@@ -31,7 +31,9 @@ pub(crate) fn select_handlers(
         .iter()
         .filter(|handler| handler.event_name == event_name)
         .filter(|handler| match event_name {
-            HookEventName::PreToolUse | HookEventName::SessionStart => {
+            HookEventName::PreToolUse
+            | HookEventName::PostToolUse
+            | HookEventName::SessionStart => {
                 matches_matcher(handler.matcher.as_deref(), matcher_input)
             }
             HookEventName::UserPromptSubmit | HookEventName::Stop => true,
@@ -106,9 +108,10 @@ pub(crate) fn completed_summary(
 fn scope_for_event(event_name: HookEventName) -> HookScope {
     match event_name {
         HookEventName::SessionStart => HookScope::Thread,
-        HookEventName::PreToolUse | HookEventName::UserPromptSubmit | HookEventName::Stop => {
-            HookScope::Turn
-        }
+        HookEventName::PreToolUse
+        | HookEventName::PostToolUse
+        | HookEventName::UserPromptSubmit
+        | HookEventName::Stop => HookScope::Turn,
     }
 }
 
@@ -184,6 +187,19 @@ mod tests {
         assert_eq!(selected[0].display_order, 0);
     }
 
+    #[test]
+    fn post_tool_use_matches_tool_name() {
+        let handlers = vec![
+            make_handler(HookEventName::PostToolUse, Some("^Bash$"), "echo same", 0),
+            make_handler(HookEventName::PostToolUse, Some("^Edit$"), "echo same", 1),
+        ];
+
+        let selected = select_handlers(&handlers, HookEventName::PostToolUse, Some("Bash"));
+
+        assert_eq!(selected.len(), 1);
+        assert_eq!(selected[0].display_order, 0);
+    }
+
     #[test]
     fn pre_tool_use_star_matcher_matches_all_tools() {
         let handlers = vec![

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

@@ -10,6 +10,8 @@ use std::path::PathBuf;
 use codex_config::ConfigLayerStack;
 use codex_protocol::protocol::HookRunSummary;
 
+use crate::events::post_tool_use::PostToolUseOutcome;
+use crate::events::post_tool_use::PostToolUseRequest;
 use crate::events::pre_tool_use::PreToolUseOutcome;
 use crate::events::pre_tool_use::PreToolUseRequest;
 use crate::events::session_start::SessionStartOutcome;
@@ -49,6 +51,7 @@ impl ConfiguredHandler {
     fn event_name_label(&self) -> &'static str {
         match self.event_name {
             codex_protocol::protocol::HookEventName::PreToolUse => "pre-tool-use",
+            codex_protocol::protocol::HookEventName::PostToolUse => "post-tool-use",
             codex_protocol::protocol::HookEventName::SessionStart => "session-start",
             codex_protocol::protocol::HookEventName::UserPromptSubmit => "user-prompt-submit",
             codex_protocol::protocol::HookEventName::Stop => "stop",
@@ -112,6 +115,13 @@ impl ClaudeHooksEngine {
         crate::events::pre_tool_use::preview(&self.handlers, request)
     }
 
+    pub(crate) fn preview_post_tool_use(
+        &self,
+        request: &PostToolUseRequest,
+    ) -> Vec<HookRunSummary> {
+        crate::events::post_tool_use::preview(&self.handlers, request)
+    }
+
     pub(crate) async fn run_session_start(
         &self,
         request: SessionStartRequest,
@@ -124,6 +134,13 @@ impl ClaudeHooksEngine {
         crate::events::pre_tool_use::run(&self.handlers, &self.shell, request).await
     }
 
+    pub(crate) async fn run_post_tool_use(
+        &self,
+        request: PostToolUseRequest,
+    ) -> PostToolUseOutcome {
+        crate::events::post_tool_use::run(&self.handlers, &self.shell, request).await
+    }
+
     pub(crate) fn preview_user_prompt_submit(
         &self,
         request: &UserPromptSubmitRequest,

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

@@ -19,6 +19,16 @@ pub(crate) struct PreToolUseOutput {
     pub invalid_reason: Option<String>,
 }
 
+#[derive(Debug, Clone)]
+pub(crate) struct PostToolUseOutput {
+    pub universal: UniversalOutput,
+    pub should_block: bool,
+    pub reason: Option<String>,
+    pub invalid_block_reason: Option<String>,
+    pub additional_context: Option<String>,
+    pub invalid_reason: Option<String>,
+}
+
 #[derive(Debug, Clone)]
 pub(crate) struct UserPromptSubmitOutput {
     pub universal: UniversalOutput,
@@ -38,6 +48,7 @@ pub(crate) struct StopOutput {
 
 use crate::schema::BlockDecisionWire;
 use crate::schema::HookUniversalOutputWire;
+use crate::schema::PostToolUseCommandOutputWire;
 use crate::schema::PreToolUseCommandOutputWire;
 use crate::schema::PreToolUseDecisionWire;
 use crate::schema::PreToolUsePermissionDecisionWire;
@@ -104,6 +115,40 @@ pub(crate) fn parse_pre_tool_use(stdout: &str) -> Option<PreToolUseOutput> {
     })
 }
 
+pub(crate) fn parse_post_tool_use(stdout: &str) -> Option<PostToolUseOutput> {
+    let wire: PostToolUseCommandOutputWire = parse_json(stdout)?;
+    let universal = UniversalOutput::from(wire.universal);
+    let invalid_reason = unsupported_post_tool_use_universal(&universal).or_else(|| {
+        wire.hook_specific_output
+            .as_ref()
+            .and_then(unsupported_post_tool_use_hook_specific_output)
+    });
+    let should_block = matches!(wire.decision, Some(BlockDecisionWire::Block));
+    let invalid_block_reason = if should_block
+        && match wire.reason.as_deref() {
+            Some(reason) => reason.trim().is_empty(),
+            None => true,
+        } {
+        Some(invalid_block_message("PostToolUse"))
+    } else if !should_block && universal.continue_processing && wire.reason.is_some() {
+        Some("PostToolUse hook returned reason without decision".to_string())
+    } else {
+        None
+    };
+    let additional_context = wire
+        .hook_specific_output
+        .and_then(|output| output.additional_context);
+
+    Some(PostToolUseOutput {
+        universal,
+        should_block: should_block && invalid_reason.is_none() && invalid_block_reason.is_none(),
+        reason: wire.reason,
+        invalid_block_reason,
+        additional_context,
+        invalid_reason,
+    })
+}
+
 pub(crate) fn parse_user_prompt_submit(stdout: &str) -> Option<UserPromptSubmitOutput> {
     let wire: UserPromptSubmitCommandOutputWire = parse_json(stdout)?;
     let should_block = matches!(wire.decision, Some(BlockDecisionWire::Block));
@@ -190,6 +235,24 @@ fn unsupported_pre_tool_use_universal(universal: &UniversalOutput) -> Option<Str
     }
 }
 
+fn unsupported_post_tool_use_universal(universal: &UniversalOutput) -> Option<String> {
+    if universal.suppress_output {
+        Some("PostToolUse hook returned unsupported suppressOutput".to_string())
+    } else {
+        None
+    }
+}
+
+fn unsupported_post_tool_use_hook_specific_output(
+    output: &crate::schema::PostToolUseHookSpecificOutputWire,
+) -> Option<String> {
+    if output.updated_mcp_tool_output.is_some() {
+        Some("PostToolUse hook returned unsupported updatedMCPToolOutput".to_string())
+    } else {
+        None
+    }
+}
+
 fn unsupported_pre_tool_use_hook_specific_output(
     output: &crate::schema::PreToolUseHookSpecificOutputWire,
 ) -> Option<String> {

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

@@ -4,6 +4,8 @@ use serde_json::Value;
 
 #[allow(dead_code)]
 pub(crate) struct GeneratedHookSchemas {
+    pub post_tool_use_command_input: Value,
+    pub post_tool_use_command_output: Value,
     pub pre_tool_use_command_input: Value,
     pub pre_tool_use_command_output: Value,
     pub session_start_command_input: Value,
@@ -17,6 +19,14 @@ pub(crate) struct GeneratedHookSchemas {
 pub(crate) fn generated_hook_schemas() -> &'static GeneratedHookSchemas {
     static SCHEMAS: OnceLock<GeneratedHookSchemas> = OnceLock::new();
     SCHEMAS.get_or_init(|| GeneratedHookSchemas {
+        post_tool_use_command_input: parse_json_schema(
+            "post-tool-use.command.input",
+            include_str!("../../schema/generated/post-tool-use.command.input.schema.json"),
+        ),
+        post_tool_use_command_output: parse_json_schema(
+            "post-tool-use.command.output",
+            include_str!("../../schema/generated/post-tool-use.command.output.schema.json"),
+        ),
         pre_tool_use_command_input: parse_json_schema(
             "pre-tool-use.command.input",
             include_str!("../../schema/generated/pre-tool-use.command.input.schema.json"),
@@ -66,6 +76,8 @@ mod tests {
     fn loads_generated_hook_schemas() {
         let schemas = generated_hook_schemas();
 
+        assert_eq!(schemas.post_tool_use_command_input["type"], "object");
+        assert_eq!(schemas.post_tool_use_command_output["type"], "object");
         assert_eq!(schemas.pre_tool_use_command_input["type"], "object");
         assert_eq!(schemas.pre_tool_use_command_output["type"], "object");
         assert_eq!(schemas.session_start_command_input["type"], "object");

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

@@ -74,7 +74,9 @@ pub(crate) fn matcher_pattern_for_event(
     matcher: Option<&str>,
 ) -> Option<&str> {
     match event_name {
-        HookEventName::PreToolUse | HookEventName::SessionStart => matcher,
+        HookEventName::PreToolUse | HookEventName::PostToolUse | HookEventName::SessionStart => {
+            matcher
+        }
         HookEventName::UserPromptSubmit | HookEventName::Stop => None,
     }
 }
@@ -172,6 +174,10 @@ mod tests {
             matcher_pattern_for_event(HookEventName::PreToolUse, Some("Bash")),
             Some("Bash")
         );
+        assert_eq!(
+            matcher_pattern_for_event(HookEventName::PostToolUse, Some("Edit|Write")),
+            Some("Edit|Write")
+        );
         assert_eq!(
             matcher_pattern_for_event(HookEventName::SessionStart, Some("startup|resume")),
             Some("startup|resume")

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

@@ -1,4 +1,5 @@
 pub(crate) mod common;
+pub mod post_tool_use;
 pub mod pre_tool_use;
 pub mod session_start;
 pub mod stop;

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

@@ -0,0 +1,489 @@
+use std::path::PathBuf;
+
+use codex_protocol::ThreadId;
+use codex_protocol::protocol::HookCompletedEvent;
+use codex_protocol::protocol::HookEventName;
+use codex_protocol::protocol::HookOutputEntry;
+use codex_protocol::protocol::HookOutputEntryKind;
+use codex_protocol::protocol::HookRunStatus;
+use codex_protocol::protocol::HookRunSummary;
+use serde_json::Value;
+
+use super::common;
+use crate::engine::CommandShell;
+use crate::engine::ConfiguredHandler;
+use crate::engine::command_runner::CommandRunResult;
+use crate::engine::dispatcher;
+use crate::engine::output_parser;
+use crate::schema::PostToolUseCommandInput;
+use crate::schema::PostToolUseToolInput;
+
+#[derive(Debug, Clone)]
+pub struct PostToolUseRequest {
+    pub session_id: ThreadId,
+    pub turn_id: String,
+    pub cwd: PathBuf,
+    pub transcript_path: Option<PathBuf>,
+    pub model: String,
+    pub permission_mode: String,
+    pub tool_name: String,
+    pub tool_use_id: String,
+    pub command: String,
+    pub tool_response: Value,
+}
+
+#[derive(Debug)]
+pub struct PostToolUseOutcome {
+    pub hook_events: Vec<HookCompletedEvent>,
+    pub should_stop: bool,
+    pub stop_reason: Option<String>,
+    pub additional_contexts: Vec<String>,
+    pub feedback_message: Option<String>,
+}
+
+#[derive(Debug, Default, PartialEq, Eq)]
+struct PostToolUseHandlerData {
+    should_stop: bool,
+    stop_reason: Option<String>,
+    additional_contexts_for_model: Vec<String>,
+    feedback_messages_for_model: Vec<String>,
+}
+
+pub(crate) fn preview(
+    handlers: &[ConfiguredHandler],
+    request: &PostToolUseRequest,
+) -> Vec<HookRunSummary> {
+    dispatcher::select_handlers(
+        handlers,
+        HookEventName::PostToolUse,
+        Some(&request.tool_name),
+    )
+    .into_iter()
+    .map(|handler| dispatcher::running_summary(&handler))
+    .collect()
+}
+
+pub(crate) async fn run(
+    handlers: &[ConfiguredHandler],
+    shell: &CommandShell,
+    request: PostToolUseRequest,
+) -> PostToolUseOutcome {
+    let matched = dispatcher::select_handlers(
+        handlers,
+        HookEventName::PostToolUse,
+        Some(&request.tool_name),
+    );
+    if matched.is_empty() {
+        return PostToolUseOutcome {
+            hook_events: Vec::new(),
+            should_stop: false,
+            stop_reason: None,
+            additional_contexts: Vec::new(),
+            feedback_message: None,
+        };
+    }
+
+    let input_json = match serde_json::to_string(&PostToolUseCommandInput {
+        session_id: request.session_id.to_string(),
+        turn_id: request.turn_id.clone(),
+        transcript_path: crate::schema::NullableString::from_path(request.transcript_path.clone()),
+        cwd: request.cwd.display().to_string(),
+        hook_event_name: "PostToolUse".to_string(),
+        model: request.model.clone(),
+        permission_mode: request.permission_mode.clone(),
+        tool_name: "Bash".to_string(),
+        tool_input: PostToolUseToolInput {
+            command: request.command.clone(),
+        },
+        tool_response: request.tool_response.clone(),
+        tool_use_id: request.tool_use_id.clone(),
+    }) {
+        Ok(input_json) => input_json,
+        Err(error) => {
+            return serialization_failure_outcome(common::serialization_failure_hook_events(
+                matched,
+                Some(request.turn_id),
+                format!("failed to serialize post tool use hook input: {error}"),
+            ));
+        }
+    };
+
+    let results = dispatcher::execute_handlers(
+        shell,
+        matched,
+        input_json,
+        request.cwd.as_path(),
+        Some(request.turn_id),
+        parse_completed,
+    )
+    .await;
+
+    let additional_contexts = common::flatten_additional_contexts(
+        results
+            .iter()
+            .map(|result| result.data.additional_contexts_for_model.as_slice()),
+    );
+    let should_stop = results.iter().any(|result| result.data.should_stop);
+    let stop_reason = results
+        .iter()
+        .find_map(|result| result.data.stop_reason.clone());
+    let feedback_message = common::join_text_chunks(
+        results
+            .iter()
+            .flat_map(|result| result.data.feedback_messages_for_model.clone())
+            .collect(),
+    );
+
+    PostToolUseOutcome {
+        hook_events: results.into_iter().map(|result| result.completed).collect(),
+        should_stop,
+        stop_reason,
+        additional_contexts,
+        feedback_message,
+    }
+}
+
+fn parse_completed(
+    handler: &ConfiguredHandler,
+    run_result: CommandRunResult,
+    turn_id: Option<String>,
+) -> dispatcher::ParsedHandler<PostToolUseHandlerData> {
+    let mut entries = Vec::new();
+    let mut status = HookRunStatus::Completed;
+    let mut should_stop = false;
+    let mut stop_reason = None;
+    let mut additional_contexts_for_model = Vec::new();
+    let mut feedback_messages_for_model = Vec::new();
+
+    match run_result.error.as_deref() {
+        Some(error) => {
+            status = HookRunStatus::Failed;
+            entries.push(HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: error.to_string(),
+            });
+        }
+        None => match run_result.exit_code {
+            Some(0) => {
+                let trimmed_stdout = run_result.stdout.trim();
+                if trimmed_stdout.is_empty() {
+                } else if let Some(parsed) = output_parser::parse_post_tool_use(&run_result.stdout)
+                {
+                    if let Some(system_message) = parsed.universal.system_message {
+                        entries.push(HookOutputEntry {
+                            kind: HookOutputEntryKind::Warning,
+                            text: system_message,
+                        });
+                    }
+                    if parsed.invalid_reason.is_none()
+                        && parsed.invalid_block_reason.is_none()
+                        && let Some(additional_context) = parsed.additional_context
+                    {
+                        common::append_additional_context(
+                            &mut entries,
+                            &mut additional_contexts_for_model,
+                            additional_context,
+                        );
+                    }
+                    if !parsed.universal.continue_processing {
+                        status = HookRunStatus::Stopped;
+                        should_stop = true;
+                        stop_reason = parsed.universal.stop_reason.clone();
+                        let stop_text = parsed
+                            .universal
+                            .stop_reason
+                            .unwrap_or_else(|| "PostToolUse hook stopped execution".to_string());
+                        entries.push(HookOutputEntry {
+                            kind: HookOutputEntryKind::Stop,
+                            text: stop_text.clone(),
+                        });
+                        let model_feedback = parsed
+                            .reason
+                            .as_deref()
+                            .and_then(common::trimmed_non_empty)
+                            .unwrap_or(stop_text);
+                        feedback_messages_for_model.push(model_feedback);
+                    } else if let Some(invalid_reason) = parsed.invalid_reason {
+                        status = HookRunStatus::Failed;
+                        entries.push(HookOutputEntry {
+                            kind: HookOutputEntryKind::Error,
+                            text: invalid_reason,
+                        });
+                    } else if let Some(invalid_block_reason) = parsed.invalid_block_reason {
+                        status = HookRunStatus::Failed;
+                        entries.push(HookOutputEntry {
+                            kind: HookOutputEntryKind::Error,
+                            text: invalid_block_reason,
+                        });
+                    } else if parsed.should_block {
+                        status = HookRunStatus::Blocked;
+                        if let Some(reason) = parsed.reason {
+                            entries.push(HookOutputEntry {
+                                kind: HookOutputEntryKind::Feedback,
+                                text: reason.clone(),
+                            });
+                            feedback_messages_for_model.push(reason);
+                        }
+                    }
+                } else if trimmed_stdout.starts_with('{') || trimmed_stdout.starts_with('[') {
+                    status = HookRunStatus::Failed;
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Error,
+                        text: "hook returned invalid post-tool-use JSON output".to_string(),
+                    });
+                }
+            }
+            Some(2) => {
+                if let Some(reason) = common::trimmed_non_empty(&run_result.stderr) {
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Feedback,
+                        text: reason.clone(),
+                    });
+                    feedback_messages_for_model.push(reason);
+                } else {
+                    status = HookRunStatus::Failed;
+                    entries.push(HookOutputEntry {
+                        kind: HookOutputEntryKind::Error,
+                        text: "PostToolUse hook exited with code 2 but did not write feedback to stderr".to_string(),
+                    });
+                }
+            }
+            Some(exit_code) => {
+                status = HookRunStatus::Failed;
+                entries.push(HookOutputEntry {
+                    kind: HookOutputEntryKind::Error,
+                    text: format!("hook exited with code {exit_code}"),
+                });
+            }
+            None => {
+                status = HookRunStatus::Failed;
+                entries.push(HookOutputEntry {
+                    kind: HookOutputEntryKind::Error,
+                    text: "hook exited without a status code".to_string(),
+                });
+            }
+        },
+    }
+
+    let completed = HookCompletedEvent {
+        turn_id,
+        run: dispatcher::completed_summary(handler, &run_result, status, entries),
+    };
+
+    dispatcher::ParsedHandler {
+        completed,
+        data: PostToolUseHandlerData {
+            should_stop,
+            stop_reason,
+            additional_contexts_for_model,
+            feedback_messages_for_model,
+        },
+    }
+}
+
+fn serialization_failure_outcome(hook_events: Vec<HookCompletedEvent>) -> PostToolUseOutcome {
+    PostToolUseOutcome {
+        hook_events,
+        should_stop: false,
+        stop_reason: None,
+        additional_contexts: Vec::new(),
+        feedback_message: None,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use std::path::PathBuf;
+
+    use codex_protocol::protocol::HookEventName;
+    use codex_protocol::protocol::HookOutputEntry;
+    use codex_protocol::protocol::HookOutputEntryKind;
+    use codex_protocol::protocol::HookRunStatus;
+    use pretty_assertions::assert_eq;
+
+    use super::PostToolUseHandlerData;
+    use super::parse_completed;
+    use crate::engine::ConfiguredHandler;
+    use crate::engine::command_runner::CommandRunResult;
+
+    #[test]
+    fn block_decision_stops_normal_processing() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"decision":"block","reason":"bash output looked sketchy"}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PostToolUseHandlerData {
+                should_stop: false,
+                stop_reason: None,
+                additional_contexts_for_model: Vec::new(),
+                feedback_messages_for_model: vec!["bash output looked sketchy".to_string()],
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Blocked);
+    }
+
+    #[test]
+    fn additional_context_is_recorded() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"Remember the bash cleanup note."}}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PostToolUseHandlerData {
+                should_stop: false,
+                stop_reason: None,
+                additional_contexts_for_model: vec!["Remember the bash cleanup note.".to_string()],
+                feedback_messages_for_model: Vec::new(),
+            }
+        );
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Context,
+                text: "Remember the bash cleanup note.".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn unsupported_updated_mcp_tool_output_fails_open() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"hookSpecificOutput":{"hookEventName":"PostToolUse","updatedMCPToolOutput":{"ok":true}}}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PostToolUseHandlerData {
+                should_stop: false,
+                stop_reason: None,
+                additional_contexts_for_model: Vec::new(),
+                feedback_messages_for_model: Vec::new(),
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Failed);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Error,
+                text: "PostToolUse hook returned unsupported updatedMCPToolOutput".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn exit_two_surfaces_feedback_to_model_without_blocking() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(2), "", "post hook says pause"),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PostToolUseHandlerData {
+                should_stop: false,
+                stop_reason: None,
+                additional_contexts_for_model: Vec::new(),
+                feedback_messages_for_model: vec!["post hook says pause".to_string()],
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Completed);
+    }
+
+    #[test]
+    fn continue_false_stops_with_reason() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(
+                Some(0),
+                r#"{"continue":false,"stopReason":"halt after bash output","reason":"post-tool hook says stop"}"#,
+                "",
+            ),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PostToolUseHandlerData {
+                should_stop: true,
+                stop_reason: Some("halt after bash output".to_string()),
+                additional_contexts_for_model: Vec::new(),
+                feedback_messages_for_model: vec!["post-tool hook says stop".to_string()],
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Stopped);
+        assert_eq!(
+            parsed.completed.run.entries,
+            vec![HookOutputEntry {
+                kind: HookOutputEntryKind::Stop,
+                text: "halt after bash output".to_string(),
+            }]
+        );
+    }
+
+    #[test]
+    fn plain_stdout_is_ignored_for_post_tool_use() {
+        let parsed = parse_completed(
+            &handler(),
+            run_result(Some(0), "plain text only", ""),
+            Some("turn-1".to_string()),
+        );
+
+        assert_eq!(
+            parsed.data,
+            PostToolUseHandlerData {
+                should_stop: false,
+                stop_reason: None,
+                additional_contexts_for_model: Vec::new(),
+                feedback_messages_for_model: Vec::new(),
+            }
+        );
+        assert_eq!(parsed.completed.run.status, HookRunStatus::Completed);
+        assert_eq!(parsed.completed.run.entries, Vec::<HookOutputEntry>::new());
+    }
+
+    fn handler() -> ConfiguredHandler {
+        ConfiguredHandler {
+            event_name: HookEventName::PostToolUse,
+            matcher: Some("^Bash$".to_string()),
+            command: "python3 post_tool_use_hook.py".to_string(),
+            timeout_sec: 5,
+            status_message: Some("running post tool use hook".to_string()),
+            source_path: PathBuf::from("/tmp/hooks.json"),
+            display_order: 0,
+        }
+    }
+
+    fn run_result(exit_code: Option<i32>, stdout: &str, stderr: &str) -> CommandRunResult {
+        CommandRunResult {
+            started_at: 1_700_000_000,
+            completed_at: 1_700_000_001,
+            duration_ms: 12,
+            exit_code,
+            stdout: stdout.to_string(),
+            stderr: stderr.to_string(),
+            error: None,
+        }
+    }
+}

codex-rs/hooks/src/lib.rs

@@ -5,6 +5,8 @@ mod registry;
 mod schema;
 mod types;
 
+pub use events::post_tool_use::PostToolUseOutcome;
+pub use events::post_tool_use::PostToolUseRequest;
 pub use events::pre_tool_use::PreToolUseOutcome;
 pub use events::pre_tool_use::PreToolUseRequest;
 pub use events::session_start::SessionStartOutcome;

codex-rs/hooks/src/registry.rs

@@ -3,6 +3,8 @@ use tokio::process::Command;
 
 use crate::engine::ClaudeHooksEngine;
 use crate::engine::CommandShell;
+use crate::events::post_tool_use::PostToolUseOutcome;
+use crate::events::post_tool_use::PostToolUseRequest;
 use crate::events::pre_tool_use::PreToolUseOutcome;
 use crate::events::pre_tool_use::PreToolUseRequest;
 use crate::events::session_start::SessionStartOutcome;
@@ -101,6 +103,13 @@ impl Hooks {
         self.engine.preview_pre_tool_use(request)
     }
 
+    pub fn preview_post_tool_use(
+        &self,
+        request: &PostToolUseRequest,
+    ) -> Vec<codex_protocol::protocol::HookRunSummary> {
+        self.engine.preview_post_tool_use(request)
+    }
+
     pub async fn run_session_start(
         &self,
         request: SessionStartRequest,
@@ -113,6 +122,10 @@ impl Hooks {
         self.engine.run_pre_tool_use(request).await
     }
 
+    pub async fn run_post_tool_use(&self, request: PostToolUseRequest) -> PostToolUseOutcome {
+        self.engine.run_post_tool_use(request).await
+    }
+
     pub fn preview_user_prompt_submit(
         &self,
         request: &UserPromptSubmitRequest,

codex-rs/hooks/src/schema.rs

@@ -13,6 +13,8 @@ use std::path::Path;
 use std::path::PathBuf;
 
 const GENERATED_DIR: &str = "generated";
+const POST_TOOL_USE_INPUT_FIXTURE: &str = "post-tool-use.command.input.schema.json";
+const POST_TOOL_USE_OUTPUT_FIXTURE: &str = "post-tool-use.command.output.schema.json";
 const PRE_TOOL_USE_INPUT_FIXTURE: &str = "pre-tool-use.command.input.schema.json";
 const PRE_TOOL_USE_OUTPUT_FIXTURE: &str = "pre-tool-use.command.output.schema.json";
 const SESSION_START_INPUT_FIXTURE: &str = "session-start.command.input.schema.json";
@@ -67,6 +69,8 @@ pub(crate) struct HookUniversalOutputWire {
 pub(crate) enum HookEventNameWire {
     #[serde(rename = "PreToolUse")]
     PreToolUse,
+    #[serde(rename = "PostToolUse")]
+    PostToolUse,
     #[serde(rename = "SessionStart")]
     SessionStart,
     #[serde(rename = "UserPromptSubmit")]
@@ -90,6 +94,33 @@ pub(crate) struct PreToolUseCommandOutputWire {
     pub hook_specific_output: Option<PreToolUseHookSpecificOutputWire>,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "post-tool-use.command.output")]
+pub(crate) struct PostToolUseCommandOutputWire {
+    #[serde(flatten)]
+    pub universal: HookUniversalOutputWire,
+    #[serde(default)]
+    pub decision: Option<BlockDecisionWire>,
+    #[serde(default)]
+    pub reason: Option<String>,
+    #[serde(default)]
+    pub hook_specific_output: Option<PostToolUseHookSpecificOutputWire>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+pub(crate) struct PostToolUseHookSpecificOutputWire {
+    pub hook_event_name: HookEventNameWire,
+    #[serde(default)]
+    pub additional_context: Option<String>,
+    #[serde(default)]
+    #[serde(rename = "updatedMCPToolOutput")]
+    pub updated_mcp_tool_output: Option<Value>,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
 #[serde(rename_all = "camelCase")]
 #[serde(deny_unknown_fields)]
@@ -150,6 +181,34 @@ pub(crate) struct PreToolUseCommandInput {
     pub tool_use_id: String,
 }
 
+#[derive(Debug, Clone, Serialize, JsonSchema)]
+#[serde(rename_all = "camelCase")]
+#[serde(deny_unknown_fields)]
+pub(crate) struct PostToolUseToolInput {
+    pub command: String,
+}
+
+#[derive(Debug, Clone, Serialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+#[schemars(rename = "post-tool-use.command.input")]
+pub(crate) struct PostToolUseCommandInput {
+    pub session_id: String,
+    /// Codex extension: expose the active turn id to internal turn-scoped hooks.
+    pub turn_id: String,
+    pub transcript_path: NullableString,
+    pub cwd: String,
+    #[schemars(schema_with = "post_tool_use_hook_event_name_schema")]
+    pub hook_event_name: String,
+    pub model: String,
+    #[schemars(schema_with = "permission_mode_schema")]
+    pub permission_mode: String,
+    #[schemars(schema_with = "post_tool_use_tool_name_schema")]
+    pub tool_name: String,
+    pub tool_input: PostToolUseToolInput,
+    pub tool_response: Value,
+    pub tool_use_id: String,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
 #[serde(rename_all = "camelCase")]
 #[serde(deny_unknown_fields)]
@@ -291,6 +350,14 @@ pub fn write_schema_fixtures(schema_root: &Path) -> anyhow::Result<()> {
     let generated_dir = schema_root.join(GENERATED_DIR);
     ensure_empty_dir(&generated_dir)?;
 
+    write_schema(
+        &generated_dir.join(POST_TOOL_USE_INPUT_FIXTURE),
+        schema_json::<PostToolUseCommandInput>()?,
+    )?;
+    write_schema(
+        &generated_dir.join(POST_TOOL_USE_OUTPUT_FIXTURE),
+        schema_json::<PostToolUseCommandOutputWire>()?,
+    )?;
     write_schema(
         &generated_dir.join(PRE_TOOL_USE_INPUT_FIXTURE),
         schema_json::<PreToolUseCommandInput>()?,
@@ -382,6 +449,14 @@ fn session_start_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema {
     string_const_schema("SessionStart")
 }
 
+fn post_tool_use_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema {
+    string_const_schema("PostToolUse")
+}
+
+fn post_tool_use_tool_name_schema(_gen: &mut SchemaGenerator) -> Schema {
+    string_const_schema("Bash")
+}
+
 fn pre_tool_use_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema {
     string_const_schema("PreToolUse")
 }
@@ -441,8 +516,11 @@ fn default_continue() -> bool {
 
 #[cfg(test)]
 mod tests {
+    use super::POST_TOOL_USE_INPUT_FIXTURE;
+    use super::POST_TOOL_USE_OUTPUT_FIXTURE;
     use super::PRE_TOOL_USE_INPUT_FIXTURE;
     use super::PRE_TOOL_USE_OUTPUT_FIXTURE;
+    use super::PostToolUseCommandInput;
     use super::PreToolUseCommandInput;
     use super::SESSION_START_INPUT_FIXTURE;
     use super::SESSION_START_OUTPUT_FIXTURE;
@@ -460,6 +538,12 @@ mod tests {
 
     fn expected_fixture(name: &str) -> &'static str {
         match name {
+            POST_TOOL_USE_INPUT_FIXTURE => {
+                include_str!("../schema/generated/post-tool-use.command.input.schema.json")
+            }
+            POST_TOOL_USE_OUTPUT_FIXTURE => {
+                include_str!("../schema/generated/post-tool-use.command.output.schema.json")
+            }
             PRE_TOOL_USE_INPUT_FIXTURE => {
                 include_str!("../schema/generated/pre-tool-use.command.input.schema.json")
             }
@@ -499,6 +583,8 @@ mod tests {
         write_schema_fixtures(&schema_root).expect("write generated hook schemas");
 
         for fixture in [
+            POST_TOOL_USE_INPUT_FIXTURE,
+            POST_TOOL_USE_OUTPUT_FIXTURE,
             PRE_TOOL_USE_INPUT_FIXTURE,
             PRE_TOOL_USE_OUTPUT_FIXTURE,
             SESSION_START_INPUT_FIXTURE,
@@ -524,6 +610,11 @@ mod tests {
             &schema_json::<PreToolUseCommandInput>().expect("serialize pre tool use input schema"),
         )
         .expect("parse pre tool use input schema");
+        let post_tool_use: Value = serde_json::from_slice(
+            &schema_json::<PostToolUseCommandInput>()
+                .expect("serialize post tool use input schema"),
+        )
+        .expect("parse post tool use input schema");
         let user_prompt_submit: Value = serde_json::from_slice(
             &schema_json::<UserPromptSubmitCommandInput>()
                 .expect("serialize user prompt submit input schema"),
@@ -534,7 +625,7 @@ mod tests {
         )
         .expect("parse stop input schema");
 
-        for schema in [&pre_tool_use, &user_prompt_submit, &stop] {
+        for schema in [&pre_tool_use, &post_tool_use, &user_prompt_submit, &stop] {
             assert_eq!(schema["properties"]["turn_id"]["type"], "string");
             assert!(
                 schema["required"]