[FEATURE] Batch background task notifications when Claude is idle

[FEATURE] Batch background task notifications when Claude is idle

Problem

When Claude is idle (waiting for background tasks to complete), notifications arrive one at a time. Each notification triggers a Claude response before the next notification is injected. This causes:

1. Wasted tokens — Claude responds to each completion individually ("Great, task X completed...") before seeing the next one
2. Suboptimal responses — Claude can't reason about multiple completed tasks together
3. Unnecessary back-and-forth — 5 completed tasks = 5 separate notification-response cycles

Current behavior:

[Claude idle, waiting for 3 background tasks]

[Notification 1] Task A completed
[Claude responds to A]
[Notification 2] Task B completed
[Claude responds to B]
[Notification 3] Task C completed
[Claude responds to C]

Desired behavior:

[Claude idle, waiting for 3 background tasks]

[Batch notification] 3 tasks completed:
  - Task A (success)
  - Task B (success)
  - Task C (success)
[Claude responds once, considering all results together]

Proposed Solution

Add settings to control notification batching when Claude is idle:

{
  "backgroundTaskNotifications": {
    "batchWhenIdle": true,
    "batchWindowMs": 2000,
    "maxBatchSize": 5
  }
}

Parameters:

• batchWhenIdle (boolean): Enable batching when Claude is idle waiting for tasks
• batchWindowMs (number): Time window to collect notifications before injecting batch (e.g., 2000ms)
• maxBatchSize (number): Max notifications to batch before forcing injection (e.g., 5)

Behavior:

• When Claude is idle and a background task completes, start a batch window
• Collect any additional completions within batchWindowMs
• If maxBatchSize is reached, inject immediately
• Inject all collected notifications as a single context block

Use Case

Parallelized workflows where multiple tasks complete around the same time:

• Running 5 test suites in parallel
• Launching multiple explore subagents
• Running builds + linting + type-checking concurrently

Currently this burns tokens on 5 separate "looks good" responses. With batching, Claude sees all results at once and can give one consolidated response.

Related Issues

• #22702 — Allow suppressing background task notifications via Notification hook
• #18544 — Add setting to disable automatic background task completion notifications
• #6854 — Non-blocking tasks / notification to main agent when background session finishes
• #11716 — Background processes cause infinite system-reminders

---

🤖 Generated with Claude Code