Problem

When spawning agents with run_in_background=true, the Stop hook configured in .claude/settings.json does not execute when the agent completes.

Steps to Reproduce

1. Configure a Stop hook in .claude/settings.json:

{
  "hooks": {
    "Stop": {
      "type": "shell",
      "command": "bash",
      "args": ["-c", "echo 'Stop hook running' && bash scripts/gate-test.sh"]
    }
  }
}

2. Spawn a background agent:

Task(
  subagent_type="general-purpose",
  prompt="Implement feature X",
  run_in_background=True
)

3. Observe: Agent completes but Stop hook never executes (no hook output in logs)

Expected Behavior

Stop hooks should execute when background agents complete, providing quality gate enforcement for async work.

Actual Behavior

Background agents bypass Stop hooks entirely. The agent output file shows no hook execution logs.

Impact

• Quality gates (tests, linting, policy checks) are bypassed
• Background agents can ship broken code undetected
• Defeats the purpose of automated quality enforcement
• Makes parallel execution unsafe for production workflows

Evidence

Agent output shows completion but no hook execution:

• No hook start message
• No gate script output
• File ends immediately after agent's final message

Workaround

Don't use run_in_background for agents requiring quality gates. But this eliminates performance benefits of parallel execution.

Suggested Fix

Either:

1. Trigger Stop hooks for background agents when they complete
2. Provide alternative enforcement (OnBackgroundAgentComplete hook?)
3. Document limitation clearly in Task tool docs

Environment

• Claude Code CLI version: 2.1.32
• Platform: macOS (Darwin 23.6.0)