Add BackgroundTasksIdle notification event

[StevenVester]

Problem

When using background agents (e.g., launching 10 parallel review agents), Claude Code triggers the terminal bell/notification after its initial response — "agents launched, waiting for results." This fires the same notification as when Claude is truly idle and waiting for user input.

As a user, I get pinged repeatedly for intermediate status messages while agents are still running in the background. The only notification I care about is when all work is truly done and Claude needs my input.

Current behavior

• Notification hook fires whenever Claude responds, regardless of whether background agents are still running
• No way to distinguish "waiting with active background tasks" from "genuinely idle, needs user input"
• Terminal bell (iTerm/other terminals) treats both the same

Proposed solution

Add a BackgroundTasksIdle event (or similar) that fires only when all background agents/tasks have completed and Claude is genuinely waiting for user input. This would allow users to:

1. Suppress notifications for intermediate "agents launched" messages
2. Only get pinged when they actually need to look at the screen
3. Configure hooks that distinguish between "busy-waiting" and "done"

Alternatively, expose background task state in the Notification hook context so users can filter with a matcher.

Workaround

Currently the only workaround is disabling notification sounds entirely (macOS System Settings → Notifications → iTerm2 → Sound off), which also silences legitimate completion notifications.

Context

This becomes especially noticeable when using patterns like:

• Launching multiple parallel agents for research/review
• Running long background commands with run_in_background
• Any workflow where Claude responds "started X, waiting..." before the real result arrives

🤖 Generated with Claude Code

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.