claude-dev-env 1.37.1 → 1.38.1

package/hooks/blocking/code_rules_enforcer.py

@@ -2580,7 +2580,30 @@ def _collect_load_names_outside_import_ranges(
     return referenced_names
 
 
-def check_unused_module_level_imports(content: str, file_path: str) -> list[str]:
+def _module_declares_dunder_all(tree: ast.Module) -> bool:
+    """Return True when the module body assigns or annotates ``__all__``."""
+    return any(
+        (
+            isinstance(each_node, ast.Assign)
+            and any(
+                isinstance(each_target, ast.Name) and each_target.id == "__all__"
+                for each_target in each_node.targets
+            )
+        )
+        or (
+            isinstance(each_node, ast.AnnAssign)
+            and isinstance(each_node.target, ast.Name)
+            and each_node.target.id == "__all__"
+        )
+        for each_node in tree.body
+    )
+
+
+def check_unused_module_level_imports(
+    content: str,
+    file_path: str,
+    full_file_content: str | None = None,
+) -> list[str]:
     """Flag module-level imports that are never referenced in the rest of the file.
 
     References are detected from AST ``Name`` / ``Attribute`` loads outside import
@@ -2589,42 +2612,39 @@ def check_unused_module_level_imports(content: str, file_path: str) -> list[str]
     whose module body includes ``if TYPE_CHECKING:`` (or
     ``typing[._extensions].TYPE_CHECKING``) are skipped. Suppression honors bare
     ``# noqa`` or an explicit ``F401`` code in the noqa list only.
+
+    When ``full_file_content`` is provided, ``content`` is treated as an Edit
+    fragment containing the imports being added or replaced, while the
+    ``__all__`` / ``TYPE_CHECKING`` gate detection and reference scanning run
+    against ``full_file_content`` (the post-edit file as it will look once the
+    Edit applies). This prevents false-positive flags on imports added in the
+    same Edit as their consumers.
     """
     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)
+        fragment_tree = ast.parse(content)
     except SyntaxError:
         return []
-    file_declares_dunder_all = any(
-        (
-            isinstance(each_node, ast.Assign)
-            and any(
-                isinstance(each_target, ast.Name) and each_target.id == "__all__"
-                for each_target in each_node.targets
-            )
-        )
-        or (
-            isinstance(each_node, ast.AnnAssign)
-            and isinstance(each_node.target, ast.Name)
-            and each_node.target.id == "__all__"
-        )
-        for each_node in tree.body
-    )
-    if file_declares_dunder_all:
+    reference_source = full_file_content if full_file_content is not None else content
+    try:
+        reference_tree = ast.parse(reference_source)
+    except SyntaxError:
+        return []
+    if _module_declares_dunder_all(reference_tree):
         return []
-    if _module_body_declares_type_checking_gate(tree):
+    if _module_body_declares_type_checking_gate(reference_tree):
         return []
-    content_lines = content.splitlines()
-    import_line_ranges = _import_statement_line_ranges(tree)
+    fragment_lines = content.splitlines()
+    reference_import_ranges = _import_statement_line_ranges(reference_tree)
     referenced_names = _collect_load_names_outside_import_ranges(
-        tree,
-        import_line_ranges,
+        reference_tree,
+        reference_import_ranges,
     )
     import_bindings: list[tuple[str, int, int | None]] = []
-    for each_node in tree.body:
+    for each_node in fragment_tree.body:
         if isinstance(each_node, (ast.Import, ast.ImportFrom)):
             if isinstance(each_node, ast.ImportFrom) and each_node.module == "__future__":
                 continue
@@ -2632,14 +2652,14 @@ def check_unused_module_level_imports(content: str, file_path: str) -> list[str]
                 import_bindings.append(each_binding)
     issues: list[str] = []
     for each_name, each_line_number, each_from_keyword_line in import_bindings:
-        if 1 <= each_line_number <= len(content_lines):
-            if line_suppresses_unused_import_via_noqa(content_lines[each_line_number - 1]):
+        if 1 <= each_line_number <= len(fragment_lines):
+            if line_suppresses_unused_import_via_noqa(fragment_lines[each_line_number - 1]):
                 continue
         if each_from_keyword_line is not None and 1 <= each_from_keyword_line <= len(
-            content_lines
+            fragment_lines
         ):
             if line_suppresses_unused_import_via_noqa(
-                content_lines[each_from_keyword_line - 1]
+                fragment_lines[each_from_keyword_line - 1]
             ):
                 continue
         if each_name in referenced_names:
@@ -2904,14 +2924,25 @@ def check_return_annotations(content: str, file_path: str) -> list[str]:
     return issues
 
 
-def validate_content(content: str, file_path: str, old_content: str = "") -> list[str]:
+def validate_content(
+    content: str,
+    file_path: str,
+    old_content: str = "",
+    full_file_content: str | None = None,
+) -> list[str]:
     """Run all applicable validators on content.
 
     Args:
-        content: The new content being written.
+        content: The new content being written. For Edit, this is the
+            ``new_string`` fragment; for Write, the entire new file body.
         file_path: Path to the file.
         old_content: Previous content (old_string for Edit, existing file for Write).
             Used to detect comment additions/removals instead of flagging all comments.
+        full_file_content: For Edit operations, the reconstructed post-edit
+            content of the entire file (existing file with ``old_string`` replaced
+            by ``new_string``). Whole-file checks such as the unused-import
+            scanner use this to evaluate references across the file rather than
+            just within the inserted fragment.
     """
     extension = get_file_extension(file_path)
     all_issues = []
@@ -2938,7 +2969,9 @@ def validate_content(content: str, file_path: str, old_content: str = "") -> lis
         all_issues.extend(check_stuttering_collection_prefix(content, file_path))
         all_issues.extend(check_hardcoded_user_paths(content, file_path))
         all_issues.extend(check_sys_path_insert_deduplication_guard(content, file_path))
-        all_issues.extend(check_unused_module_level_imports(content, file_path))
+        all_issues.extend(
+            check_unused_module_level_imports(content, file_path, full_file_content)
+        )
         all_issues.extend(check_library_print(content, file_path))
         all_issues.extend(check_parameter_annotations(content, file_path))
         all_issues.extend(check_return_annotations(content, file_path))
@@ -2959,6 +2992,30 @@ def validate_content(content: str, file_path: str, old_content: str = "") -> lis
     return all_issues
 
 
+def _reconstruct_post_edit_file_content(
+    file_path: str, old_string: str, new_string: str,
+) -> str | None:
+    """Return the file content as it will look after the Edit applies, or None.
+
+    Reads ``file_path`` from disk and replaces the first occurrence of
+    ``old_string`` with ``new_string``, mirroring how the Edit tool itself
+    applies a single replacement. Returns None when the file cannot be read,
+    ``old_string`` is empty, or ``old_string`` is not present in the existing
+    file (which means the Edit will fail or has already been applied — neither
+    case yields a well-defined post-edit view).
+    """
+    if not old_string:
+        return None
+    try:
+        with open(file_path, "r", encoding="utf-8") as existing_file:
+            existing_content = existing_file.read()
+    except (FileNotFoundError, OSError, UnicodeDecodeError):
+        return None
+    if old_string not in existing_content:
+        return None
+    return existing_content.replace(old_string, new_string, 1)
+
+
 def main() -> None:
     try:
         input_data = json.load(sys.stdin)
@@ -2980,9 +3037,13 @@ def main() -> None:
         sys.exit(0)
 
     old_content = ""
+    full_file_content_after_edit: str | None = None
     if tool_name == "Edit":
         content = tool_input.get("new_string", "")
         old_content = tool_input.get("old_string", "")
+        full_file_content_after_edit = _reconstruct_post_edit_file_content(
+            file_path, old_content, content,
+        )
     else:
         content = tool_input.get("content", "") or tool_input.get("new_string", "")
         try:
@@ -2997,7 +3058,7 @@ def main() -> None:
     if not content:
         sys.exit(0)
 
-    issues = validate_content(content, file_path, old_content)
+    issues = validate_content(content, file_path, old_content, full_file_content_after_edit)
 
     if issues:
         issue_list = "; ".join(issues[:10])

package/hooks/blocking/hedging_language_blocker.py

@@ -123,7 +123,7 @@ def main() -> None:
     else:
         skill_reference = (
             "under research-mode constraints "
-            "(no research-mode skill installed; verify with sources or reply 'I don't know')"
+            "(no research-mode skill installed; verify with sources or prompt the user via AskUserQuestion with potential options + context)"
         )
 
     block_response = {
@@ -134,7 +134,7 @@ def main() -> None:
             f"These words signal unverified claims. You MUST rewrite your response "
             f"{skill_reference}\n\n"
             f"Do NOT simply remove the hedging word and keep the unverified claim. "
-            f"Either VERIFY it with a source or replace it with 'I don't know'.\n\n"
+            f"Do more research to VERIFY it with a source, or prompt the user via AskUserQuestion with some potential options + context if you are unable to find anything online.\n\n"
             f"You MUST re-output the complete, revised response with the corrections applied."
         ),
         "systemMessage": USER_FACING_NOTICE,

package/hooks/blocking/state_description_blocker.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: blocks Write/Edit containing historical/comparative language in comments and .md files.
+
+Enforces the "describe current state only" rule — no "instead of", "previously",
+"now uses", or similar transitional framing. Comments and documentation should
+describe what IS, not what WAS or what CHANGED.
+"""
+
+import io
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def _insert_hooks_tree_for_imports() -> None:
+    hooks_tree = Path(__file__).absolute().parent.parent
+    hooks_tree_string = str(hooks_tree)
+    if hooks_tree_string not in sys.path:
+        sys.path.insert(0, hooks_tree_string)
+
+
+_insert_hooks_tree_for_imports()
+
+from config.state_description_blocker_constants import (
+    ALL_BLOCK_COMMENT_EXTENSIONS,
+    ALL_BLOCK_COMMENT_ONLY_EXTENSIONS,
+    ALL_COMMENT_BEARING_EXTENSIONS,
+    ALL_COMMENT_TRANSITION_PATTERNS,
+    ALL_HASH_AND_SLASH_EXTENSIONS,
+    ALL_HASH_ONLY_EXTENSIONS,
+    ALL_MARKDOWN_EXTENSIONS,
+    CODE_FENCE_PATTERN,
+    INLINE_CODE_PATTERN,
+)
+
+
+def _get_file_extension(file_path: str) -> str:
+    _, extension = os.path.splitext(file_path)
+    return extension.lower()
+
+
+def is_markdown_file(file_path: str) -> bool:
+    return _get_file_extension(file_path) in ALL_MARKDOWN_EXTENSIONS
+
+
+def is_comment_bearing_file(file_path: str) -> bool:
+    return _get_file_extension(file_path) in ALL_COMMENT_BEARING_EXTENSIONS
+
+
+def _get_inline_markers(extension: str) -> tuple[str, ...]:
+    if extension in ALL_HASH_ONLY_EXTENSIONS:
+        return ("#",)
+    if extension in ALL_HASH_AND_SLASH_EXTENSIONS:
+        return ("#", "//")
+    if extension in ALL_BLOCK_COMMENT_ONLY_EXTENSIONS:
+        return ()
+    return ("//",)
+
+
+def _extract_comment_lines(text: str, extension: str = "") -> list[str]:
+    """Extract comment lines from source code — Python (#), JS/TS/C/Rust/Go (//), and block comments."""
+    all_comment_lines: list[str] = []
+    all_lines = text.splitlines()
+
+    is_in_block_comment = False
+    has_block_comments = extension in ALL_BLOCK_COMMENT_EXTENSIONS
+    all_inline_markers = _get_inline_markers(extension)
+    for each_line in all_lines:
+        stripped = each_line.strip()
+
+        if has_block_comments:
+            if any(
+                stripped.startswith(each_marker)
+                for each_marker in all_inline_markers
+            ):
+                all_comment_lines.append(stripped)
+                continue
+            if "/*" in stripped and not is_in_block_comment:
+                is_in_block_comment = True
+                slash_star_index = stripped.find("/*")
+                close_star_index = stripped.find("*/", slash_star_index + len("/*"))
+                if close_star_index >= 0:
+                    all_comment_lines.append(
+                        stripped[slash_star_index : close_star_index + 2]
+                    )
+                    is_in_block_comment = False
+                    after_close = stripped[close_star_index + 2:].lstrip()
+                    if not after_close:
+                        continue
+                    stripped = after_close
+                else:
+                    all_comment_lines.append(stripped[slash_star_index:])
+                    continue
+            if is_in_block_comment:
+                close_index = stripped.find("*/")
+                if close_index >= 0:
+                    all_comment_lines.append(stripped[: close_index + 2])
+                    is_in_block_comment = False
+                else:
+                    all_comment_lines.append(stripped)
+                    continue
+
+        if any(
+            stripped.startswith(each_marker) for each_marker in all_inline_markers
+        ):
+            all_comment_lines.append(stripped)
+            continue
+
+        inline_index = _find_inline_comment_start(stripped, all_inline_markers)
+        if inline_index is not None and inline_index > 0:
+            all_comment_lines.append(stripped[inline_index:])
+            continue
+
+    return all_comment_lines
+
+
+def _find_inline_comment_start(stripped: str, all_markers: tuple[str, ...]) -> int | None:
+    """Find the earliest inline comment marker in a code line, across all markers.
+    Skips // when preceded by : to avoid treating URLs as inline comments,
+    but continues searching for subsequent // that are actual comments."""
+    best_position: int | None = None
+    for each_marker in all_markers:
+        search_start = 0
+        while True:
+            position = stripped.find(each_marker, search_start)
+            if position <= 0:
+                break
+            if each_marker == "//" and stripped[position - 1] == ":":
+                search_start = position + 1
+                continue
+            if best_position is None or position < best_position:
+                best_position = position
+            break
+    return best_position
+
+
+def find_violations(text: str, file_path: str) -> list[str]:
+    """Return all violated patterns found in text for the given file.
+
+    For .md files, scans the entire text. For code files, scans only comment lines.
+    Returns a list of matched pattern source strings.
+    """
+    if is_markdown_file(file_path):
+        scan_text = text
+    elif is_comment_bearing_file(file_path):
+        all_comment_lines = _extract_comment_lines(text, _get_file_extension(file_path))
+        scan_text = "\n".join(all_comment_lines)
+    else:
+        return []
+
+    if is_markdown_file(file_path):
+        scan_text = CODE_FENCE_PATTERN.sub("", scan_text)
+        scan_text = INLINE_CODE_PATTERN.sub("", scan_text)
+
+    if not scan_text.strip():
+        return []
+
+    all_detected: list[str] = []
+    all_transition_patterns = ALL_COMMENT_TRANSITION_PATTERNS
+    for each_pattern in all_transition_patterns:
+        all_matches = each_pattern.findall(scan_text)
+        if all_matches:
+            all_detected.append(all_matches[0].strip().lower())
+
+    return all_detected
+
+
+def main() -> None:
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    if not isinstance(input_data, dict):
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    if not isinstance(tool_name, str):
+        sys.exit(0)
+
+    tool_input = input_data.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        sys.exit(0)
+
+    if tool_name not in ("Write", "Edit"):
+        sys.exit(0)
+
+    file_path = tool_input.get("file_path", "")
+    if not file_path or not (
+        is_markdown_file(file_path) or is_comment_bearing_file(file_path)
+    ):
+        sys.exit(0)
+
+    content_to_check = ""
+    if tool_name == "Write":
+        content_to_check = tool_input.get("content", "")
+    elif tool_name == "Edit":
+        content_to_check = tool_input.get("new_string", "")
+
+    if not content_to_check:
+        sys.exit(0)
+
+    all_detected_patterns = find_violations(content_to_check, file_path)
+    if not all_detected_patterns:
+        sys.exit(0)
+
+    formatted = ", ".join(f'"{p}"' for p in all_detected_patterns)
+
+    block_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": (
+                f"Historical/comparative language detected in {file_path}: "
+                f"{formatted}. Describe current state only — no 'instead of', "
+                f"'previously', 'now uses', etc. The git log tracks what changed. "
+                f"Comments and docs describe what IS."
+            ),
+            "additionalContext": (
+                "Rewrite the affected comments or documentation to describe "
+                "only the current state. For example:\n"
+                '  BAD: "Uses X instead of Y"  →  GOOD: "Uses X"\n'
+                '  BAD: "Previously configured via Z"  →  GOOD: "Configured via Z"\n'
+                "See ~/.claude/rules/no-historical-clutter.md for full rules."
+            ),
+        },
+        "systemMessage": "Agent wrote comparative/historical language - describe current state only",
+        "suppressOutput": True,
+    }
+
+    _emit_hook_result(block_payload, sys.stdout)
+    sys.exit(0)
+
+
+def _emit_hook_result(all_hook_data: dict, output_stream: io.TextIOBase) -> None:
+    """Write the hook result JSON to the given output stream."""
+    output_stream.write(json.dumps(all_hook_data) + "\n")
+    output_stream.flush()
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/tdd_enforcer.py

@@ -13,6 +13,7 @@ import sys
 import time
 from pathlib import Path
 
+
 _hooks_root_path_string = str(Path(__file__).resolve().parent.parent)
 if _hooks_root_path_string not in sys.path:
     sys.path.insert(0, _hooks_root_path_string)
@@ -58,6 +59,48 @@ def _is_module_docstring_expression(module_level_node: ast.stmt) -> bool:
     return isinstance(expression_value.value, str)
 
 
+def _safe_constant_functions() -> frozenset[str]:
+    """Unqualified function names treated as safe value constructors."""
+    return frozenset({"Path", "frozenset"})
+
+
+def _safe_constant_attribute_calls() -> frozenset[tuple[str, str]]:
+    """(module, attr) pairs treated as safe value constructors."""
+    return frozenset({("re", "compile")})
+
+
+def _rhs_has_unsafe_call(rhs_node: ast.AST) -> bool:
+    """Return True when rhs_node contains a function call outside the safe allowlist.
+
+    Safe calls are value constructors (``Path(...)``, ``re.compile(...)``)
+    that create objects without side effects. Any other call pattern is
+    treated as unsafe import-time behavior.
+    """
+    safe_functions = _safe_constant_functions()
+    safe_attribute_calls = _safe_constant_attribute_calls()
+    for each_subnode in ast.walk(rhs_node):
+        if isinstance(each_subnode, ast.Call):
+            function_node = each_subnode.func
+            if isinstance(function_node, ast.Name):
+                if function_node.id not in safe_functions:
+                    return True
+            elif isinstance(function_node, ast.Attribute):
+                if isinstance(function_node.value, ast.Name):
+                    pair = (function_node.value.id, function_node.attr)
+                    if pair not in safe_attribute_calls:
+                        return True
+                else:
+                    return True
+            else:
+                return True
+        elif isinstance(
+            each_subnode,
+            (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp, ast.Lambda),
+        ):
+            return True
+    return False
+
+
 def _is_constants_only_python_content(content: str) -> bool:
     if not content.strip():
         return False
@@ -70,6 +113,10 @@ def _is_constants_only_python_content(content: str) -> bool:
     allowed_node_types = _constants_only_allowed_node_types()
     for each_top_level_node in parsed_tree.body:
         if isinstance(each_top_level_node, allowed_node_types):
+            if isinstance(each_top_level_node, (ast.Assign, ast.AnnAssign)):
+                rhs = each_top_level_node.value
+                if rhs is not None and _rhs_has_unsafe_call(rhs):
+                    return False
             continue
         if _is_module_docstring_expression(each_top_level_node):
             continue
@@ -77,6 +124,44 @@ def _is_constants_only_python_content(content: str) -> bool:
     return True
 
 
+def _apply_edit_to_content(existing_content: str, old_str: str, new_str: str) -> str:
+    """Replace the first occurrence of old_str with new_str in the content."""
+    return existing_content.replace(old_str, new_str, 1)
+
+
+def _is_post_edit_constants_only(existing_content: str, tool_name: str, tool_input: dict) -> bool:
+    """Check if post-edit content remains constants-only after Edit or MultiEdit.
+
+    Both the existing content and the post-edit result must be constants-only
+    to prevent edits on files with behavior from bypassing the TDD gate.
+    """
+    if not _is_constants_only_python_content(existing_content):
+        return False
+
+    if tool_name == "Edit":
+        old_str = tool_input.get("old_string", "")
+        new_str = tool_input.get("new_string", "") or ""
+        if not old_str:
+            return False
+        post_edit_content = _apply_edit_to_content(existing_content, old_str, new_str)
+        return _is_constants_only_python_content(post_edit_content)
+
+    if tool_name == "MultiEdit":
+        all_edits = tool_input.get("edits", []) or []
+        post_edit_content = existing_content
+        for each_edit in all_edits:
+            if not isinstance(each_edit, dict):
+                return False
+            each_old = each_edit.get("old_string", "")
+            each_new = each_edit.get("new_string", "") or ""
+            if not each_old:
+                return False
+            post_edit_content = _apply_edit_to_content(post_edit_content, each_old, each_new)
+        return _is_constants_only_python_content(post_edit_content)
+
+    return False
+
+
 def _tests_directory_name() -> str:
     return "tests"
 
@@ -297,11 +382,20 @@ def main() -> None:
         sys.exit(0)
 
     # Block production code - require confirmation
+    # Exempt constants-only content for Write (full content provided)
     written_content = _extract_written_content(tool_name, tool_input)
     if tool_name == "Write" and ext == ".py" and _is_constants_only_python_content(written_content):
         emit_allow()
         sys.exit(0)
 
+    # Exempt Edit/MultiEdit on constants-only files when post-edit content remains constants-only
+    if tool_name in ("Edit", "MultiEdit") and ext == ".py" and path.exists():
+        existing_content = _read_candidate_text(path)
+        if existing_content is not None:
+            if _is_post_edit_constants_only(existing_content, tool_name, tool_input):
+                emit_allow()
+                sys.exit(0)
+
     all_candidates = candidate_test_paths_for(path)
     if has_fresh_test(all_candidates, _freshness_seconds()):
         emit_allow()