forge-cw 0.1.0

package/cw/hooks/scripts/auto-compact.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""
+CW Auto-Compact Hook (PostToolUse)
+===================================
+Counts tool calls per session. After a threshold, injects additionalContext
+telling Claude to run /compact proactively before the system auto-compacts.
+
+Counter files stored in ~/.cw/compact-counters/<session_hash>.json
+Configurable via hooks-config.json: "disableAutoCompactHook": true/false
+                                    "autoCompactThreshold": N (default 100)
+                                    "autoCompactCooldown": N (default 60)
+"""
+
+import sys
+import json
+import os
+import hashlib
+from pathlib import Path
+
+
+DEFAULT_THRESHOLD = 100  # Tool calls before first compact suggestion
+DEFAULT_COOLDOWN = 60    # Tool calls between subsequent suggestions
+
+
+def _read_config():
+    """Read auto-compact settings from hooks-config files."""
+    script_dir = Path(__file__).parent
+    config_dir = script_dir.parent / "config"
+    local_path = config_dir / "hooks-config.local.json"
+    default_path = config_dir / "hooks-config.json"
+
+    local_cfg = {}
+    default_cfg = {}
+
+    try:
+        if local_path.exists():
+            with open(local_path) as f:
+                local_cfg = json.load(f)
+    except Exception:
+        pass
+
+    try:
+        if default_path.exists():
+            with open(default_path) as f:
+                default_cfg = json.load(f)
+    except Exception:
+        pass
+
+    def _get(key, fallback):
+        if key in local_cfg:
+            return local_cfg[key]
+        if key in default_cfg:
+            return default_cfg[key]
+        return fallback
+
+    return {
+        "disabled": _get("disableAutoCompactHook", False),
+        "threshold": _get("autoCompactThreshold", DEFAULT_THRESHOLD),
+        "cooldown": _get("autoCompactCooldown", DEFAULT_COOLDOWN),
+    }
+
+
+def main():
+    try:
+        stdin_content = sys.stdin.read().strip()
+        if not stdin_content:
+            sys.exit(0)
+
+        hook_data = json.loads(stdin_content)
+        session_id = hook_data.get("session_id", "")
+        if not session_id:
+            sys.exit(0)
+
+        cfg = _read_config()
+        if cfg["disabled"]:
+            sys.exit(0)
+
+        # Counter directory
+        cw_home = os.environ.get("CW_HOME", os.path.expanduser("~/.cw"))
+        counter_dir = os.path.join(cw_home, "compact-counters")
+        os.makedirs(counter_dir, exist_ok=True)
+
+        # Hash session_id for filename safety
+        session_hash = hashlib.sha256(session_id.encode()).hexdigest()[:16]
+        counter_file = os.path.join(counter_dir, f"{session_hash}.json")
+
+        # Read current state
+        count = 0
+        last_compact_at = 0
+        try:
+            with open(counter_file) as f:
+                data = json.load(f)
+                count = data.get("count", 0)
+                last_compact_at = data.get("last_compact_at", 0)
+        except (FileNotFoundError, json.JSONDecodeError):
+            pass
+
+        count += 1
+
+        # Decide whether to suggest compact
+        suggest = False
+        if last_compact_at == 0 and count >= cfg["threshold"]:
+            suggest = True
+        elif last_compact_at > 0 and (count - last_compact_at) >= cfg["cooldown"]:
+            suggest = True
+
+        # Save updated counter
+        save_data = {"count": count, "last_compact_at": last_compact_at}
+        if suggest:
+            save_data["last_compact_at"] = count
+        with open(counter_file, "w") as f:
+            json.dump(save_data, f)
+
+        # Inject context for Claude
+        if suggest:
+            result = {
+                "additionalContext": (
+                    f"[CW Auto-Compact] This session has reached {count} tool calls. "
+                    "You MUST run /compact now to preserve context quality. "
+                    "Tell the user you're compacting proactively, then run /compact."
+                )
+            }
+            print(json.dumps(result))
+
+        sys.exit(0)
+
+    except Exception:
+        # Never block Claude's work
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/cw/hooks/scripts/hooks.py

@@ -0,0 +1,472 @@
+#!/usr/bin/env python3
+"""
+Claude Code Hook Handler
+=============================================
+This script handles events from Claude Code and plays sounds for different hook events.
+Supports all 18 Claude Code hooks: https://code.claude.com/docs/en/hooks
+
+Special handling for git commits: plays pretooluse-git-committing.mp3
+
+Agent Support:
+  Use --agent=<name> to play agent-specific sounds from agent_* folders.
+  Agent frontmatter hooks support 6 hooks: PreToolUse, PostToolUse, PermissionRequest, PostToolUseFailure, Stop, SubagentStop
+"""
+
+import sys
+import json
+import subprocess
+import re
+import platform
+import argparse
+from pathlib import Path
+
+# Windows-only module for playing WAV files
+try:
+    import winsound
+except ImportError:
+    winsound = None
+
+# ===== HOOK EVENT TO SOUND FOLDER MAPPING =====
+# Maps each hook event to its corresponding sound folder
+HOOK_SOUND_MAP = {
+    "PreToolUse": "pretooluse",
+    "PermissionRequest": "permissionrequest",
+    "PostToolUse": "posttooluse",
+    "PostToolUseFailure": "posttoolusefailure",
+    "UserPromptSubmit": "userpromptsubmit",
+    "Notification": "notification",
+    "Stop": "stop",
+    "SubagentStart": "subagentstart",
+    "SubagentStop": "subagentstop",
+    "PreCompact": "precompact",
+    "SessionStart": "sessionstart",
+    "SessionEnd": "sessionend",
+    "Setup": "setup",
+    "TeammateIdle": "teammateidle",
+    "TaskCompleted": "taskcompleted",
+    "ConfigChange": "configchange",
+    "WorktreeCreate": "worktreecreate",
+    "WorktreeRemove": "worktreeremove"
+}
+
+# ===== AGENT HOOK EVENT TO SOUND FOLDER MAPPING =====
+# Maps agent hook events to agent-specific sound folders
+# Only the 6 hooks that actually fire in agent contexts are mapped
+AGENT_HOOK_SOUND_MAP = {
+    "PreToolUse": "agent_pretooluse",
+    "PostToolUse": "agent_posttooluse",
+    "PermissionRequest": "agent_permissionrequest",
+    "PostToolUseFailure": "agent_posttoolusefailure",
+    "Stop": "agent_stop",
+    "SubagentStop": "agent_subagentstop"
+}
+
+# ===== BASH COMMAND PATTERNS =====
+# Regex patterns to detect specific bash commands and map to special sounds
+BASH_PATTERNS = [
+    (r'git commit', "pretooluse-git-committing"),  # Git commits (anywhere in command)
+]
+
+def get_audio_player():
+    """
+    Detect the appropriate audio player for the current platform.
+
+    Returns:
+        List of command and args to use for playing audio, or None if no player found
+    """
+    system = platform.system()
+
+    if system == "Darwin":
+        # macOS: use afplay (built-in)
+        return ["afplay"]
+    elif system == "Linux":
+        # Linux: try different players in order of preference
+        # Try to find an available player
+        players = [
+            ["paplay"],           # PulseAudio (most common on modern Linux)
+            ["aplay"],            # ALSA (fallback)
+            ["ffplay", "-nodisp", "-autoexit"],  # FFmpeg (if installed)
+            ["mpg123", "-q"],     # mpg123 (if installed)
+        ]
+
+        for player in players:
+            try:
+                # Check if the player exists
+                subprocess.run(
+                    ["which", player[0]],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    check=True
+                )
+                return player
+            except (subprocess.CalledProcessError, FileNotFoundError):
+                continue
+
+        # No player found
+        return None
+    elif system == "Windows":
+        # Windows: Use winsound for WAV, PowerShell for MP3
+        return ["WINDOWS"]
+    else:
+        # Other OS - not supported yet
+        return None
+
+
+def play_sound(sound_name):
+    """
+    Play a sound file for the given sound name.
+
+    Args:
+        sound_name: Name of the sound file (e.g., "pretooluse", "pretooluse-git-committing")
+                   The file should be at .claude/hooks/sounds/{folder}/{sound_name}.{mp3|wav}
+
+    Returns:
+        True if sound played successfully, False otherwise
+    """
+    # Security check: Prevent directory traversal attacks
+    if "/" in sound_name or "\\" in sound_name or ".." in sound_name:
+        print(f"Invalid sound name: {sound_name}", file=sys.stderr)
+        return False
+
+    # Get the appropriate audio player for this platform
+    audio_player = get_audio_player()
+    if not audio_player:
+        # No audio player available - fail silently
+        return False
+
+    # Build the path to the sound folder
+    # Scripts are in .claude/hooks/scripts/, sounds are in .claude/hooks/sounds/
+    script_dir = Path(__file__).parent  # .claude/hooks/scripts/
+    hooks_dir = script_dir.parent  # .claude/hooks/
+
+    # Determine the folder based on the sound name prefix
+    # For special sounds like "pretooluse-git-committing", look in "pretooluse" folder
+    folder_name = sound_name.split('-')[0]
+    sounds_dir = hooks_dir / "sounds" / folder_name
+
+    # Check if we're on Windows and need special handling
+    is_windows = audio_player[0] == "WINDOWS"
+
+    # Try different audio formats
+    # Note: paplay (PulseAudio) doesn't support MP3, so try WAV first
+    # On Windows, only use WAV files to avoid PowerShell/COM issues
+    extensions = ['.wav'] if is_windows else ['.wav', '.mp3']
+
+    for extension in extensions:
+        file_path = sounds_dir / f"{sound_name}{extension}"
+
+        if file_path.exists():
+            try:
+                if is_windows:
+                    # Windows: Use winsound for WAV files (built-in, reliable, fast)
+                    if winsound:
+                        # SND_FILENAME: file_path is a filename
+                        # SND_SYNC: play sound synchronously (wait until complete)
+                        # SND_NODEFAULT: don't play default sound if file not found
+                        # Note: Using SND_SYNC instead of SND_ASYNC because the script exits immediately
+                        # after this call, which would terminate async playback before it completes
+                        winsound.PlaySound(str(file_path),
+                                         winsound.SND_FILENAME | winsound.SND_NODEFAULT)
+                        return True
+                    else:
+                        # winsound not available, fail silently
+                        return False
+                else:
+                    # Unix/Linux/macOS: use subprocess with audio player
+                    subprocess.Popen(
+                        audio_player + [str(file_path)],
+                        stdout=subprocess.DEVNULL,
+                        stderr=subprocess.DEVNULL,
+                        start_new_session=True
+                    )
+                    return True
+            except (FileNotFoundError, OSError) as e:
+                print(f"Error playing sound {file_path.name}: {e}", file=sys.stderr)
+                return False
+            except Exception as e:
+                # Catch any other exceptions (e.g., winsound errors)
+                print(f"Error playing sound {file_path.name}: {e}", file=sys.stderr)
+                return False
+
+    # Sound not found - fail silently to avoid disrupting Claude's work
+    return False
+
+def is_hook_disabled(event_name):
+    """
+    Check if a specific hook is disabled in the config files.
+    Uses fallback logic: hooks-config.local.json -> hooks-config.json
+
+    Priority:
+    1. If hooks-config.local.json exists and has the setting, use it
+    2. Otherwise, fall back to hooks-config.json
+    3. If neither exists or the key is missing, assume hook is enabled (return False)
+
+    Args:
+        event_name: The hook event name (e.g., "PreToolUse", "PostToolUse")
+
+    Returns:
+        True if the hook is disabled, False otherwise
+    """
+    try:
+        # Scripts are in .claude/hooks/scripts/, config is in .claude/hooks/config/
+        script_dir = Path(__file__).parent  # .claude/hooks/scripts/
+        hooks_dir = script_dir.parent  # .claude/hooks/
+        config_dir = hooks_dir / "config"  # .claude/hooks/config/
+
+        local_config_path = config_dir / "hooks-config.local.json"
+        default_config_path = config_dir / "hooks-config.json"
+
+        # Map event names to config keys
+        config_key = f"disable{event_name}Hook"
+
+        # Try to load local config first
+        local_config = None
+        if local_config_path.exists():
+            try:
+                with open(local_config_path, "r", encoding="utf-8") as config_file:
+                    local_config = json.load(config_file)
+            except Exception as e:
+                print(f"Error reading local config: {e}", file=sys.stderr)
+
+        # Try to load default config
+        default_config = None
+        if default_config_path.exists():
+            try:
+                with open(default_config_path, "r", encoding="utf-8") as config_file:
+                    default_config = json.load(config_file)
+            except Exception as e:
+                print(f"Error reading default config: {e}", file=sys.stderr)
+
+        # Apply fallback logic: local -> default -> False (enabled)
+        if local_config is not None and config_key in local_config:
+            return local_config[config_key]
+        elif default_config is not None and config_key in default_config:
+            return default_config[config_key]
+        else:
+            # If neither config has the key, assume hook is enabled
+            return False
+
+    except Exception as e:
+        # If anything goes wrong, assume hook is enabled
+        print(f"Error in is_hook_disabled: {e}", file=sys.stderr)
+        return False
+
+def is_logging_disabled():
+    """
+    Check if logging is disabled in the config files.
+    Uses fallback logic: hooks-config.local.json -> hooks-config.json
+
+    Returns:
+        True if logging is disabled, False otherwise
+    """
+    try:
+        # Scripts are in .claude/hooks/scripts/, config is in .claude/hooks/config/
+        script_dir = Path(__file__).parent  # .claude/hooks/scripts/
+        hooks_dir = script_dir.parent  # .claude/hooks/
+        config_dir = hooks_dir / "config"  # .claude/hooks/config/
+
+        local_config_path = config_dir / "hooks-config.local.json"
+        default_config_path = config_dir / "hooks-config.json"
+
+        # Try to load local config first
+        local_config = None
+        if local_config_path.exists():
+            try:
+                with open(local_config_path, "r", encoding="utf-8") as config_file:
+                    local_config = json.load(config_file)
+            except Exception as e:
+                print(f"Error reading local config: {e}", file=sys.stderr)
+
+        # Try to load default config
+        default_config = None
+        if default_config_path.exists():
+            try:
+                with open(default_config_path, "r", encoding="utf-8") as config_file:
+                    default_config = json.load(config_file)
+            except Exception as e:
+                print(f"Error reading default config: {e}", file=sys.stderr)
+
+        # Apply fallback logic: local -> default -> False (logging enabled)
+        if local_config is not None and "disableLogging" in local_config:
+            return local_config["disableLogging"]
+        elif default_config is not None and "disableLogging" in default_config:
+            return default_config["disableLogging"]
+        else:
+            # If neither config has the key, assume logging is enabled
+            return False
+
+    except Exception as e:
+        # If anything goes wrong, assume logging is enabled
+        print(f"Error in is_logging_disabled: {e}", file=sys.stderr)
+        return False
+
+def log_hook_data(hook_data, agent_name=None):
+    """
+    Log the full hook_data to hooks-log.jsonl for debugging/auditing.
+    Log file is stored at .claude/hooks/logs/hooks-log.jsonl
+
+    Args:
+        hook_data: Dictionary containing event information from Claude
+        agent_name: Optional agent name if hook was invoked from a sub-agent
+    """
+    # Check if logging is disabled
+    if is_logging_disabled():
+        return
+
+    try:
+        # Scripts are in .claude/hooks/scripts/, logs are in .claude/hooks/logs/
+        script_dir = Path(__file__).parent  # .claude/hooks/scripts/
+        hooks_dir = script_dir.parent  # .claude/hooks/
+        logs_dir = hooks_dir / "logs"  # .claude/hooks/logs/
+
+        # Ensure logs directory exists
+        logs_dir.mkdir(parents=True, exist_ok=True)
+
+        # Add source field to indicate if hook was called from main session or sub-agent
+        log_entry = hook_data.copy()
+
+        # Remove fields we don't need in logs
+        log_entry.pop("transcript_path", None)
+        log_entry.pop("cwd", None)
+
+        # Only add agent name if hook was invoked from a sub-agent
+        if agent_name:
+            log_entry["invoked_by_agent"] = agent_name
+
+        log_path = logs_dir / "hooks-log.jsonl"
+        with open(log_path, "a", encoding="utf-8") as log_file:
+            log_file.write(json.dumps(log_entry, ensure_ascii=False, indent=2) + "\n")
+    except Exception as e:
+        # Fail silently, but print to stderr for visibility
+        print(f"Failed to log hook_data: {e}", file=sys.stderr)
+
+
+def detect_bash_command_sound(command):
+    """
+    Detect special bash commands and return the corresponding sound name.
+
+    Args:
+        command: The bash command string
+
+    Returns:
+        Sound name (string) if a pattern matches, None otherwise
+    """
+    if not command:
+        return None
+
+    for pattern, sound_name in BASH_PATTERNS:
+        if re.search(pattern, command.strip()):
+            return sound_name
+
+    return None
+
+
+def get_sound_name(hook_data, agent_name=None):
+    """
+    Determine which sound to play based on the hook event and context.
+
+    Args:
+        hook_data: Dictionary containing event information from Claude
+        agent_name: Optional agent name for agent-specific sounds
+
+    Returns:
+        Sound name (string) or None if no sound should play
+    """
+    event_name = hook_data.get("hook_event_name", "")
+    tool_name = hook_data.get("tool_name", "")
+
+    # If this is an agent hook, use agent-specific sounds
+    if agent_name:
+        return AGENT_HOOK_SOUND_MAP.get(event_name)
+
+    # Check if this is a PreToolUse event with Bash tool
+    if event_name == "PreToolUse" and tool_name == "Bash":
+        tool_input = hook_data.get("tool_input", {})
+        command = tool_input.get("command", "")
+
+        # Check for special bash command patterns (e.g., git commit)
+        special_sound = detect_bash_command_sound(command)
+        if special_sound:
+            return special_sound
+
+    # Return the default sound for this hook event
+    return HOOK_SOUND_MAP.get(event_name)
+
+def parse_arguments():
+    """
+    Parse command line arguments.
+
+    Returns:
+        Parsed arguments namespace
+    """
+    parser = argparse.ArgumentParser(
+        description="Claude Code Hook Handler - plays sounds for hook events"
+    )
+    parser.add_argument(
+        "--agent",
+        type=str,
+        default=None,
+        help="Agent name for agent-specific sounds (used by agent frontmatter hooks)"
+    )
+    return parser.parse_args()
+
+
+def main():
+    """
+    Main program - this runs when Claude triggers a hook.
+
+    How it works:
+    1. Parse command line arguments (--agent for agent-specific sounds)
+    2. Claude sends event data as JSON through stdin
+    3. We check if this specific hook is disabled in hooks-config.json
+    4. We parse the JSON to understand which hook event occurred
+    5. We check for special bash commands (like git commit)
+    6. We play the corresponding sound for that event
+    7. We exit successfully
+    """
+    try:
+        # Step 1: Parse command line arguments
+        args = parse_arguments()
+
+        # Step 2: Read the event data from Claude
+        stdin_content = sys.stdin.read().strip()
+
+        # If stdin is empty, exit gracefully (hook was called without data)
+        if not stdin_content:
+            sys.exit(0)
+
+        input_data = json.loads(stdin_content)
+
+        # Log hook data with source information (main session vs sub-agent)
+        log_hook_data(input_data, agent_name=args.agent)
+
+        # Step 3: Check if this hook is disabled (skip for agent hooks)
+        event_name = input_data.get("hook_event_name", "")
+        if not args.agent and is_hook_disabled(event_name):
+            # Hook is disabled, exit silently without playing sound
+            sys.exit(0)
+
+        # Step 4: Determine which sound to play (may be special, default, or agent-specific)
+        sound_name = get_sound_name(input_data, agent_name=args.agent)
+
+        # Step 5: Play the sound (if we found one)
+        if sound_name:
+            play_sound(sound_name)
+
+        # Step 6: Exit successfully
+        # Always exit with code 0 so we don't interrupt Claude's work
+        sys.exit(0)
+
+    except json.JSONDecodeError as e:
+        print(f"Error parsing JSON input: {e}", file=sys.stderr)
+        # Exit with 0 to avoid blocking Claude's work
+        sys.exit(0)
+    except Exception as e:
+        print(f"Unexpected error: {e}", file=sys.stderr)
+        # Exit with 0 to avoid blocking Claude's work
+        sys.exit(0)
+
+
+# Entry point - Python calls main() when the script runs
+if __name__ == "__main__":
+    main()