SubagentStart and SubagentStop Hooks - Claude Code

SubagentStart and SubagentStop hooks fire around subagent lifecycles - at spawn and at completion.

What it does

SubagentStart runs when the main agent delegates to a subagent. It receives the subagent definition and the initial task. SubagentStop runs when the subagent finishes. Together they let you track parallel work, enforce concurrency limits, log per-agent metrics, or annotate the returned result before it reaches the main session.

When to use it

• Counting active subagents to cap parallelism.
• Tagging logs with the subagent name for observability.
• Adding project-specific context to every subagent prompt via Start.
• Normalizing or sanitizing subagent return values via Stop.

Gotchas

• Many subagents running in parallel means these hooks fire a lot. Keep them lightweight.
• Start hooks that modify the task too aggressively can confuse the subagent.
• Stop hooks that rewrite results hide what the subagent actually said. Log originals.

Official docs: https://code.claude.com/docs/en/hooks.md#subagentstart