Before the subagent reads its first prompt
The Agent tool spawns a subagent, a separate Claude with its own context that module 08 covers. You might want to inject context before that subagent reads anything. That is when SubagentStart runs, before its first prompt. The hook can hand the subagent context. It cannot stop the spawn.
Matching an agent by type
You usually want a hook to fire for one agent type, not every spawn. The matcher filters the agent type: a built-in name such as general-purpose, Explore, or Plan, a custom name from a subagent file’s frontmatter, or an anchored plugin-scoped name. A hook aimed at Explore never fires for a custom agent under another name. The payload carries agent_id and agent_type, enough to tell which subagent spawned and which definition it runs from.
Context in, nothing out
Exit 0 starts the subagent with any valid hookSpecificOutput.additionalContext the hook returned, under hookEventName: "SubagentStart". That is the one JSON field the hooks reference lists for this event. Exit 1 starts it too, with valid JSON still applied. Exit 2 starts it as well. The stderr appears as a hook-error notice inside the subagent’s own transcript, for you and not for Claude, and the subagent proceeds.
You do not want Explore agents in this repository, so you match Explore and exit 2 with “no Explore agents here” on stderr.
The subagent starts anyway. Your sentence shows as a hook error inside the subagent’s transcript, which you may never open, and the parent session sees nothing. There is no exit code on this event that refuses a spawn.
The place to refuse one is PreToolUse with a matcher of Agent. There, tool_input carries subagent_type and exit 2 blocks the call before any subagent exists.