feat: per-hook notification mode overrides (v4.3.0)

Add `notification_settings.per_hook` to independently control audio and
desktop notifications per hook type. Frequent hooks like pretooluse can
use audio_only to avoid slow desktop notification queuing, while critical
hooks keep both channels. New `disabled` mode suppresses audio and
desktop but preserves TTS/logging. Fully backward compatible — omitting
per_hook uses the global mode as before.

- Add per-hook mode resolution with validation and fallback in hook_runner.py
- Add `--hook-mode` CLI flag to configure.sh
- Add `disabled` as a valid notification mode
- Update config templates, CLAUDE.md, README.md, CHANGELOG.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ChanMeng666

CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to Claude Code Audio Hooks will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.3.0] - 2026-02-17
+
+### Added
+- **Per-hook notification mode overrides**: New `notification_settings.per_hook` config allows independently controlling audio and desktop notifications per hook type (e.g., `"pretooluse": "audio_only"` to skip desktop notifications for frequent hooks)
+- **`disabled` notification mode**: Suppresses both audio and desktop notifications while still allowing TTS and logging — different from `enabled_hooks: false` which skips everything
+- **`--hook-mode` CLI flag**: `bash scripts/configure.sh --hook-mode pretooluse=audio_only posttooluse=disabled` for quick per-hook mode configuration
+- Per-hook mode validation with automatic fallback to global mode on invalid values
+
+### Changed
+- `hook_runner.py` notification mode resolution now checks `per_hook` overrides before falling back to global `notification_settings.mode`
+- Debug logging now shows both per-hook and global mode for each hook trigger
+- Updated `config/default_preferences.json` and `config/user_preferences.json` with `per_hook` field
+- Updated CLAUDE.md, README.md with per-hook notification mode documentation
+
+### Upgrade
+
+No reinstall needed — existing installations self-update automatically on the next hook trigger after `git pull`. The `per_hook` field is fully backward compatible: if absent, all hooks use the global mode as before.
+
+---
+
 ## [4.2.2] - 2026-02-14
 
 ### Fixed

CLAUDE.md

@@ -1,6 +1,6 @@
 # Claude Code Audio Hooks - AI Assistant Guide
 
-> **Version:** 4.2.2 | **Last Updated:** 2026-02-14
+> **Version:** 4.3.0 | **Last Updated:** 2026-02-17
 
 This document is designed for AI assistants (Claude Code, Cursor, Copilot, etc.) to understand and help users install this project correctly.
 
@@ -238,7 +238,11 @@ D:/github_repository/claude-code-audio-hooks
   },
   "notification_settings": {
     "mode": "audio_and_notification",
-    "show_context": true
+    "show_context": true,
+    "per_hook": {
+      "pretooluse": "audio_only",
+      "posttooluse": "audio_only"
+    }
   },
   "tts_settings": {
     "enabled": false,
@@ -382,6 +386,7 @@ Instruct user to:
 
 | Version | Date | Key Changes |
 |---------|------|-------------|
+| 4.3.0 | 2026-02-17 | Per-hook notification mode overrides: independently control audio/desktop notifications per hook type via `notification_settings.per_hook` |
 | 4.2.2 | 2026-02-14 | Robust theme switching: remove conflicting `audio_files` config, add hook_runner.py auto-sync from project dir, configure.sh syncs on theme switch |
 | 4.2.0 | 2026-02-13 | Add 4 new hooks (PostToolUseFailure, SubagentStart, TeammateIdle, TaskCompleted), 14 total hooks, 14 unique audio files |
 | 4.0.3 | 2026-02-11 | Fix Windows installer hook filtering, uninstaller hook_runner.py detection, defensive wrapping |

README.md

@@ -791,13 +791,46 @@ Configure in `config/user_preferences.json`:
 | `audio_only` | Yes | No | Classic behavior, backward compatible |
 | `notification_only` | No | Yes | Silent environments, visual-only alerts |
 | `audio_and_notification` | Yes | Yes | Maximum awareness (recommended) |
+| `disabled` | No | No | Suppress both (TTS/logging still works) |
 
 Desktop notifications show context from Claude Code:
 - **Stop**: "Task completed"
 - **Notification**: "Authorization needed: Allow Bash command?"
 - **PreToolUse**: "Running: Bash"
 - **SubagentStop**: "Background task finished (Explore)"
 
+### **Per-Hook Notification Mode** *(v4.3.0)*
+
+Override the global mode for specific hooks. Hooks not listed in `per_hook` fall back to the global `mode`. This is useful when frequent hooks (like `pretooluse`) should only play audio without queuing slow desktop notifications:
+
+```json
+{
+  "notification_settings": {
+    "mode": "audio_and_notification",
+    "show_context": true,
+    "per_hook": {
+      "pretooluse": "audio_only",
+      "posttooluse": "audio_only",
+      "precompact": "disabled"
+    }
+  }
+}
+```
+
+| Mode | Audio | Desktop Popup | Notes |
+|------|-------|---------------|-------|
+| `audio_only` | Yes | No | Fast, no desktop notification delay |
+| `notification_only` | No | Yes | Visual-only, no audio |
+| `audio_and_notification` | Yes | Yes | Both channels |
+| `disabled` | No | No | Suppresses both (TTS/logging still works) |
+
+> **Note:** `"disabled"` is different from `enabled_hooks: false` — the hook still fires for TTS and logging, it just skips audio and desktop notifications.
+
+**CLI shortcut:**
+```bash
+bash scripts/configure.sh --hook-mode pretooluse=audio_only posttooluse=disabled
+```
+
 ### **Text-to-Speech**
 
 Enable spoken context-aware messages:

config/default_preferences.json

@@ -64,9 +64,11 @@
   },
 
   "notification_settings": {
-    "_comment": "Desktop notification mode: audio_only, notification_only, audio_and_notification",
+    "_comment": "Desktop notification mode: audio_only, notification_only, audio_and_notification, disabled",
     "mode": "audio_and_notification",
-    "show_context": true
+    "show_context": true,
+    "_comment_per_hook": "Per-hook mode overrides. Omit a hook to use the global mode above.",
+    "per_hook": {}
   },
 
   "tts_settings": {

config/user_preferences.json

@@ -64,9 +64,14 @@
   },
 
   "notification_settings": {
-    "_comment": "Desktop notification mode: audio_only, notification_only, audio_and_notification",
+    "_comment": "Desktop notification mode: audio_only, notification_only, audio_and_notification, disabled",
     "mode": "audio_and_notification",
-    "show_context": true
+    "show_context": true,
+    "_comment_per_hook": "Override the global mode for specific hooks. Omit a hook to use the global mode.",
+    "per_hook": {
+      "pretooluse": "audio_only",
+      "posttooluse": "audio_only"
+    }
   },
 
   "tts_settings": {

hooks/hook_runner.py

@@ -29,7 +29,7 @@
 
 # Version used for auto-sync: when the installed copy in ~/.claude/hooks/
 # detects a newer version in the project directory, it self-updates.
-HOOK_RUNNER_VERSION = "4.2.2"
+HOOK_RUNNER_VERSION = "4.3.0"
 
 # =============================================================================
 # DEBUG LOGGING SYSTEM
@@ -1028,11 +1028,20 @@ def run_hook(hook_type: str, stdin_data: dict = None) -> int:
     # Load config once for notification/TTS settings
     config = load_config()
 
-    # Determine notification mode (backward compatible: default to audio_only)
+    # Determine notification mode with per-hook override support
     notification_settings = config.get("notification_settings", {})
-    mode = notification_settings.get("mode", "audio_only")
-
-    # Play audio (unless mode is notification_only)
+    global_mode = notification_settings.get("mode", "audio_only")
+    per_hook_modes = {k: v for k, v in notification_settings.get("per_hook", {}).items() if not k.startswith("_")}
+    mode = per_hook_modes.get(hook_type, global_mode)
+
+    # Validate mode (fall back to global if invalid)
+    valid_modes = ("audio_only", "notification_only", "audio_and_notification", "disabled")
+    if mode not in valid_modes:
+        log_debug(f"Invalid per_hook mode '{mode}' for {hook_type}, falling back to '{global_mode}'")
+        mode = global_mode
+    log_debug(f"Notification mode for {hook_type}: {mode} (global={global_mode})")
+
+    # Play audio (unless mode is notification_only or disabled)
     if mode in ("audio_only", "audio_and_notification"):
         audio_file = get_audio_file(hook_type)
         if not audio_file:
@@ -1049,14 +1058,18 @@ def run_hook(hook_type: str, stdin_data: dict = None) -> int:
                 log_error(f"Failed to play audio: {audio_file}")
     elif mode == "notification_only":
         log_trigger(hook_type, "AUDIO_SKIPPED", f"mode={mode}")
+    elif mode == "disabled":
+        log_trigger(hook_type, "AUDIO_SKIPPED", "mode=disabled")
 
-    # Desktop notification
+    # Desktop notification (unless mode is audio_only or disabled)
     if mode in ("notification_only", "audio_and_notification"):
         context = get_notification_context(hook_type, stdin_data or {})
         urgency = "critical" if hook_type in ("notification", "permission_request", "posttoolusefailure") else "normal"
         notif_sent = send_desktop_notification("Claude Code", context, urgency)
         if notif_sent:
             log_debug(f"Desktop notification sent for {hook_type}: {context}")
+    elif mode == "disabled":
+        log_trigger(hook_type, "NOTIFICATION_SKIPPED", "mode=disabled")
 
     # TTS (text-to-speech)
     tts_settings = config.get("tts_settings", {})

scripts/configure.sh

@@ -364,6 +364,99 @@ print("OK")
 PYTHON_SCRIPT
 }
 
+# Programmatic per-hook notification mode setting
+cmd_hook_mode() {
+    local assignments=("$@")
+    if [ ${#assignments[@]} -eq 0 ]; then
+        echo -e "${RED}Error: At least one hook=mode assignment required${NC}" >&2
+        echo "Usage: $0 --hook-mode <hook>=<mode> [hook2=mode2 ...]" >&2
+        echo "Valid modes: audio_only, notification_only, audio_and_notification, disabled" >&2
+        echo "Example: $0 --hook-mode pretooluse=audio_only posttooluse=disabled" >&2
+        exit 1
+    fi
+
+    local valid_modes="audio_only notification_only audio_and_notification disabled"
+    local changed=0
+
+    for assignment in "${assignments[@]}"; do
+        if [[ ! "$assignment" =~ ^([a-z_]+)=(.+)$ ]]; then
+            echo -e "${YELLOW}Warning: Invalid format '$assignment', use hook=mode${NC}" >&2
+            continue
+        fi
+
+        local hook_name="${BASH_REMATCH[1]}"
+        local mode="${BASH_REMATCH[2]}"
+
+        # Validate hook name
+        local index=$(get_hook_index "$hook_name")
+        if [ -z "$index" ]; then
+            echo -e "${YELLOW}Warning: Unknown hook '$hook_name', skipping${NC}" >&2
+            continue
+        fi
+
+        # Validate mode
+        local mode_valid=false
+        for vm in $valid_modes; do
+            if [[ "$mode" == "$vm" ]]; then
+                mode_valid=true
+                break
+            fi
+        done
+        if [[ "$mode_valid" != "true" ]]; then
+            echo -e "${YELLOW}Warning: Invalid mode '$mode' for $hook_name, skipping${NC}" >&2
+            echo "  Valid modes: $valid_modes" >&2
+            continue
+        fi
+
+        echo -e "${GREEN}✓${NC} Set $hook_name mode = $mode"
+        ((changed++))
+    done
+
+    if [ $changed -eq 0 ]; then
+        echo -e "${RED}No valid assignments to apply${NC}" >&2
+        exit 1
+    fi
+
+    # Apply all changes via Python
+    python3 << PYTHON_SCRIPT
+import json
+
+config_file = "$CONFIG_FILE"
+assignments = """$@""".split()
+
+try:
+    with open(config_file, 'r') as f:
+        config = json.load(f)
+except:
+    config = {}
+
+notification_settings = config.setdefault("notification_settings", {})
+per_hook = notification_settings.setdefault("per_hook", {})
+
+for assignment in assignments:
+    if '=' in assignment:
+        hook_name, mode = assignment.split('=', 1)
+        per_hook[hook_name] = mode
+
+# Remove _comment keys from per_hook if present (clean save)
+per_hook_clean = {k: v for k, v in per_hook.items() if not k.startswith('_')}
+notification_settings["per_hook"] = per_hook_clean
+
+with open(config_file, 'w') as f:
+    json.dump(config, f, indent=2)
+
+print("OK")
+PYTHON_SCRIPT
+
+    if [ $? -eq 0 ]; then
+        echo -e "\n${GREEN}${BOLD}✓ Per-hook notification modes saved${NC}"
+        echo -e "${YELLOW}Remember to restart Claude Code to apply changes${NC}"
+    else
+        echo -e "${RED}✗${NC} Failed to save per-hook modes" >&2
+        exit 1
+    fi
+}
+
 # Programmatic theme switching
 cmd_theme() {
     local theme=$1
@@ -514,6 +607,12 @@ ${CYAN}PROGRAMMATIC MODE${NC} (with arguments):
     custom  - Modern UI sound effects, no voice (audio/custom/)
     Example: $0 --theme custom
 
+  ${BOLD}--hook-mode <hook>=<mode> [hook2=mode2 ...]${NC}
+    Set per-hook notification mode overrides
+    Valid modes: audio_only, notification_only, audio_and_notification, disabled
+    Hooks not listed fall back to the global notification_settings.mode
+    Example: $0 --hook-mode pretooluse=audio_only posttooluse=disabled
+
   ${BOLD}--reset${NC}
     Reset to recommended defaults
     (Enables: notification, stop, subagent_stop, permission_request; Disables: all others)
@@ -544,6 +643,9 @@ ${CYAN}EXAMPLES${NC}:
   # Mixed operations
   $0 --enable notification --disable pretooluse --set stop=true
 
+  # Set per-hook notification modes (audio only for noisy hooks)
+  $0 --hook-mode pretooluse=audio_only posttooluse=disabled
+
   # Check if notification hook is enabled
   $0 --get notification
 
@@ -815,6 +917,16 @@ process_arguments() {
                 cmd_theme "$1"
                 exit 0
                 ;;
+            --hook-mode)
+                shift
+                local hook_modes=()
+                while [ $# -gt 0 ] && [[ ! "$1" =~ ^-- ]]; do
+                    hook_modes+=("$1")
+                    shift
+                done
+                cmd_hook_mode "${hook_modes[@]}"
+                exit 0
+                ;;
             --reset)
                 cmd_reset
                 exit 0