mirror of
https://github.com/openai/codex.git
synced 2026-05-25 13:34:51 +00:00
eee3e60db3
# What <img width="1792" height="1024" alt="image" src="https://github.com/user-attachments/assets/8f81d232-5813-4994-a61d-e42a05a93a3e" /> `SubagentStop` runs when a thread-spawned subagent turn is about to finish. Thread-spawned subagents use `SubagentStop` instead of the normal root-agent `Stop` hook. Configured handlers match on `agent_type`. Hook input includes the normal stop fields plus: - `agent_id`: the child thread id. - `agent_type`: the resolved subagent type. - `agent_transcript_path`: the child subagent transcript path. - `transcript_path`: the parent thread transcript path. - `last_assistant_message`: the final assistant message from the child turn, when available. - `stop_hook_active`: `true` when the child is already continuing because an earlier stop-like hook blocked completion. `SubagentStop` shares the same completion-control semantics as `Stop`, scoped to the child turn: - No decision allows the child turn to finish. - `decision: "block"` with a non-empty `reason` records that reason as hook feedback and continues the child with that prompt. - `continue: false` stops the child turn. If `stopReason` is present, Codex surfaces it as the stop reason. # Lifecycle Scope Only thread-spawned subagents run `SubagentStop`. Internal/system subagents such as Review, Compact, MemoryConsolidation, and Other do not run normal `Stop` hooks and do not run `SubagentStop`. This avoids exposing synthetic matcher labels for internal implementation paths. # Stack 1. #22782: add `SubagentStart`. 2. This PR: add `SubagentStop`. 3. #22882: add subagent identity to normal hook inputs.
110 lines
3.6 KiB
Rust
110 lines
3.6 KiB
Rust
mod config_rules;
|
|
mod declarations;
|
|
mod engine;
|
|
pub(crate) mod events;
|
|
mod legacy_notify;
|
|
mod output_spill;
|
|
mod registry;
|
|
mod schema;
|
|
mod types;
|
|
|
|
use codex_protocol::protocol::HookEventName;
|
|
|
|
pub use config_rules::hook_states_from_stack;
|
|
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; 10] = [
|
|
"PreToolUse",
|
|
"PermissionRequest",
|
|
"PostToolUse",
|
|
"PreCompact",
|
|
"PostCompact",
|
|
"SessionStart",
|
|
"UserPromptSubmit",
|
|
"SubagentStart",
|
|
"SubagentStop",
|
|
"Stop",
|
|
];
|
|
|
|
/// Hook event names whose matcher fields are meaningful during dispatch.
|
|
///
|
|
/// 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; 8] = [
|
|
"PreToolUse",
|
|
"PermissionRequest",
|
|
"PostToolUse",
|
|
"PreCompact",
|
|
"PostCompact",
|
|
"SessionStart",
|
|
"SubagentStart",
|
|
"SubagentStop",
|
|
];
|
|
|
|
pub use events::compact::PostCompactRequest;
|
|
pub use events::compact::PreCompactOutcome;
|
|
pub use events::compact::PreCompactRequest;
|
|
pub use events::compact::StatelessHookOutcome;
|
|
pub use events::permission_request::PermissionRequestDecision;
|
|
pub use events::permission_request::PermissionRequestOutcome;
|
|
pub use events::permission_request::PermissionRequestRequest;
|
|
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;
|
|
pub use events::session_start::SessionStartRequest;
|
|
pub use events::session_start::SessionStartSource;
|
|
pub use events::session_start::StartHookTarget;
|
|
pub use events::stop::StopHookTarget;
|
|
pub use events::stop::StopOutcome;
|
|
pub use events::stop::StopRequest;
|
|
pub use events::user_prompt_submit::UserPromptSubmitOutcome;
|
|
pub use events::user_prompt_submit::UserPromptSubmitRequest;
|
|
pub use legacy_notify::legacy_notify_json;
|
|
pub use legacy_notify::notify_hook;
|
|
pub use registry::HookListOutcome;
|
|
pub use registry::Hooks;
|
|
pub use registry::HooksConfig;
|
|
pub use registry::command_from_argv;
|
|
pub use registry::list_hooks;
|
|
pub use schema::write_schema_fixtures;
|
|
pub use types::Hook;
|
|
pub use types::HookEvent;
|
|
pub use types::HookEventAfterAgent;
|
|
pub use types::HookPayload;
|
|
pub use types::HookResponse;
|
|
pub use types::HookResult;
|
|
|
|
/// Returns the hook event label used in persisted hook-state keys.
|
|
pub fn hook_event_key_label(event_name: HookEventName) -> &'static str {
|
|
match event_name {
|
|
HookEventName::PreToolUse => "pre_tool_use",
|
|
HookEventName::PermissionRequest => "permission_request",
|
|
HookEventName::PostToolUse => "post_tool_use",
|
|
HookEventName::PreCompact => "pre_compact",
|
|
HookEventName::PostCompact => "post_compact",
|
|
HookEventName::SessionStart => "session_start",
|
|
HookEventName::UserPromptSubmit => "user_prompt_submit",
|
|
HookEventName::SubagentStart => "subagent_start",
|
|
HookEventName::SubagentStop => "subagent_stop",
|
|
HookEventName::Stop => "stop",
|
|
}
|
|
}
|
|
|
|
/// Builds the persisted config-state key for one discovered hook handler.
|
|
pub fn hook_key(
|
|
key_source: &str,
|
|
event_name: HookEventName,
|
|
group_index: usize,
|
|
handler_index: usize,
|
|
) -> String {
|
|
format!(
|
|
"{key_source}:{}:{group_index}:{handler_index}",
|
|
hook_event_key_label(event_name)
|
|
)
|
|
}
|