Hooks: distinguish subagent events from main agent

[WaelBKZ]

What variant of Codex are you using?

CLI

What feature would you like to see?

Problem

All hook events (SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop) fire identically for both the main agent and subagent sessions. The hook input JSON contains no field to distinguish between the two, making it impossible for hook scripts to apply logic only to the main session or only to subagents.

Claude Code already solves this

Claude Code includes agent_id and agent_type as common fields on all hook event inputs. From the hooks documentation: these fields are present for subagents and --agent sessions, allowing hook scripts to filter, route, or log differently based on context. This was added in v2.1.69: "Added agent_id (for subagents) and agent_type (for subagents and --agent) to hook events".

Codex already knows when a session is a subagent (SessionSource::SubAgent(...) at codex-rs/protocol/src/protocol.rs:2365) and already has a stable thread/session ID for each child session (e.g. codex-rs/core/src/tools/handlers/multi_agents/spawn.rs:163). Hooks just don't receive that metadata.

Additional information

No response

[WaelBKZ]

(Since I saw you worked on adding hooks in the past: @eternal-openai ; thanks for adding those by the way!)

[WaelBKZ]

Also as a follow-up it'd be great to have a way to have a post-compaction hook!

[WaelBKZ]

Gentle ping @eternal-openai

[jgmontoya]

This would be helpful!

[ignatremizov]

This would also unblock orchestration-based hook workflows where the root session owns lifecycle state, but spawned coder/reviewer subagents run in the same worktree and currently receive the same hook events.

Concrete use case: a root orchestrator session installs a Stop/SessionStart hook to enforce review-loop or hardening closure, while child agents should either no-op or be filtered out reliably. Today scripts can approximate this with transcript-keyed state, but it is indirect and fragile. Having hook inputs expose at least agent_id/agent_type, and ideally parent_thread_id/depth/agent_role for ThreadSpawn, would let hooks explicitly target root sessions or specific supervisor roles without guessing from state files.

[ignatremizov]

Pairing this with hot reloading hooks (#17636) would make this a very powerful workflow