Hooks: distinguish subagent events from main agent

Open 💬 9 comments Opened Mar 30, 2026 by WaelBKZ

💡 Likely answer: A maintainer (eternal-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?

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_

View original on GitHub ↗

9 Comments

WaelBKZ · 3 months ago

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

WaelBKZ · 3 months ago

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

WaelBKZ · 3 months ago

Gentle ping @eternal-openai

jgmontoya · 3 months ago

This would be helpful!

ignatremizov · 3 months ago

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 · 3 months ago

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

sanyathoque · 2 months ago

Strong +1 on this. For external orchestration and audit tooling, having subagent identity in every hook event is the difference between reliable correlation and guesswork.

One compatibility detail that would help downstream parsers:

keep session_id as-is
add optional agent_id / agent_type
explicitly document that main-agent events omit those fields

That gives deterministic filtering without breaking existing hooks and also composes cleanly with run lifecycle proposals like #20943.

eternal-openai contributor · 2 months ago

Thanks guys! We're working on the subagent hooks

oxysoft · 2 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.