claude-dev-env 1.31.0 → 1.33.0

package/hooks/blocking/code_rules_enforcer.py

@@ -60,6 +60,13 @@ NOT_INSIDE_TYPE_CHECKING_BLOCK = -1
 MAX_ISSUES_PER_CHECK = 3
 FILE_GLOBAL_UPPER_SNAKE_PATTERN = re.compile(r"^_?[A-Z][A-Z0-9_]*$")
 
+COLLECTION_TYPE_NAMES: frozenset[str] = frozenset({
+    "list", "tuple", "set", "frozenset", "dict",
+    "Iterable", "Sequence", "Mapping", "MutableMapping", "FrozenSet",
+})
+COLLECTION_BY_NAME_PATTERN: re.Pattern[str] = re.compile(r"^[a-z][a-z0-9]*_by_[a-z][a-z0-9_]*$")
+CLI_FILE_PATH_MARKERS: tuple[str, ...] = ("/scripts/", "\\scripts\\", "_cli.py", "/cli.py", "\\cli.py")
+
 
 def get_file_extension(file_path: str) -> str:
     """Extract lowercase file extension."""
@@ -1933,6 +1940,106 @@ def check_unused_optional_parameters(content: str, file_path: str) -> list[str]:
     return issues
 
 
+def _annotation_names_collection(annotation_node: ast.expr | None) -> bool:
+    if annotation_node is None:
+        return False
+    if isinstance(annotation_node, ast.Name):
+        return annotation_node.id in COLLECTION_TYPE_NAMES
+    if isinstance(annotation_node, ast.Subscript):
+        return _annotation_names_collection(annotation_node.value)
+    if isinstance(annotation_node, ast.Attribute):
+        return annotation_node.attr in COLLECTION_TYPE_NAMES
+    return False
+
+
+def check_collection_prefix(content: str, file_path: str) -> list[str]:
+    if is_test_file(file_path):
+        return []
+    if is_workflow_registry_file(file_path) or is_migration_file(file_path):
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for node in tree.body:
+        target_name: str | None = None
+        target_line = 0
+        is_collection_value = False
+        if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+            target_name = node.target.id
+            target_line = node.lineno
+            is_collection_value = _annotation_names_collection(node.annotation)
+        elif isinstance(node, ast.Assign) and len(node.targets) == 1 and isinstance(node.targets[0], ast.Name):
+            target_name = node.targets[0].id
+            target_line = node.lineno
+            is_collection_value = isinstance(node.value, (ast.Tuple, ast.List, ast.Set, ast.Dict))
+        if target_name is None or not is_collection_value:
+            continue
+        if not UPPER_SNAKE_CONSTANT_PATTERN.match(target_name):
+            continue
+        if target_name.startswith("ALL_") or COLLECTION_BY_NAME_PATTERN.match(target_name.lower()):
+            continue
+        issues.append(
+            f"Line {target_line}: Collection constant {target_name} - prefix with ALL_ (CODE_RULES §5)"
+        )
+        if len(issues) >= MAX_ISSUES_PER_CHECK:
+            break
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        for each_arg in _collect_annotated_arguments(node):
+            if not _annotation_names_collection(each_arg.annotation):
+                continue
+            if each_arg.arg in {"self", "cls"}:
+                continue
+            if each_arg.arg.startswith("all_") or COLLECTION_BY_NAME_PATTERN.match(each_arg.arg):
+                continue
+            issues.append(
+                f"Line {each_arg.lineno}: Collection parameter {each_arg.arg} - prefix with all_ (CODE_RULES §5)"
+            )
+            if len(issues) >= MAX_ISSUES_PER_CHECK:
+                return issues
+    return issues
+
+
+def _is_cli_entry_point(file_path: str) -> bool:
+    path_lower = file_path.lower().replace("\\", "/")
+    return any(marker.replace("\\", "/") in path_lower for marker in CLI_FILE_PATH_MARKERS)
+
+
+def check_library_print(content: str, file_path: str) -> list[str]:
+    if is_test_file(file_path) or is_config_file(file_path) or is_hook_infrastructure(file_path):
+        return []
+    if _is_cli_entry_point(file_path):
+        return []
+    if get_file_extension(file_path) not in PYTHON_EXTENSIONS:
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call):
+            continue
+        function_reference = node.func
+        if isinstance(function_reference, ast.Name) and function_reference.id == "print":
+            issues.append(
+                f"Line {node.lineno}: Library print() - route through logger or accept an explicit stream parameter"
+            )
+        elif isinstance(function_reference, ast.Attribute) and function_reference.attr == "write":
+            value_node = function_reference.value
+            if isinstance(value_node, ast.Attribute) and isinstance(value_node.value, ast.Name):
+                if value_node.value.id == "sys" and value_node.attr in {"stdout", "stderr"}:
+                    issues.append(
+                        f"Line {node.lineno}: sys.{value_node.attr}.write - route through logger"
+                    )
+        if len(issues) >= MAX_ISSUES_PER_CHECK:
+            break
+    return issues
+
+
 def validate_content(content: str, file_path: str, old_content: str = "") -> list[str]:
     """Run all applicable validators on content.
 
@@ -1964,6 +2071,8 @@ def validate_content(content: str, file_path: str, old_content: str = "") -> lis
         all_issues.extend(check_existence_check_tests(content, file_path))
         all_issues.extend(check_constant_equality_tests(content, file_path))
         all_issues.extend(check_unused_optional_parameters(content, file_path))
+        all_issues.extend(check_collection_prefix(content, file_path))
+        all_issues.extend(check_library_print(content, file_path))
         check_incomplete_mocks(content, file_path)
         check_duplicated_format_patterns(content, file_path)
 

package/hooks/blocking/test_windows_rmtree_blocker.py

@@ -0,0 +1,155 @@
+"""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_blocks_rmtree_with_nested_parens_in_args() -> None:
+    assert payload_contains_unsafe_rmtree(
+        "shutil.rmtree(Path(target).resolve(), ignore_errors=True)"
+    )
+
+
+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()
+    exit_code = 0
+    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,102 @@
+#!/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
+
+
+def payload_contains_unsafe_rmtree(payload_text: str) -> bool:
+    if not payload_text:
+        return False
+    rmtree_ignore_errors_pattern = re.compile(
+        r"shutil\s*\.\s*rmtree\s*\(.*?\bignore_errors\s*=\s*True\b",
+        re.DOTALL,
+    )
+    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"}:
+        return tool_input.get("content", "") or tool_input.get("new_string", "") or ""
+    if tool_name == "Bash":
+        return tool_input.get("command", "") or ""
+    return ""
+
+
+def main() -> None:
+    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."
+    )
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.stderr.write("windows_rmtree_blocker: malformed JSON on stdin\n")
+        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,20 @@
+"""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
+
+ALL_RMTREE_ONEXC_PYTHON_VERSION_PARTS: tuple[int, int] = (3, 12)
+
+SESSION_ID_PAYLOAD_KEY: str = "session_id"
+
+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,60 @@
+"""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, SESSION_ID_PAYLOAD_KEY
+
+
+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 TestSessionIdPayloadKey:
+    def test_session_id_payload_key_matches_hook_protocol_field(self) -> None:
+        assert SESSION_ID_PAYLOAD_KEY == "session_id"
+
+
+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