Support asynchronous command hooks (#37533)

## Why

Hook configurations can mark command handlers as asynchronous, but Codex previously skipped those handlers outside `SessionEnd`.

## What changed

- Run asynchronous command hooks in the background with a per-session concurrency limit, while keeping `SessionEnd` hooks synchronous.
- Prevent asynchronous hooks from blocking, stopping, rewriting, or otherwise controlling the operation that launched them.
- Deliver warnings and additional context at safe turn boundaries: inject results into an active turn after sampling, or buffer them ahead of the next user prompt when the session is idle.
- Preserve in-flight hooks across configuration reloads, scope spilled output to the thread, and abort outstanding work during session shutdown.

## Testing

Add unit and integration coverage for background scheduling, concurrency, output parsing, active and idle result delivery, configuration reloads, and shutdown cleanup.

GitOrigin-RevId: 8094552e4afe7b47b09a61bb575bb20f4e491d8d
This commit is contained in:
Abhinav
2026-08-08 04:24:12 +00:00
committed by copyberry
parent 61a3dd4387
commit 6f647caa9b
29 changed files with 1514 additions and 429 deletions
+110 -3
View File
@@ -29,12 +29,15 @@ use codex_protocol::protocol::CodexErrorInfo;
use codex_protocol::protocol::EventMsg;
use codex_protocol::protocol::HookCompletedEvent;
use codex_protocol::protocol::HookEventName;
use codex_protocol::protocol::HookExecutionMode;
use codex_protocol::protocol::HookOutputEntryKind;
use codex_protocol::protocol::HookRunStatus;
use codex_protocol::protocol::HookRunSummary;
use codex_protocol::protocol::HookSource;
use codex_protocol::protocol::HookStartedEvent;
use codex_protocol::protocol::SessionSource;
use codex_protocol::protocol::SubAgentSource;
use codex_protocol::protocol::WarningEvent;
use codex_thread_store::ReadThreadParams;
use serde_json::Value;
use tracing::instrument;
@@ -678,6 +681,51 @@ pub(crate) async fn reject_pending_input(
}
}
/// Processes finished async hook results at a safe turn boundary.
///
/// Before the user prompt, records additional context directly into conversation
/// history so results from a previous turn appear before the new prompt. After
/// sampling, injects context into the active turn's pending-input queue so it
/// reaches the next sampling request. Warnings and telemetry are handled in both
/// cases.
pub(crate) async fn drain_async_hook_results(
sess: &Arc<Session>,
turn_context: &Arc<TurnContext>,
before_user_prompt: bool,
) {
while let Ok(result) = sess.async_hook_results.try_recv() {
let additional_contexts = result
.run
.entries
.iter()
.filter(|entry| entry.kind == HookOutputEntryKind::Context)
.map(|entry| entry.text.clone())
.collect::<Vec<_>>();
if before_user_prompt {
record_additional_contexts(sess, turn_context, additional_contexts).await;
} else if !additional_contexts.is_empty() {
let _ = sess
.inject_if_running(additional_context_messages(additional_contexts))
.await;
}
for entry in &result.run.entries {
if entry.kind == HookOutputEntryKind::Warning {
sess.send_event(
turn_context,
EventMsg::Warning(WarningEvent {
message: entry.text.clone(),
}),
)
.await;
}
}
emit_hook_completed_events(sess, turn_context, vec![result]).await;
}
}
async fn run_context_injecting_hook<Fut, Outcome>(
sess: &Arc<Session>,
turn_context: &Arc<TurnContext>,
@@ -734,7 +782,10 @@ async fn emit_hook_started_events(
turn_context: &Arc<TurnContext>,
preview_runs: Vec<HookRunSummary>,
) {
for run in preview_runs {
for run in preview_runs
.into_iter()
.filter(|run| run.execution_mode == HookExecutionMode::Sync)
{
sess.send_event(
turn_context,
EventMsg::HookStarted(HookStartedEvent {
@@ -754,8 +805,10 @@ pub(crate) async fn emit_hook_completed_events(
for completed in completed_events {
emit_hook_completed_metrics(turn_context, &completed);
track_hook_completed_analytics(sess, turn_context, &completed);
sess.send_event(turn_context, EventMsg::HookCompleted(completed))
.await;
if completed.run.execution_mode == HookExecutionMode::Sync {
sess.send_event(turn_context, EventMsg::HookCompleted(completed))
.await;
}
}
}
@@ -902,9 +955,12 @@ mod tests {
use pretty_assertions::assert_eq;
use super::additional_context_messages;
use super::emit_hook_completed_events;
use super::emit_hook_started_events;
use super::hook_run_analytics_payload;
use super::hook_run_metric_tags;
use crate::session::tests::make_session_and_context;
use crate::session::tests::make_session_and_context_with_rx;
use codex_protocol::protocol::HookCompletedEvent;
use codex_protocol::protocol::HookRunSummary;
use codex_utils_absolute_path::test_support::PathBufExt;
@@ -946,6 +1002,57 @@ mod tests {
);
}
#[tokio::test]
async fn hook_lifecycle_notifications_only_report_synchronous_runs() {
let (session, turn_context, events) = make_session_and_context_with_rx().await;
let mut synchronous_run = sample_hook_run(HookRunStatus::Running, HookSource::User);
synchronous_run.id = "synchronous-hook".to_string();
let mut asynchronous_run = synchronous_run.clone();
asynchronous_run.id = "asynchronous-hook".to_string();
asynchronous_run.execution_mode = HookExecutionMode::Async;
emit_hook_started_events(
&session,
&turn_context,
vec![asynchronous_run.clone(), synchronous_run.clone()],
)
.await;
let started = events.try_recv().expect("synchronous hook should start");
assert!(matches!(
started.msg,
codex_protocol::protocol::EventMsg::HookStarted(event)
if event.run.id == synchronous_run.id
));
assert!(events.try_recv().is_err());
asynchronous_run.status = HookRunStatus::Completed;
synchronous_run.status = HookRunStatus::Completed;
emit_hook_completed_events(
&session,
&turn_context,
vec![
HookCompletedEvent {
turn_id: Some(turn_context.sub_id.clone()),
run: asynchronous_run,
},
HookCompletedEvent {
turn_id: Some(turn_context.sub_id.clone()),
run: synchronous_run.clone(),
},
],
)
.await;
let completed = events.try_recv().expect("synchronous hook should complete");
assert!(matches!(
completed.msg,
codex_protocol::protocol::EventMsg::HookCompleted(event)
if event.run.id == synchronous_run.id
));
assert!(events.try_recv().is_err());
}
#[tokio::test]
async fn hook_run_analytics_payload_uses_completed_turn_id() {
let (_session, turn_context) = make_session_and_context().await;