claude-dev-env 1.31.0 → 1.32.0

package/hooks/blocking/test_windows_rmtree_blocker.py

@@ -0,0 +1,148 @@
+"""Unit tests for windows_rmtree_blocker PreToolUse hook."""
+
+import importlib.util
+import json
+import io
+import pathlib
+import sys
+from contextlib import redirect_stdout
+
+_HOOK_DIR = pathlib.Path(__file__).parent
+if str(_HOOK_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOK_DIR))
+
+hook_spec = importlib.util.spec_from_file_location(
+    "windows_rmtree_blocker",
+    _HOOK_DIR / "windows_rmtree_blocker.py",
+)
+assert hook_spec is not None
+assert hook_spec.loader is not None
+hook_module = importlib.util.module_from_spec(hook_spec)
+hook_spec.loader.exec_module(hook_module)
+
+payload_contains_unsafe_rmtree = hook_module.payload_contains_unsafe_rmtree
+extract_payload_text = hook_module.extract_payload_text
+
+
+def test_detects_basic_ignore_errors_call() -> None:
+    assert payload_contains_unsafe_rmtree(
+        "shutil.rmtree(target_path, ignore_errors=True)"
+    )
+
+
+def test_detects_call_with_path_first_then_ignore_errors() -> None:
+    assert payload_contains_unsafe_rmtree(
+        'shutil.rmtree(r"C:\\temp\\foo", ignore_errors=True)'
+    )
+
+
+def test_detects_oneliner_python_dash_c_form() -> None:
+    bash_command = (
+        'python -c "import shutil; '
+        "shutil.rmtree(r'<team_temp_dir>', ignore_errors=True)\""
+    )
+    assert payload_contains_unsafe_rmtree(bash_command)
+
+
+def test_detects_call_with_extra_whitespace() -> None:
+    assert payload_contains_unsafe_rmtree(
+        "shutil .rmtree (path,    ignore_errors  =  True)"
+    )
+
+
+def test_detects_call_split_across_lines() -> None:
+    multiline_code = "shutil.rmtree(\n    target_path,\n    ignore_errors=True,\n)"
+    assert payload_contains_unsafe_rmtree(multiline_code)
+
+
+def test_allows_rmtree_with_onexc_handler() -> None:
+    safe_code = "shutil.rmtree(target_path, onexc=_strip_read_only_and_retry)"
+    assert not payload_contains_unsafe_rmtree(safe_code)
+
+
+def test_allows_rmtree_with_onerror_handler() -> None:
+    safe_code = "shutil.rmtree(target_path, onerror=_strip_read_only_and_retry)"
+    assert not payload_contains_unsafe_rmtree(safe_code)
+
+
+def test_allows_bare_rmtree_call() -> None:
+    bare_call = "shutil.rmtree(target_path)"
+    assert not payload_contains_unsafe_rmtree(bare_call)
+
+
+def test_allows_ignore_errors_false() -> None:
+    assert not payload_contains_unsafe_rmtree(
+        "shutil.rmtree(target_path, ignore_errors=False)"
+    )
+
+
+def test_extract_payload_handles_write_content() -> None:
+    extracted = extract_payload_text("Write", {"content": "abc"})
+    assert extracted == "abc"
+
+
+def test_extract_payload_handles_edit_new_string() -> None:
+    extracted = extract_payload_text("Edit", {"new_string": "abc"})
+    assert extracted == "abc"
+
+
+def test_extract_payload_handles_bash_command() -> None:
+    extracted = extract_payload_text("Bash", {"command": "ls"})
+    assert extracted == "ls"
+
+
+def test_extract_payload_returns_empty_for_unknown_tool() -> None:
+    extracted = extract_payload_text("OtherTool", {"content": "abc"})
+    assert extracted == ""
+
+
+def _run_hook(hook_input: dict) -> tuple[str, int]:
+    captured = io.StringIO()
+    sys.stdin = io.StringIO(json.dumps(hook_input))
+    try:
+        with redirect_stdout(captured):
+            try:
+                hook_module.main()
+            except SystemExit as exit_signal:
+                exit_code = exit_signal.code or 0
+    finally:
+        sys.stdin = sys.__stdin__
+    return captured.getvalue(), exit_code
+
+
+def test_main_blocks_unsafe_bash_command() -> None:
+    stdout_text, exit_code = _run_hook(
+        {
+            "tool_name": "Bash",
+            "tool_input": {
+                "command": (
+                    'python -c "import shutil; '
+                    "shutil.rmtree(r'/tmp/x', ignore_errors=True)\""
+                )
+            },
+        }
+    )
+    assert exit_code == 0
+    response_payload = json.loads(stdout_text)
+    decision_block = response_payload["hookSpecificOutput"]
+    assert decision_block["permissionDecision"] == "deny"
+    assert "windows-rmtree" in decision_block["permissionDecisionReason"]
+
+
+def test_main_passes_through_safe_write() -> None:
+    stdout_text, exit_code = _run_hook(
+        {
+            "tool_name": "Write",
+            "tool_input": {"content": "shutil.rmtree(path, onexc=handler)"},
+        }
+    )
+    assert exit_code == 0
+    assert stdout_text == ""
+
+
+def test_main_passes_through_unrelated_tool() -> None:
+    stdout_text, exit_code = _run_hook(
+        {"tool_name": "Read", "tool_input": {"file_path": "/tmp/x"}}
+    )
+    assert exit_code == 0
+    assert stdout_text == ""

package/hooks/blocking/windows_rmtree_blocker.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: block shutil.rmtree(..., ignore_errors=True).
+
+shutil.rmtree on Windows raises PermissionError when it encounters a file carrying
+the ReadOnly attribute (FILE_ATTRIBUTE_READONLY). With ignore_errors=True the failure
+is silently swallowed and the tree stays on disk — cleanup looks successful but
+pruned nothing. Linux never hits this because unlink on Linux only needs write on
+the parent directory, not on the file itself. Tests run inside pytest's tmp_path
+do not exercise the regression path because tmp dirs do not carry the attribute.
+
+This hook scans Write/Edit content and Bash commands for the dangerous pattern and
+blocks it with a corrective message pointing to the force_rmtree replacement.
+"""
+
+import json
+import re
+import sys
+
+_WRITE_EDIT_TOOL_NAMES = {"Write", "Edit"}
+_BASH_TOOL_NAME = "Bash"
+
+_RMTREE_IGNORE_ERRORS_PATTERN = re.compile(
+    r"shutil\s*\.\s*rmtree\s*\([^)]*\bignore_errors\s*=\s*True\b",
+    re.DOTALL,
+)
+
+_CORRECTIVE_MESSAGE = (
+    "BLOCKED [windows-rmtree]: shutil.rmtree(..., ignore_errors=True) silently "
+    "fails on Windows when a file carries the ReadOnly attribute "
+    "(FILE_ATTRIBUTE_READONLY). The PermissionError is swallowed and the tree "
+    "stays on disk -- cleanup looks successful but removes nothing. Linux is "
+    "unaffected because unlink only needs write on the parent directory.\n\n"
+    "Use a Windows-safe handler that strips the attribute and retries the "
+    "syscall:\n\n"
+    "    import os\n"
+    "    import shutil\n"
+    "    import stat\n"
+    "    import sys\n\n"
+    "    def _strip_read_only_and_retry(removal_function, target_path, *_exc_info):\n"
+    "        try:\n"
+    "            os.chmod(target_path, stat.S_IWRITE)\n"
+    "            removal_function(target_path)\n"
+    "        except OSError:\n"
+    "            pass\n\n"
+    "    def force_rmtree(target_path: str) -> None:\n"
+    "        handler_kw = (\n"
+    '            {"onexc": _strip_read_only_and_retry}\n'
+    "            if sys.version_info >= (3, 12)\n"
+    '            else {"onerror": _strip_read_only_and_retry}\n'
+    "        )\n"
+    "        try:\n"
+    "            shutil.rmtree(target_path, **handler_kw)\n"
+    "        except OSError:\n"
+    "            pass\n\n"
+    "Two things to know about the handler:\n"
+    "  - *_exc_info collapses the signature difference. onerror passes "
+    "(type, value, traceback); onexc (Python 3.12+) passes a single exception.\n"
+    "  - removal_function is whichever syscall rmtree was attempting "
+    "(os.unlink for files, os.rmdir for dirs). Re-call it after chmod to finish "
+    "the work that originally failed.\n\n"
+    "See ~/.claude/rules/windows-filesystem-safe.md for full guidance."
+)
+
+
+def payload_contains_unsafe_rmtree(payload_text: str) -> bool:
+    if not payload_text:
+        return False
+    return bool(_RMTREE_IGNORE_ERRORS_PATTERN.search(payload_text))
+
+
+def extract_payload_text(tool_name: str, tool_input: dict) -> str:
+    if tool_name in _WRITE_EDIT_TOOL_NAMES:
+        return tool_input.get("content", "") or tool_input.get("new_string", "") or ""
+    if tool_name == _BASH_TOOL_NAME:
+        return tool_input.get("command", "") or ""
+    return ""
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = hook_input.get("tool_name", "")
+    tool_input = hook_input.get("tool_input", {})
+
+    payload_text = extract_payload_text(tool_name, tool_input)
+
+    if not payload_contains_unsafe_rmtree(payload_text):
+        sys.exit(0)
+
+    deny_response = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": _CORRECTIVE_MESSAGE,
+        }
+    }
+    print(json.dumps(deny_response))
+    sys.stdout.flush()
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/config/hook_log_extractor_constants.py

@@ -216,6 +216,19 @@ BWS_RUN_SEPARATOR: str = "--"
 BWS_RUN_SUBCOMMAND: str = "run"
 STOP_WRAPPER_EXTRACTOR_SCRIPT_NAME: str = "hook_log_extractor.py"
 
+STOP_WRAPPER_DEBOUNCE_SECONDS: int = 60
+STOP_WRAPPER_LAST_RUN_TIMESTAMP_FILE: str = str(
+    _resolve_claude_home_directory()
+    / "logs"
+    / "hooks"
+    / ".state"
+    / "stop_wrapper_last_run.txt"
+)
+
+WINDOWS_OS_NAME: str = "nt"
+WINDOWS_DETACHED_PROCESS_FLAG: int = 0x00000008
+WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG: int = 0x00000200
+
 LOCK_MAXIMUM_RETRY_COUNT: int = 30
 LOCK_RETRY_SLEEP_SECONDS: float = 0.1
 

package/hooks/config/session_env_cleanup_constants.py

@@ -0,0 +1,18 @@
+"""Configuration constants for the session_env_cleanup SessionStart hook."""
+
+from __future__ import annotations
+
+import os
+import re
+
+SESSION_ENV_DIRECTORY = os.path.join(os.path.expanduser("~"), ".claude", "session-env")
+
+SECONDS_PER_DAY = 24 * 60 * 60
+STALE_AGE_DAYS = 7
+STALE_AGE_SECONDS = STALE_AGE_DAYS * SECONDS_PER_DAY
+
+RMTREE_ONEXC_PYTHON_VERSION = (3, 12)
+
+SESSION_ID_PATTERN = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
+
+WINDOWS_PLATFORM_TAG = "win32"

package/hooks/config/test_hook_log_extractor_constants.py

@@ -21,6 +21,10 @@ from config.hook_log_extractor_constants import (
     QUERY_NAME_PATTERN,
     SENTINEL_INSERT_FAILURE_MESSAGE,
     SENTINEL_SELECT_FAILURE_MESSAGE,
+    STOP_WRAPPER_DEBOUNCE_SECONDS,
+    STOP_WRAPPER_LAST_RUN_TIMESTAMP_FILE,
+    WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG,
+    WINDOWS_DETACHED_PROCESS_FLAG,
 )
 
 
@@ -94,3 +98,26 @@ def test_resolver_falls_back_to_home_when_claude_home_is_whitespace(
 def test_lock_retry_constants_are_positive_and_bounded() -> None:
     assert LOCK_MAXIMUM_RETRY_COUNT > 0
     assert LOCK_RETRY_SLEEP_SECONDS > 0
+
+
+def test_stop_wrapper_debounce_seconds_is_positive() -> None:
+    assert STOP_WRAPPER_DEBOUNCE_SECONDS > 0
+
+
+def test_stop_wrapper_last_run_timestamp_file_is_under_claude_home() -> None:
+    expected_path = (
+        hook_log_extractor_constants._resolve_claude_home_directory()
+        / "logs"
+        / "hooks"
+        / ".state"
+        / "stop_wrapper_last_run.txt"
+    )
+    assert Path(STOP_WRAPPER_LAST_RUN_TIMESTAMP_FILE) == expected_path
+
+
+def test_windows_creation_flags_are_distinct_nonzero_bits() -> None:
+    assert WINDOWS_DETACHED_PROCESS_FLAG > 0
+    assert WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG > 0
+    assert (
+        WINDOWS_DETACHED_PROCESS_FLAG & WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG
+    ) == 0

package/hooks/config/test_session_env_cleanup_constants.py

@@ -0,0 +1,55 @@
+"""Tests for session_env_cleanup_constants — behavioral checks on SESSION_ID_PATTERN."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_CONFIG_DIRECTORY = Path(__file__).resolve().parent
+_HOOKS_ROOT = _CONFIG_DIRECTORY.parent
+for each_sys_path_entry in (str(_CONFIG_DIRECTORY), str(_HOOKS_ROOT)):
+    if each_sys_path_entry not in sys.path:
+        sys.path.insert(0, each_sys_path_entry)
+
+from config.session_env_cleanup_constants import SESSION_ID_PATTERN
+
+
+class TestSessionIdPatternAccepts:
+    def test_accepts_uuid_with_hyphens(self) -> None:
+        valid_uuid_input = "5fcc01b3-138b-49e1-9976-ff1035013a4f"
+        matched = SESSION_ID_PATTERN.fullmatch(valid_uuid_input)
+        assert matched.group(0) == valid_uuid_input
+
+    def test_accepts_alphanumeric_only(self) -> None:
+        alphanumeric_input = "abc123XYZ"
+        matched = SESSION_ID_PATTERN.fullmatch(alphanumeric_input)
+        assert matched.group(0) == alphanumeric_input
+
+    def test_accepts_underscore_separated(self) -> None:
+        underscore_input = "session_42_alpha"
+        matched = SESSION_ID_PATTERN.fullmatch(underscore_input)
+        assert matched.group(0) == underscore_input
+
+
+class TestSessionIdPatternRejects:
+    def test_rejects_forward_slash(self) -> None:
+        assert SESSION_ID_PATTERN.match("etc/passwd") is None
+
+    def test_rejects_back_slash(self) -> None:
+        assert SESSION_ID_PATTERN.match("Users\\jon") is None
+
+    def test_rejects_parent_traversal(self) -> None:
+        assert SESSION_ID_PATTERN.match("..") is None
+
+    def test_rejects_absolute_windows_path(self) -> None:
+        assert SESSION_ID_PATTERN.match("C:\\Windows\\Temp") is None
+
+    def test_rejects_empty_string(self) -> None:
+        assert SESSION_ID_PATTERN.match("") is None
+
+    def test_rejects_overlong_input(self) -> None:
+        overlong_input = "a" * 65
+        assert SESSION_ID_PATTERN.match(overlong_input) is None
+
+    def test_rejects_dot_in_middle(self) -> None:
+        assert SESSION_ID_PATTERN.match("session.uuid") is None

package/hooks/diagnostic/hook_log_stop_wrapper.py

@@ -1,12 +1,25 @@
 #!/usr/bin/env python3
-"""Stop-hook wrapper for hook_log_extractor that never surfaces a hook failure.
-
-Invokes ``hook_log_extractor.py --incremental`` via ``bws run`` only when
-both ``bws`` is on PATH and ``BWS_ACCESS_TOKEN`` is set; otherwise falls
-through to run the extractor directly. The extractor itself exits 0 when
-``NEON_HOOK_LOGS_DATABASE_URL`` is unset, so the wrapper can rely on that
-offline-graceful path. This wrapper always exits 0 so the Stop hook
-never blocks session end on a missing dependency.
+"""Stop-hook wrapper for hook_log_extractor: debounced, fire-and-forget.
+
+Runs after every assistant turn (Stop hook), so per-turn latency must
+stay near zero. The wrapper:
+
+1. Reads the last-spawn timestamp; if it falls within the debounce
+   window, exits 0 immediately without spawning anything (typical fast
+   path: a small file read, well under 10ms).
+2. Otherwise records the current timestamp, then launches the extractor
+   as a fully detached background process (no stdio, separate process
+   group on POSIX or DETACHED_PROCESS|CREATE_NEW_PROCESS_GROUP on
+   Windows) and returns without waiting for it.
+
+Bitwarden injection: when both ``bws`` is on PATH and
+``BWS_ACCESS_TOKEN`` is set, the extractor is launched via
+``bws run --`` so the Neon URL never hits disk; otherwise it is
+launched directly. The extractor itself exits 0 when
+``NEON_HOOK_LOGS_DATABASE_URL`` is unset, so missing dependencies
+cannot block session shutdown.
+
+This wrapper always exits 0 so the Stop hook never surfaces a failure.
 """
 
 from __future__ import annotations
@@ -15,6 +28,7 @@ import os
 import shutil
 import subprocess
 import sys
+import time
 from pathlib import Path
 
 if str(Path(__file__).resolve().parent.parent) not in sys.path:
@@ -27,7 +41,12 @@ from config.hook_log_extractor_constants import (
     BWS_RUN_SUBCOMMAND,
     EXIT_CODE_SUCCESS,
     FLAG_INCREMENTAL,
+    STOP_WRAPPER_DEBOUNCE_SECONDS,
     STOP_WRAPPER_EXTRACTOR_SCRIPT_NAME,
+    STOP_WRAPPER_LAST_RUN_TIMESTAMP_FILE,
+    WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG,
+    WINDOWS_DETACHED_PROCESS_FLAG,
+    WINDOWS_OS_NAME,
 )
 
 
@@ -37,14 +56,77 @@ def _extractor_script_path() -> str:
     )
 
 
+def _last_run_timestamp_path() -> Path:
+    return Path(STOP_WRAPPER_LAST_RUN_TIMESTAMP_FILE)
+
+
+def _is_within_debounce_window() -> bool:
+    timestamp_path = _last_run_timestamp_path()
+    if not timestamp_path.exists():
+        return False
+    try:
+        previous_timestamp = float(timestamp_path.read_text().strip())
+    except (OSError, ValueError):
+        return False
+    seconds_since_previous_spawn = time.time() - previous_timestamp
+    if seconds_since_previous_spawn < 0:
+        return False
+    return seconds_since_previous_spawn < STOP_WRAPPER_DEBOUNCE_SECONDS
+
+
+def _record_current_timestamp() -> None:
+    timestamp_path = _last_run_timestamp_path()
+    timestamp_path.parent.mkdir(parents=True, exist_ok=True)
+    timestamp_path.write_text(str(time.time()))
+
+
+def _clear_recorded_timestamp() -> None:
+    """Remove the debounce timestamp regardless of which process wrote it.
+
+    The unlink is unconditional: if process A writes a timestamp, process
+    B observes it and debounces, then A's spawn fails, A's rollback here
+    deletes the timestamp B already saw. The next Stop hook then spawns
+    a fresh extractor instead of debouncing the remainder of the window.
+    Consequence is benign because the extractor's own offset-file lock
+    (LOCK_MAXIMUM_RETRY_COUNT in hook_log_extractor_constants) serializes
+    concurrent extractor runs, so at most one extra extractor briefly
+    waits on the lock. Scoping the rollback to A's own write would
+    require a per-process sentinel and tighter atomicity than the
+    benefit warrants for this Stop-hook fast path.
+    """
+    timestamp_path = _last_run_timestamp_path()
+    timestamp_path.unlink(missing_ok=True)
+
+
 def _can_use_bws() -> bool:
     if not os.environ.get(BWS_ACCESS_TOKEN_ENV_VAR):
         return False
     return shutil.which(BWS_EXECUTABLE_NAME) is not None
 
 
-def _run_with_bws() -> None:
-    subprocess.run(
+def _detached_spawn_keyword_arguments() -> dict[str, object]:
+    spawn_arguments: dict[str, object] = {
+        "stdin": subprocess.DEVNULL,
+        "stdout": subprocess.DEVNULL,
+        "stderr": subprocess.DEVNULL,
+        "close_fds": True,
+    }
+    if os.name == WINDOWS_OS_NAME:
+        spawn_arguments["creationflags"] = (
+            WINDOWS_DETACHED_PROCESS_FLAG
+            | WINDOWS_CREATE_NEW_PROCESS_GROUP_FLAG
+        )
+        startup_info = subprocess.STARTUPINFO()
+        startup_info.dwFlags |= subprocess.STARTF_USESHOWWINDOW
+        startup_info.wShowWindow = subprocess.SW_HIDE
+        spawn_arguments["startupinfo"] = startup_info
+    else:
+        spawn_arguments["start_new_session"] = True
+    return spawn_arguments
+
+
+def _spawn_with_bws() -> None:
+    subprocess.Popen(
         [
             BWS_EXECUTABLE_NAME,
             BWS_RUN_SUBCOMMAND,
@@ -53,28 +135,34 @@ def _run_with_bws() -> None:
             _extractor_script_path(),
             FLAG_INCREMENTAL,
         ],
-        check=False,
+        **_detached_spawn_keyword_arguments(),
     )
 
 
-def _run_without_bws() -> None:
-    subprocess.run(
+def _spawn_without_bws() -> None:
+    subprocess.Popen(
         [
             sys.executable,
             _extractor_script_path(),
             FLAG_INCREMENTAL,
         ],
-        check=False,
+        **_detached_spawn_keyword_arguments(),
     )
 
 
 def main() -> int:
-    """Invoke the extractor with or without bws; swallow all failures."""
+    """Debounce, then fire-and-forget the extractor; always exit 0."""
     try:
-        if _can_use_bws():
-            _run_with_bws()
-        else:
-            _run_without_bws()
+        if _is_within_debounce_window():
+            return EXIT_CODE_SUCCESS
+        _record_current_timestamp()
+        try:
+            if _can_use_bws():
+                _spawn_with_bws()
+            else:
+                _spawn_without_bws()
+        except Exception:
+            _clear_recorded_timestamp()
     except Exception:
         pass
     return EXIT_CODE_SUCCESS