Claude Code agents don't clean up spawned subprocesses

Claude Code agents don't clean up spawned subprocesses

Summary

When Claude Code agents spawn subprocesses (e.g., pytest with parallel workers), those processes are not automatically cleaned up when the agent session ends or crashes. This results in hundreds of orphaned processes consuming system resources.

Steps to Reproduce

1. Have Claude Code run tests that spawn multiple worker processes (e.g., pytest tests/ -q)
2. Agent spawns 500+ pytest worker processes
3. Exit/kill the terminal or Claude Code session
4. Observe that all spawned subprocesses remain running as orphaned processes

Expected Behavior

• Agent should track all spawned subprocesses
• On agent exit (normal or abnormal), all child processes should be automatically terminated
• Process groups should be used to ensure cleanup of entire process trees
• Timeout mechanisms should kill hung/stuck processes

Actual Behavior

• 550+ pytest processes remained running after agent session ended
• Processes became orphaned zombies consuming CPU/memory
• No automatic cleanup mechanism
• Required manual pkill to terminate all processes
• System experienced sustained high CPU usage and thermal load

Environment

• OS: macOS
• Claude Code: CLI version
• Model: Sonnet 4.5

Impact

• Severity: High - System resources exhausted
• Multiple recurrences of the same issue
• Required manual intervention each time

Suggested Fix

Implement process lifecycle management:

1. Use process group management when spawning subprocesses
2. Track all spawned PIDs in agent state
3. Register cleanup handlers (atexit, signal handlers)
4. On agent exit: terminate entire process group
5. Implement watchdog for hung processes (timeout + force kill)

Additional Context

This issue occurred while an agent was running test suites. The problem recurred multiple times, requiring manual cleanup each time.