From 48110f91dcd319e67bcef39b4f87a6893edf8634 Mon Sep 17 00:00:00 2001 From: Abhinav Vedmala Date: Fri, 15 May 2026 18:01:57 +0000 Subject: [PATCH] Add SubagentStop hook --- codex-rs/analytics/src/events.rs | 1 + .../schema/json/ServerNotification.json | 1 + .../codex_app_server_protocol.schemas.json | 8 + .../codex_app_server_protocol.v2.schemas.json | 8 + .../v2/ConfigRequirementsReadResponse.json | 7 + .../json/v2/HookCompletedNotification.json | 1 + .../json/v2/HookStartedNotification.json | 1 + .../schema/json/v2/HooksListResponse.json | 1 + .../schema/json/v2/PluginReadResponse.json | 1 + .../schema/typescript/v2/HookEventName.ts | 2 +- .../typescript/v2/ManagedHooksRequirements.ts | 2 +- .../src/protocol/v2/config.rs | 3 + .../src/protocol/v2/hook.rs | 2 +- .../request_processors/config_processor.rs | 2 + codex-rs/config/src/hook_config.rs | 9 +- codex-rs/core/config.schema.json | 7 + codex-rs/core/src/hook_runtime.rs | 70 ++++ codex-rs/core/src/session/turn.rs | 41 +-- .../tests/suite/subagent_notifications.rs | 306 +++++++++++++++++- ...mission-request.command.output.schema.json | 1 + .../post-tool-use.command.output.schema.json | 1 + .../pre-tool-use.command.output.schema.json | 1 + .../session-start.command.output.schema.json | 1 + .../subagent-start.command.output.schema.json | 1 + .../subagent-stop.command.input.schema.json | 75 +++++ .../subagent-stop.command.output.schema.json | 45 +++ ...r-prompt-submit.command.output.schema.json | 1 + codex-rs/hooks/src/engine/dispatcher.rs | 2 + codex-rs/hooks/src/engine/mod.rs | 1 + codex-rs/hooks/src/engine/output_parser.rs | 39 ++- codex-rs/hooks/src/engine/schema_loader.rs | 12 + codex-rs/hooks/src/events/common.rs | 1 + codex-rs/hooks/src/events/stop.rs | 197 +++++++++-- codex-rs/hooks/src/lib.rs | 8 +- codex-rs/hooks/src/schema.rs | 69 ++++ codex-rs/protocol/src/protocol.rs | 1 + .../tui/src/bottom_pane/hooks_browser_view.rs | 2 + ...ser_view__tests__hooks_browser_events.snap | 1 + ...sts__hooks_browser_events_with_issues.snap | 1 + ...oks_browser_events_with_review_column.snap | 1 + ...s__hooks_popup_shows_list_diagnostics.snap | 1 + codex-rs/tui/src/chatwidget/tests/helpers.rs | 1 + codex-rs/tui/src/history_cell/hook_cell.rs | 1 + 43 files changed, 853 insertions(+), 84 deletions(-) create mode 100644 codex-rs/hooks/schema/generated/subagent-stop.command.input.schema.json create mode 100644 codex-rs/hooks/schema/generated/subagent-stop.command.output.schema.json diff --git a/codex-rs/analytics/src/events.rs b/codex-rs/analytics/src/events.rs index f7c64e0e74..87cb165ac2 100644 --- a/codex-rs/analytics/src/events.rs +++ b/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", } } diff --git a/codex-rs/app-server-protocol/schema/json/ServerNotification.json b/codex-rs/app-server-protocol/schema/json/ServerNotification.json index 1695a54870..5da36e1d24 100644 --- a/codex-rs/app-server-protocol/schema/json/ServerNotification.json +++ b/codex-rs/app-server-protocol/schema/json/ServerNotification.json @@ -1741,6 +1741,7 @@ "sessionStart", "userPromptSubmit", "subagentStart", + "subagentStop", "stop" ], "type": "string" diff --git a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json index a85aa77c0b..67dea3f00b 100644 --- a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json +++ b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.schemas.json @@ -9565,6 +9565,7 @@ "sessionStart", "userPromptSubmit", "subagentStart", + "subagentStop", "stop" ], "type": "string" @@ -10463,6 +10464,12 @@ }, "type": "array" }, + "SubagentStop": { + "items": { + "$ref": "#/definitions/v2/ConfiguredHookMatcherGroup" + }, + "type": "array" + }, "UserPromptSubmit": { "items": { "$ref": "#/definitions/v2/ConfiguredHookMatcherGroup" @@ -10491,6 +10498,7 @@ "SessionStart", "Stop", "SubagentStart", + "SubagentStop", "UserPromptSubmit" ], "type": "object" diff --git a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json index eb9e46fd68..2517ad59ba 100644 --- a/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json +++ b/codex-rs/app-server-protocol/schema/json/codex_app_server_protocol.v2.schemas.json @@ -6065,6 +6065,7 @@ "sessionStart", "userPromptSubmit", "subagentStart", + "subagentStop", "stop" ], "type": "string" @@ -7012,6 +7013,12 @@ }, "type": "array" }, + "SubagentStop": { + "items": { + "$ref": "#/definitions/ConfiguredHookMatcherGroup" + }, + "type": "array" + }, "UserPromptSubmit": { "items": { "$ref": "#/definitions/ConfiguredHookMatcherGroup" @@ -7040,6 +7047,7 @@ "SessionStart", "Stop", "SubagentStart", + "SubagentStop", "UserPromptSubmit" ], "type": "object" diff --git a/codex-rs/app-server-protocol/schema/json/v2/ConfigRequirementsReadResponse.json b/codex-rs/app-server-protocol/schema/json/v2/ConfigRequirementsReadResponse.json index 577cd7bbc9..9c86bb4572 100644 --- a/codex-rs/app-server-protocol/schema/json/v2/ConfigRequirementsReadResponse.json +++ b/codex-rs/app-server-protocol/schema/json/v2/ConfigRequirementsReadResponse.json @@ -267,6 +267,12 @@ }, "type": "array" }, + "SubagentStop": { + "items": { + "$ref": "#/definitions/ConfiguredHookMatcherGroup" + }, + "type": "array" + }, "UserPromptSubmit": { "items": { "$ref": "#/definitions/ConfiguredHookMatcherGroup" @@ -295,6 +301,7 @@ "SessionStart", "Stop", "SubagentStart", + "SubagentStop", "UserPromptSubmit" ], "type": "object" diff --git a/codex-rs/app-server-protocol/schema/json/v2/HookCompletedNotification.json b/codex-rs/app-server-protocol/schema/json/v2/HookCompletedNotification.json index 164b4865fb..088da47484 100644 --- a/codex-rs/app-server-protocol/schema/json/v2/HookCompletedNotification.json +++ b/codex-rs/app-server-protocol/schema/json/v2/HookCompletedNotification.json @@ -15,6 +15,7 @@ "sessionStart", "userPromptSubmit", "subagentStart", + "subagentStop", "stop" ], "type": "string" diff --git a/codex-rs/app-server-protocol/schema/json/v2/HookStartedNotification.json b/codex-rs/app-server-protocol/schema/json/v2/HookStartedNotification.json index 924d522a82..38395cded9 100644 --- a/codex-rs/app-server-protocol/schema/json/v2/HookStartedNotification.json +++ b/codex-rs/app-server-protocol/schema/json/v2/HookStartedNotification.json @@ -15,6 +15,7 @@ "sessionStart", "userPromptSubmit", "subagentStart", + "subagentStop", "stop" ], "type": "string" diff --git a/codex-rs/app-server-protocol/schema/json/v2/HooksListResponse.json b/codex-rs/app-server-protocol/schema/json/v2/HooksListResponse.json index 913962b603..c58a5c767d 100644 --- a/codex-rs/app-server-protocol/schema/json/v2/HooksListResponse.json +++ b/codex-rs/app-server-protocol/schema/json/v2/HooksListResponse.json @@ -30,6 +30,7 @@ "sessionStart", "userPromptSubmit", "subagentStart", + "subagentStop", "stop" ], "type": "string" diff --git a/codex-rs/app-server-protocol/schema/json/v2/PluginReadResponse.json b/codex-rs/app-server-protocol/schema/json/v2/PluginReadResponse.json index 6d2a0b5d56..c9fe43c34f 100644 --- a/codex-rs/app-server-protocol/schema/json/v2/PluginReadResponse.json +++ b/codex-rs/app-server-protocol/schema/json/v2/PluginReadResponse.json @@ -47,6 +47,7 @@ "sessionStart", "userPromptSubmit", "subagentStart", + "subagentStop", "stop" ], "type": "string" diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/HookEventName.ts b/codex-rs/app-server-protocol/schema/typescript/v2/HookEventName.ts index b12f47169f..477476289d 100644 --- a/codex-rs/app-server-protocol/schema/typescript/v2/HookEventName.ts +++ b/codex-rs/app-server-protocol/schema/typescript/v2/HookEventName.ts @@ -2,4 +2,4 @@ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. -export type HookEventName = "preToolUse" | "permissionRequest" | "postToolUse" | "preCompact" | "postCompact" | "sessionStart" | "userPromptSubmit" | "subagentStart" | "stop"; +export type HookEventName = "preToolUse" | "permissionRequest" | "postToolUse" | "preCompact" | "postCompact" | "sessionStart" | "userPromptSubmit" | "subagentStart" | "subagentStop" | "stop"; diff --git a/codex-rs/app-server-protocol/schema/typescript/v2/ManagedHooksRequirements.ts b/codex-rs/app-server-protocol/schema/typescript/v2/ManagedHooksRequirements.ts index 2b54af3c6d..1143bd017f 100644 --- a/codex-rs/app-server-protocol/schema/typescript/v2/ManagedHooksRequirements.ts +++ b/codex-rs/app-server-protocol/schema/typescript/v2/ManagedHooksRequirements.ts @@ -3,4 +3,4 @@ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually. import type { ConfiguredHookMatcherGroup } from "./ConfiguredHookMatcherGroup"; -export type ManagedHooksRequirements = { managedDir: string | null, windowsManagedDir: string | null, PreToolUse: Array, PermissionRequest: Array, PostToolUse: Array, PreCompact: Array, PostCompact: Array, SessionStart: Array, UserPromptSubmit: Array, SubagentStart: Array, Stop: Array, }; +export type ManagedHooksRequirements = { managedDir: string | null, windowsManagedDir: string | null, PreToolUse: Array, PermissionRequest: Array, PostToolUse: Array, PreCompact: Array, PostCompact: Array, SessionStart: Array, UserPromptSubmit: Array, SubagentStart: Array, SubagentStop: Array, Stop: Array, }; diff --git a/codex-rs/app-server-protocol/src/protocol/v2/config.rs b/codex-rs/app-server-protocol/src/protocol/v2/config.rs index 0efa216940..8bbd375d6c 100644 --- a/codex-rs/app-server-protocol/src/protocol/v2/config.rs +++ b/codex-rs/app-server-protocol/src/protocol/v2/config.rs @@ -424,6 +424,9 @@ pub struct ManagedHooksRequirements { #[serde(rename = "SubagentStart")] #[ts(rename = "SubagentStart")] pub subagent_start: Vec, + #[serde(rename = "SubagentStop")] + #[ts(rename = "SubagentStop")] + pub subagent_stop: Vec, #[serde(rename = "Stop")] #[ts(rename = "Stop")] pub stop: Vec, diff --git a/codex-rs/app-server-protocol/src/protocol/v2/hook.rs b/codex-rs/app-server-protocol/src/protocol/v2/hook.rs index 8163e9f51a..6e6c1ef7d4 100644 --- a/codex-rs/app-server-protocol/src/protocol/v2/hook.rs +++ b/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 } ); diff --git a/codex-rs/app-server/src/request_processors/config_processor.rs b/codex-rs/app-server/src/request_processors/config_processor.rs index eb65331b4c..0a53980d23 100644 --- a/codex-rs/app-server/src/request_processors/config_processor.rs +++ b/codex-rs/app-server/src/request_processors/config_processor.rs @@ -456,6 +456,7 @@ fn map_hooks_requirements_to_api(hooks: ManagedHooksRequirementsToml) -> Managed session_start, user_prompt_submit, subagent_start, + subagent_stop, stop, } = hooks; @@ -470,6 +471,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), } } diff --git a/codex-rs/config/src/hook_config.rs b/codex-rs/config/src/hook_config.rs index 4d1329229f..eee66896af 100644 --- a/codex-rs/config/src/hook_config.rs +++ b/codex-rs/config/src/hook_config.rs @@ -47,6 +47,8 @@ pub struct HookEventsToml { pub user_prompt_submit: Vec, #[serde(rename = "SubagentStart", default)] pub subagent_start: Vec, + #[serde(rename = "SubagentStop", default)] + pub subagent_stop: Vec, #[serde(rename = "Stop", default)] pub stop: Vec, } @@ -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); 9] { + pub fn into_matcher_groups(self) -> [(HookEventName, Vec); 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), ] } diff --git a/codex-rs/core/config.schema.json b/codex-rs/core/config.schema.json index 8599708bf7..7ef8b58be1 100644 --- a/codex-rs/core/config.schema.json +++ b/codex-rs/core/config.schema.json @@ -1100,6 +1100,13 @@ }, "type": "array" }, + "SubagentStop": { + "default": [], + "items": { + "$ref": "#/definitions/MatcherGroup" + }, + "type": "array" + }, "UserPromptSubmit": { "default": [], "items": { diff --git a/codex-rs/core/src/hook_runtime.rs b/codex-rs/core/src/hook_runtime.rs index 8647c3ef5b..6acae02578 100644 --- a/codex-rs/core/src/hook_runtime.rs +++ b/codex-rs/core/src/hook_runtime.rs @@ -14,6 +14,8 @@ use codex_hooks::PreToolUseOutcome; use codex_hooks::PreToolUseRequest; use codex_hooks::SessionStartOutcome; use codex_hooks::SessionStartTarget; +use codex_hooks::StopHookTarget; +use codex_hooks::StopOutcome; use codex_hooks::UserPromptSubmitOutcome; use codex_hooks::UserPromptSubmitRequest; use codex_otel::HOOK_RUN_DURATION_METRIC; @@ -32,6 +34,7 @@ use codex_protocol::protocol::HookStartedEvent; use codex_protocol::protocol::SessionSource; use codex_protocol::protocol::SubAgentSource; use codex_protocol::user_input::UserInput; +use codex_thread_store::ReadThreadParams; use serde_json::Value; use crate::context::ContextualUserFragment; @@ -294,6 +297,72 @@ pub(crate) async fn run_post_tool_use_hooks( outcome } +pub(crate) async fn run_turn_stop_hooks( + sess: &Arc, + turn_context: &Arc, + stop_hook_active: bool, + last_assistant_message: Option, +) -> StopOutcome { + let (target, transcript_path) = match &turn_context.session_source { + SessionSource::SubAgent(SubAgentSource::ThreadSpawn { + agent_role, + parent_thread_id, + .. + }) => { + let metadata = subagent_hook_metadata(sess, agent_role); + 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: metadata.agent_id, + agent_type: metadata.agent_type, + agent_transcript_path, + }, + parent_transcript_path, + ) + } + 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, turn_context: &Arc, @@ -578,6 +647,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 { diff --git a/codex-rs/core/src/session/turn.rs b/codex-rs/core/src/session/turn.rs index 86710e4871..5d3808d20f 100644 --- a/codex-rs/core/src/session/turn.rs +++ b/codex-rs/core/src/session/turn.rs @@ -21,11 +21,11 @@ use crate::connectors; use crate::context::ContextualUserFragment; use crate::feedback_tags; use crate::hook_runtime::PendingInputHookDisposition; -use crate::hook_runtime::emit_hook_completed_events; use crate::hook_runtime::inspect_pending_input; use crate::hook_runtime::record_additional_contexts; use crate::hook_runtime::record_pending_input; use crate::hook_runtime::run_pending_session_start_hooks; +use crate::hook_runtime::run_turn_stop_hooks; use crate::hook_runtime::run_user_prompt_submit_hooks; use crate::injection::ToolMentionKind; use crate::injection::app_id_from_path; @@ -90,7 +90,6 @@ use codex_protocol::models::ResponseInputItem; use codex_protocol::models::ResponseItem; use codex_protocol::protocol::AgentMessageContentDeltaEvent; use codex_protocol::protocol::AgentReasoningSectionBreakEvent; -use codex_protocol::protocol::AskForApproval; use codex_protocol::protocol::CodexErrorInfo; use codex_protocol::protocol::ErrorEvent; use codex_protocol::protocol::EventMsg; @@ -518,39 +517,13 @@ pub(crate) async fn run_turn( if !needs_follow_up { last_agent_message = sampling_request_last_agent_message; - let stop_hook_permission_mode = match turn_context.approval_policy.value() { - AskForApproval::Never => "bypassPermissions", - AskForApproval::UnlessTrusted - | AskForApproval::OnFailure - | AskForApproval::OnRequest - | AskForApproval::Granular(_) => "default", - } - .to_string(); - let stop_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: sess.hook_transcript_path().await, - model: turn_context.model_info.slug.clone(), - permission_mode: stop_hook_permission_mode, + let stop_outcome = run_turn_stop_hooks( + &sess, + &turn_context, stop_hook_active, - last_assistant_message: last_agent_message.clone(), - }; - let hooks = sess.hooks(); - for run in hooks.preview_stop(&stop_request) { - sess.send_event( - &turn_context, - EventMsg::HookStarted(codex_protocol::protocol::HookStartedEvent { - turn_id: Some(turn_context.sub_id.clone()), - run, - }), - ) - .await; - } - let stop_outcome = hooks.run_stop(stop_request).await; - emit_hook_completed_events(&sess, &turn_context, stop_outcome.hook_events) - .await; + last_agent_message.clone(), + ) + .await; if stop_outcome.should_block { if let Some(hook_prompt_message) = build_hook_prompt_message(&stop_outcome.continuation_fragments) diff --git a/codex-rs/core/tests/suite/subagent_notifications.rs b/codex-rs/core/tests/suite/subagent_notifications.rs index a91149b46a..95d6b0e62d 100644 --- a/codex-rs/core/tests/suite/subagent_notifications.rs +++ b/codex-rs/core/tests/suite/subagent_notifications.rs @@ -1,9 +1,19 @@ use anyhow::Result; +use codex_core::StartThreadOptions; use codex_core::ThreadConfigSnapshot; use codex_core::config::AgentRoleConfig; use codex_features::Feature; use codex_protocol::ThreadId; +use codex_protocol::models::PermissionProfile; use codex_protocol::openai_models::ReasoningEffort; +use codex_protocol::protocol::AskForApproval; +use codex_protocol::protocol::EventMsg; +use codex_protocol::protocol::InitialHistory; +use codex_protocol::protocol::Op; +use codex_protocol::protocol::SessionSource; +use codex_protocol::protocol::SubAgentSource; +use codex_protocol::user_input::UserInput; +use core_test_support::hooks::trust_discovered_hooks; use core_test_support::responses::ResponsesRequest; use core_test_support::responses::ev_assistant_message; use core_test_support::responses::ev_completed; @@ -17,6 +27,8 @@ use core_test_support::responses::start_mock_server; use core_test_support::skip_if_no_network; use core_test_support::test_codex::TestCodex; use core_test_support::test_codex::test_codex; +use core_test_support::test_codex::turn_permission_fields; +use core_test_support::wait_for_event_match; use pretty_assertions::assert_eq; use serde_json::json; use std::fs; @@ -38,6 +50,8 @@ const REQUESTED_REASONING_EFFORT: ReasoningEffort = ReasoningEffort::Low; const ROLE_MODEL: &str = "gpt-5.4"; const ROLE_REASONING_EFFORT: ReasoningEffort = ReasoningEffort::High; const SUBAGENT_START_CONTEXT: &str = "subagent start context reaches child"; +const SUBAGENT_STOP_CONTINUATION: &str = "continue only the child"; +const INTERNAL_SUBAGENT_PROMPT: &str = "internal subagent: review"; fn body_contains(req: &wiremock::Request, text: &str) -> bool { let is_zstd = req @@ -111,7 +125,11 @@ fn write_home_skill(codex_home: &Path, dir: &str, name: &str, description: &str) Ok(()) } -fn write_subagent_start_hooks(home: &Path) -> Result<()> { +fn write_subagent_lifecycle_hooks( + home: &Path, + stop_prompts: &[&str], + subagent_stop_matcher: &str, +) -> Result<()> { let session_start_script_path = home.join("session_start_hook.py"); let session_start_log_path = home.join("session_start_hook_log.jsonl"); let session_start_script = format!( @@ -143,6 +161,51 @@ print(json.dumps({{"hookSpecificOutput": {{"hookEventName": "SubagentStart", "ad start_log_path = start_log_path.display(), ); + let subagent_stop_script_path = home.join("subagent_stop_hook.py"); + let subagent_stop_log_path = home.join("subagent_stop_hook_log.jsonl"); + let prompts_json = serde_json::to_string(stop_prompts)?; + let subagent_stop_script = format!( + r#"import json +from pathlib import Path +import sys + +log_path = Path(r"{subagent_stop_log_path}") +block_prompts = {prompts_json} + +payload = json.load(sys.stdin) +existing = [] +if log_path.exists(): + existing = [line for line in log_path.read_text(encoding="utf-8").splitlines() if line.strip()] + +with log_path.open("a", encoding="utf-8") as handle: + handle.write(json.dumps(payload) + "\n") + +invocation_index = len(existing) +if invocation_index < len(block_prompts): + print(json.dumps({{"decision": "block", "reason": block_prompts[invocation_index]}})) +else: + print(json.dumps({{"systemMessage": f"subagent stop pass {{invocation_index + 1}} complete"}})) +"#, + subagent_stop_log_path = subagent_stop_log_path.display(), + prompts_json = prompts_json, + ); + + let stop_script_path = home.join("stop_hook.py"); + let stop_log_path = home.join("stop_hook_log.jsonl"); + let stop_script = format!( + r#"import json +from pathlib import Path +import sys + +log_path = Path(r"{stop_log_path}") +payload = json.load(sys.stdin) +with log_path.open("a", encoding="utf-8") as handle: + handle.write(json.dumps(payload) + "\n") +print(json.dumps({{"systemMessage": "root stop complete"}})) +"#, + stop_log_path = stop_log_path.display(), + ); + let hooks = serde_json::json!({ "hooks": { "SessionStart": [{ @@ -158,12 +221,27 @@ print(json.dumps({{"hookSpecificOutput": {{"hookEventName": "SubagentStart", "ad "type": "command", "command": format!("python3 {}", start_script_path.display()), }] + }], + "SubagentStop": [{ + "matcher": subagent_stop_matcher, + "hooks": [{ + "type": "command", + "command": format!("python3 {}", subagent_stop_script_path.display()), + }] + }], + "Stop": [{ + "hooks": [{ + "type": "command", + "command": format!("python3 {}", stop_script_path.display()), + }] }] } }); fs::write(&session_start_script_path, session_start_script)?; fs::write(&start_script_path, start_script)?; + fs::write(&subagent_stop_script_path, subagent_stop_script)?; + fs::write(&stop_script_path, stop_script)?; fs::write(home.join("hooks.json"), hooks.to_string())?; Ok(()) } @@ -180,6 +258,27 @@ fn read_hook_log(home: &Path, filename: &str) -> Result> .collect() } +async fn wait_for_hook_log_entries( + home: &Path, + filename: &str, + expected_len: usize, +) -> Result> { + let deadline = Instant::now() + Duration::from_secs(2); + loop { + let entries = read_hook_log(home, filename)?; + if entries.len() >= expected_len { + return Ok(entries); + } + if Instant::now() >= deadline { + anyhow::bail!( + "expected at least {expected_len} entries in {filename}, got {}", + entries.len() + ); + } + sleep(Duration::from_millis(10)).await; + } +} + async fn wait_for_spawned_thread_id(test: &TestCodex) -> Result { let deadline = Instant::now() + Duration::from_secs(2); loop { @@ -400,12 +499,12 @@ async fn subagent_start_replaces_session_start_and_injects_context() -> Result<( let test = test_codex() .with_pre_build_hook(|home| { - if let Err(error) = write_subagent_start_hooks(home) { + if let Err(error) = write_subagent_lifecycle_hooks(home, &[], "worker") { panic!("failed to write subagent hook fixture: {error}"); } }) .with_config(|config| { - core_test_support::hooks::trust_discovered_hooks(config); + trust_discovered_hooks(config); config .features .enable(Feature::Collab) @@ -439,6 +538,207 @@ async fn subagent_start_replaces_session_start_and_injects_context() -> Result<( Ok(()) } +#[tokio::test(flavor = "multi_thread", worker_threads = 2)] +async fn subagent_stop_replaces_stop_and_skips_internal_subagents() -> Result<()> { + skip_if_no_network!(Ok(())); + + let server = start_mock_server().await; + let spawn_args = serde_json::to_string(&json!({ + "message": CHILD_PROMPT, + "task_name": "child", + "agent_type": "worker", + }))?; + + mount_sse_once_match( + &server, + |req: &wiremock::Request| body_contains(req, TURN_1_PROMPT), + sse(vec![ + ev_response_created("resp-turn1-1"), + ev_function_call(SPAWN_CALL_ID, "spawn_agent", &spawn_args), + ev_completed("resp-turn1-1"), + ]), + ) + .await; + + let first_child_request = mount_sse_once_match( + &server, + |req: &wiremock::Request| { + body_contains(req, CHILD_PROMPT) && !body_contains(req, SPAWN_CALL_ID) + }, + sse(vec![ + ev_response_created("resp-child-1"), + ev_assistant_message("msg-child-1", "child done first"), + ev_completed("resp-child-1"), + ]), + ) + .await; + let second_child_request = mount_sse_once_match( + &server, + |req: &wiremock::Request| { + body_contains(req, SUBAGENT_STOP_CONTINUATION) && !body_contains(req, SPAWN_CALL_ID) + }, + sse(vec![ + ev_response_created("resp-child-2"), + ev_assistant_message("msg-child-2", "child done final"), + ev_completed("resp-child-2"), + ]), + ) + .await; + + let _turn1_followup = mount_sse_once_match( + &server, + |req: &wiremock::Request| body_contains(req, SPAWN_CALL_ID), + sse(vec![ + ev_response_created("resp-turn1-2"), + ev_assistant_message("msg-turn1-2", "parent done"), + ev_completed("resp-turn1-2"), + ]), + ) + .await; + let internal_request = mount_sse_once_match( + &server, + |req: &wiremock::Request| body_contains(req, INTERNAL_SUBAGENT_PROMPT), + sse(vec![ + ev_response_created("resp-internal-1"), + ev_assistant_message("msg-internal-1", "internal subagent done"), + ev_completed("resp-internal-1"), + ]), + ) + .await; + + let test = test_codex() + .with_pre_build_hook(|home| { + if let Err(error) = + write_subagent_lifecycle_hooks(home, &[SUBAGENT_STOP_CONTINUATION], "") + { + panic!("failed to write subagent hook fixture: {error}"); + } + }) + .with_config(|config| { + trust_discovered_hooks(config); + config + .features + .enable(Feature::Collab) + .expect("test config should allow feature update"); + }) + .build(&server) + .await?; + + test.submit_turn(TURN_1_PROMPT).await?; + let _ = wait_for_requests(&first_child_request).await?; + let _ = wait_for_requests(&second_child_request).await?; + + let subagent_stop_inputs = wait_for_hook_log_entries( + test.codex_home_path(), + "subagent_stop_hook_log.jsonl", + /*expected_len*/ 2, + ) + .await?; + assert_eq!(subagent_stop_inputs.len(), 2); + assert_eq!( + subagent_stop_inputs + .iter() + .map(|input| input["stop_hook_active"].as_bool()) + .collect::>(), + vec![Some(false), Some(true)] + ); + assert_eq!( + subagent_stop_inputs[0]["agent_type"].as_str(), + Some("worker") + ); + let parent_transcript_path = subagent_stop_inputs[0]["transcript_path"] + .as_str() + .expect("SubagentStop should include parent transcript_path"); + let agent_transcript_path = subagent_stop_inputs[0]["agent_transcript_path"] + .as_str() + .expect("SubagentStop should include agent_transcript_path"); + assert_ne!(parent_transcript_path, agent_transcript_path); + assert_eq!( + subagent_stop_inputs[1]["transcript_path"].as_str(), + Some(parent_transcript_path) + ); + assert_eq!( + subagent_stop_inputs[1]["agent_transcript_path"].as_str(), + Some(agent_transcript_path) + ); + assert_eq!( + subagent_stop_inputs[0]["last_assistant_message"].as_str(), + Some("child done first") + ); + + let stop_inputs = read_hook_log(test.codex_home_path(), "stop_hook_log.jsonl")?; + assert!( + stop_inputs + .iter() + .all(|input| input["last_assistant_message"].as_str() != Some("child done first")), + "child completion should not invoke the normal Stop hook" + ); + let stop_input_count = stop_inputs.len(); + + // This matcher would catch the old synthetic "review" SubagentStop target + // because the SubagentStop hook above intentionally matches all agent types. + let internal_thread = test + .thread_manager + .start_thread_with_options(StartThreadOptions { + config: test.config.clone(), + initial_history: InitialHistory::New, + session_source: Some(SessionSource::SubAgent(SubAgentSource::Review)), + thread_source: None, + dynamic_tools: Vec::new(), + persist_extended_history: false, + metrics_service_name: None, + parent_trace: None, + environments: Vec::new(), + }) + .await?; + + let (sandbox_policy, permission_profile) = + turn_permission_fields(PermissionProfile::Disabled, test.cwd_path()); + internal_thread + .thread + .submit(Op::UserTurn { + environments: None, + items: vec![UserInput::Text { + text: INTERNAL_SUBAGENT_PROMPT.to_string(), + text_elements: Vec::new(), + }], + final_output_json_schema: None, + cwd: test.config.cwd.to_path_buf(), + approval_policy: AskForApproval::Never, + approvals_reviewer: None, + sandbox_policy, + permission_profile, + model: internal_thread.session_configured.model.clone(), + effort: None, + summary: None, + service_tier: None, + collaboration_mode: None, + personality: None, + }) + .await?; + let turn_id = wait_for_event_match(internal_thread.thread.as_ref(), |event| match event { + EventMsg::TurnStarted(event) => Some(event.turn_id.clone()), + _ => None, + }) + .await; + wait_for_event_match(internal_thread.thread.as_ref(), |event| match event { + EventMsg::TurnComplete(event) if event.turn_id == turn_id => Some(()), + _ => None, + }) + .await; + let requests = wait_for_requests(&internal_request).await?; + assert_eq!(requests.len(), 1); + + let subagent_stop_inputs_after_internal = + read_hook_log(test.codex_home_path(), "subagent_stop_hook_log.jsonl")?; + assert_eq!(subagent_stop_inputs_after_internal, subagent_stop_inputs); + + let stop_inputs_after_internal = read_hook_log(test.codex_home_path(), "stop_hook_log.jsonl")?; + assert_eq!(stop_inputs_after_internal.len(), stop_input_count); + + Ok(()) +} + #[tokio::test(flavor = "multi_thread", worker_threads = 2)] async fn subagent_notification_is_included_without_wait() -> Result<()> { skip_if_no_network!(Ok(())); diff --git a/codex-rs/hooks/schema/generated/permission-request.command.output.schema.json b/codex-rs/hooks/schema/generated/permission-request.command.output.schema.json index 44e775a03d..7d63b56c96 100644 --- a/codex-rs/hooks/schema/generated/permission-request.command.output.schema.json +++ b/codex-rs/hooks/schema/generated/permission-request.command.output.schema.json @@ -12,6 +12,7 @@ "SessionStart", "UserPromptSubmit", "SubagentStart", + "SubagentStop", "Stop" ], "type": "string" diff --git a/codex-rs/hooks/schema/generated/post-tool-use.command.output.schema.json b/codex-rs/hooks/schema/generated/post-tool-use.command.output.schema.json index b762c549c5..964c3ba624 100644 --- a/codex-rs/hooks/schema/generated/post-tool-use.command.output.schema.json +++ b/codex-rs/hooks/schema/generated/post-tool-use.command.output.schema.json @@ -18,6 +18,7 @@ "SessionStart", "UserPromptSubmit", "SubagentStart", + "SubagentStop", "Stop" ], "type": "string" diff --git a/codex-rs/hooks/schema/generated/pre-tool-use.command.output.schema.json b/codex-rs/hooks/schema/generated/pre-tool-use.command.output.schema.json index c4c4132448..a74abd14e8 100644 --- a/codex-rs/hooks/schema/generated/pre-tool-use.command.output.schema.json +++ b/codex-rs/hooks/schema/generated/pre-tool-use.command.output.schema.json @@ -12,6 +12,7 @@ "SessionStart", "UserPromptSubmit", "SubagentStart", + "SubagentStop", "Stop" ], "type": "string" diff --git a/codex-rs/hooks/schema/generated/session-start.command.output.schema.json b/codex-rs/hooks/schema/generated/session-start.command.output.schema.json index d8a0f46482..e1abb88a52 100644 --- a/codex-rs/hooks/schema/generated/session-start.command.output.schema.json +++ b/codex-rs/hooks/schema/generated/session-start.command.output.schema.json @@ -12,6 +12,7 @@ "SessionStart", "UserPromptSubmit", "SubagentStart", + "SubagentStop", "Stop" ], "type": "string" diff --git a/codex-rs/hooks/schema/generated/subagent-start.command.output.schema.json b/codex-rs/hooks/schema/generated/subagent-start.command.output.schema.json index 16140f326b..4e645bb918 100644 --- a/codex-rs/hooks/schema/generated/subagent-start.command.output.schema.json +++ b/codex-rs/hooks/schema/generated/subagent-start.command.output.schema.json @@ -12,6 +12,7 @@ "SessionStart", "UserPromptSubmit", "SubagentStart", + "SubagentStop", "Stop" ], "type": "string" diff --git a/codex-rs/hooks/schema/generated/subagent-stop.command.input.schema.json b/codex-rs/hooks/schema/generated/subagent-stop.command.input.schema.json new file mode 100644 index 0000000000..19646db1d2 --- /dev/null +++ b/codex-rs/hooks/schema/generated/subagent-stop.command.input.schema.json @@ -0,0 +1,75 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": false, + "definitions": { + "NullableString": { + "type": [ + "string", + "null" + ] + } + }, + "properties": { + "agent_id": { + "type": "string" + }, + "agent_transcript_path": { + "$ref": "#/definitions/NullableString" + }, + "agent_type": { + "type": "string" + }, + "cwd": { + "type": "string" + }, + "hook_event_name": { + "const": "SubagentStop", + "type": "string" + }, + "last_assistant_message": { + "$ref": "#/definitions/NullableString" + }, + "model": { + "type": "string" + }, + "permission_mode": { + "enum": [ + "default", + "acceptEdits", + "plan", + "dontAsk", + "bypassPermissions" + ], + "type": "string" + }, + "session_id": { + "type": "string" + }, + "stop_hook_active": { + "type": "boolean" + }, + "transcript_path": { + "$ref": "#/definitions/NullableString" + }, + "turn_id": { + "description": "Codex extension: expose the active turn id to internal turn-scoped hooks.", + "type": "string" + } + }, + "required": [ + "agent_id", + "agent_transcript_path", + "agent_type", + "cwd", + "hook_event_name", + "last_assistant_message", + "model", + "permission_mode", + "session_id", + "stop_hook_active", + "transcript_path", + "turn_id" + ], + "title": "subagent-stop.command.input", + "type": "object" +} \ No newline at end of file diff --git a/codex-rs/hooks/schema/generated/subagent-stop.command.output.schema.json b/codex-rs/hooks/schema/generated/subagent-stop.command.output.schema.json new file mode 100644 index 0000000000..0cb1dd2a57 --- /dev/null +++ b/codex-rs/hooks/schema/generated/subagent-stop.command.output.schema.json @@ -0,0 +1,45 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "additionalProperties": false, + "definitions": { + "BlockDecisionWire": { + "enum": [ + "block" + ], + "type": "string" + } + }, + "properties": { + "continue": { + "default": true, + "type": "boolean" + }, + "decision": { + "allOf": [ + { + "$ref": "#/definitions/BlockDecisionWire" + } + ], + "default": null + }, + "reason": { + "default": null, + "description": "Claude requires `reason` when `decision` is `block`; we enforce that semantic rule during output parsing rather than in the JSON schema.", + "type": "string" + }, + "stopReason": { + "default": null, + "type": "string" + }, + "suppressOutput": { + "default": false, + "type": "boolean" + }, + "systemMessage": { + "default": null, + "type": "string" + } + }, + "title": "subagent-stop.command.output", + "type": "object" +} \ No newline at end of file diff --git a/codex-rs/hooks/schema/generated/user-prompt-submit.command.output.schema.json b/codex-rs/hooks/schema/generated/user-prompt-submit.command.output.schema.json index d4d66d2976..61c530ce04 100644 --- a/codex-rs/hooks/schema/generated/user-prompt-submit.command.output.schema.json +++ b/codex-rs/hooks/schema/generated/user-prompt-submit.command.output.schema.json @@ -18,6 +18,7 @@ "SessionStart", "UserPromptSubmit", "SubagentStart", + "SubagentStop", "Stop" ], "type": "string" diff --git a/codex-rs/hooks/src/engine/dispatcher.rs b/codex-rs/hooks/src/engine/dispatcher.rs index 51c6d6672e..50822bfc96 100644 --- a/codex-rs/hooks/src/engine/dispatcher.rs +++ b/codex-rs/hooks/src/engine/dispatcher.rs @@ -50,6 +50,7 @@ pub(crate) fn select_handlers_for_matcher_inputs( | HookEventName::PostToolUse | HookEventName::SessionStart | HookEventName::SubagentStart + | HookEventName::SubagentStop | HookEventName::PreCompact | HookEventName::PostCompact => { if matcher_inputs.is_empty() { @@ -147,6 +148,7 @@ fn scope_for_event(event_name: HookEventName) -> HookScope { | HookEventName::PreCompact | HookEventName::PostCompact | HookEventName::UserPromptSubmit + | HookEventName::SubagentStop | HookEventName::Stop => HookScope::Turn, } } diff --git a/codex-rs/hooks/src/engine/mod.rs b/codex-rs/hooks/src/engine/mod.rs index 7cbbd7a027..859fc54069 100644 --- a/codex-rs/hooks/src/engine/mod.rs +++ b/codex-rs/hooks/src/engine/mod.rs @@ -71,6 +71,7 @@ impl ConfiguredHandler { codex_protocol::protocol::HookEventName::SessionStart => "session-start", codex_protocol::protocol::HookEventName::UserPromptSubmit => "user-prompt-submit", codex_protocol::protocol::HookEventName::SubagentStart => "subagent-start", + codex_protocol::protocol::HookEventName::SubagentStop => "subagent-stop", codex_protocol::protocol::HookEventName::Stop => "stop", } } diff --git a/codex-rs/hooks/src/engine/output_parser.rs b/codex-rs/hooks/src/engine/output_parser.rs index 1ea44c0903..11b44395c8 100644 --- a/codex-rs/hooks/src/engine/output_parser.rs +++ b/codex-rs/hooks/src/engine/output_parser.rs @@ -87,6 +87,7 @@ use crate::schema::PreToolUsePermissionDecisionWire; use crate::schema::SessionStartCommandOutputWire; use crate::schema::StopCommandOutputWire; use crate::schema::SubagentStartCommandOutputWire; +use crate::schema::SubagentStopCommandOutputWire; use crate::schema::UserPromptSubmitCommandOutputWire; pub(crate) fn parse_session_start(stdout: &str) -> Option { @@ -280,22 +281,46 @@ pub(crate) fn parse_user_prompt_submit(stdout: &str) -> Option Option { let wire: StopCommandOutputWire = parse_json(stdout)?; - let should_block = matches!(wire.decision, Some(BlockDecisionWire::Block)); + Some(stop_output( + wire.universal, + wire.decision, + wire.reason, + "Stop", + )) +} + +pub(crate) fn parse_subagent_stop(stdout: &str) -> Option { + let wire: SubagentStopCommandOutputWire = parse_json(stdout)?; + Some(stop_output( + wire.universal, + wire.decision, + wire.reason, + "SubagentStop", + )) +} + +fn stop_output( + universal: HookUniversalOutputWire, + decision: Option, + reason: Option, + event_name: &str, +) -> StopOutput { + let should_block = matches!(decision, Some(BlockDecisionWire::Block)); let invalid_block_reason = if should_block - && match wire.reason.as_deref() { + && match reason.as_deref() { Some(reason) => reason.trim().is_empty(), None => true, } { - Some(invalid_block_message("Stop")) + Some(invalid_block_message(event_name)) } else { None }; - Some(StopOutput { - universal: UniversalOutput::from(wire.universal), + StopOutput { + universal: UniversalOutput::from(universal), should_block: should_block && invalid_block_reason.is_none(), - reason: wire.reason, + reason, invalid_block_reason, - }) + } } impl From for UniversalOutput { diff --git a/codex-rs/hooks/src/engine/schema_loader.rs b/codex-rs/hooks/src/engine/schema_loader.rs index 2b1994f28d..655e283124 100644 --- a/codex-rs/hooks/src/engine/schema_loader.rs +++ b/codex-rs/hooks/src/engine/schema_loader.rs @@ -18,6 +18,8 @@ pub(crate) struct GeneratedHookSchemas { pub session_start_command_output: Value, pub subagent_start_command_input: Value, pub subagent_start_command_output: Value, + pub subagent_stop_command_input: Value, + pub subagent_stop_command_output: Value, pub user_prompt_submit_command_input: Value, pub user_prompt_submit_command_output: Value, pub stop_command_input: Value, @@ -83,6 +85,14 @@ pub(crate) fn generated_hook_schemas() -> &'static GeneratedHookSchemas { "subagent-start.command.output", include_str!("../../schema/generated/subagent-start.command.output.schema.json"), ), + subagent_stop_command_input: parse_json_schema( + "subagent-stop.command.input", + include_str!("../../schema/generated/subagent-stop.command.input.schema.json"), + ), + subagent_stop_command_output: parse_json_schema( + "subagent-stop.command.output", + include_str!("../../schema/generated/subagent-stop.command.output.schema.json"), + ), user_prompt_submit_command_input: parse_json_schema( "user-prompt-submit.command.input", include_str!("../../schema/generated/user-prompt-submit.command.input.schema.json"), @@ -130,6 +140,8 @@ mod tests { assert_eq!(schemas.session_start_command_output["type"], "object"); assert_eq!(schemas.subagent_start_command_input["type"], "object"); assert_eq!(schemas.subagent_start_command_output["type"], "object"); + assert_eq!(schemas.subagent_stop_command_input["type"], "object"); + assert_eq!(schemas.subagent_stop_command_output["type"], "object"); assert_eq!(schemas.user_prompt_submit_command_input["type"], "object"); assert_eq!(schemas.user_prompt_submit_command_output["type"], "object"); assert_eq!(schemas.stop_command_input["type"], "object"); diff --git a/codex-rs/hooks/src/events/common.rs b/codex-rs/hooks/src/events/common.rs index f96de58020..c97129ebef 100644 --- a/codex-rs/hooks/src/events/common.rs +++ b/codex-rs/hooks/src/events/common.rs @@ -105,6 +105,7 @@ pub(crate) fn matcher_pattern_for_event( | HookEventName::PostToolUse | HookEventName::SessionStart | HookEventName::SubagentStart + | HookEventName::SubagentStop | HookEventName::PreCompact | HookEventName::PostCompact => matcher, HookEventName::UserPromptSubmit | HookEventName::Stop => None, diff --git a/codex-rs/hooks/src/events/stop.rs b/codex-rs/hooks/src/events/stop.rs index 3cd2d44270..a7cf33e196 100644 --- a/codex-rs/hooks/src/events/stop.rs +++ b/codex-rs/hooks/src/events/stop.rs @@ -18,6 +18,7 @@ use crate::engine::dispatcher; use crate::engine::output_parser; use crate::schema::NullableString; use crate::schema::StopCommandInput; +use crate::schema::SubagentStopCommandInput; #[derive(Debug, Clone)] pub struct StopRequest { @@ -29,9 +30,36 @@ pub struct StopRequest { pub permission_mode: String, pub stop_hook_active: bool, pub last_assistant_message: Option, + pub target: StopHookTarget, } -#[derive(Debug)] +#[derive(Debug, Clone)] +pub enum StopHookTarget { + Stop, + SubagentStop { + agent_id: String, + agent_type: String, + agent_transcript_path: Option, + }, +} + +impl StopHookTarget { + fn event_name(&self) -> HookEventName { + match self { + Self::Stop => HookEventName::Stop, + Self::SubagentStop { .. } => HookEventName::SubagentStop, + } + } + + fn matcher_input(&self) -> Option<&str> { + match self { + Self::Stop => None, + Self::SubagentStop { agent_type, .. } => Some(agent_type.as_str()), + } + } +} + +#[derive(Debug, Default)] pub struct StopOutcome { pub hook_events: Vec, pub should_stop: bool, @@ -52,12 +80,16 @@ struct StopHandlerData { pub(crate) fn preview( handlers: &[ConfiguredHandler], - _request: &StopRequest, + request: &StopRequest, ) -> Vec { - dispatcher::select_handlers(handlers, HookEventName::Stop, /*matcher_input*/ None) - .into_iter() - .map(|handler| dispatcher::running_summary(&handler)) - .collect() + dispatcher::select_handlers( + handlers, + request.target.event_name(), + request.target.matcher_input(), + ) + .into_iter() + .map(|handler| dispatcher::running_summary(&handler)) + .collect() } pub(crate) async fn run( @@ -65,8 +97,11 @@ pub(crate) async fn run( shell: &CommandShell, request: StopRequest, ) -> StopOutcome { - let matched = - dispatcher::select_handlers(handlers, HookEventName::Stop, /*matcher_input*/ None); + let matched = dispatcher::select_handlers( + handlers, + request.target.event_name(), + request.target.matcher_input(), + ); if matched.is_empty() { return StopOutcome { hook_events: Vec::new(), @@ -78,24 +113,85 @@ pub(crate) async fn run( }; } - let input_json = match serde_json::to_string(&StopCommandInput { - session_id: request.session_id.to_string(), - turn_id: request.turn_id.clone(), - transcript_path: NullableString::from_path(request.transcript_path.clone()), - cwd: request.cwd.display().to_string(), - hook_event_name: "Stop".to_string(), - model: request.model.clone(), - permission_mode: request.permission_mode.clone(), - stop_hook_active: request.stop_hook_active, - last_assistant_message: NullableString::from_string(request.last_assistant_message.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 stop hook input: {error}"), - )); + let (input_json, parse_completed) = match request.target { + StopHookTarget::Stop => { + let input = StopCommandInput { + session_id: request.session_id.to_string(), + turn_id: request.turn_id.clone(), + transcript_path: NullableString::from_path(request.transcript_path.clone()), + cwd: request.cwd.display().to_string(), + hook_event_name: "Stop".to_string(), + model: request.model.clone(), + permission_mode: request.permission_mode.clone(), + stop_hook_active: request.stop_hook_active, + last_assistant_message: NullableString::from_string( + request.last_assistant_message.clone(), + ), + }; + match serde_json::to_string(&input) { + Ok(input_json) => ( + input_json, + parse_completed + as fn( + &ConfiguredHandler, + CommandRunResult, + Option, + ) + -> dispatcher::ParsedHandler, + ), + Err(error) => { + return serialization_failure_outcome( + common::serialization_failure_hook_events( + matched, + Some(request.turn_id), + format!("failed to serialize stop hook input: {error}"), + ), + ); + } + } + } + StopHookTarget::SubagentStop { + agent_id, + agent_type, + agent_transcript_path, + } => { + let input = SubagentStopCommandInput { + session_id: request.session_id.to_string(), + turn_id: request.turn_id.clone(), + transcript_path: NullableString::from_path(request.transcript_path.clone()), + agent_transcript_path: NullableString::from_path(agent_transcript_path), + cwd: request.cwd.display().to_string(), + hook_event_name: "SubagentStop".to_string(), + model: request.model.clone(), + permission_mode: request.permission_mode.clone(), + stop_hook_active: request.stop_hook_active, + agent_id, + agent_type, + last_assistant_message: NullableString::from_string( + request.last_assistant_message.clone(), + ), + }; + match serde_json::to_string(&input) { + Ok(input_json) => ( + input_json, + parse_subagent_stop_completed + as fn( + &ConfiguredHandler, + CommandRunResult, + Option, + ) + -> dispatcher::ParsedHandler, + ), + Err(error) => { + return serialization_failure_outcome( + common::serialization_failure_hook_events( + matched, + Some(request.turn_id), + format!("failed to serialize subagent stop hook input: {error}"), + ), + ); + } + } } }; @@ -125,6 +221,39 @@ fn parse_completed( handler: &ConfiguredHandler, run_result: CommandRunResult, turn_id: Option, +) -> dispatcher::ParsedHandler { + parse_stop_completed( + handler, + run_result, + turn_id, + "Stop", + "stop", + output_parser::parse_stop, + ) +} + +fn parse_subagent_stop_completed( + handler: &ConfiguredHandler, + run_result: CommandRunResult, + turn_id: Option, +) -> dispatcher::ParsedHandler { + parse_stop_completed( + handler, + run_result, + turn_id, + "SubagentStop", + "subagent stop", + output_parser::parse_subagent_stop, + ) +} + +fn parse_stop_completed( + handler: &ConfiguredHandler, + run_result: CommandRunResult, + turn_id: Option, + hook_name: &str, + hook_label: &str, + parse_output: fn(&str) -> Option, ) -> dispatcher::ParsedHandler { let mut entries = Vec::new(); let mut status = HookRunStatus::Completed; @@ -146,7 +275,7 @@ fn parse_completed( Some(0) => { let trimmed_stdout = run_result.stdout.trim(); if trimmed_stdout.is_empty() { - } else if let Some(parsed) = output_parser::parse_stop(&run_result.stdout) { + } else if let Some(parsed) = parse_output(&run_result.stdout) { if let Some(system_message) = parsed.universal.system_message { entries.push(HookOutputEntry { kind: HookOutputEntryKind::Warning, @@ -186,9 +315,9 @@ fn parse_completed( status = HookRunStatus::Failed; entries.push(HookOutputEntry { kind: HookOutputEntryKind::Error, - text: - "Stop hook returned decision:block without a non-empty reason" - .to_string(), + text: format!( + "{hook_name} hook returned decision:block without a non-empty reason" + ), }); } } @@ -196,7 +325,7 @@ fn parse_completed( status = HookRunStatus::Failed; entries.push(HookOutputEntry { kind: HookOutputEntryKind::Error, - text: "hook returned invalid stop hook JSON output".to_string(), + text: format!("hook returned invalid {hook_label} hook JSON output"), }); } } @@ -214,9 +343,9 @@ fn parse_completed( status = HookRunStatus::Failed; entries.push(HookOutputEntry { kind: HookOutputEntryKind::Error, - text: - "Stop hook exited with code 2 but did not write a continuation prompt to stderr" - .to_string(), + text: format!( + "{hook_name} hook exited with code 2 but did not write a continuation prompt to stderr" + ), }); } } diff --git a/codex-rs/hooks/src/lib.rs b/codex-rs/hooks/src/lib.rs index 93bbe72ba5..2bd0cc2d6e 100644 --- a/codex-rs/hooks/src/lib.rs +++ b/codex-rs/hooks/src/lib.rs @@ -15,7 +15,7 @@ pub use declarations::PluginHookDeclaration; pub use declarations::plugin_hook_declarations; pub use engine::HookListEntry; /// Hook event names as they appear in hooks JSON and config files. -pub const HOOK_EVENT_NAMES: [&str; 9] = [ +pub const HOOK_EVENT_NAMES: [&str; 10] = [ "PreToolUse", "PermissionRequest", "PostToolUse", @@ -24,6 +24,7 @@ pub const HOOK_EVENT_NAMES: [&str; 9] = [ "SessionStart", "UserPromptSubmit", "SubagentStart", + "SubagentStop", "Stop", ]; @@ -32,7 +33,7 @@ pub const HOOK_EVENT_NAMES: [&str; 9] = [ /// Other events can appear in hooks JSON, but Codex ignores their matcher /// fields because those events do not dispatch against a tool, compaction /// trigger, or session-start source. -pub const HOOK_EVENT_NAMES_WITH_MATCHERS: [&str; 7] = [ +pub const HOOK_EVENT_NAMES_WITH_MATCHERS: [&str; 8] = [ "PreToolUse", "PermissionRequest", "PostToolUse", @@ -40,6 +41,7 @@ pub const HOOK_EVENT_NAMES_WITH_MATCHERS: [&str; 7] = [ "PostCompact", "SessionStart", "SubagentStart", + "SubagentStop", ]; pub use events::compact::PostCompactRequest; @@ -57,6 +59,7 @@ pub use events::session_start::SessionStartOutcome; pub use events::session_start::SessionStartRequest; pub use events::session_start::SessionStartSource; pub use events::session_start::SessionStartTarget; +pub use events::stop::StopHookTarget; pub use events::stop::StopOutcome; pub use events::stop::StopRequest; pub use events::user_prompt_submit::UserPromptSubmitOutcome; @@ -87,6 +90,7 @@ pub fn hook_event_key_label(event_name: HookEventName) -> &'static str { HookEventName::SessionStart => "session_start", HookEventName::UserPromptSubmit => "user_prompt_submit", HookEventName::SubagentStart => "subagent_start", + HookEventName::SubagentStop => "subagent_stop", HookEventName::Stop => "stop", } } diff --git a/codex-rs/hooks/src/schema.rs b/codex-rs/hooks/src/schema.rs index 96d5f790be..8b11407b65 100644 --- a/codex-rs/hooks/src/schema.rs +++ b/codex-rs/hooks/src/schema.rs @@ -29,6 +29,8 @@ const USER_PROMPT_SUBMIT_INPUT_FIXTURE: &str = "user-prompt-submit.command.input const USER_PROMPT_SUBMIT_OUTPUT_FIXTURE: &str = "user-prompt-submit.command.output.schema.json"; const SUBAGENT_START_INPUT_FIXTURE: &str = "subagent-start.command.input.schema.json"; const SUBAGENT_START_OUTPUT_FIXTURE: &str = "subagent-start.command.output.schema.json"; +const SUBAGENT_STOP_INPUT_FIXTURE: &str = "subagent-stop.command.input.schema.json"; +const SUBAGENT_STOP_OUTPUT_FIXTURE: &str = "subagent-stop.command.output.schema.json"; const STOP_INPUT_FIXTURE: &str = "stop.command.input.schema.json"; const STOP_OUTPUT_FIXTURE: &str = "stop.command.output.schema.json"; @@ -91,6 +93,8 @@ pub(crate) enum HookEventNameWire { UserPromptSubmit, #[serde(rename = "SubagentStart")] SubagentStart, + #[serde(rename = "SubagentStop")] + SubagentStop, #[serde(rename = "Stop")] Stop, } @@ -399,6 +403,21 @@ pub(crate) struct StopCommandOutputWire { pub reason: Option, } +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)] +#[serde(rename_all = "camelCase")] +#[serde(deny_unknown_fields)] +#[schemars(rename = "subagent-stop.command.output")] +pub(crate) struct SubagentStopCommandOutputWire { + #[serde(flatten)] + pub universal: HookUniversalOutputWire, + #[serde(default)] + pub decision: Option, + /// Claude requires `reason` when `decision` is `block`; we enforce that + /// semantic rule during output parsing rather than in the JSON schema. + #[serde(default)] + pub reason: Option, +} + #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] pub(crate) enum BlockDecisionWire { #[serde(rename = "block")] @@ -495,6 +514,27 @@ pub(crate) struct StopCommandInput { pub last_assistant_message: NullableString, } +#[derive(Debug, Clone, Serialize, JsonSchema)] +#[serde(deny_unknown_fields)] +#[schemars(rename = "subagent-stop.command.input")] +pub(crate) struct SubagentStopCommandInput { + 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 agent_transcript_path: NullableString, + pub cwd: String, + #[schemars(schema_with = "subagent_stop_hook_event_name_schema")] + pub hook_event_name: String, + pub model: String, + #[schemars(schema_with = "permission_mode_schema")] + pub permission_mode: String, + pub stop_hook_active: bool, + pub agent_id: String, + pub agent_type: String, + pub last_assistant_message: NullableString, +} + pub fn write_schema_fixtures(schema_root: &Path) -> anyhow::Result<()> { let generated_dir = schema_root.join(GENERATED_DIR); ensure_empty_dir(&generated_dir)?; @@ -563,6 +603,14 @@ pub fn write_schema_fixtures(schema_root: &Path) -> anyhow::Result<()> { &generated_dir.join(SUBAGENT_START_OUTPUT_FIXTURE), schema_json::()?, )?; + write_schema( + &generated_dir.join(SUBAGENT_STOP_INPUT_FIXTURE), + schema_json::()?, + )?; + write_schema( + &generated_dir.join(SUBAGENT_STOP_OUTPUT_FIXTURE), + schema_json::()?, + )?; write_schema( &generated_dir.join(STOP_INPUT_FIXTURE), schema_json::()?, @@ -658,6 +706,10 @@ fn subagent_start_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema { string_const_schema("SubagentStart") } +fn subagent_stop_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema { + string_const_schema("SubagentStop") +} + fn stop_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema { string_const_schema("Stop") } @@ -730,8 +782,11 @@ mod tests { use super::STOP_OUTPUT_FIXTURE; use super::SUBAGENT_START_INPUT_FIXTURE; use super::SUBAGENT_START_OUTPUT_FIXTURE; + use super::SUBAGENT_STOP_INPUT_FIXTURE; + use super::SUBAGENT_STOP_OUTPUT_FIXTURE; use super::StopCommandInput; use super::SubagentStartCommandInput; + use super::SubagentStopCommandInput; use super::USER_PROMPT_SUBMIT_INPUT_FIXTURE; use super::USER_PROMPT_SUBMIT_OUTPUT_FIXTURE; use super::UserPromptSubmitCommandInput; @@ -791,6 +846,12 @@ mod tests { SUBAGENT_START_OUTPUT_FIXTURE => { include_str!("../schema/generated/subagent-start.command.output.schema.json") } + SUBAGENT_STOP_INPUT_FIXTURE => { + include_str!("../schema/generated/subagent-stop.command.input.schema.json") + } + SUBAGENT_STOP_OUTPUT_FIXTURE => { + include_str!("../schema/generated/subagent-stop.command.output.schema.json") + } STOP_INPUT_FIXTURE => { include_str!("../schema/generated/stop.command.input.schema.json") } @@ -828,6 +889,8 @@ mod tests { USER_PROMPT_SUBMIT_OUTPUT_FIXTURE, SUBAGENT_START_INPUT_FIXTURE, SUBAGENT_START_OUTPUT_FIXTURE, + SUBAGENT_STOP_INPUT_FIXTURE, + SUBAGENT_STOP_OUTPUT_FIXTURE, STOP_INPUT_FIXTURE, STOP_OUTPUT_FIXTURE, ] { @@ -875,6 +938,11 @@ mod tests { .expect("serialize subagent start input schema"), ) .expect("parse subagent start input schema"); + let subagent_stop: Value = serde_json::from_slice( + &schema_json::() + .expect("serialize subagent stop input schema"), + ) + .expect("parse subagent stop input schema"); let stop: Value = serde_json::from_slice( &schema_json::().expect("serialize stop input schema"), ) @@ -888,6 +956,7 @@ mod tests { &post_compact, &user_prompt_submit, &subagent_start, + &subagent_stop, &stop, ] { assert_eq!(schema["properties"]["turn_id"]["type"], "string"); diff --git a/codex-rs/protocol/src/protocol.rs b/codex-rs/protocol/src/protocol.rs index 36fca9fbab..1d6f1e51ff 100644 --- a/codex-rs/protocol/src/protocol.rs +++ b/codex-rs/protocol/src/protocol.rs @@ -1459,6 +1459,7 @@ pub enum HookEventName { SessionStart, UserPromptSubmit, SubagentStart, + SubagentStop, Stop, } diff --git a/codex-rs/tui/src/bottom_pane/hooks_browser_view.rs b/codex-rs/tui/src/bottom_pane/hooks_browser_view.rs index 1202265aa2..ce31abf404 100644 --- a/codex-rs/tui/src/bottom_pane/hooks_browser_view.rs +++ b/codex-rs/tui/src/bottom_pane/hooks_browser_view.rs @@ -737,6 +737,7 @@ fn event_label(event_name: HookEventName) -> &'static str { HookEventName::SessionStart => "SessionStart", HookEventName::UserPromptSubmit => "UserPromptSubmit", HookEventName::SubagentStart => "SubagentStart", + HookEventName::SubagentStop => "SubagentStop", HookEventName::Stop => "Stop", } } @@ -751,6 +752,7 @@ fn event_description(event_name: HookEventName) -> &'static str { HookEventName::SessionStart => "When a new session starts", HookEventName::UserPromptSubmit => "When the user submits a prompt", HookEventName::SubagentStart => "When a subagent is created", + HookEventName::SubagentStop => "Right before a subagent ends its turn", HookEventName::Stop => "Right before Codex ends its turn", } } diff --git a/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_events.snap b/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_events.snap index 836a65c3f1..eaf06f6c45 100644 --- a/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_events.snap +++ b/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_events.snap @@ -15,6 +15,7 @@ expression: "render_lines(&view, 112)" SessionStart 0 0 When a new session starts UserPromptSubmit 0 0 When the user submits a prompt SubagentStart 0 0 When a subagent is created + SubagentStop 0 0 Right before a subagent ends its turn Stop 0 0 Right before Codex ends its turn Press enter to view hooks; esc to close diff --git a/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_events_with_issues.snap b/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_events_with_issues.snap index fabd9c1707..7dc71463dc 100644 --- a/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_events_with_issues.snap +++ b/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_events_with_issues.snap @@ -19,6 +19,7 @@ expression: "render_lines(&view, 112)" SessionStart 0 0 When a new session starts UserPromptSubmit 0 0 When the user submits a prompt SubagentStart 0 0 When a subagent is created + SubagentStop 0 0 Right before a subagent ends its turn Stop 0 0 Right before Codex ends its turn Press enter to view hooks; esc to close diff --git a/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_events_with_review_column.snap b/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_events_with_review_column.snap index dd4e5e33b5..c18657d8a1 100644 --- a/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_events_with_review_column.snap +++ b/codex-rs/tui/src/bottom_pane/snapshots/codex_tui__bottom_pane__hooks_browser_view__tests__hooks_browser_events_with_review_column.snap @@ -17,6 +17,7 @@ expression: "render_lines(&view, 112)" SessionStart 0 0 0 When a new session starts UserPromptSubmit 0 0 0 When the user submits a prompt SubagentStart 0 0 0 When a subagent is created + SubagentStop 0 0 0 Right before a subagent ends its turn Stop 0 0 0 Right before Codex ends its turn Press t to trust all; enter to review hooks; esc to close diff --git a/codex-rs/tui/src/chatwidget/snapshots/codex_tui__chatwidget__tests__hooks_popup_shows_list_diagnostics.snap b/codex-rs/tui/src/chatwidget/snapshots/codex_tui__chatwidget__tests__hooks_popup_shows_list_diagnostics.snap index 9a532f563d..99922ac630 100644 --- a/codex-rs/tui/src/chatwidget/snapshots/codex_tui__chatwidget__tests__hooks_popup_shows_list_diagnostics.snap +++ b/codex-rs/tui/src/chatwidget/snapshots/codex_tui__chatwidget__tests__hooks_popup_shows_list_diagnostics.snap @@ -18,6 +18,7 @@ expression: popup SessionStart 0 0 When a new session starts UserPromptSubmit 0 0 When the user submits a prompt SubagentStart 0 0 When a subagent is created + SubagentStop 0 0 Right before a subagent ends its turn Stop 0 0 Right before Codex ends its turn Press enter to view hooks; esc to close diff --git a/codex-rs/tui/src/chatwidget/tests/helpers.rs b/codex-rs/tui/src/chatwidget/tests/helpers.rs index f6a6001bdb..3ed508769c 100644 --- a/codex-rs/tui/src/chatwidget/tests/helpers.rs +++ b/codex-rs/tui/src/chatwidget/tests/helpers.rs @@ -1573,6 +1573,7 @@ fn hook_event_label(event_name: codex_app_server_protocol::HookEventName) -> &'s codex_app_server_protocol::HookEventName::SessionStart => "SessionStart", codex_app_server_protocol::HookEventName::UserPromptSubmit => "UserPromptSubmit", codex_app_server_protocol::HookEventName::SubagentStart => "SubagentStart", + codex_app_server_protocol::HookEventName::SubagentStop => "SubagentStop", codex_app_server_protocol::HookEventName::Stop => "Stop", } } diff --git a/codex-rs/tui/src/history_cell/hook_cell.rs b/codex-rs/tui/src/history_cell/hook_cell.rs index 824fdc1de8..6a4e8498d9 100644 --- a/codex-rs/tui/src/history_cell/hook_cell.rs +++ b/codex-rs/tui/src/history_cell/hook_cell.rs @@ -721,6 +721,7 @@ fn hook_event_label(event_name: HookEventName) -> &'static str { HookEventName::SessionStart => "SessionStart", HookEventName::UserPromptSubmit => "UserPromptSubmit", HookEventName::SubagentStart => "SubagentStart", + HookEventName::SubagentStop => "SubagentStop", HookEventName::Stop => "Stop", } }