[FEATURE] Allow suppressing background task notifications via Notification hook

[FEATURE] Allow suppressing background task notifications via Notification hook

Problem

There's no way to programmatically filter or suppress background task completion notifications. This causes issues when:

1. Long-running processes (servers, games, watchers) complete — Claude responds unnecessarily
2. Expected failures — A task fails as expected but still triggers a notification
3. Noise reduction — Some background tasks don't need Claude's attention when they complete (e.g., sleep check-in jobs)

Current State

The Notification hook exists but has limitations:

• Cannot block/suppress notifications (no gate behavior)
• Limited notification types: permission_prompt, idle_prompt, auth_success, elicitation_dialog
• No background task notification type to match on

PostToolUse hook fires at task launch time (when run_in_background: true returns immediately), not at task completion time, so it can't be used to filter completion notifications.

Proposed Solution

Two changes to the Notification hook:

1. Add background_task_complete notification type

Allow matching on background task completions:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "background_task_complete",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/filter-bg-task.sh"
          }
        ]
      }
    ]
  }
}

2. Add gate behavior to allow suppression

Currently Notification hooks can only run commands but not prevent the notification. Adding gate behavior would allow:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "background_task_complete",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/filter-bg-task.sh",
            "behavior": "gate"
          }
        ]
      }
    ]
  }
}

If the hook exits non-zero, the notification is suppressed.

Environment variables passed to hook:

• CLAUDE_NOTIFICATION_TYPE: background_task_complete
• CLAUDE_TASK_ID: ID of the completed task
• CLAUDE_TASK_STATUS: success | failure | timeout
• CLAUDE_TASK_DESCRIPTION: Short description of the task

Example Use Cases

1. Suppress notifications for sleep check-in jobs

#!/bin/bash
# ~/.claude/hooks/filter-bg-task.sh

# Suppress notifications for "sleep" check-in jobs
if [[ "$CLAUDE_TASK_DESCRIPTION" == *"check on"* ]]; then
  exit 1  # Suppress
fi

exit 0  # Allow

2. Only notify on failures

#!/bin/bash
if [[ "$CLAUDE_TASK_STATUS" == "success" ]]; then
  exit 1  # Suppress successful completions
fi
exit 0

3. Route to external notification system and suppress internal

#!/bin/bash
curl -s -d "Task completed: $CLAUDE_TASK_STATUS" ntfy.sh/my-claude-tasks
exit 1  # Suppress internal notification

Related Issues

• #18544 — Add setting to disable automatic background task completion notifications
• #11716 — Background processes cause infinite system-reminders and token exhaustion
• #13249 — Background shell reminders persist after KillShell

---

🤖 Generated with Claude Code