[BUG] SubagentStart hooks not fired for background agents (run_in_background: true)

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

When spawning agents with run_in_background: true via the Agent tool, SubagentStart hooks are not fired. However, SubagentStop hooks are fired when the background agent completes, and PostToolUse hooks fire normally for tool calls made by background agents.

This creates an asymmetry where agent lifecycle events are only partially observable for background agents.

What Should Happen?

SubagentStart hooks should fire for all agents regardless of the run_in_background setting, matching the behavior of SubagentStop and PostToolUse. The hook should be dispatched at agent creation time — before the caller returns — rather than being tied to the synchronous execution path.

Error Messages/Logs

No error is produced. The hook is silently skipped — no error output, no warning. The only way to detect the problem is by observing that configured SubagentStart hooks never execute for background agents.

Steps to Reproduce

1. Register a SubagentStart hook in settings.json (or plugin hooks.json) that writes to a log file:

``json
{
"hooks": {
"SubagentStart": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "echo \"SubagentStart fired: agent_type=$CLAUDE_AGENT_TYPE\" >> /tmp/hook-log.txt"
}
]
}
],
"SubagentStop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "echo \"SubagentStop fired: agent_type=$CLAUDE_AGENT_TYPE\" >> /tmp/hook-log.txt"
}
]
}
]
}
}
``

1. In a conversation, ask Claude to spawn a foreground agent (e.g., an Explore agent). Check /tmp/hook-log.txt — both SubagentStart and SubagentStop appear. ✅
2. Now ask Claude to spawn a background agent (one launched with run_in_background: true). Check /tmp/hook-log.txt:

• SubagentStart does NOT appear for the background agent ❌
• SubagentStop does appear when the background agent completes ✅

Claude Model

Opus

Is this a regression?

I don't know

Claude Code Version

2.1.92 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

iTerm2

Additional Information

Evidence

Across 27 historical SubagentStart observations from foreground agents, all were captured correctly. In a session that spawned 2 background agents (Explore and plugin-dev:plugin-validator), zero SubagentStart events were captured, while both SubagentStop events and 75 PostToolUse events from those background agents were captured normally.

Impact on hook consumers

This breaks any tooling that relies on SubagentStart to:

• Create agent spans in OpenTelemetry traces (background agents appear flat under the main agent instead of hierarchically)
• Track agent lifecycle timing (no start timestamp available)
• Inject context into subagents at launch time (sync hooks on SubagentStart are the only mechanism for this)

Suggested fix

The root cause appears to be that the SubagentStart hook dispatch is in the synchronous agent execution path. When run_in_background: true, the agent is forked/backgrounded before reaching the hook dispatch point.

The fix would be to dispatch SubagentStart hooks before forking the agent into the background — at agent creation time, not at execution time. This ensures:

1. The hook fires regardless of foreground/background mode
2. Sync hooks (like context injection) can still modify the agent's initial context
3. The caller doesn't need to await the full agent execution

Alternatively, if the concern is blocking the main thread, the SubagentStart dispatch could be made async-safe while still guaranteed to fire.

Related issues

• #27755 — broader SubagentStart/SubagentStop unreliability for settings.json hooks (different root cause but same event surface)
• #32016 — feature request to include task prompt in SubagentStart payload
• #44307 — SubagentStart hook missing subagent_type field

I'd be happy to provide additional trace data or help test a fix if that would be useful.