Expose CollabAgentSpawn{Begin,End} as hook events

Resolved 💬 2 comments Opened Mar 23, 2026 by mr-lee Closed May 2, 2026
💡 Likely answer: A maintainer (etraut-openai, contributor) responded on this thread — see the highlighted reply below.

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 ↗

2 Comments

etraut-openai contributor · 3 months ago

This feature request hasn't received enough upvotes, so I'm closing it.

oxysoft · 3 months ago

Indexed this hook ticket in the umbrella tracker: #21753

Goal: collect the scattered Codex hook requests and bugs into one parity matrix for Full Claude Code Hook Parity (29+), while preserving this issue as the detailed thread for its specific behavior.