Expose CollabAgentSpawn{Begin,End} as hook events

Resolved 💬 2 comments Opened Mar 23, 2026 by mr-lee Closed May 2, 2026

What variant of Codex are you using?

CLI

What feature would you like to see?

I'd like to hook into subagent (collaboration agent) lifecycle events via hooks.json, the same way I can hook into SessionStart, UserPromptSubmit, and Stop today.

Specifically, I'm requesting that CollabAgentSpawnBegin and CollabAgentSpawnEnd be exposed as configurable hook events in hooks.json.

The internal protocol already defines these events with rich data:

  • CollabAgentSpawnBeginEvent: call_id, sender_thread_id, prompt, model, reasoning_effort
  • CollabAgentSpawnEndEvent: call_id, sender_thread_id, new_thread_id, new_agent_nickname, new_agent_role, prompt, status

This data is exactly what's needed to track subagent delegation — which agents were spawned, their parent/child relationships, what they were asked to do, and whether they succeeded.

Use case: I'm hooking into agent lifecycles to understand subagent delegation patterns — which subagents get spawned, how they relate to parent sessions, and their outcomes. The existing hooks cover the main agent loop well, but subagent spawning/completion is invisible from the hook surface today.

This seems aligned with the lifecycle hooks work mentioned in #13498 (which scopes "subagent boundaries") and the broader hooks expansion tracked in #2109.

Additional information

The hook engine architecture already supports this cleanly — each hook event follows the same pattern (enum variant + schema + dispatcher entry + registry method). The data structures in the protocol are already perfectly shaped for hook exposure. The gap is purely in the hooks.json engine wiring.

Happy to discuss the use case in more detail if helpful.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗