Add SubagentStop hook

codex-rs/analytics/src/events.rs

@@ -991,6 +991,7 @@ fn analytics_hook_event_name(event_name: HookEventName) -> &'static str {
         HookEventName::SessionStart => "SessionStart",
         HookEventName::UserPromptSubmit => "UserPromptSubmit",
         HookEventName::SubagentStart => "SubagentStart",
+        HookEventName::SubagentStop => "SubagentStop",
         HookEventName::Stop => "Stop",
     }
 }

codex-rs/app-server-protocol/src/protocol/v2/config.rs

@@ -426,6 +426,9 @@ pub struct ManagedHooksRequirements {
     #[serde(rename = "SubagentStart")]
     #[ts(rename = "SubagentStart")]
     pub subagent_start: Vec<ConfiguredHookMatcherGroup>,
+    #[serde(rename = "SubagentStop")]
+    #[ts(rename = "SubagentStop")]
+    pub subagent_stop: Vec<ConfiguredHookMatcherGroup>,
     #[serde(rename = "Stop")]
     #[ts(rename = "Stop")]
     pub stop: Vec<ConfiguredHookMatcherGroup>,

codex-rs/app-server-protocol/src/protocol/v2/hook.rs

@@ -17,7 +17,7 @@ use ts_rs::TS;
 
 v2_enum_from_core!(
     pub enum HookEventName from CoreHookEventName {
-        PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SessionStart, UserPromptSubmit, SubagentStart, Stop
+        PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, SessionStart, UserPromptSubmit, SubagentStart, SubagentStop, Stop
     }
 );
 

codex-rs/app-server/src/request_processors/config_processor.rs

@@ -455,6 +455,7 @@ fn map_hooks_requirements_to_api(hooks: ManagedHooksRequirementsToml) -> Managed
         session_start,
         user_prompt_submit,
         subagent_start,
+        subagent_stop,
         stop,
     } = hooks;
 
@@ -469,6 +470,7 @@ fn map_hooks_requirements_to_api(hooks: ManagedHooksRequirementsToml) -> Managed
         session_start: map_hook_matcher_groups_to_api(session_start),
         user_prompt_submit: map_hook_matcher_groups_to_api(user_prompt_submit),
         subagent_start: map_hook_matcher_groups_to_api(subagent_start),
+        subagent_stop: map_hook_matcher_groups_to_api(subagent_stop),
         stop: map_hook_matcher_groups_to_api(stop),
     }
 }

codex-rs/config/src/hook_config.rs

@@ -47,6 +47,8 @@ pub struct HookEventsToml {
     pub user_prompt_submit: Vec<MatcherGroup>,
     #[serde(rename = "SubagentStart", default)]
     pub subagent_start: Vec<MatcherGroup>,
+    #[serde(rename = "SubagentStop", default)]
+    pub subagent_stop: Vec<MatcherGroup>,
     #[serde(rename = "Stop", default)]
     pub stop: Vec<MatcherGroup>,
 }
@@ -62,6 +64,7 @@ impl HookEventsToml {
             session_start,
             user_prompt_submit,
             subagent_start,
+            subagent_stop,
             stop,
         } = self;
         pre_tool_use.is_empty()
@@ -72,6 +75,7 @@ impl HookEventsToml {
             && session_start.is_empty()
             && user_prompt_submit.is_empty()
             && subagent_start.is_empty()
+            && subagent_stop.is_empty()
             && stop.is_empty()
     }
 
@@ -85,6 +89,7 @@ impl HookEventsToml {
             session_start,
             user_prompt_submit,
             subagent_start,
+            subagent_stop,
             stop,
         } = self;
         [
@@ -96,6 +101,7 @@ impl HookEventsToml {
             session_start,
             user_prompt_submit,
             subagent_start,
+            subagent_stop,
             stop,
         ]
         .into_iter()
@@ -104,7 +110,7 @@ impl HookEventsToml {
         .sum()
     }
 
-    pub fn into_matcher_groups(self) -> [(HookEventName, Vec<MatcherGroup>); 9] {
+    pub fn into_matcher_groups(self) -> [(HookEventName, Vec<MatcherGroup>); 10] {
         [
             (HookEventName::PreToolUse, self.pre_tool_use),
             (HookEventName::PermissionRequest, self.permission_request),
@@ -114,6 +120,7 @@ impl HookEventsToml {
             (HookEventName::SessionStart, self.session_start),
             (HookEventName::UserPromptSubmit, self.user_prompt_submit),
             (HookEventName::SubagentStart, self.subagent_start),
+            (HookEventName::SubagentStop, self.subagent_stop),
             (HookEventName::Stop, self.stop),
         ]
     }

codex-rs/core/config.schema.json

@@ -1129,6 +1129,13 @@
           },
           "type": "array"
         },
+        "SubagentStop": {
+          "default": [],
+          "items": {
+            "$ref": "#/definitions/MatcherGroup"
+          },
+          "type": "array"
+        },
         "UserPromptSubmit": {
           "default": [],
           "items": {

codex-rs/core/src/hook_runtime.rs

@@ -14,8 +14,8 @@ use codex_hooks::PreToolUseOutcome;
 use codex_hooks::PreToolUseRequest;
 use codex_hooks::SessionStartOutcome;
 use codex_hooks::StartHookTarget;
+use codex_hooks::StopHookTarget;
 use codex_hooks::StopOutcome;
-use codex_hooks::StopRequest;
 use codex_hooks::UserPromptSubmitOutcome;
 use codex_hooks::UserPromptSubmitRequest;
 use codex_otel::HOOK_RUN_DURATION_METRIC;
@@ -33,6 +33,7 @@ use codex_protocol::protocol::HookSource;
 use codex_protocol::protocol::HookStartedEvent;
 use codex_protocol::protocol::SessionSource;
 use codex_protocol::protocol::SubAgentSource;
+use codex_thread_store::ReadThreadParams;
 use serde_json::Value;
 
 use crate::context::ContextualUserFragment;
@@ -285,6 +286,78 @@ pub(crate) async fn run_post_tool_use_hooks(
     outcome
 }
 
+pub(crate) async fn run_turn_stop_hooks(
+    sess: &Arc<Session>,
+    turn_context: &Arc<TurnContext>,
+    stop_hook_active: bool,
+    last_assistant_message: Option<String>,
+) -> StopOutcome {
+    // Resolve the stop hook kind from the session source before building the
+    // request. Root turns run Stop; thread-spawned child turns run SubagentStop.
+    let (target, transcript_path) = match &turn_context.session_source {
+        SessionSource::SubAgent(SubAgentSource::ThreadSpawn {
+            agent_role,
+            parent_thread_id,
+            ..
+        }) => {
+            let agent_type = agent_role
+                .clone()
+                .unwrap_or_else(|| crate::agent::role::DEFAULT_ROLE_NAME.to_string());
+            let agent_transcript_path = sess.hook_transcript_path().await;
+            let parent_transcript_path = match sess
+                .services
+                .thread_store
+                .read_thread(ReadThreadParams {
+                    thread_id: *parent_thread_id,
+                    include_archived: true,
+                    include_history: false,
+                })
+                .await
+            {
+                Ok(thread) => thread.rollout_path,
+                Err(error) => {
+                    tracing::warn!(
+                        parent_thread_id = %parent_thread_id,
+                        error = %error,
+                        "failed to resolve parent transcript path for subagent hook"
+                    );
+                    None
+                }
+            };
+            (
+                StopHookTarget::SubagentStop {
+                    agent_id: sess.thread_id().to_string(),
+                    agent_type,
+                    agent_transcript_path,
+                },
+                parent_transcript_path,
+            )
+        }
+        // Internal/synthetic subagents do not expose user-configured lifecycle
+        // hooks, so there is no Stop or SubagentStop request to dispatch.
+        SessionSource::SubAgent(_) => return StopOutcome::default(),
+        _ => (StopHookTarget::Stop, sess.hook_transcript_path().await),
+    };
+    let request = codex_hooks::StopRequest {
+        session_id: sess.session_id().into(),
+        turn_id: turn_context.sub_id.clone(),
+        #[allow(deprecated)]
+        cwd: turn_context.cwd.clone(),
+        transcript_path,
+        model: turn_context.model_info.slug.clone(),
+        permission_mode: hook_permission_mode(turn_context),
+        stop_hook_active,
+        last_assistant_message,
+        target,
+    };
+    let hooks = sess.hooks();
+    emit_hook_started_events(sess, turn_context, hooks.preview_stop(&request)).await;
+
+    let mut outcome = hooks.run_stop(request).await;
+    emit_hook_completed_events(sess, turn_context, std::mem::take(&mut outcome.hook_events)).await;
+    outcome
+}
+
 pub(crate) async fn run_pre_compact_hooks(
     sess: &Arc<Session>,
     turn_context: &Arc<TurnContext>,
@@ -349,30 +422,6 @@ pub(crate) async fn run_post_compact_hooks(
     }
 }
 
-pub(crate) async fn run_stop_hooks(
-    sess: &Arc<Session>,
-    turn_context: &Arc<TurnContext>,
-    stop_hook_active: bool,
-    last_assistant_message: Option<String>,
-) -> StopOutcome {
-    let request = StopRequest {
-        session_id: sess.session_id().into(),
-        turn_id: turn_context.sub_id.clone(),
-        #[allow(deprecated)]
-        cwd: turn_context.cwd.clone(),
-        transcript_path: sess.hook_transcript_path().await,
-        model: turn_context.model_info.slug.clone(),
-        permission_mode: hook_permission_mode(turn_context),
-        stop_hook_active,
-        last_assistant_message,
-    };
-    let hooks = sess.hooks();
-    emit_hook_started_events(sess, turn_context, hooks.preview_stop(&request)).await;
-    let mut outcome = hooks.run_stop(request).await;
-    emit_hook_completed_events(sess, turn_context, std::mem::take(&mut outcome.hook_events)).await;
-    outcome
-}
-
 pub(crate) async fn run_legacy_after_agent_hook(
     sess: &Arc<Session>,
     turn_context: &Arc<TurnContext>,
@@ -635,6 +684,7 @@ fn hook_run_metric_tags(run: &HookRunSummary) -> [(&'static str, &'static str);
         HookEventName::SessionStart => "SessionStart",
         HookEventName::UserPromptSubmit => "UserPromptSubmit",
         HookEventName::SubagentStart => "SubagentStart",
+        HookEventName::SubagentStop => "SubagentStop",
         HookEventName::Stop => "Stop",
     };
     let hook_source = match run.source {

codex-rs/core/src/session/turn.rs

@@ -23,7 +23,7 @@ use crate::hook_runtime::record_additional_contexts;
 use crate::hook_runtime::record_pending_input;
 use crate::hook_runtime::run_legacy_after_agent_hook;
 use crate::hook_runtime::run_pending_session_start_hooks;
-use crate::hook_runtime::run_stop_hooks;
+use crate::hook_runtime::run_turn_stop_hooks;
 use crate::injection::ToolMentionKind;
 use crate::injection::app_id_from_path;
 use crate::injection::tool_kind_for_path;
@@ -360,7 +360,7 @@ pub(crate) async fn run_turn(
 
                 if !needs_follow_up {
                     last_agent_message = sampling_request_last_agent_message;
-                    let stop_outcome = run_stop_hooks(
+                    let stop_outcome = run_turn_stop_hooks(
                         &sess,
                         &turn_context,
                         stop_hook_active,