claude-dev-env 1.0.0

package/hooks/notification/notification_utils.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+
+import os
+import platform
+import subprocess
+
+NTFY_TOPIC = os.environ.get("NTFY_TOPIC", "claude-notifications")
+NTFY_BASE_URL = f"https://ntfy.sh/{NTFY_TOPIC}"
+WINDOWS_CHIMES_PATH = os.path.join(os.environ.get("SYSTEMROOT", r"C:\Windows"), "Media", "Windows Battery Critical.wav")
+LINUX_NOTIFICATION_SOUND = os.environ.get("NOTIFICATION_SOUND", "/usr/share/sounds/freedesktop/stereo/message.oga")
+LINUX_NOTIFICATION_TIMEOUT_MS = "3000"
+TOAST_DISPLAY_DURATION_MILLISECONDS = 6000
+DEFAULT_LINUX_TOAST_TITLE = "Claude Code"
+DEFAULT_LINUX_TOAST_MESSAGE = "Waiting for your input"
+
+TOAST_SCRIPT_TEMPLATE = r'''
+Add-Type -AssemblyName System.Windows.Forms
+Add-Type -AssemblyName System.Drawing
+Add-Type @"
+using System;
+using System.Runtime.InteropServices;
+public class Win32 {{
+    [DllImport("user32.dll")]
+    public static extern bool SetProcessDPIAware();
+    [DllImport("user32.dll")]
+    public static extern bool SetWindowPos(IntPtr hWnd, IntPtr hWndInsertAfter, int X, int Y, int cx, int cy, uint uFlags);
+    [DllImport("user32.dll")]
+    public static extern int GetWindowLong(IntPtr hWnd, int nIndex);
+    [DllImport("user32.dll")]
+    public static extern int SetWindowLong(IntPtr hWnd, int nIndex, int dwNewLong);
+    [DllImport("user32.dll")]
+    public static extern bool SetLayeredWindowAttributes(IntPtr hwnd, uint crKey, byte bAlpha, uint dwFlags);
+    public static readonly IntPtr HWND_TOPMOST = new IntPtr(-1);
+    public const uint SWP_NOACTIVATE = 0x0010;
+    public const uint SWP_SHOWWINDOW = 0x0040;
+    public const int GWL_EXSTYLE = -20;
+    public const int WS_EX_LAYERED = 0x80000;
+    public const int WS_EX_TRANSPARENT = 0x20;
+    public const uint LWA_ALPHA = 0x2;
+}}
+"@
+
+[Win32]::SetProcessDPIAware() | Out-Null
+
+$form = New-Object System.Windows.Forms.Form
+$form.FormBorderStyle = [System.Windows.Forms.FormBorderStyle]::None
+$form.Size = New-Object System.Drawing.Size(520, 110)
+$form.ShowInTaskbar = $false
+$form.BackColor = [System.Drawing.Color]::FromArgb(66, 135, 245)
+$form.StartPosition = [System.Windows.Forms.FormStartPosition]::Manual
+
+$screen = [System.Windows.Forms.Screen]::PrimaryScreen.WorkingArea
+$x = [int]($screen.Left + ($screen.Width - 520) / 2)
+$y = [int]($screen.Bottom - 110 - 50)
+$form.Location = New-Object System.Drawing.Point($x, $y)
+
+$inner = New-Object System.Windows.Forms.Panel
+$inner.Size = New-Object System.Drawing.Size(514, 104)
+$inner.Location = New-Object System.Drawing.Point(3, 3)
+$inner.BackColor = [System.Drawing.Color]::FromArgb(45, 45, 45)
+$form.Controls.Add($inner)
+
+$titleLabel = New-Object System.Windows.Forms.Label
+$titleLabel.Text = "{title}"
+$titleLabel.Font = New-Object System.Drawing.Font("Segoe UI", 12, [System.Drawing.FontStyle]::Bold)
+$titleLabel.ForeColor = [System.Drawing.Color]::FromArgb(120, 180, 255)
+$titleLabel.AutoSize = $false
+$titleLabel.Size = New-Object System.Drawing.Size(514, 30)
+$titleLabel.Location = New-Object System.Drawing.Point(0, 8)
+$titleLabel.TextAlign = [System.Drawing.ContentAlignment]::MiddleCenter
+$inner.Controls.Add($titleLabel)
+
+$messageLabel = New-Object System.Windows.Forms.Label
+$messageLabel.Text = "{message}"
+$messageLabel.Font = New-Object System.Drawing.Font("Segoe UI", 11)
+$messageLabel.ForeColor = [System.Drawing.Color]::White
+$messageLabel.AutoSize = $false
+$messageLabel.Size = New-Object System.Drawing.Size(500, 58)
+$messageLabel.Location = New-Object System.Drawing.Point(7, 40)
+$messageLabel.TextAlign = [System.Drawing.ContentAlignment]::TopCenter
+$inner.Controls.Add($messageLabel)
+
+$timer = New-Object System.Windows.Forms.Timer
+$timer.Interval = {toast_duration}
+$timer.Add_Tick({{ $form.Close() }})
+$timer.Start()
+
+$exStyle = [Win32]::GetWindowLong($form.Handle, [Win32]::GWL_EXSTYLE)
+[Win32]::SetWindowLong($form.Handle, [Win32]::GWL_EXSTYLE, $exStyle -bor [Win32]::WS_EX_LAYERED -bor [Win32]::WS_EX_TRANSPARENT)
+[Win32]::SetLayeredWindowAttributes($form.Handle, 0, 230, [Win32]::LWA_ALPHA)
+[Win32]::SetWindowPos($form.Handle, [Win32]::HWND_TOPMOST, $x, $y, 520, 110, [Win32]::SWP_NOACTIVATE -bor [Win32]::SWP_SHOWWINDOW)
+$form.Show()
+[System.Windows.Forms.Application]::Run($form)
+'''
+
+
+def is_wsl() -> bool:
+    if platform.system() != "Linux":
+        return False
+    try:
+        with open("/proc/version") as proc_version_file:
+            return "microsoft" in proc_version_file.read().lower()
+    except FileNotFoundError:
+        return False
+
+
+def build_toast_script(title: str, message: str) -> str:
+    safe_title = title.replace('"', '`"').replace("'", "`'")
+    safe_message = message.replace('"', '`"').replace("'", "`'")
+    return TOAST_SCRIPT_TEMPLATE.format(
+        title=safe_title,
+        message=safe_message,
+        toast_duration=TOAST_DISPLAY_DURATION_MILLISECONDS,
+    )
+
+
+def notify_wsl(title: str, message: str) -> None:
+    script = build_toast_script(title, message)
+    try:
+        subprocess.Popen(
+            ["powershell.exe", "-ExecutionPolicy", "Bypass", "-Command", script],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True
+        )
+    except FileNotFoundError:
+        pass
+
+
+def notify_windows(title: str, message: str) -> None:
+    script = build_toast_script(title, message)
+    subprocess.Popen(
+        ["powershell", "-ExecutionPolicy", "Bypass", "-Command", script],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        creationflags=subprocess.CREATE_NO_WINDOW if hasattr(subprocess, "CREATE_NO_WINDOW") else 0
+    )
+
+
+def notify_ntfy(title: str, message: str, priority: str = "high") -> None:
+    try:
+        subprocess.Popen(
+            [
+                "curl", "-s",
+                "-H", f"Priority: {priority}",
+                "-H", "Tags: bell",
+                "-H", f"Title: {title}",
+                "-d", message,
+                NTFY_BASE_URL,
+            ],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL
+        )
+    except FileNotFoundError:
+        pass
+
+
+def notify_linux() -> None:
+    subprocess.Popen(
+        [
+            "notify-send", "-t", LINUX_NOTIFICATION_TIMEOUT_MS,
+            "-u", "normal", "-i", "dialog-warning",
+            DEFAULT_LINUX_TOAST_TITLE, DEFAULT_LINUX_TOAST_MESSAGE,
+        ],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL
+    )
+
+
+def sound_windows() -> None:
+    subprocess.Popen(
+        ["powershell", "-WindowStyle", "Hidden", "-Command", f"(New-Object Media.SoundPlayer '{WINDOWS_CHIMES_PATH}').PlaySync()"],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        creationflags=subprocess.CREATE_NO_WINDOW if hasattr(subprocess, "CREATE_NO_WINDOW") else 0
+    )
+
+
+def sound_wsl() -> None:
+    try:
+        subprocess.Popen(
+            ["powershell.exe", "-WindowStyle", "Hidden", "-Command", f"(New-Object Media.SoundPlayer '{WINDOWS_CHIMES_PATH}').PlaySync()"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL
+        )
+    except FileNotFoundError:
+        pass
+
+
+def sound_linux() -> None:
+    if os.path.exists(LINUX_NOTIFICATION_SOUND):
+        for each_player in ["paplay", "aplay", "play"]:
+            try:
+                subprocess.Popen(
+                    [each_player, LINUX_NOTIFICATION_SOUND],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL
+                )
+                return
+            except FileNotFoundError:
+                continue
+    print("\a", end="", flush=True)
+
+
+def get_project_name() -> str:
+    return os.path.basename(os.getcwd())

package/hooks/rewrite-plugin-paths.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Rewrite plugin config paths to match the current platform.
+
+Solves the cross-platform path problem for shared ~/.claude directories.
+On WSL/Docker, rewrites Windows paths to Linux paths.
+On Windows, rewrites Linux paths back to Windows paths (heals WSL damage).
+
+Uses json.load/json.dump to avoid all backslash escaping issues.
+Called from Docker entrypoint.sh and can be called from session hooks.
+"""
+
+import json
+import os
+import sys
+from typing import Union
+
+
+PLUGIN_CONFIG_FILENAMES = [
+    "known_marketplaces.json",
+    "installed_plugins.json",
+]
+
+WINDOWS_PATH_PREFIX = os.path.join("C:\\Users", os.environ.get("USERNAME", "unknown"), ".claude")
+LINUX_HOME_PATH_PREFIX = os.path.join(os.path.expanduser("~"), ".claude") if os.name != "nt" else ""
+
+JsonValue = Union[str, int, float, bool, None, list, dict]
+
+
+def detect_local_claude_directory() -> str:
+    return os.path.join(os.path.expanduser("~"), ".claude")
+
+
+def rewrite_paths_in_value(
+    value: JsonValue,
+    from_prefix: str,
+    to_prefix: str,
+) -> JsonValue:
+    if isinstance(value, str):
+        return value.replace(from_prefix, to_prefix)
+    if isinstance(value, dict):
+        return {
+            each_key: rewrite_paths_in_value(each_value, from_prefix, to_prefix)
+            for each_key, each_value in value.items()
+        }
+    if isinstance(value, list):
+        return [
+            rewrite_paths_in_value(each_element, from_prefix, to_prefix)
+            for each_element in value
+        ]
+    return value
+
+
+def rewrite_plugin_config_file(
+    file_path: str,
+    from_prefix: str,
+    to_prefix: str,
+) -> bool:
+    try:
+        with open(file_path, "r", encoding="utf-8") as source_file:
+            parsed_config = json.load(source_file)
+    except FileNotFoundError:
+        return False
+    except json.JSONDecodeError as e:
+        print(
+            f"[rewrite-paths] ERROR: Invalid JSON in {file_path}: {e}",
+            file=sys.stderr,
+        )
+        return False
+
+    rewritten_config = rewrite_paths_in_value(
+        parsed_config,
+        from_prefix,
+        to_prefix,
+    )
+
+    if rewritten_config == parsed_config:
+        return False
+
+    with open(file_path, "w", encoding="utf-8") as destination_file:
+        json.dump(rewritten_config, destination_file, indent=2)
+        destination_file.write("\n")
+
+    return True
+
+
+def main() -> None:
+    is_windows = os.name == "nt"
+    local_claude_directory = detect_local_claude_directory()
+
+    if is_windows:
+        from_prefix = LINUX_HOME_PATH_PREFIX
+        to_prefix = WINDOWS_PATH_PREFIX
+    else:
+        from_prefix = WINDOWS_PATH_PREFIX
+        to_prefix = local_claude_directory
+
+    plugins_directory = os.path.join(local_claude_directory, "plugins")
+
+    rewritten_count = 0
+    for each_filename in PLUGIN_CONFIG_FILENAMES:
+        each_file_path = os.path.join(plugins_directory, each_filename)
+        was_rewritten = rewrite_plugin_config_file(
+            each_file_path,
+            from_prefix,
+            to_prefix,
+        )
+        if was_rewritten:
+            rewritten_count += 1
+            print(
+                f"[rewrite-paths] Rewrote paths in {each_filename}",
+                file=sys.stderr,
+            )
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session/bulk-edit-reminder.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+import json
+import sys
+
+BULK_UPDATE_KEYWORDS = ["update all", "replace all", "change all", "fix all", "rename all"]
+
+BULK_UPDATE_REMINDER = "BULK UPDATE DETECTED: Use a Python script with --preview/--apply instead of line-by-line edits."
+
+
+def main() -> None:
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    prompt = input_data.get("prompt", "")
+
+    if not prompt:
+        sys.exit(0)
+
+    message_lower = prompt.lower()
+
+    if any(keyword in message_lower for keyword in BULK_UPDATE_KEYWORDS):
+        print(BULK_UPDATE_REMINDER)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session/code-rules-reminder.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""
+UserPromptSubmit hook that detects code-related requests and injects CODE_RULES.md reminder.
+Triggers on keywords indicating code writing, planning, or implementation.
+"""
+
+import json
+import re
+import sys
+
+CODE_KEYWORDS = [
+    # Creation verbs
+    r'\b(write|create|implement|add|build|make|generate|develop|setup|scaffold|bootstrap|initialize|init|compose|construct|define|declare|register|wire|connect|integrate|introduce)\b',
+    # Code nouns
+    r'\b(code|function|class|method|script|module|component|hook|test|spec|api|endpoint|route|handler|service|util|helper|factory|interface|type|enum|constant|variable|parameter|argument|logic|algorithm|feature|library|package|dependency|plugin|extension|widget|element|node|token|parser|serializer|validator|formatter|linter|compiler|transpiler|bundler|loader|resolver|provider|consumer|producer|subscriber|publisher|emitter|dispatcher|reducer|selector|adapter|wrapper|decorator|mixin|trait|protocol|abstract|generic|iterator|generator|coroutine|fiber|thread|process|worker|job|task|queue|stack|buffer|stream|pipe|socket|channel|signal|slot|observer|mediator|strategy|command|visitor|singleton|repository|gateway|mapper|transformer|converter|encoder|decoder|interceptor|guard|filter|middleware|pipeline|chain|proxy|facade|bridge|flyweight|memento|prototype)\b',
+    # Modification verbs
+    r'\b(fix|update|refactor|modify|change|edit|rewrite|improve|enhance|optimize|debug|patch|correct|adjust|tweak|rework|revise|extend|expand|rename|move|extract|inline|split|merge|combine|consolidate|simplify|clean|cleanup|reorganize|restructure|decouple|encapsulate|abstract|generalize|specialize|upgrade|downgrade|migrate|convert|transform|adapt|port|backport)\b',
+    # Deletion/removal verbs
+    r'\b(delete|remove|drop|deprecate|disable|deactivate|unregister|detach|disconnect|unbind|unsubscribe|uninstall|prune|trim|strip|purge|clear|reset|destroy|dispose|release|free|deallocate)\b',
+    # Planning verbs
+    r'\b(plan|design|structure|architect|outline|draft|sketch|propose|suggest|approach|strategy|solution|how would|how should|how do|how can|how to|what if|where should|when should|why does|why is|could we|should we|can we|let.s|need to|want to|going to)\b',
+    # Review/analysis verbs
+    r'\b(review|check|analyze|audit|inspect|examine|validate|verify|assess|evaluate|trace|profile|benchmark|measure|monitor|diagnose|troubleshoot|investigate|identify|detect|discover|locate|find the bug|root cause)\b',
+    # Testing verbs
+    r'\b(test|run tests|unit test|integration test|e2e test|end.to.end|assert|expect|mock|stub|spy|fake|fixture|setup|teardown|arrange|act|coverage|regression|smoke test|snapshot|parameterize)\b',
+    # File types
+    r'\.(py|js|ts|tsx|jsx|css|scss|less|html|json|yaml|yml|toml|ini|cfg|sql|sh|bash|zsh|vue|svelte|go|rs|java|kt|swift|rb|php|c|cpp|h|hpp|cs|fs|ex|exs|erl|hs|ml|clj|scala|groovy|dart|lua|r|jl|nim|zig|wasm|graphql|proto|tf|hcl)\b',
+    # Programming concepts
+    r'\b(loop|condition|if statement|switch|try|catch|exception|error handling|async|await|promise|callback|event|listener|state|props|render|return|import|export|inherit|extend|override|decorator|middleware|migration|schema|model|view|controller|template|query|mutation|subscription|context|scope|closure|binding|reference|pointer|memory|allocation|garbage collection|concurrency|parallelism|synchronization|deadlock|race condition|mutex|semaphore|lock|atomic|transaction|rollback|commit|index|constraint|foreign key|primary key|join|aggregate|subquery|cursor|trigger|stored procedure|materialized view)\b',
+    # DevOps/infrastructure
+    r'\b(deploy|release|publish|ship|rollout|rollback|ci|cd|pipeline|docker|container|kubernetes|k8s|terraform|ansible|nginx|apache|server|cluster|replica|shard|partition|load balancer|proxy|cdn|ssl|tls|certificate|dns|domain|cors|csp|firewall|vpc|subnet|security group|iam|role|policy|secret|vault|env var|environment variable|configuration|config file|dotenv)\b',
+    # Database/data
+    r'\b(database|db|sql|nosql|mongo|postgres|mysql|sqlite|redis|elasticsearch|dynamodb|cassandra|orm|queryset|recordset|dataset|dataframe|csv|parquet|avro|protobuf|graphql|rest|grpc|websocket|sse|webhook|polling|pagination|cursor|offset|limit|batch|bulk|upsert|crud)\b',
+    # Sample/example requests
+    r'\b(example|sample|snippet|demo|prototype|proof of concept|poc|skeleton|boilerplate|starter|template|scaffold|seed|initial|baseline|reference implementation|minimal|basic|simple|quick|small)\b',
+    # Common tool/framework references
+    r'\b(django|flask|fastapi|express|next|react|vue|angular|svelte|tailwind|bootstrap|jest|pytest|mocha|cypress|playwright|selenium|webpack|vite|rollup|esbuild|npm|yarn|pnpm|pip|poetry|cargo|gradle|maven|cmake|bazel|make|dockerfile|compose|github|gitlab|bitbucket|jira|confluence)\b',
+]
+
+CONDENSED_RULES = """
+<code-rules-reminder>
+## MANDATORY CODE RULES - APPLY TO ALL CODE (samples, plans, implementations)
+
+1. **NO COMMENTS** - Self-documenting names only
+   - BAD: `d = 0.5  # delay` -> GOOD: `delay_between_retries_seconds = 0.5`
+
+2. **NO MAGIC VALUES** - Everything named and in config
+   - BAD: `if score > 0.8:` -> GOOD: `if score > MINIMUM_CONFIDENCE_THRESHOLD:`
+
+3. **NO ABBREVIATIONS** - Full words always
+   - BAD: `ctx`, `cfg`, `msg`, `btn` -> GOOD: `context`, `configuration`, `message`, `button`
+
+4. **COMPLETE TYPE HINTS** - All parameters and returns typed, no `Any`
+
+5. **CENTRALIZED CONFIG** - Constants in config/, imported everywhere
+
+6. **SEARCH BEFORE CREATE** - Use everything-search skill before defining constants
+
+7. **ALL IMPORTS SHOWN** - Every code block includes its imports
+
+8. **SELF-CONTAINED COMPONENTS** - Components own their modals/toasts/state
+
+CHECKLIST before writing ANY code:
+[ ] No comments (names explain everything)
+[ ] No magic values (all named constants)
+[ ] No abbreviations (full words)
+[ ] Complete types (all params + returns)
+[ ] Imports shown
+
+SCOPE: These rules apply to code you WRITE or MODIFY. Do NOT fix violations in untouched code unless explicitly instructed.
+</code-rules-reminder>
+"""
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    prompt = hook_input.get("prompt", "")
+
+    if not prompt:
+        sys.exit(0)
+
+    message_lower = prompt.lower()
+
+    for pattern in CODE_KEYWORDS:
+        if re.search(pattern, message_lower, re.IGNORECASE):
+            print(CONDENSED_RULES)
+            sys.exit(0)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session/compact-context-reinject.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+import json
+import os
+import sys
+
+PLUGIN_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+CODE_RULES_PATH = os.path.join(PLUGIN_ROOT, "docs", "CODE_RULES.md")
+
+
+def load_code_rules() -> str:
+    try:
+        with open(CODE_RULES_PATH, encoding="utf-8") as code_rules_file:
+            return code_rules_file.read()
+    except (FileNotFoundError, OSError):
+        return ""
+
+
+def main() -> None:
+    try:
+        json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    code_rules_content = load_code_rules()
+    if not code_rules_content:
+        sys.exit(0)
+
+    reinject_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": code_rules_content,
+        }
+    }
+    print(json.dumps(reinject_payload))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session/hook-structure-context.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""
+UserPromptSubmit hook that detects "hook" mentions and injects
+context about our current hook structure and how to add new hooks.
+"""
+
+import json
+import sys
+
+
+TRIGGER_PHRASES = [
+    "hook",
+]
+
+EXCLUDE_PHRASES = [
+    "react hook",
+    "usehook",
+    "usestate",
+    "useeffect",
+    "custom hook",
+    "git hook",
+    "pre-commit hook",
+    "webhook",
+]
+
+CONTEXT = """
+<hook-structure-context>
+## Claude Code Hook System
+
+### Architecture
+- **Runner pattern**: `run-hook-wrapper.js` (Node.js) -> `run-hook.py` (Python) -> individual hook
+- **Hook directory**: `hooks/`
+
+### Hook Organization (subfolder structure)
+```
+hooks/
+|-- rewrite-plugin-paths.py
+|-- session/
+|   |-- compact-context-reinject.py
+|   |-- plugin-data-dir-cleanup.py
+|   +-- hook-structure-context.py
+|-- notification/
+|   |-- attention-needed-notify.py
+|   |-- claude-notification-handler.py
+|   +-- notification_utils.py
+|-- advisory/
+|   |-- refactor-guard.py
+|   +-- migration-safety-advisor.py
+|-- validation/
+|   |-- code-style-validator.py
+|   |-- hook-format-validator.py
+|   |-- mypy_validator.py
+|   +-- e2e-test-validator.py
+|-- lifecycle/
+|   |-- config-change-guard.py
+|   +-- session-end-cleanup.py
+|-- blocking/
+|   |-- pyautogui-scroll-blocker.py
+|   |-- sensitive-file-protector.py
+|   |-- write-existing-file-blocker.py
+|   +-- destructive-command-blocker.py
+|-- git-hooks/
+|   +-- post-commit.py
+|-- github-action/
+|   +-- test_workflow.py
++-- validators/
+    |-- (validation check modules)
+    +-- test_files/
+```
+
+### Event Types
+| Event | When | Input (stdin JSON) | Can Block? |
+|-------|------|-------------------|------------|
+| SessionStart | Session begins | `{}` | No |
+| UserPromptSubmit | User sends message | `{"prompt": "..."}` | No (advisory) |
+| PreToolUse | Before tool execution | `{"tool_name": "...", "tool_input": {...}}` | YES (exit 2) |
+| PostToolUse | After tool execution | `{"tool_name": "...", "tool_input": {...}, "tool_output": "..."}` | No |
+| SubagentStop | Agent completes | `{"agent_type": "...", ...}` | No |
+| Stop | Session ends | `{}` | No |
+
+### How to Add a New Hook
+
+1. **Create the hook file** in the appropriate subfolder:
+   ```python
+   #!/usr/bin/env python3
+   import json
+   import sys
+
+   hook_input = json.load(sys.stdin)
+   print("Context to inject")
+   sys.exit(0)
+   ```
+
+2. **Register in settings.json** under the correct event type:
+   ```json
+   {
+     "type": "command",
+     "command": "node -e \\"process.argv.splice(1,0,'_');require(require('os').homedir()+'/.claude/hooks/run-hook-wrapper.js')\\" \\"session/your-hook.py\\"",
+     "timeout": 15000
+   }
+   ```
+
+3. **Key rules**:
+   - Always use the `run-hook-wrapper.js` pattern (cross-platform)
+   - Set explicit timeouts (10000-30000ms)
+   - PreToolUse hooks use `matcher` to scope which tools they fire on
+   - UserPromptSubmit hooks match on `prompt` content
+   - Print output = context injected into Claude's conversation
+   - Advisory hooks exit 0; blocking hooks exit 2 with `hookSpecificOutput.permissionDecision`
+</hook-structure-context>
+"""
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    prompt = hook_input.get("prompt", "")
+
+    if not prompt:
+        sys.exit(0)
+
+    message_lower = prompt.lower()
+
+    for exclude in EXCLUDE_PHRASES:
+        if exclude in message_lower:
+            sys.exit(0)
+
+    for phrase in TRIGGER_PHRASES:
+        if phrase in message_lower:
+            print(CONTEXT)
+            sys.exit(0)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/session/plugin-data-dir-cleanup.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""SessionStart hook — removes empty plugin data directories to prevent EEXIST.
+
+Claude Code's infrastructure calls mkdirSync without {recursive: true} when
+setting up plugin data directories for hook execution. If the directory already
+exists from a previous session, the mkdir throws EEXIST and the hook fails.
+
+This workaround removes known empty plugin data directories at session start
+so the infrastructure's mkdir succeeds when the Stop hook fires later.
+
+Tracking: https://github.com/anthropics/claude-code/issues — unfixed code path
+separate from the EEXIST fixes in v2.1.70-v2.1.72.
+"""
+
+import os
+import sys
+
+PLUGINS_DATA_DIRECTORY = os.path.join(
+    os.path.expanduser("~"), ".claude", "plugins", "data"
+)
+
+AFFECTED_PLUGIN_DIRECTORIES = [
+    "ralph-loop-claude-plugins-official",
+]
+
+
+def main() -> None:
+    for plugin_directory_name in AFFECTED_PLUGIN_DIRECTORIES:
+        target_path = os.path.join(PLUGINS_DATA_DIRECTORY, plugin_directory_name)
+        if not os.path.isdir(target_path):
+            continue
+        try:
+            os.rmdir(target_path)
+        except OSError:
+            pass
+
+
+if __name__ == "__main__":
+    main()