[FEATURE] Expose running background tasks to hooks via input JSON

Summary

Hooks currently have no way to know what background tasks (Bash with run_in_background: true, Task subagents) are currently running in the session. This information would enable hooks to make smarter decisions.

Use Cases

1. Prevent duplicate work: A PreToolUse hook could block starting a second build/test run if one is already in progress
2. Resource management: Limit concurrent background tasks to avoid overwhelming the system
3. Coordination: A Stop hook could check if background work is still pending before allowing Claude to finish
4. Debugging/observability: Log or display what's currently running

Proposed Solution

Add a background_tasks array to the hook input JSON:

{
  "session_id": "abc123",
  "transcript_path": "...",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "npm test", "run_in_background": true },
  "background_tasks": [
    {
      "task_id": "task-xyz",
      "tool_name": "Bash",
      "started_at": "2026-02-05T10:30:00Z",
      "description": "Running npm build"
    },
    {
      "task_id": "agent-abc",
      "tool_name": "Task",
      "subagent_type": "Explore",
      "started_at": "2026-02-05T10:31:00Z",
      "description": "Exploring codebase structure"
    }
  ]
}

Current Workaround

Users must implement their own tracking via session-scoped state files (keyed by session_id from hook input), but this is error-prone and duplicates information Claude Code already has internally.

Related

• #4321 - Session-Scoped In-Memory State for Hooks (auto-closed, broader feature request)

🤖 Generated with Claude Code