feat: add volume control for bundled sounds (0-100)

- Add hooks.sound_volume config option (0-100, default 50)
- Update playSound() with cross-platform volume support:
  - Windows: WPF MediaPlayer with Volume property
  - macOS: afplay -v flag (0.0-1.0)
  - Linux: paplay --volume flag (0-65536)
- Volume only applies to bundled WAV sounds, system sounds use OS volume
- Update getSoundPreference() to return SoundConfig object (style + volume)
- Update notification and stop hooks to pass volume to playSound
- Update tests for new SoundConfig return type and volume parameter

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: maystudios

packages/cli/src/hooks/maxsim-notification-sound.ts

@@ -27,11 +27,11 @@ function playSystemNotification(): void {
 }
 
 /** Play the best available notification sound for the current platform. */
-function playNotification(preference: 'bundled' | 'system'): void {
+function playNotification(preference: 'bundled' | 'system', volume: number): void {
   if (preference === 'bundled') {
     const wav = bundledSound('notification.wav');
     if (wav) {
-      playSound(wav);
+      playSound(wav, volume);
       return;
     }
     // Fall back to system sound if bundled WAV not found
@@ -41,7 +41,7 @@ function playNotification(preference: 'bundled' | 'system'): void {
 }
 
 readStdinJson<NotificationInput>((input) => {
-  const pref = getSoundPreference(input.cwd ?? process.cwd());
-  playNotification(pref);
+  const { style, volume } = getSoundPreference(input.cwd ?? process.cwd());
+  playNotification(style, volume);
   process.exit(0);
 });

packages/cli/src/hooks/maxsim-stop-sound.ts

@@ -28,11 +28,11 @@ function playSystemCompletion(): void {
 }
 
 /** Play the best available completion sound for the current platform. */
-function playCompletion(preference: 'bundled' | 'system'): void {
+function playCompletion(preference: 'bundled' | 'system', volume: number): void {
   if (preference === 'bundled') {
     const wav = bundledSound('complete.wav');
     if (wav) {
-      playSound(wav);
+      playSound(wav, volume);
       return;
     }
     // Fall back to system sound if bundled WAV not found
@@ -45,7 +45,7 @@ readStdinJson<StopInput>((input) => {
   if (input.stop_hook_active === true) {
     process.exit(0);
   }
-  const pref = getSoundPreference(input.cwd ?? process.cwd());
-  playCompletion(pref);
+  const { style, volume } = getSoundPreference(input.cwd ?? process.cwd());
+  playCompletion(style, volume);
   process.exit(0);
 });

packages/cli/src/hooks/shared.ts

@@ -32,19 +32,29 @@ export function isMaxsimProject(projectDir: string): boolean {
   }
 }
 
+/** Parsed sound config from .claude/maxsim/config.json. */
+export interface SoundConfig {
+  style: 'bundled' | 'system';
+  /** Volume 0–100. Only applies to bundled WAV sounds. */
+  volume: number;
+}
+
 /**
- * Read the sound preference from .claude/maxsim/config.json.
- * Returns 'bundled' (use WAV files) or 'system' (use OS system sounds).
- * Defaults to 'system' if config is missing or unreadable.
+ * Read sound preferences from .claude/maxsim/config.json.
+ * Returns style ('bundled' | 'system') and volume (0–100).
+ * Defaults to style='system', volume=50.
  */
-export function getSoundPreference(projectDir: string): 'bundled' | 'system' {
+export function getSoundPreference(projectDir: string): SoundConfig {
   try {
     const configPath = path.join(projectDir, CLAUDE_DIR, 'maxsim', 'config.json');
     const raw = fs.readFileSync(configPath, 'utf8');
     const config = JSON.parse(raw);
-    return config?.hooks?.sound_style === 'bundled' ? 'bundled' : 'system';
+    const style = config?.hooks?.sound_style === 'bundled' ? 'bundled' as const : 'system' as const;
+    const rawVol = Number(config?.hooks?.sound_volume);
+    const volume = Number.isFinite(rawVol) ? Math.max(0, Math.min(100, rawVol)) : 50;
+    return { style, volume };
   } catch {
-    return 'system';
+    return { style: 'system', volume: 50 };
   }
 }
 
@@ -111,40 +121,53 @@ export function bundledSound(name: string): string | null {
  * @param soundFile Absolute path to a WAV/MP3/etc. file, or a named system
  *                  sound token recognised by the platform helper (e.g. the
  *                  Windows-only SystemAsterisk token).
+ * @param volume    Volume 0–100. Only effective for file-based sounds (WAV/AIFF/OGA),
+ *                  not for named system sound tokens. Default: 50.
  */
-export function playSound(soundFile: string): void {
+export function playSound(soundFile: string, volume = 50): void {
   try {
+    const vol = Math.max(0, Math.min(100, volume));
+
     if (isWindows()) {
-      // PowerShell's SoundPlayer works with WAV files synchronously.
-      // For named system sounds (no extension) fall back to rundll32.
       const isWav = soundFile.toLowerCase().endsWith('.wav');
       if (isWav) {
-        // Use double-quoted string which handles spaces and most special chars
+        // Use WPF MediaPlayer for volume control on WAV files.
+        const volFraction = (vol / 100).toFixed(2);
         const escaped = soundFile.replace(/"/g, '\\"');
         spawnSync(
           'powershell',
           [
             '-NoProfile',
             '-NonInteractive',
             '-Command',
-            `$p="${escaped}"; (New-Object System.Media.SoundPlayer $p).PlaySync()`,
+            [
+              'Add-Type -AssemblyName PresentationCore;',
+              `$m = New-Object System.Windows.Media.MediaPlayer;`,
+              `$m.Open([uri]"${escaped}");`,
+              `$m.Volume = ${volFraction};`,
+              '$m.Play();',
+              'Start-Sleep -Milliseconds 1500;',
+              '$m.Close()',
+            ].join(' '),
           ],
-          { stdio: 'ignore' },
+          { stdio: 'ignore', timeout: 5000 },
         );
       } else {
-        // Named system sound token (e.g. "SystemAsterisk") or unsupported format —
-        // use the rundll32 winsound bridge.
+        // Named system sound token — no volume control available.
         spawnSync(
           'rundll32',
           ['user32.dll,MessageBeep'],
           { stdio: 'ignore' },
         );
       }
     } else if (isMac()) {
-      spawnSync('afplay', [soundFile], { stdio: 'ignore' });
+      // afplay -v accepts a float: 0.0 = silent, 1.0 = full volume
+      const afVol = (vol / 100).toFixed(2);
+      spawnSync('afplay', ['-v', afVol, soundFile], { stdio: 'ignore' });
     } else {
-      // Linux: try paplay (PulseAudio) then aplay (ALSA)
-      const paplay = spawnSync('paplay', [soundFile], { stdio: 'ignore' });
+      // Linux: paplay --volume accepts 0–65536 (0=silent, 65536=100%)
+      const paVol = String(Math.round(vol * 655.36));
+      const paplay = spawnSync('paplay', [`--volume=${paVol}`, soundFile], { stdio: 'ignore' });
       if (paplay.status !== 0) {
         spawnSync('aplay', [soundFile], { stdio: 'ignore' });
       }

packages/cli/tests/unit/notification-sound.test.ts

@@ -50,7 +50,7 @@ async function loadHook(opts: {
   isWindowsMock = vi.fn(() => opts.isWindows ?? false);
   isMacMock = vi.fn(() => opts.isMac ?? false);
   bundledSoundMock = vi.fn(() => opts.bundledSound ?? null);
-  getSoundPreferenceMock = vi.fn(() => opts.soundPreference ?? 'system');
+  getSoundPreferenceMock = vi.fn(() => ({ style: opts.soundPreference ?? 'system', volume: 50 }));
 
   vi.doMock('../../src/hooks/shared.js', () => ({
     readStdinJson: vi.fn((cb: (data: Record<string, unknown>) => void) => {
@@ -84,7 +84,7 @@ describe('sound playback on Notification event', () => {
 
     hookCallback!({ message: 'Question' });
 
-    expect(playSoundMock).toHaveBeenCalledWith('/path/to/notification.wav');
+    expect(playSoundMock).toHaveBeenCalledWith('/path/to/notification.wav', 50);
   });
 
   it('checks for bundled notification.wav when preference is bundled', async () => {
@@ -132,7 +132,7 @@ describe('platform-specific sound selection', () => {
 
     hookCallback!({});
 
-    expect(playSoundMock).toHaveBeenCalledWith('/bundled/notification.wav');
+    expect(playSoundMock).toHaveBeenCalledWith('/bundled/notification.wav', 50);
     // Should not have been called with the Windows system sound
     expect(playSoundMock).not.toHaveBeenCalledWith('SystemAsterisk');
   });

packages/cli/tests/unit/stop-sound.test.ts

@@ -71,7 +71,7 @@ async function loadHook(opts: {
   isWindowsMock = vi.fn(() => opts.isWindows ?? false);
   isMacMock = vi.fn(() => opts.isMac ?? false);
   bundledSoundMock = vi.fn(() => opts.bundledSound ?? null);
-  getSoundPreferenceMock = vi.fn(() => opts.soundPreference ?? 'system');
+  getSoundPreferenceMock = vi.fn(() => ({ style: opts.soundPreference ?? 'system', volume: 50 }));
 
   vi.doMock('../../src/hooks/shared.js', () => ({
     readStdinJson: vi.fn((cb: (data: Record<string, unknown>) => void) => {
@@ -144,7 +144,7 @@ describe('sound playback when stop_hook_active is false', () => {
 
     invokeHook({ stop_hook_active: false });
 
-    expect(playSoundMock).toHaveBeenCalledWith('/path/to/complete.wav');
+    expect(playSoundMock).toHaveBeenCalledWith('/path/to/complete.wav', 50);
   });
 
   it('checks for bundled complete.wav when preference is bundled', async () => {
@@ -186,7 +186,7 @@ describe('sound playback when stop_hook_active is false', () => {
 
     invokeHook({});
 
-    expect(playSoundMock).toHaveBeenCalledWith('/bundled/complete.wav');
+    expect(playSoundMock).toHaveBeenCalledWith('/bundled/complete.wav', 50);
     expect(playSoundMock).not.toHaveBeenCalledWith('SystemNotification');
   });
 });

templates/templates/config.json

@@ -96,7 +96,9 @@
   "hooks": {
     "enabled": true,
     "__doc_sound_style": "Sound style for notification and completion hooks. 'system' uses OS-native system sounds (default). 'bundled' uses MaxsimCLI's custom chime sounds (pleasant ascending tones).",
-    "sound_style": "system"
+    "sound_style": "system",
+    "__doc_sound_volume": "Volume for bundled sounds (0–100). Only applies when sound_style is 'bundled'. System sounds always play at OS volume. Default: 50.",
+    "sound_volume": 50
   },
   "workflow": {
     "research": true,