feat(session-notification): add question tool sound and skip background completion sound

[yhc509]

Summary

• Play notification sound when AI uses question tool requiring user input
• Skip notification sound when background/subagent tasks complete (only main session completion triggers sound)

Changes

• Add playSoundOnQuestion config option (default: true) - plays notification when question tool awaits user input
• Add skipSoundOnBackgroundCompletion config option (default: true) - prevents notification when background tasks complete
• Track background completion via message.part.updated event detecting [BACKGROUND TASK or [ALL BACKGROUND TASKS COMPLETE] markers
• Only play question notification for main sessions (not subagents)

Why

1. Question tool notification: Currently no notification when AI asks user to choose between options, causing users to miss prompts
2. Background task noise: When background tasks complete, parent session goes idle and plays sound - this is noisy when multiple subagents finish

Testing

• TypeScript typecheck passes
• All 11 session-notification tests pass
• Build successful

Closes #1453

---

Summary by cubic

Adds a sound when the question tool asks for user input and skips sounds when background/subagent tasks finish. Reduces noise while making prompts harder to miss. Addresses #1453.

• New Features
  • playSoundOnQuestion (default: true): plays sound on question tool, main sessions only.
  • skipSoundOnBackgroundCompletion (default: true): suppresses sound when idle is caused by background task completion.
  • Detects background completion via message.part.updated markers: “[BACKGROUND TASK” and “[ALL BACKGROUND TASKS COMPLETE]”.

^{Written for commit 57a5346. Summary will update on new commits.}

[github-actions]

Thank you for your contribution! Before we can merge this PR, we need you to sign our Contributor License Agreement (CLA).

To sign the CLA, please comment on this PR with:

I have read the CLA Document and I hereby sign the CLA

This is a one-time requirement. Once signed, all your future contributions will be automatically accepted.

---

I have read the CLA Document and I hereby sign the CLA

---

_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}

[cubic-dev-ai]

1 issue found across 1 file

Confidence score: 4/5

• backgroundCompletionTriggeredIdle in src/hooks/session-notification.ts is never cleared on user activity/cancelled notifications, which can suppress sound on later normal idle notifications
• Overall risk is low since this is a localized state-handling issue with limited scope, but it could affect notification behavior
• Pay close attention to src/hooks/session-notification.ts - ensure the background marker is reset appropriately

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="src/hooks/session-notification.ts">

<violation number="1" location="src/hooks/session-notification.ts:339">
P2: backgroundCompletionTriggeredIdle is never cleared on user activity/cancelled notifications, so a background marker can suppress sound on later normal idle notifications.</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Ask questions if you need clarification on any suggestion

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: backgroundCompletionTriggeredIdle is never cleared on user activity/cancelled notifications, so a background marker can suppress sound on later normal idle notifications.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/hooks/session-notification.ts, line 339:

<comment>backgroundCompletionTriggeredIdle is never cleared on user activity/cancelled notifications, so a background marker can suppress sound on later normal idle notifications.</comment>

<file context>
@@ -315,7 +328,39 @@ export function createSessionNotification(
+      
+      if (sessionID && partType === "text" && text) {
+        if (text.includes("[BACKGROUND TASK") || text.includes("[ALL BACKGROUND TASKS COMPLETE]")) {
+          backgroundCompletionTriggeredIdle.add(sessionID)
+        }
+      }
</file context>

[yhc509]

Thanks for the review! However, this appears to be a false positive.

Looking at lines 262-264:

const shouldSkipSound = mergedConfig.skipSoundOnBackgroundCompletion && 
  backgroundCompletionTriggeredIdle.has(sessionID)
backgroundCompletionTriggeredIdle.delete(sessionID)  // ← Cleared immediately after check

The flow is:

1. Background task completes → backgroundCompletionTriggeredIdle.add(sessionID) (line 339)
2. Session goes idle → executeNotification() is called
3. We check has() and immediately delete() (lines 263-264)
4. Next normal idle → Set no longer contains this sessionID → sound plays normally

Additionally, line 379 provides cleanup on session stop:

backgroundCompletionTriggeredIdle.delete(sessionInfo.id)

The marker is always cleared in one of two ways:

• When notification executes (line 264)
• When session stops (line 379)

There's no scenario where the marker persists to suppress later normal idle notifications.