Add SubagentStart hook

[abhinav-oai]

What

SubagentStart runs once when Codex creates a thread-spawned subagent, before that child sends its first model request. Thread-spawned subagents use SubagentStart instead of the normal root-agent SessionStart hook.

Configured handlers match on the subagent agent_type, using the same value passed to spawn_agent. When no agent type is specified, Codex uses the default agent type.

Hook input includes the normal session-start fields plus:

• agent_id: the child thread id.
• agent_type: the resolved subagent type.

SubagentStart may return hookSpecificOutput.additionalContext. That context is added to the child conversation before the first model request.

Lifecycle Scope

Only thread-spawned subagents run SubagentStart.

Internal/system subagents such as Review, Compact, MemoryConsolidation, and Other do not run normal SessionStart hooks and do not run SubagentStart. This avoids exposing synthetic matcher labels for internal implementation paths.

Also the SessionStart hook no longer fires for subagents, this matches behavior with other coding agents' implementation

Stack

1. This PR: add SubagentStart.
2. Add SubagentStop hook #22873: add SubagentStop.
3. [codex] Add subagent identity to hook inputs #22882: add subagent identity to normal hook inputs.

[abhinav-oai]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8dfeb972c7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[sayan-oai]

codex finding not specific to this pr, feel free to ignore if wrong:

the parser doesnt verify the hookEventName is actually the corresponding hook, so itd accept the equivalently shaped SessionStart hook event because we dont validate the name

[abhinav-oai]

this is true but only catches a hook-author mistake

hooks.json remains the dispatch source of truth while hookSpecificOutput.hookEventName is not used to route or authorize behavior